APIs
/
Account Payouts
/
Get payouts
/
Retrieve payout details

Account Payouts (2025-01-01)

Send funds to your customer's bank accounts and search for payouts using parameters.

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 authentication with SSL/TLS.

WP-Api-Version Header

  WP-Api-Version: 2025-01-01

We use the WP-Api-Version header to identify which version of our API you are using.

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
Try
https://try.access.worldpay.com/
Live
https://access.worldpay.com/

Single payout

Make a single payout to an account using our Account Payouts endpoint.

Operations

Batch payout

Make up to 500 payouts in one batch using our Account Payouts endpoint.

Operations

Get payouts by Payout Request ID

Search for payout details by using a Payout Request ID.

Operations

Get payouts

Search for payout details by filtering parameters.

Operations

Retrieve payout details

Request

Query
narrativestring[ 0 .. 50 ]

Reference that may appear on beneficiary statements.

transactionReferencestring[ 0 .. 50 ]

Unique reference provided by you.

accountNumberstring[ 0 .. 50 ]

Beneficiary bank account number.

payoutInstrumentIdstring

A unique ID generated by us, holding the beneficiary bank details. You receive this in the response after successfully creating a payout instrument in our Parties API.

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 ]

Your entity reference created as part of on-boarding. Used to route the request in Access Worldpay.

countryCodestring[ 2 .. 2 ]
pageNumberinteger(int32)>= 1required

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

paymentStatestring<= 255
Enum ValueDescription
AWAITING_EXECUTION

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

NEW

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

VALID

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

REJECTED

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

EXECUTED

The API has accepted your payout request and it is now waiting in the queue for submission to our banking partner.

COMPLETED

Our banking partner has accepted the payout request for processing. Final state or REVERSED in a return scenario.

REVERSED

Our validation rules, banking partner or beneficiary bank has rejected the payout request. The funds have subsequently been returned to your account. All rejected payouts include a description with reasoning (if available).

FAILED

Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

INVALID

Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

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 ]
sourceAmountnumber(double)[ 1 .. 19 ]

Source amount. 18 digit precision including 2 decimal places

targetCurrencystring[ 1 .. 35 ]
targetAmountnumber(double)[ 1 .. 35 ]

18 digit precision including 2 decimal places

Headers
WP-CorrelationIdstring

A unique identifier used to trace and correlate a request across systems. Must be a GUID.

Example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
WP-Timestampstring
Default 1749045264
WP-Api-Versionstring

The version of the API you are using.

Default 2025-01-01
Example: 2025-01-01
Idempotency-Keystring[ 1 .. 35 ]

A unique key to identify the request. This is used to prevent duplicate processing of the same request.

Default 1234567890
Example: 1234567890
Acceptstring
Default application/json
Example: application/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
sourceAmountnumber(double)

Source amount. 18 digit precision including 2 decimal places.

targetCurrencystring or null[ 3 .. 3 ]
targetAmountnumber(double)

Target amount.

paymentStatestring or null

State of the payment.

Enum ValueDescription
AWAITING_EXECUTION

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

NEW

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

VALID

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

REJECTED

Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

EXECUTED

The API has accepted your payout request and it is now waiting in the queue for submission to our banking partner.

COMPLETED

Our banking partner has accepted the payout request for processing. Final state or REVERSED in a return scenario.

REVERSED

Our validation rules, banking partner or beneficiary bank has rejected the payout request. The funds have subsequently been returned to your account. All rejected payouts include a description with reasoning (if available).

FAILED

Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

INVALID

Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.

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.

estimatedDeliveryDatestring or null
outcomeReasonstring or null
payoutRequestIdstring[ 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.

narrativestring or null[ 0 .. 50 ]

Reference that may appear on beneficiary statements.

transactionReferencestring or null[ 0 .. 50 ]

Unique reference provided by you.

accountNumberstring or null[ 0 .. 50 ]

Bank Account number.

swiftBicstring or null<= 50

Beneficiary bank account SWIFT/BIC.

countryCodestring or null[ 2 .. 2 ]
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.443Z",
      "payeeName": "John Smith",
      "sourceCurrency": "ARS",
      "sourceAmount": 0,
      "targetCurrency": "ARS",
      "targetAmount": 1.05,
      "paymentState": "EXECUTED",
      "bankName": "Test Bank",
      "bankCode": "10 02 04",
      "iban": "GB29NWBK60161331926819",
      "payoutRequestId": "PO000N65",
      "narrative": "XYZ102025",
      "transactionReference": "XYZ102025",
      "accountNumber": "45533882",
      "swiftBic": "BUKBGB22",
      "entity": "default",
      "countryCode": "AR"
    },
    {
      "paymentId": "c1b659f6-4c30-ee11-b58a-005056b48b8e",
      "paymentDatetime": "2023-08-01T09:22:41.377Z",
      "payeeName": "John Johno Johnson",
      "sourceCurrency": "GBP",
      "sourceAmount": 0,
      "targetCurrency": "GBP",
      "targetAmount": 10,
      "paymentState": "EXECUTED",
      "bankName": "Test Bank",
      "bankCode": "404433",
      "iban": "GB29NWBK60161331926819",
      "payoutRequestId": "PN00004N",
      "narrative": "Ref: 123456",
      "transactionReference": "123456",
      "accountNumber": "12345677",
      "swiftBic": "BUKBGB22",
      "entity": "default",
      "countryCode": "GB"
    }
  ],
  "pagination": {
    "pageNumber": 1,
    "pageSize": 2,
    "pageCount": 5610,
    "totalNumberOfRecords": 11220
  }
}