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.
https://try.access.worldpay.com/
https://access.worldpay.com/
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.
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. The ID supplied is checked to be valid. It must also be authorized by the token provided in the Authorization header. Special characters are restricted.
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.
ISO 3166-1 Alpha-2 country code of the payout destination.
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
Preferable channel for the payment. For the full list of allowed values see the appendix. This field is currently not used.
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".
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.
Beneficiary IBAN. You must either provide an IBAN or Beneficiary Account Number.
Beneficiary account branch code. Special characters are allowed.
Beneficiary account bank code. Special characters are allowed.
Beneficiary bank name. Special characters are allowed.
Type of account code. See the appendix for full details.
Beneficiary bank account number. You must either provide a Beneficiary Account Number or IBAN. Special characters are allowed.
Unique reference for the payout request provided by you. Special characters are allowed.
Source currency code for the payout (if different to targetCurrency
, Foreign Exchange (FX) is applied).
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.
Target ISO 4217 alpha-3 currency codes for the payout (if different to sourceCurrency
, Foreign Exchange (FX) is applied).
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.
Id of the party for the payment request. This field is currently not used.
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.
Reference that may appear on beneficiary statements. Special characters are allowed.
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.
Description for purpose of payment. Special characters are allowed.
Type of transaction code. This is mandatory for some payout routes - please check country specific requirements. See the appendix for full details..
https://try.access.worldpay.com/payouts/accounts/single
https://access.worldpay.com/payouts/accounts/single
{ "requester": { "instructingTreasuryId": "000055", "entity": "000055", "apiRequestReference": "mustBeUnique", "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": 0, "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" }
OK response if a request with the same credentials has already been submitted successfully
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
{ "ubr": "PZ000EC4", "apiRequestReference": "UniqueCustomerReference", "instructingTreasuryId": "001948" }