APIs
/
Account Payouts
/
Get Payouts
/
Retrieve payment details based on the provided information

Account Payouts (2)

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 Account Payouts API, unless you are using client certificate authenticating with SSL/TLS.

GET Requests and 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 GET request you send to our Account Payouts APIs.

POST Requests and Content-Type Header

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

We use the Content-Type header to identify which version of our API you are using. You must use the Content-Type header for any POST request you send to our Account Payout API.

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

Batch Payout

Operations

Get Payouts by Unique Payout Request ID (ubr)

Operations

Get Payouts

Operations

Retrieve payment details based on the provided information

Request

Security
BasicAuth
Query
narrativestring[ 0 .. 50 ]

Reference provided by you.

transactionReferencestring[ 0 .. 50 ]

Unique reference provided by you.

accountNumberstring[ 0 .. 50 ]

Beneficiary bank account number. (IBAN is currently not supported).

payoutInstrumentIdstring

An ID generated by us, holding the beneficiary bank details.

payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details.

pageSizeinteger(int32)[ 1 .. 499 ]required

Positive whole number indicating the number of payouts to return in each page.

entitystring[ 6 .. 6 ]

6-digit reference given to you by your Implementation Manager during the onboarding process.

countryCodestring[ 2 .. 2 ]

ISO 3166-1 Alpha-2 country code of the payout destination.

pageNumberinteger(int32)>= 1required

Positive whole number indicating which page of the statement to return.

paymentStatestring<= 255
startDatestring[ 10 .. 10 ]

Posting start date for the payout. This is the start of a 'window' of time which must satisfy the constraints described. This should be before the current date and before the end date, as well as being after the minimum date (0001-01-01). The difference between start and end dates should not exceed 30 days. Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD.

endDatestring[ 10 .. 10 ]

Posting end date for the payout. This is the end of a 'window' of time which must satisfy the constraints described. This should be before the current date, as well as after the start date and the minimum date (0001-01-01).

payeeNamestring[ 0 .. 140 ]

Complete payee name for the payout. This will be one of the following (depending on the beneficiary type): fullName - concatenated value from title + firstName + middleName + lastName; companyName

sourceCurrencystring[ 3 .. 3 ]

Source ISO 4217 alpha-3 currency codes for the payout.

sourceAmountnumber(double)[ 1 .. 19 ]

Source amount. 18 digit precision including 2 decimal places

targetCurrencystring[ 1 .. 35 ]

Target ISO 4217 alpha-3 currency codes for the payout.

targetAmountnumber(double)[ 1 .. 35 ]

18 digit precision including 2 decimal places

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

An ID used for logging purposes.

WP-Timestampstring
Default 1743087806
Acceptstring
Default application/vnd.worldpay.wts.payout-v2+json
Example: application/vnd.worldpay.wts.payout-v2+json
No request payload

Responses

OK

Bodyapplication/json
itemsArray of objects or null
paymentIdstring or null

Unique identifier associated with the payment. GUID.

paymentDatetimestring or null(date-time)

Date and time of the payment submission. DateTime ISO 8601.

payeeNamestring or null<= 140

Complete payee name for the payout. This will be one of (depending on the beneficiary type): fullName- concatenated value from title + firstName + middleName + lastName companyName.

sourceCurrencystring or null<= 3

ISO 4217 alpha-3 currency code for the remitter account.

sourceAmountnumber(double)

Source amount. 18 digit precision including 2 decimal places.

targetCurrencystring or null[ 3 .. 3 ]

Target ISO 4217 alpha-3 currency codes for the payout.

targetAmountnumber(double)

Target amount.

paymentStatestring or null

State of the payment. See appendix for possible states.

bankNamestring or null

Name of the payee (beneficiary) bank which the payout is being made to.

bankCodestring or null

Beneficiary bank account bank code.

ibanstring or null

Beneficiary IBAN. You must either provide the beneficiary's IBAN or account number.

ubrstring[ 8 .. 10 ]AlphaNumericRegex = ^[0-9a-zA-Z]+$required

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.

narrativestring or null[ 0 .. 50 ]

Reference provided by the remitter of the payment (unique for a remitter). In Account Payouts API - merchantNarrative.

transactionReferencestring or null[ 0 .. 50 ]

Unique reference provided by you.

beneficiaryAccountNumberstring or null[ 0 .. 50 ]

Beneficiary bank account number. You must either provide beneficiary's account number or IBAN. Special characters are allowed.

swiftBicstring or null<= 50

Beneficiary bank account SWIFT/BIC.

entitystring[ 6 .. 6 ]required

6-digit reference given to you by your Implementation Manager during the onboarding process.

countryCodestring or null[ 2 .. 2 ]

ISO 3166-1 Alpha-2 country code of the payout destination.

payoutInstrumentIdstring or null

An ID generated by us, holding the beneficiary bank details.You have received this in the response of your "payout instrument creation" call using the Parties API..

payoutInstrumentReferencestring or null

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. When not sending the payoutInstrumentReference you can use the payoutInstrumentId instead. When sending both, ensure they relate to the same payoutInstrument.

paginationobject
pageNumberinteger(int32)required

Positive whole number indicating which page of the statement to return. Greater than 0.

pageSizeinteger(int32)[ 1 .. 499 ]required

Number of items listed per page.

pageCountinteger(int32)

Total number of pages.

totalNumberOfRecordsinteger(int32)

Total number of items listed across all pages.

Response
application/json
{
  "items": [
    {
      "paymentId": "51a448e5-4430-ee11-b58a-005056b48b8e",
      "paymentDatetime": "2023-08-01T08:24:44.443",
      "payeeName": "John Smith",
      "sourceCurrency": "ARS",
      "sourceAmount": 0,
      "targetCurrency": "ARS",
      "targetAmount": 1.05,
      "paymentState": "EXECUTED",
      "bankName": "Test Bank",
      "bankCode": "10 02 04",
      "iban": "GB29NWBK60161331926819",
      "ubr": "PO000N65",
      "narrative": "XYZ102025",
      "transactionReference": "XYZ102025",
      "beneficiaryAccountNumber": "45533882",
      "swiftBic": "BUKBGB22",
      "entity": "000055",
      "countryCode": "AR"
    },
    {
      "paymentId": "c1b659f6-4c30-ee11-b58a-005056b48b8e",
      "paymentDatetime": "2023-08-01T09:22:41.377",
      "payeeName": "John Johno Johnson",
      "sourceCurrency": "GBP",
      "sourceAmount": 0,
      "targetCurrency": "GBP",
      "targetAmount": 10,
      "paymentState": "EXECUTED",
      "bankName": "Test Bank",
      "bankCode": "404433",
      "iban": "GB29NWBK60161331926819",
      "ubr": "PN00004N",
      "narrative": "Ref: 123456",
      "transactionReference": "123456",
      "beneficiaryAccountNumber": "12345677",
      "swiftBic": "BUKBGB22",
      "entity": "000055",
      "countryCode": "GB"
    }
  ],
  "pagination": {
    "pageNumber": 1,
    "pageSize": 2,
    "pageCount": 5610,
    "totalNumberOfRecords": 11220
  }
}