Access Worldpay
/
Single Payout

Account Payouts (v2)

Authentication Header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.

You must use the Authorization header for any request you send to our Token API, unless you are using client certificate authenticating with SSL/TLS.

Accept Header

  Accept: application/vnd.worldpay.account-payouts-v2.hal+json

We use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our Account APIs.

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
Overview
License WorldPay
Languages
Servers
testing(try)
https://try.access.worldpay.com/
live
https://access.worldpay.com/

Single Payout

Operations

Make a single payout to an account

Request

Headers
WP-CorrelationIdstring
Example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
WP-CallerIdstring

An ID used for logging purposes.

WP-Timestampstring
Default 1734081651
Bodyapplication/json
requesterobject
instructingTreasuryIdstring[ 6 .. 6 ]required

6-digit reference given to you by your Implementation Manager during the onboarding process. instructingTreasuryId is the same as the entity if the payout request is being instructed by the ultimate consumer itself. Special characters are restricted.

entitystring[ 6 .. 6 ]required

6-digit reference given to you by your Implementation Manager during the onboarding process. entity is the same as the instructingTreasuryId if the payout request is being instructed by the ultimate consumer itself. \tThe ID supplied is checked to be valid. It must also be authorized by the token provided in the Authorization header. Special characters are restricted.

apiRequestReferencestring[ 1 .. 35 ]required

Unique reference for the request supplied by you. This field in combination with instructingTreasuryId is used by our API for idempotency checks. Must be unique. Special characters are allowed.

notificationUrlstring or null

Currently not in use.

countryCodestring[ 2 .. 2 ]required
expandableKeyValuePairsobject or null

JSON object of key-value pairs used to supply additional data. The keys and values that you might need to process an account payout to a specific destination, are communicated during the onboarding process. Duplicate key names are not allowed. Invalid Keys

channelstring or null

Preferable channel for the payment. For the full list of allowed values see the appendix. This field is currently not used.

quoteIdstring or null

ID of the FX quote for the request. This must be a valid, active quote which is for the same source and target currencies as the payout request. It must have valid intent of "FORWARD FX" or "PAYOUT".

scheduleDatestring or null[ 10 .. 10 ]

Scheduled date of the payout request. Must be a Gregorian calendar date with ISO format 8601 YYYY-MM-DD. This field is currently not used.

bankDetailsobject
ibanstring or null[ 1 .. 34 ]

Beneficiary IBAN. You must either provide an account number or an IBAN.

branchCodestring or null[ 1 .. 35 ]

Beneficiary account branch code. Beneficiary IBAN. You must either provide an account number or an IBAN. Special characters are allowed.

bankCodestring or null[ 1 .. 35 ]
swiftBicstring or null[ 8 .. 11 ]

Beneficiary bank account SWIFT/BIC. Beneficiary IBAN. You must either provide an account number or an IBAN. Special characters are allowed.

bankNamestring[ 1 .. 35 ]required
beneficiaryAccountTypeCodestring or null

Type of account code. See the appendix for full details.

Enum"AC01""AC02""AC03""AC04""AC05""AC99"
beneficiaryAccountNumberstring or null[ 1 .. 35 ]

Beneficiary bank account number. You must either provide an account number or an IBAN. Special characters are allowed.

addressobject
transactionReferencestring[ 6 .. 50 ]required
sourceCurrencystring[ 3 .. 3 ]required

Source currency code for the payout (if different to targetCurrency, Foreign Exchange (FX) is applied).

sourceAmountnumber or null(double)[ 1 .. 10 ]

Source amount (if targetAmount is not stated, this amount is used). Must be a positive value up to 2 decimal places. FX rate of the payout is applied by us, therefore, only one of the sourceAmount or targetAmount is required in your request.

targetCurrencystring[ 3 .. 3 ]required
targetAmountnumber or null(double)[ 1 .. 10 ]

Target amount (if sourceAmount is not specified, this amount is used). Must be a positive value up to 2 decimal places. FX rate of the payout is applied by us, therefore, only one of the sourceAmount or targetAmount is required in your request.

partiesArray of objects or null
partyIdstring or null[ 36 .. 36 ]

Id of the party for the payment request. This field is currently not used.

Example: "1E016F5E-9D4A-49E7-B44C-A4C8AAE8290D"
partyTypeCodestringrequired

Party type code. See further details in the appendix.

Enum"PT01""PT03"
personalDetailsobject
addressobject
customerPartyIdstring or null[ 1 .. 35 ]

The ID of the remitter: Domain ID, Account Number, Tax ID, BIC, Internal Customer ID or any other numerical or alphanumerical unique identifier of the customer where the payment request has originated. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025. Special characters are restricted. For the full list of allowed values see the appendix.

narrativestring or null[ 6 .. 50 ]
purposeOfPaymentCodestringrequired

The code that represents the purpose of the payment. This is mandatory for some payout routes - please check country specific requirements. For the full list of allowed values see the appendix.

purposeOfPaymentNarrativestring[ 1 .. 35 ]required
transactionTypeCodestringrequired

Type of transaction code. This is mandatory for some payout routes - please check country specific requirements. See the appendix for full details..

Enum"TT01""TT02""TT03""TT04""TT05""TT08""TT06""TT07""TT09""TT10"
fastPaymentstring

Flag for a fast payment. If supplied the value for the field must be Y. You can exclude the field from the request body.

application/json
{
  "requester": {
    "instructingTreasuryId": "000055",
    "entity": "000055",
    "apiRequestReference": "TestReference123",
    "notificationUrl": null
  },
  "countryCode": "GB",
  "expandableKeyValuePairs": {
    "remitterSourceOfIncome": "salary",
    "beneficiaryNationality": "British"
  },
  "quoteId": "",
  "bankDetails": {
    "iban": "GB29NWBK60161331926819",
    "branchCode": "300",
    "bankCode": "404433",
    "swiftBic": "BUKBGB22",
    "bankName": "Bank of Sale",
    "beneficiaryAccountTypeCode": "AC01",
    "beneficiaryAccountNumber": "12345677",
    "address": {
      "city": "Sale",
      "state": "Cheshire",
      "countryCode": "GB",
      "street": "3 Rock Lane",
      "additionalAddressLine": "An Area",
      "postcodeOrZipCode": "M33 7ZA"
    }
  },
  "transactionReference": "123456",
  "sourceCurrency": "GBP",
  "sourceAmount": 1,
  "targetCurrency": "GBP",
  "targetAmount": 10,
  "parties": [
    {
      "partyTypeCode": "PT03",
      "personalDetails": {
        "companyName": null,
        "firstName": "John",
        "middleName": "Johno",
        "lastName": "Johnson",
        "dateOfBirth": "1993-12-31",
        "email": "john@domain.com",
        "typeCode": "PD02",
        "titleCode": "TI01",
        "telephony": [
          { … }
        ],
        "identity": [
          { … }
        ]
      },
      "address": {
        "city": "Some City",
        "state": "Some State",
        "countryCode": "GB",
        "street": "1 Some Street",
        "additionalAddressLine": "Some Neighborhood",
        "postcodeOrZipCode": "S14 T4R",
        "addressTypeCode": "AD01",
        "residentialStatusCode": "RS01"
      },
      "customerPartyId": "customer123"
    },
    {
      "partyTypeCode": "PT01",
      "personalDetails": {
        "companyName": "testCompanyInc",
        "firstName": null,
        "middleName": null,
        "lastName": null,
        "dateOfBirth": "1993-12-31",
        "email": "john@domain.com",
        "typeCode": "PD01",
        "titleCode": null,
        "telephony": [
          { … }
        ],
        "identity": [
          { … }
        ]
      },
      "address": {
        "city": "Some City",
        "state": "Some State",
        "countryCode": "GB",
        "street": "1 Some Street",
        "additionalAddressLine": "Some Neighborhood",
        "postcodeOrZipCode": "S14 T4R",
        "addressTypeCode": "AD01",
        "residentialStatusCode": "RS01"
      },
      "customerPartyId": ""
    }
  ],
  "narrative": "Ref: 123456",
  "purposeOfPaymentCode": "WPPAYR",
  "purposeOfPaymentNarrative": "Salary payment",
  "transactionTypeCode": "TT04",
  "fastPayment": "Y"
}

Responses

OK response if a request with the same credentials has already been submitted successfully

Bodyapplication/json
ubrstring

Unique payout request ID associated with a payout submitted through our Account Payouts API. PN/PZ/PO prefix plus 6 characters, e.g. PZ000N65. Five numbers, a letter and finally two/four further numbers

apiRequestReferencestring

Unique reference from the request.

instructingTreasuryIdstring

Unique ID given during the onboarding process.

Response
application/json
{
  "ubr": "PZ000EC4",
  "apiRequestReference": "UniqueCustomerReference",
  "instructingTreasuryId": "001948"
}

Batch Payout

Operations

Get Payouts by Unique Payout Request ID (ubr)

Operations

Get Payouts

Operations