Skip to content
APIs/Card Payouts/
Retrieve payout details

Card Payouts (4)

Send funds to your customer's cards. Standard or using Fast Access.

Authentication

Set your headers:

  Authorization: {your_credentials}
  Content-Type: application/vnd.worldpay.payouts-v4+json
  Accept: application/vnd.worldpay.payouts-v4+json

Replace {your_credentials} with your base64-encoded Basic Auth username and password.


DNS whitelisting

Whitelist the following URLs:

  • https://try.access.worldpay.com/
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Test (Try)
https://try.access.worldpay.com
Live
https://access.worldpay.com

Retrieve payout details

Request

Retrieve the details of an existing basic disbursement or Fast Access payout.

Security
BasicAuth
Path
resourcestringrequired

The payouts:payout href value returned in the response to your basic disbursement or Fast Access payout request.

No request payload

Responses

Payout resource.

Bodyapplication/vnd.worldpay.payouts-v4+json
outcomestringrequired

Outcome of payout request.

schemeobject
namestringrequired

The name of the card scheme that was used to process your payout request

Enum ValueDescription
visa

Processed with Visa Direct

mastercard

Processed with Mastercard Send

referencestring

The reference returned by the card scheme for your payout request.

Example: "520000000001"
receivedAtstringrequired

A timestamp of receivedAt.

Response
application/vnd.worldpay.payouts-v4+json

Basic Disbursement: Successful resource retrieval with outcome requestReceived

{
  "outcome": "requestReceived",
  "receivedAt": "2023-09-01T10:37:36.923Z",
  "_links": {
    "payouts:payout": {
      "href": "https://try.access.worldpay.com/payouts/{resource}"
    },
    "curies": [
      {
        "name": "payouts",
        "href": "https://try.access.worldpay.com/rels/payouts/{rel}",
        "templated": true
      }
    ]
  }
}

Retrieve payout details from a historic resource

Request

Query by transaction reference and entity to retrieve a payout.

Security
BasicAuth
Query
transactionReferencestringrequired

A unique reference generated by you, used to identify a payout throughout its lifecycle.

Example: transactionReference=12345
entitystringrequired

merchant entity

Example: entity=default
No request payload

Responses

Returns a payout resource, provided one matches the transaction and entity references.

Bodyapplication/vnd.worldpay.payouts-v4+json
outcomestringrequired

outcome of payouts query request

schemeobject
namestringrequired

The name of the card scheme that was used to process your payout request

Enum ValueDescription
visa

Processed with Visa Direct

mastercard

Processed with Mastercard Send

referencestring

The reference returned by the card scheme for your payout request.

Example: "520000000001"
receivedAtstringrequired

A timestamp of receivedAt

Response
application/vnd.worldpay.payouts-v4+json

Basic Disbursement: An existing resource is retrieved with outcome 'requestReceived'

{
  "outcome": "requestReceived",
  "receivedAt": "2025-08-01T10:37:36.923Z",
  "_links": {
    "payouts:payout": {
      "href": "https://try.access.worldpay.com/payouts/{resource}"
    },
    "curies": [
      {
        "name": "payouts",
        "href": "https://try.access.worldpay.com/rels/payouts/{rel}",
        "templated": true
      }
    ]
  }
}

Standard payout

Request

Disburse funds to a payout instrument.

Security
BasicAuth
Bodyapplication/vnd.worldpay.payouts-v4+json
instructionobjectrequired

An object that contains all the information related to your payout request.

narrativeobjectrequired

An object that contains identification and further details of the merchant.

payoutInstrumentobjectrequired

An object that contains your customer's payout type.

valueobjectrequired

An object that contains payout amount and currency.

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 32 ] characters^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$required

Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.

Example: "default"
transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference generated by you, used to identify a payout throughout its lifecycle.

application/vnd.worldpay.payouts-v4+json

Successful Basic Disbursement

{
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "value": {
      "amount": 300,
      "currency": "GBP"
    },
    "payoutInstrument": {
      "type": "card/plain",
      "cardHolderName": "Sherlock Holmes",
      "cardExpiryDate": {
        "month": 1,
        "year": 2025
      },
      "cardNumber": "4444333322221111",
      "billingAddress": {
        "address1": "address1",
        "address2": "address2",
        "address3": "address3",
        "postalCode": "postalCode",
        "city": "city",
        "state": "state",
        "countryCode": "GB"
      }
    },
    "narrative": {
      "line1": "STATEMENT",
      "line2": "OPTIONAL"
    }
  },
  "transactionReference": "transaction-ref"
}

Responses

The outcome of your card payout request.

Bodyapplication/vnd.worldpay.payouts-v4+json
outcomestringrequired

Outcome of payouts request.

receivedAtstringrequired

A timestamp of receivedAt.

_linksobjectrequired
payouts:payoutobject

Your card payout resource.

Response
application/vnd.worldpay.payouts-v4+json

Successful Basic Disbursement

{
  "outcome": "requestReceived",
  "receivedAt": "2025-08-01T10:37:36.923Z",
  "_links": {
    "payouts:payout": {
      "href": "https://try.access.worldpay.com/payouts/{resource}"
    },
    "curies": [
      {
        "name": "payouts",
        "href": "https://try.access.worldpay.com/rels/payouts/{rel}",
        "templated": true
      }
    ]
  }
}

Fast Access payout

Request

Disburse funds to a payout instrument using Fast Access.

Security
BasicAuth
Bodyapplication/vnd.worldpay.payouts-v4+json
instructionobjectrequired

An object that contains all the information related to your payout request.

narrativeobjectrequired

An object that contains identification and further details of the merchant.

payoutInstrumentobjectrequired

An object that contains your customer's payout type.

valueobjectrequired

An object that contains payout amount and currency.

routingobject
merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 1 .. 32 ] characters^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$required

Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.

Example: "default"
transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference generated by you, used to identify a payout throughout its lifecycle.

application/vnd.worldpay.payouts-v4+json

Successful issuing of a disbursal request

{
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "value": {
      "amount": 300,
      "currency": "GBP"
    },
    "payoutInstrument": {
      "type": "card/plain",
      "cardHolderName": "Sherlock Holmes",
      "cardExpiryDate": {
        "month": 1,
        "year": 2030
      },
      "cardNumber": "4444333322221111",
      "billingAddress": {
        "address1": "address1",
        "address2": "address2",
        "address3": "address3",
        "postalCode": "postalCode",
        "city": "city",
        "state": "state",
        "countryCode": "GB"
      }
    },
    "narrative": {
      "line1": "STATEMENT",
      "line2": "OPTIONAL"
    }
  },
  "transactionReference": "transaction-ref"
}

Responses

The outcome of your Fast Access card payout request.

Bodyapplication/vnd.worldpay.payouts-v4+json
outcomestringrequired

Outcome of payouts request.

Enum ValueDescription
requested

We have received your Fast Access disbursement. Retrieve the payout later to confirm status.

pending

We have sent your Fast Access disbursement request to Visa Direct/Mastercard Send. If there are no updates within 48 hours then this moves to an error outcome.

approved

Visa/Mastercard has approved your request and the funds are allocated within 30 minutes if the issuer is Fast Access enabled. If not, standard timescales apply.

disbursed

The transaction is reconciled with Visa/Mastercard’s daily reporting.

refused

Your Fast Access disbursement request is refused.

  • The card issuer declines the disbursement
  • Visa/Mastercard declines your request because the issuing bank is not responding
  • Disbursements are not allowed in the requested country
error

There is no response from Visa/Mastercard within 48 hours or Visa/Mastercard returns an error confirming the request has failed.

requestReceived

We have received your Fast Access disbursement request, but the card does not support Fast Access.

inReview

We are reviewing your Fast Access disbursement request. If the review is successful, then your payout is processed and moves to an approved or refused outcome. If the review fails, the payout moves to an error outcome.

schemeobject
namestringrequired

The name of the card scheme that was used to process your payout request

Enum ValueDescription
visa

Processed with Visa Direct

mastercard

Processed with Mastercard Send

referencestring

The reference returned by the card scheme for your payout request.

Example: "520000000001"
receivedAtstringrequired

A timestamp of when the payout request was received.

_linksobjectrequired
payouts:payoutobject

Your card payout resource.

Response
application/vnd.worldpay.payouts-v4+json

Successful issuing of a disbursal request

{
  "outcome": "pending",
  "receivedAt": "2025-08-01T10:37:36.923Z",
  "_links": {
    "payouts:payout": {
      "href": "https://try.access.worldpay.com/payouts/{resource}"
    },
    "curies": [
      {
        "name": "payouts",
        "href": "https://try.access.worldpay.com/rels/payouts/{rel}",
        "templated": true
      }
    ]
  }
}