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.

requesterobject(WP.FXT.SinglePayoutApi.Domain.Payout.Shared.Models.RequesterDetails)
countryCodestring[ 2 .. 2 ]required

<a href="/products/access/reference/useful-tables#iso-country-codes">ISO 3166-1 Alpha-2 country code</a> of the payout destination.

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. <a href="/products/access/account-payouts/appendix#invalid-expandablekeyvaluepairs">Invalid Keys</a>

channelstring or null

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.

quoteIdstring or null

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".

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(WP.FXT.SinglePayoutApi.Domain.Payout.V2.Models.BankDetails)
transactionReferencestring[ 6 .. 50 ]required

Unique reference for the payout request provided by you. <a href="/products/access/account-payouts/appendix#special-characters">Special characters</a> are allowed.

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

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).

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(WP.FXT.SinglePayoutApi.Domain.Payout.V2.Models.Party)
narrativestring or null[ 6 .. 50 ]

Reference that may appear on beneficiary statements. <a href="/products/access/account-payouts/appendix#special-characters">Special characters</a> are allowed.

purposeOfPaymentCodestringrequired

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>.

purposeOfPaymentNarrativestring[ 1 .. 35 ]required

Description for purpose of payment. <a href="/products/access/account-payouts/appendix#special-characters">Special characters</a> are allowed.

transactionTypeCodestringrequired

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..

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.

Response:

Successful response example

{
    "ubr": "PZ000EC4",
    "apiRequestReference": "UniqueCustomerReference",
    "instructingTreasuryId": "001948"
}

Successful response schema

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.

See our full schema in our API reference.

Schema validation responses

You can view a list of potential schema validation responses in our appendix.