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.

Field Name	Description	Data Type/Format	Required?	Min-Max Length	Validation Criteria
`requester.instructingTreasuryId`	Unique ID given during the onboarding process. `instructingTreasuryId` will be same as the `entity` if the payment request is being instructed by the ultimate consumer itself.	AN	✅	6	Special characters are restricted.
`requester.entity`	Unique consumer ID given during the onboarding process. It indicates the consumer who instructs the payment. The `instructingTreasuryId` is the same as the entity if the payout request is being instructed by the ultimate consumer itself.	AN	✅	6	The ID supplied is checked to be valid. It must also be authorized by the token provided in the Authorization header. This may be the same as the `instructingTreasuryId` or a sub-merchant of it. Special characters are restricted.
`requester.apiRequestReference`	Unique reference for the request. This field in combination with `instructingTreasuryId` is used by our API for idempotency checks.	String	✅	1-35	Must be unique and 1-35 characters. Special characters are allowed.
`transactionReference`	Customer's unique reference for the payout request.	AN	✅	6-50	Special characters are allowed.
`countryCode`	Country code of the payout destination.	A	✅	2	ISO 3166-1 Alpha-2 code
`sourceCurrency`	Source currency for the payout.	A	✅	3	ISO 4217 Valid currency codes.
`sourceAmount`	Source currency amount (if target amount is not stated, this amount is used).	N	Conditional	1-10	Must be a positive value up to 2 decimal places.
`targetCurrency`	Target currency sent in the payout request (if different to source currency, Foreign Exchange (FX) is applied).	A	✅	3	ISO 4217 Valid currency codes.
`targetAmount`	Target currency amount (if source amount is not specified, this amount is used).	N	Conditional	1-10	Must be a positive value up to 2 decimal places.
`narrative`	Reference that may appear on beneficiary statements.	String	❌	6-50	Special characters are allowed.
`purposeOfPaymentCode`	The code that represents the purpose of the payment. This is mandatory for some payout routes - please check country specific requirements.	A	✅	Value	For the full list of allowed values see the appendix.
`fastPayment`	Flag for a fast payment. If a value is provided, it must always be "Y".	A	✅	Value	The value supplied for the field must be "Y", blank or null. You can exclude the field from the request body.
`purposeOfPaymentNarrative`	Description for purpose of payment.	String	✅	1-35	Special characters are allowed.
`transactionTypeCode`	Type of transaction code (for example 'TT04' that refers to 'Business to Customer'). This is mandatory for some payout routes - please check country specific requirements.	AN	✅	Value	For the full list of allowed values see the appendix.
`channel`	Preferable channel for the payment (for example 'WIRE').	A	❌	Value	For the full list of allowed values see the appendix.
`quoteId`	ID of the FX quote for the payment 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".	String	❌
`scheduleDate`	Scheduled date of the payout request.	date	❌	10	Must be a Gregorian calendar date with ISO format 8601 YYYY-MM-DD.
`expandableKeyValuePairs`	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.	AN	❌		Duplicate key names are not allowed.
`bankDetails.beneficiaryAccountTypeCode`	Type of account code (for example 'AC01' that refers to 'Checking').	AN	❌	Value	For the full list of allowed values see the appendix.
`bankDetails.beneficiaryAccountNumber`	Beneficiary bank account number. You must either provide an account number or an IBAN.	String	Conditional	1-35	Special characters are allowed
`bankDetails.iban`	Beneficiary IBAN. You must either provide an account number or an IBAN.	AN	Conditional	1-34
`bankDetails.bankCode`	Beneficiary account bank code.	String	❌	1-35	Special characters are allowed.
`bankDetails.branchCode`	Beneficiary account branch code.	String	❌	1-35	Special characters are allowed.
`bankDetails.swiftBic`	Beneficiary bank account SWIFT/BIC	AN	❌	8 or 11
`bankDetails.bankName`	Beneficiary bank name	String	✅	1-35	Special characters are allowed.
`bankDetails.address.street`	Street address of the beneficiary's bank.	String	❌	1-35	Special characters are allowed.
`bankDetails.address.additionalAddressLine`	Additional address line of the beneficiary's bank.	String	❌	1-35	Special characters are allowed.
`bankDetails.address.city`	City of the beneficiary's bank.	String	❌	1-35	Special characters are allowed.
`bankDetails.address.state`	State or province of the beneficiary's bank.	String	❌	2-35	Special characters are allowed.
`bankDetails.address.postCodeOrZipCode`	Postcode or ZipCode of the beneficiary's bank.	String	❌	1-20	Special characters are allowed.
`bankDetails.address.countryCode`	Country code of the beneficiary's bank.	A	❌	2	ISO 3166-1 Alpha-2 code.
`parties.partyId`	Id of the party for the payment request. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025.	String	❌	36 (Guid with Hyphens only)	Example: 1E016F5E-9D4A-49E7-B44C-A4C8AAE8290D
`parties.customerPartyId`	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	AN	❌	1-35	Special characters are restricted.
`parties.partyTypeCode`	Party type code (for example 'PT03' that refers to beneficiary)	AN	✅	Value	For the full list of allowed values see the appendix.
`parties.personalDetails.typeCode`	Entity description code of the party (for example 'PD02' that refers to 'Individual').	AN	Conditional	Value	For the full list of allowed values see the appendix. This field is mandatory if the partyTypeCode supplied is that for a beneficiary.
`parties.personalDetails.titleCode`	Title code for the Individual (applicable when party entity type is "Individual"). Must not be provided when type is not “Individual”.	AN	Conditional	Value	For the full list of allowed values see the appendix.
`parties.personalDetails.companyName`	Name of the party if not an individual. Mandatory where party entity type is "Institution", "Government" or "Company". Must not be provided when type is 'Individual'.	String	Conditional	1-140	Special characters are allowed.
`parties.personalDetails.firstName`	First name of the party. Mandatory where party entity type is "Individual".	AN	Conditional	1-50	Special characters are allowed. See formatting rules
`parties.personalDetails.middleName`	Middle name of the party (applicable when party entity type is "Individual").	AN	❌	1-50	Special characters are allowed. See formatting rules
`parties.personalDetails.lastName`	Last name of the party. Mandatory where party entity type is "Individual".	AN	Conditional	1-50	Special characters are allowed. See formatting rules
`parties.personalDetails.dateOfBirth`	Date of birth or date of incorporation of the party.	Date	❌	10-10	Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD.
`parties.personalDetails.email`	E-mail address of the party. This field will be available for use as part of the future enhancements to the Account Payouts API in 2025.	String	❌		A valid e-mail address format.
`parties.personalDetails.telephony.phoneNumber`	Phone number of the party. Mandatory if 'prefix' has been provided.	N	Conditional	1-20	Special characters are restricted.
`parties.personalDetails.telephony.prefix`	Phone dialling country code of the party. Mandatory if 'phoneNumber' has been provided.	N	Conditional	1-3	Special characters are restricted. International country calling code following ITU-T standard. Must be 1-3 digits e.g. "44" or "420"
`parties.personalDetails.identity.identityTypeCode`	Type of identification. Mandatory if 'identity number' is populated.	AN	Conditional	Value	For the full list of allowed values see the appendix.
`parties.personalDetails.identity.identityNumber`	Identification number that is presented in the identification type. Mandatory if "IdentityTypeCode" is populated.	String	Conditional	1-35	Special characters are allowed.
`parties.personalDetails.identity.issuingCountry`	Country of identification type origin. Mandatory if "identityTypeCode"/"identityNumber" is populated.	A	Conditional	2	ISO 3166-1 Alpha-2 code.
`parties.personalDetails.identity.issuingInstitution`	Issuing institution that provided identification type.	AN	❌	1-35	Special characters are allowed. Can't be provided if the conditional fields in the identity section are missing.
`parties.personalDetails.identity.startDate`	Identification type start date.	Date	❌	10	Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD. Cannot be provided if conditional fields in the identity section are missing.
`parties.personalDetails.identity.endDate`	Identification type end date.	Date	❌	10	Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD. Cannot be provided if conditional fields in the identity section are missing.
`parties.address.addressTypeCode`	Type of party address code (for example 'AD02' that refers to 'Business').	AN	❌	Value	For the full list of allowed values see the appendix.
`parties.address.street`	Street address of the party.	String	❌	1-35	Special characters are allowed.
`parties.address.additionalAddressLine`	Additional address line of the party.	String	❌	1-35	Special characters are allowed.
`parties.address.city`	City of the party's address.	String	❌	1-35	Special characters are allowed.
`parties.address.state`	State or province of the party's address.	String	❌	2-35	Special characters are allowed.
`parties.address.postCodeOrZipCode`	Postcode/ZipCode of the party's address.	String	❌	1-20	Special characters are allowed.
`parties.address.countryCode`	Country code (for example 'GB') to be supplied for the party address.	A	❌	2	ISO 3166-1 Alpha-2 code.
`parties.address.residentialStatusCode`	Type of residency code (for example 'RS01' that refers to 'Resident).	AN	❌	Value	For the full list of allowed values see the appendix.

Response:

Successful response example

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

Error response example

{
    "errors": {
        "callerId": [
            "CallerId is mandatory"
        ]
    },
    "httpStatusCode": 400,
    "customCode": "SPAB01",
    "message": "There was an error in the request"
}

Error response codes

General

HTTP code	Custom code	Message	Scenario
202	N/A	N/A	Payment request accepted
200	N/A	N/A	Payment request already submitted and accepted
400	SPAB01	There was an error in the request	Caller ID exceeds 100 characters limit
400	SPAV01	An API version is required, but was not specified.	Version not specified or incorrect / Provided versions are conflicting
401	SPAE11X	Unauthorized request	Unauthorized request
401	SPAU02	Unauthorized	The token has expired
401	SPAU03	Unauthorized	The edge token is not trusted
401	SPAU06A	Unauthorized request	Token validation failed
401	SPAU06A	Unauthorized request	Token has expired
401	SPAU07A	Unauthorized request	Token is empty
401	SPAU10 SPAU07B	Authentication failed	Token validation failed
401	SPAU14	Unauthorized	Unauthorized request
403	SPAF07	Consumer isn't allowed to instruct payouts	Consumer isn't allowed to instruct payout using the entitlements that were provided in the token.
403	SPAF18	Authorisation failed for this domain	Consumer isn't allowed to instruct payout using the entitlements that were provided in the token.
404	SPAN16	Unable to find external consumer data	Consumer with subject-domain combination not found
415	N/A	Unsupported Media Type	Invalid Content Type Value
422	N/A	Quote validation failed	The quote supplied has currencies which does not match those supplied in the token, or has an `intent` which is other than "PAYOUT" or "FORWARD FX".
422	N/A	Quote Expired	The quote supplied has expired.
422	N/A	Contract not Active	The quote supplied cannot yet be used. This will only be the case for quotes with `intent` "FORWARD FX".
500	SPAE12 SPAE11 SPAE11A SPAE11B SPAE11C SPAE11D SPAE11E	Unexpected Issue. Please try again.	Internal Server Error
500	SPAU04	Unexpected issue	Unexpected issue. Please try again.

Note

In the event of 401-500 range HTTP code error response please contact your Implementation Manager.

Schema validation responses

All schema validation responses have the same format of httpStatusCode, customCode and message. Response code and message values differ depending on the validation error.

HTTP code	Custom code	Example message	Scenario
400	SPAB05	The length of 'Company Name' must be 140 characters or fewer. You entered 475 characters.	Property length is incorrect ('or fewer' scenario).
400	SPAB05	'Unique Payout Id' must be between 6 and 50 characters. You entered 2 characters.	Property length is incorrect ('between' scenario).
400	SPAB05	'Issuing Country' is not in the correct format.	Property is not in a correct format.
400	SPAB05	sourceAmount must be a positive value.	Amount is not a positive value.
400	SPAB05	Only one of the fields targetAmount/sourceAmount must be provided.	Both source/target amounts have been provided.
400	SPAB05	The 'Fast Payment' field can only be 'Y' or blank.	Value invalid.
400	SPAB05	`transactionTypeCode` field does not allow free-format text. One of the following values only to be used in Transaction Type: TT01,TT02,TT03,TT04.	Value invalid.
400	SPAB05	One of the following values only to be used in `transactionTypeCode`: PD01, PD02, PD03, PD04, PD99.	Value invalid.
400	SPAB05	'Full Name' is not in the correct format.	Name Regex validation failed.
400	SPAB05	titleCode is not allowed when the typeCode is set to PD01/PD03/PD04.	Property restricted with this type of customer.
400	SPAB05	companyName must not be blank when typeCode is set to PD01.	Property restricted with this type of customer. This applies if `Individual` data is provided but type is set to Company, Government, or Institution
400	SPAB05	companyName is not allowed when the type is set to Individual.	Property restricted with this type of customer. This applies if `Individual` data is provided but typeCode is set to PD01, PD04 or PD02. This applies to parties which are beneficiary & remitter (partyTypeCode PT01 and PT03).
400	SPAB05	DateOfBirth is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD.	Invalid Date format.
400	SPAB05	'Bank name' must not be empty.	Mandatory section/field is missing.
400	SPAB05	phoneNumber must consist of numbers only.	The property can be only Numerical.
400	SPAB05	customerPartyId must be between 1-35 characters length.	Property length is incorrect (between scenario with no indication of provided value).
400	SPAB05	'IBAN' is not in the correct format.	Invalid format of the property.
400	SPAB05	IBAN or 'Account Number' Must be present.	Both IBAN/Account Number missing
400	SPAB05	prefix must be provided if the phoneNumber field is populated.	Condition of linked fields not met.
400	SPAB05	identityTypeCode must be provided if any of the other identity block fields are populated.	Condition of linked fields not met. If any of the identity block fields are given then all mandatory identity BLOCK fields should be provided. If there is no intention of providing identity fields then the whole BLOCK should be removed from the payload.**
400	SPAB05	When expandableKeyValuePairs are provided.	There must not be duplicate key names.
400	SPAB05	When expandableKeyValuePairs are provided but property value is not a JSON object containing key value pairs.	Property value if provided must be a JSON object containing key value pairs.