Last Updated: 14 May 2025 | Change Log
Account Payouts
Execute a single Account Payout to a nominated beneficiary bank account.
Authorization: {your_credentials}
Content-Type: application/vnd.worldpay.account-payouts-v2+json
Standard payout
Payout request
POST
https://try.access.worldpay.com/payouts/accounts/single
Payout request body
{
"requester": {
"instructingTreasuryId": "000055",
"entity": "000055",
"apiRequestReference": "TestReference123"
},
"transactionReference": "123456",
"countryCode": "GB",
"sourceCurrency": "GBP",
"sourceAmount": 0,
"targetCurrency": "GBP",
"targetAmount": 10,
"narrative": "Ref: 123456",
"purposeOfPaymentCode": "WPPAYR",
"fastPayment": "Y",
"purposeOfPaymentNarrative": "Salary payment",
"transactionTypeCode": "TT04",
"channel": "WIRE",
"quoteId": "",
"scheduleDate": "2022-12-31",
"expandableKeyValuePairs": {
"RemitterSourceOfIncome": "salary",
"BeneficiaryNationality": "British"
},
"bankDetails": {
"beneficiaryAccountTypeCode": "AC01",
"beneficiaryAccountNumber": "12345677",
"iban": "GB29NWBK60161331926819",
"branchCode": "300",
"bankCode": "404433",
"swiftBic": "BUKBGB22",
"bankName": "Bank of Sale",
"address": {
"street": "3 Rock Lane",
"additionalAddressLine": "An Area",
"city": "Sale",
"state": "Cheshire",
"postCodeOrZipCode": "P55 T1B",
"countryCode": "GB"
}
},
"parties": [
{
"partyId": "",
"customerPartyId": "customer123",
"partyTypeCode": "PT03",
"personalDetails": {
"typeCode": "PD02",
"titleCode": "TI01",
"firstName": "John",
"middleName": "Johno",
"lastName": "Johnson",
"dateOfBirth": "1993-12-31",
"email": "john@domain.com",
"telephony": [
{
"phoneNumber": "01375841159",
"prefix": "44"
}
],
"identity": [
{
"identityTypeCode": "ID01",
"identityNumber": "123456789",
"issuingInstitution": "IPS",
"issuingCountry": "GB",
"startDate": "2013-05-22",
"endDate": "2014-05-21"
}
]
},
"address": {
"street": "1 Some Street",
"additionalAddressLine": "Some Neighborhood",
"city": "Some City",
"state": "Some State",
"postCodeOrZipCode": "S14 T4R",
"countryCode": "GB",
"addressTypeCode": "AD01",
"residentialStatusCode": "RS01"
}
},
{
"partyId": "",
"customerPartyId": "",
"partyTypeCode": "PT01",
"personalDetails": {
"typeCode": "PD01",
"companyName": "testCompanyInc",
"dateOfBirth": "1993-12-31",
"email": "john@domain.com",
"telephony": [
{
"phoneNumber": "01375841159",
"prefix": "44"
}
],
"identity": [
{
"identityTypeCode": "ID01",
"identityNumber": "123456789",
"issuingInstitution": "IPS",
"issuingCountry": "GB",
"startDate": "2013-05-22",
"endDate": "2014-05-21"
}
]
},
"address": {
"street": "1 Some Street",
"additionalAddressLine": "Some Neighborhood",
"city": "Some City",
"state": "Some State",
"postCodeOrZipCode": "S14 T4R",
"countryCode": "GB",
"addressTypeCode": "AD01",
"residentialStatusCode": "RS01"
}
}
]
}
Parameters
Permitted special characters for appropriate fields, as well as preset values for specific fields are listed in the Appendix.
<a href="/products/access/reference/useful-tables#iso-country-codes">ISO 3166-1 Alpha-2 country code</a> 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. <a href="/products/access/account-payouts/appendix#invalid-expandablekeyvaluepairs">Invalid Keys</a>
Preferable channel for the payment. For the full list of allowed values see the <a href="/products/access/account-payouts/appendix">appendix</a>. This field is currently not used.
ID of the <a href="/products/access/fx">FX quote</a> 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.
Unique reference for the payout request provided by you. <a href="/products/access/account-payouts/appendix#special-characters">Special characters</a> 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 <a href="/products/access/reference/useful-tables#currency-codes">ISO 4217 alpha-3 currency codes</a> 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.
Reference that may appear on beneficiary statements. <a href="/products/access/account-payouts/appendix#special-characters">Special characters</a> are allowed.
The code that represents the purpose of the payment. This is mandatory for some payout routes - please check <a href="/products/access/account-payouts/v2/coverage">country specific requirements</a>. For the full list of allowed values see the <a href="/products/access/account-payouts/appendix#purpose-of-payment-code-values-v2">appendix</a>.
Description for purpose of payment. <a href="/products/access/account-payouts/appendix#special-characters">Special characters</a> are allowed.
Type of transaction code. This is mandatory for some payout routes - please check country specific requirements. See the <a href="/products/access/account-payouts/appendix">appendix</a> for full details..
Flag for a fast payment. If supplied the value for the field must be Y
. You can exclude the field from the request body.
Response:
Successful response example
{
"ubr": "PZ000EC4",
"apiRequestReference": "UniqueCustomerReference",
"instructingTreasuryId": "001948"
}
Successful response schema
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
Unique reference from the request.
Unique ID given during the onboarding process.
See our full schema in our API reference.
Schema validation responses
You can view a list of potential schema validation responses in our appendix.