🧾 Payees

Payees API Documentation

Required Permissions

Endpoint	Permission Required
GET endpoints	read:payees
POST (create)	create:payee
PUT (update)	update:payee
POST (upsert)	create:payee AND update:payee

🔹 GET /payees — Query All Payees

Returns a paginated list of all payees belonging to the authenticated user.

Query Parameters:

Parameter	Type	Required	Description
page	number	❌	The page number to retrieve (default: 0).
limit	number	❌	Number of results per page (default: 10, max: 100).

🔹 GET /payee/{xpid} — Query Single Payee

Retrieve details of a single payee using its unique xpid (xace payee id).

Path Parameter:

Parameter	Type	Required	Description
xpid	string	✅	The xace payee id.

🔹 GET /account/{xaid}/payees — Query Payees of an Account

Returns a paginated list of payees associated with a specific account.

Path Parameter:

Parameter	Type	Required	Description
xaid	string	✅	The xace account id.

Query Parameters:

Parameter	Type	Required	Description
page	number	❌	The page number to retrieve (default: 0).
limit	number	❌	Number of results per page (default: 10, max: 100).

🔹 POST /account/{xaid}/payees — Create Payee

Creates a new payee belonging to a specific account.

Path Parameter:

Parameter	Type	Required	Description
xaid	string	✅	The xace account id.

Body Parameters:

Parameter	Type	Required	Description
name	string	✅	Payee name (4-140 characters, alphanumeric and basic punctuation).
displayName	string	❌	Display name for the payee (4-140 characters).
reference	string	✅	Payment reference (6-18 chars for GBP, 6-140 for others).
purpose	string	✅	Payment purpose code.
purposeCategory	string	✅	Payment purpose category.
isBusiness	boolean	❌	Set true if payee is a business, false for individual.
email	string	❌	Payee email address (valid email format).
mobilePhone	string	❌	Payee mobile phone number (7-15 digits, can include +, spaces, dashes).
website	string	❌	Payee website URL.
addressLine1	string	✅	Payee address line 1 (1-50 characters).
addressLine2	string	❌	Payee address line 2 (3-35 characters).
townCity	string	✅	Town or city (1-35 characters).
countyState	string	❌	County or state (4-35 characters).
postCode	string	✅	Postal code (4-10 alphanumeric characters).
countryCode	string	✅	ISO country code, 2 letters (e.g., GB, US, DE).
sortCode	string	⚠️	UK sort code (6 digits). Required for GBP payments.
accountNumber	string	⚠️	Bank account number (4-17 digits). Required for GBP or when IBAN not provided.
iban	string	⚠️	International Bank Account Number (15-34 chars). Required for EUR/international.
bic	string	⚠️	Bank Identifier Code (8-11 chars). Required when IBAN is provided.
aba	string	⚠️	ABA routing number (9 digits). Required for USD payments.
bankCountryCode	string	❌	Bank country code (2 letters, e.g., GB, US).
institutionNumber	string	⚠️	Institution number (3 digits). Required for CAD payments.
transitNumber	string	⚠️	Transit number (5 digits). Required for CAD payments.
intermediaryName	string	❌	Intermediary bank name (2-140 characters).
intermediaryBic	string	❌	Intermediary bank BIC (8-11 chars).
intermediaryAba	string	❌	Intermediary bank ABA routing number (9 digits).
intermediaryAddress1	string	❌	Intermediary bank address line 1 (max 50 chars).
intermediaryAddress2	string	❌	Intermediary bank address line 2 (max 50 chars).
intermediaryTownCity	string	❌	Intermediary bank town/city (max 35 chars).
intermediaryCountyState	string	❌	Intermediary bank county/state (max 35 chars).
intermediaryPostcode	string	❌	Intermediary bank postal code (max 10 chars).
intermediaryCountryCode	string	❌	Intermediary bank country code.

⚠️ Note: Account details requirements vary by currency:

GBP: sortCode + accountNumber
EUR/International: iban + bic
USD: accountNumber + aba
CAD: institutionNumber + transitNumber + accountNumber

Note: The xid, xaid, and currency are automatically set from the authenticated user and account.

🔹 PUT /account/{xaid}/payees/{xpid} — Update Payee

Updates an existing payee belonging to a specific account.

Path Parameters:

Parameter	Type	Required	Description
xaid	string	✅	The xace account id.
xpid	string	✅	The xace payee id to update.

Body Parameters:

Parameter	Type	Required	Description
name	string	❌	Payee name (4-140 characters).
displayName	string	❌	Display name for the payee (4-140 characters).
reference	string	❌	Payment reference (6-18 chars for GBP, 6-140 for others).
purpose	string	❌	Payment purpose code.
purposeCategory	string	❌	Payment purpose category.
isBusiness	boolean	❌	Set true if payee is a business, false for individual.
email	string	❌	Payee email address.
mobilePhone	string	❌	Payee mobile phone number.
website	string	❌	Payee website URL.
addressLine1	string	❌	Payee address line 1 (1-50 characters).
addressLine2	string	❌	Payee address line 2 (3-35 characters).
townCity	string	❌	Town or city (1-35 characters).
countyState	string	❌	County or state (4-35 characters).
postCode	string	❌	Postal code (4-10 alphanumeric characters).
countryCode	string	❌	ISO country code (2 letters).
sortCode	string	❌	UK sort code (6 digits).
accountNumber	string	❌	Bank account number (4-17 digits).
iban	string	❌	International Bank Account Number (15-34 chars).
bic	string	❌	Bank Identifier Code (8-11 chars).
aba	string	❌	ABA routing number (9 digits).
bankCountryCode	string	❌	Bank country code (2 letters).
institutionNumber	string	❌	Institution number (3 digits).
transitNumber	string	❌	Transit number (5 digits).
intermediaryName	string	❌	Intermediary bank name.
intermediaryBic	string	❌	Intermediary bank BIC.
intermediaryAba	string	❌	Intermediary bank ABA routing number.
intermediaryAddress1	string	❌	Intermediary bank address line 1.
intermediaryAddress2	string	❌	Intermediary bank address line 2.
intermediaryTownCity	string	❌	Intermediary bank town/city.
intermediaryCountyState	string	❌	Intermediary bank county/state.
intermediaryPostcode	string	❌	Intermediary bank postal code.
intermediaryCountryCode	string	❌	Intermediary bank country code.

Note: Bank account details (iban, sortCode, accountNumber, etc.) can be updated but will be re-validated before saving.

🔹 POST /account/{xaid}/payee — Upsert Payee (Unified Endpoint)

Creates a new payee or updates an existing one. This is a unified endpoint that determines the operation based on whether xpid is provided in the request body.

If xpid is omitted → Creates a new payee
If xpid is provided → Updates the existing payee

Required Permissions: Both create:payee AND update:payee

Path Parameter:

Parameter	Type	Required	Description
xaid	string	✅	The xace account id.

Body Parameters:

Parameter	Type	Required	Description
xpid	string	❌	The xace payee id. If provided, updates existing payee. If omitted, creates new payee.
name	string	✅*	Payee name (required for create, optional for update).
displayName	string	❌	Display name for the payee.
reference	string	✅*	Payment reference (required for create).
purpose	string	✅*	Payment purpose code (required for create).
purposeCategory	string	✅*	Payment purpose category (required for create).
isBusiness	boolean	❌	Business or individual flag.
email	string	❌	Payee email address.
mobilePhone	string	❌	Payee mobile phone number.
website	string	❌	Payee website URL.
addressLine1	string	✅*	Payee address line 1 (required for create).
addressLine2	string	❌	Payee address line 2.
townCity	string	✅*	Town or city (required for create).
countyState	string	❌	County or state.
postCode	string	✅*	Postal code (required for create).
countryCode	string	✅*	ISO country code (required for create).
sortCode	string	⚠️	UK sort code. Required for GBP.
accountNumber	string	⚠️	Bank account number.
iban	string	⚠️	IBAN. Required for EUR/international.
bic	string	⚠️	BIC. Required when IBAN provided.
aba	string	⚠️	ABA routing number. Required for USD.
bankCountryCode	string	❌	Bank country code.
institutionNumber	string	⚠️	Institution number. Required for CAD.
transitNumber	string	⚠️	Transit number. Required for CAD.
intermediaryName	string	❌	Intermediary bank name.
intermediaryBic	string	❌	Intermediary bank BIC.
intermediaryAba	string	❌	Intermediary bank ABA.
intermediaryAddress1	string	❌	Intermediary bank address line 1.
intermediaryAddress2	string	❌	Intermediary bank address line 2.
intermediaryTownCity	string	❌	Intermediary bank town/city.
intermediaryCountyState	string	❌	Intermediary bank county/state.
intermediaryPostcode	string	❌	Intermediary bank postal code.
intermediaryCountryCode	string	❌	Intermediary bank country code.

✅* = Required when creating (xpid not provided), optional when updating

Response Object

All payee endpoints return a payee object with the following fields:

Field	Type	Description
xpid	string	The xace payee id.
xaid	string	The xace account id this payee belongs to.
currency	string	Currency code (inherited from account).
name	string	Payee name.
displayName	string	Display name for the payee.
reference	string	Payment reference.
purpose	string	Payment purpose code.
purposeCategory	string	Payment purpose category.
isBusiness	boolean	Business or individual flag.
email	string	Payee email address.
mobilePhone	string	Payee mobile phone number.
website	string	Payee website URL.
addressLine1	string	Address line 1.
addressLine2	string	Address line 2.
townCity	string	Town or city.
countyState	string	County or state.
postCode	string	Postal code.
countryCode	string	ISO country code.
sortCode	string	UK sort code.
accountNumber	string	Bank account number.
iban	string	IBAN.
bic	string	BIC.
aba	string	ABA routing number.
bankCountryCode	string	Bank country code.
institutionNumber	string	Institution number (CAD).
transitNumber	string	Transit number (CAD).
intermediaryName	string	Intermediary bank name.
intermediaryBic	string	Intermediary bank BIC.
intermediaryAba	string	Intermediary bank ABA.
intermediaryAddress1	string	Intermediary bank address line 1.
intermediaryAddress2	string	Intermediary bank address line 2.
intermediaryTownCity	string	Intermediary bank town/city.
intermediaryCountyState	string	Intermediary bank county/state.
intermediaryPostcode	string	Intermediary bank postal code.
intermediaryCountryCode	string	Intermediary bank country code.
created	string	Timestamp when payee was created.
updated	string	Timestamp when payee was last updated.

Validation Rules

Name Fields

name: 4-140 characters, alphanumeric with basic punctuation (& ) ( . -)
displayName: Same as name

Address Fields

addressLine1: 1-50 characters
addressLine2: 3-35 characters
townCity: 1-35 characters
countyState: 4-35 characters
postCode: 4-10 alphanumeric characters
countryCode: Exactly 2 uppercase letters (ISO code)

Bank Details

sortCode: Exactly 6 digits (GBP only)
accountNumber: 4-17 digits
iban: 15-34 characters, alphanumeric
bic: 8-11 characters, alphanumeric
aba: Exactly 9 digits (USD only)
institutionNumber: Exactly 3 digits (CAD only)
transitNumber: Exactly 5 digits (CAD only)

Contact Fields

email: Valid email format
mobilePhone: 7-15 characters, can include +, spaces, dashes, parentheses
website: Valid URL format

Error Codes

Code	Error	Description
401	Unauthorized	Account not found or doesn't belong to user.
403	Forbidden	Missing required permission (read:payees, create:payee, or update:payee).
404	Not Found	Payee not found or doesn't belong to the specified account.
429	Account Inactive	The specified account is not active.
500	Internal Server Error	Server error occurred.