Appendix

Details on fields found across our Single Payout API, Batch Payouts API and the Payment Item Search. This page particularly focuses on fields which have a preset range of accepted values.

Single Payout API (V2) request values

Field name	Accepted values
`transactionTypeCode`	TT01 (Customer to Customer) TT02 (Business to Business) TT03 (Customer to Business) TT04 (Business to Customer) TT05 (Return) TT08 (Customer to Government) TT06 (Reversal) TT07 (Government to Government) TT09 (Business to Government) TT10 (Tax) TT99 (Other)
`channel`	ACH, WIRE, FP, SEPA, LOCAL, INTERNAL
`beneficiaryAccountTypeCode`	AC01 (Checking) AC02 (Savings) AC03 (Money market) AC04 (Certificate of Deposit) AC05 (Vista) AC99 (Other)
`partyTypeCode`	PT03 (Beneficiary) PT01 (Remitter)
`typeCode`	PD01 (Company) PD02 (Individual) PD023 (Institution) PD04 (Government) PD99 (Other)
`titleCode`	TI01 (Ms) TI02 (Miss) TI03 (Mr) TI04 (Mrs) TI05 (Dr) TI06 (Mx) TI99 (Misc.)
`identityTypeCode`	ID01 (Passport) ID02 (National ID) ID03 (Driver Licence) ID04 (Work Permit) ID05 (Employment Pass) ID06 (Student Pass) ID07 (Permanent Resident Card) ID09 (Company Registration Number) ID10 (Company VAT Number) ID11 (Citizenship Card) ID12 (Tax ID) ID13 (National Insurance) ID99 (Other) ID15 (Legal Identity Card) ID16 (Tax Registration Code)
`addressTypeCode`	AD01 (Home) AD02 (Business) AD03 (PO Box) AD99 (Other)
`residentialStatusCode`	RS01 (Resident) RS02 (Non Resident) RS99 (Other)
`paymentState`	NEW VALID AWAITING_EXECUTION EXECUTED COMPLETED REJECTED REVERSED INVALID FAILED CANCELLED

Payment state values

`paymentState` value	Description	Next action
`AWAITING_EXECUTION` `NEW` `VALID` `REJECTED`	Interim states in the asynchrounous payout request.	Please contact your Relationship Manager if any of those states persist 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` or `REVERSED`
`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).	Final state
`FAILED` `INVALID`	Final states in the asynchrounous payout request.	Please contact your Relationship Manager if any of those states persist as this might suggest integration issues.

Purpose of payment code values (V2)

purposeOfPaymentCode	Description
WPPAYR	Payment of payroll
WPPENS	Pension payment
WPFAMT	Family maintenance
WPUBIL	Payment to common utility provider
WPSTDY	Payment of study/tuition costs
WPTAXS	Payment of taxes
WPGDDS	Purchase sale of goods
WPCHAR	Payment for charity reasons
WPMDCS	Payment for medical care services
WPSAVS	Payment to savings/retirement account
WPPROP	Payment of property purchase
WPSCVE	Purchase sale of services
WPSHAR	Payment of shares
WPIVST	Payment of an investment (interest)
WPTKAG	Tourism (Invoiced Tickets/Travel Agency costs)
WPTOUR	Tourism (other)
WPREMT	Remittances
WPMOVR	Payment of movable property rental
WPSUPP	Supplier payment
WPCAPI	Payment of capital contribution
WPCHRG	Charges/Fees
WPTRAN	Payment for transportation
WPSALR	Payment for salaries
WPDIVD	Dividends
WPLOAN	Loans
WPISER	Payment of insurance services
WPFSER	Payment for financial services
WPCARD	Card payments
WPRENT	Rental payments
WPEXPE	Payment of expenses
WPTRNF	Transfer of funds
WPBONS	Bonus/compensation
WPOTHR	Other

Special characters

Field Name	Accepted Values
List of accepted Special Characters (CallerId)	.-
List of accepted Special Characters for AN fields (including space)	+=%!£$^&*()-_<>@{}[]~#:;',.?/¬`\\\|

Note

Please note that only double backslash is allowed.

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.

Schema validation responses for Get Payouts

All Schema validation responses will have the same format of httpStatusCode, customCode and message, however the responses differs with the error message as per table below.

HTTP code	Custom Code	Example Message	Scenario
**400	SPAB05	'Merchant Treasury Id' must be 6 characters long and not contain I or O	Merchant Treasury ID longer/shorter than expected.
**400	PAB05	'Merchant Treasury Id' must not be empty.	Merchant Treasury ID is empty.
400	SPAB05	'Start Date' is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD.	Start Date or End Date empty. Start Date or End Date is not a valid Gregorian calendar date. Start Date or End Date is before minimum date.
400	SPAB05	'Start Date' is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD.	Difference between Start and End dates is too great (more than 30 days).
400	SPAB05	'Start Date' is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD.**	Start Date must not equal End Date.
400	SPAB05	**"'Page' must be greater than '0'.	Page field is empty, has a value of 0 or a negative value.
400	SPAB05	'Page Size' must be greater than 0 and less than 500	Page Size is empty, is less than or equal to 0 or greater than 500.

Invalid ExpandableKeyValuePairs

The following keys are not allowed in the ExpandableKeyValuePairs:

Key
payoutTransactionType
payoutInstrumentId
payoutInstrumentReference
beneficiaryPartyId
remitterPartyId
debitorPartyReference