Creating payees: the fields you need per currency

The Payees reference lists every field. This guide is the short version: what you actually have to send, per currency, and the mistakes that cause a 400.

Payees belong to an account

A payee is created under an account and inherits its currency. A supplier you pay in EUR and GBP is two payees, one on each account. Plan your mapping table accordingly: your supplier ID maps to one xpid per currency.

The minimum per currency

Always required: name, reference, purpose, purposeCategory, addressLine1, townCity, postCode, countryCode. Then the bank details depend on the account currency:

For SWIFT payments that need an intermediary bank, send the full intermediary set together: name, BIC, ABA for USD, and address. Partial intermediary details fail validation.

Rules that catch people out

• reference is 6 to 18 characters on GBP payees and 6 to 140 elsewhere. A five-character reference is rejected.
• name is 4 to 140 characters, letters, digits and basic punctuation. Strip anything else before sending.
• countryCode is exactly two uppercase letters.
• postCode is 4 to 10 alphanumeric characters. Remove spaces if your data has them and the value is too long.
• purpose and purposeCategory are enumerated. Common pairs: SupplierPayment / SupplierPayment, InvoicePayment / SupplierPayment, IntraCompanyPayment / IntraCompanyPayment. The full lists are in the API reference.

Use upsert

POST /account/{xaid}/payee creates when xpid is omitted and updates when it is present. It is the right endpoint for any integration that syncs suppliers from another system, because a retry with the xpid you stored is an update, not a duplicate.

{
  "name": "Acme Content Ltd",
  "reference": "ACME-INV",
  "purpose": "SupplierPayment",
  "purposeCategory": "SupplierPayment",
  "isBusiness": true,
  "addressLine1": "12 Triq il-Kbira",
  "townCity": "Valletta",
  "postCode": "VLT1100",
  "countryCode": "MT",
  "iban": "MT84MALT011000012345MTLCAST001S",
  "bic": "MALTMTMT"
}

Store the returned xpid against your supplier record and currency.

Approvals and name checks

If the account has an approval policy on payee creation, the payee may not be usable until someone approves it in the web app. Name verification (Confirmation of Payee on GBP, Verification of Payee on EUR) runs when payments are created and approved, so a payee that saved successfully can still show a Close Match or No Match at payment time. See Verification of Payee for what each result means.