Skip to content
APIs/Card Payouts/
Disburses funds to the pa...

Payouts (3)

Authentication

Set your headers

  Authorization: {your_credentials}
  Content-Type: application/vnd.worldpay.payouts-v3+json
  Accept: application/vnd.worldpay.payouts-v3+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

original resource

No request payload

Responses

Payout resource.

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

outcome of payouts request

receivedAtstringrequired

A timestamp of receivedAt

Response
application/vnd.worldpay.payouts-v3+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 the payout details of 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-v3+json
outcomestringrequired

outcome of payouts query request

receivedAtstringrequired

A timestamp of receivedAt

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

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

{
  "outcome": "requestReceived",
  "receivedAt": "2018-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
      }
    ]
  }
}

Disburses funds to the payout instrument specified

Request

Disburse funds to a payout instrument.

Security
BasicAuth
Bodyapplication/vnd.worldpay.payouts-v3+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.

payoutInstrumentanyrequired

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.

entitystringrequired

This is mandatory for authentication and queries. Contact your Implementation Manager for more information.

transactionReferencestringrequired

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

application/vnd.worldpay.payouts-v3+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

Funds have been disbursed or queued for disbursal successfully.

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

outcome of payouts request

receivedAtstringrequired

A timestamp of receivedAt

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

Successful Basic Disbursement

{
  "outcome": "requestReceived",
  "receivedAt": "2018-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
      }
    ]
  }
}

Disburses funds to the payout instrument specified

Request

Disburse funds to a payout instrument using fastAccess.

Security
BasicAuth
Bodyapplication/vnd.worldpay.payouts-v3+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.

payoutInstrumentanyrequired

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.

entitystringrequired

This is mandatory for authentication and queries. Contact your Implementation Manager for more information.

transactionReferencestringrequired

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

application/vnd.worldpay.payouts-v3+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": 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

Funds have been disbursed or queued for disbursal successfully.

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

outcome of payouts request

receivedAtstringrequired

A timestamp of receivedAt

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

Successful issuing of a disbursal request

{
  "outcome": "pending",
  "receivedAt": "2018-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
      }
    ]
  }
}