Create a payee for a customer.

Prerequisites: customerId must exist on your platform; currency must be one returned by GET /api/v1/payments/payee/currencies for that customer.

Important: always send X-Idempotency-Key — retrying without it can create a duplicate payee. Which bankAccount sub-fields are required depends on the destination country/currency; see the bank-detail table in the Payee tag description.

Async vs sync: synchronous — the payee is created and returned in the same call (200 OK).

Related: discover currencies with GET /payee/currencies; populate purpose/relationship/country fields with GET /payee/purposes, GET /payee/relationships and GET /payee/countries.

⚠️ Required Fields

Field	Type	Description	Constraints
`customerId`	string (uuid)	The customer this payee is being saved for. Must already exist on your platform.	—
`favouriteName`	string	A partner-chosen display label for this payee (e.g. "Acme Supplier — EUR"). Shown back to you on GET/list; not shown to the beneficiary.	minLength 1; maxLength 100; pattern `^[\p{L}\p{N} .,'&\-]{1,100}$`
`currency`	string	The currency this payee will be paid in. Check `GET /payee/currencies` for the currencies enabled for this customer.	minLength 1; pattern `^[A-Z]{3}$`

Optional Fields

Field	Type	Description	Constraints
`beneficiary`	object	Who the payee is — an individual's name, or a business name, plus contact details.	—
`beneficiary.individual`	object	Populate this when the beneficiary is a natural person. Mutually exclusive in practice with `business` — supply one or the other.	—
`beneficiary.individual.firstName`	string	Given name, when the beneficiary is an individual.	pattern `^[\p{L} '\-]{1,50}$`; nullable
`beneficiary.individual.middleName`	string	Middle name, if applicable.	pattern `^[\p{L} '\-]{1,50}$`; nullable
`beneficiary.individual.lastName`	string	Family name, when the beneficiary is an individual.	pattern `^[\p{L} '\-]{1,50}$`; nullable
`beneficiary.business`	object	Populate this when the beneficiary is a company. Mutually exclusive in practice with `individual`.	—
`beneficiary.business.name`	string	Registered business name, when the beneficiary is a business rather than an individual.	pattern `^[\p{L}\p{N} &.,'\-()]{1,150}$`; nullable
`beneficiary.contact`	object	Contact details for the beneficiary, individual or business.	—
`beneficiary.contact.email`	string (email)	The beneficiary's email address, used for payout notifications where the corridor supports them.	minLength 0; maxLength 254; nullable
`beneficiary.contact.phone`	object	The beneficiary's phone number.	—
`beneficiary.contact.phone.countryCode`	string	Phone country calling code, e.g. "+1".	pattern `^\+?[0-9]{1,4}$`; nullable
`beneficiary.contact.phone.number`	string	Local phone number, digits only.	pattern `^[0-9]{4,15}$`; nullable
`address`	object	The beneficiary's address. Required by some corridors before a payout can be sent.	—
`address.line1`	string	Street address line.	pattern `^[\p{L}\p{N} .,'\-#/]{1,150}$`; nullable
`address.city`	string	City or town.	pattern `^[\p{L} .\-]{1,50}$`; nullable
`address.state`	string	State, province or region, where applicable.	pattern `^[\p{L} .\-]{1,50}$`; nullable
`address.postalCode`	string	Postal or ZIP code.	pattern `^[A-Za-z0-9 \-]{2,12}$`; nullable
`address.country`	string	Country name. Check `GET /payee/countries` for the accepted values for a given currency.	pattern `^[\p{L} .,'()\-]{2,100}$`; nullable
`kycDetails`	object	Business-type and registration details, required for business beneficiaries in some corridors.	—
`kycDetails.businessType`	string	Legal business type, e.g. "llc" or "corporation" — required for business beneficiaries in some corridors.	pattern `^[A-Za-z _\-]{1,50}$`; nullable
`kycDetails.businessRegistrationNumber`	string	Government-issued business registration number.	pattern `^[A-Za-z0-9 \-/.]{1,50}$`; nullable
`bankAccount`	object	Where the payout lands. Which sub-fields are required depends on `currency` and `bankCountry` — see the Payee tag description for the common shapes (IBAN countries vs. account+routing vs. SWIFT-only).	—
`bankAccount.accountType`	string	Account type at the bank, e.g. "checking" or "savings" — required for some corridors (notably US ACH), ignored for others.	pattern `^[A-Za-z]{2,30}$`; nullable
`bankAccount.bankName`	string	Name of the beneficiary bank.	pattern `^[\p{L}\p{N} &.,'\-()]{1,150}$`; nullable
`bankAccount.bankCountry`	string	Country the beneficiary bank is domiciled in.	pattern `^[\p{L} .,'()\-]{2,100}$`; nullable
`bankAccount.bankCode`	string	Local bank identifier where the corridor uses one instead of (or alongside) a SWIFT/BIC code, e.g. a sort-code-style bank code.	pattern `^[A-Za-z0-9\-]{1,20}$`; nullable
`bankAccount.accountNumber`	string	The local account number. Not required where `iban` is supplied instead.	pattern `^[A-Za-z0-9]{4,34}$`; nullable
`bankAccount.iban`	string	IBAN, for corridors that use it in place of a local account number.	pattern `^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{10,30}$`; nullable
`bankAccount.swiftBic`	string	SWIFT/BIC code identifying the beneficiary bank for international wires.	pattern `^[A-Za-z]{6}[A-Za-z0-9]{2}([A-Za-z0-9]{3})?$`; nullable
`bankAccount.routingNumber`	string	US ABA routing number, for US domestic transfers.	pattern `^[0-9]{5,12}$`; nullable
`bankAccount.sortCode`	string	UK sort code, for GBP domestic transfers.	pattern `^[0-9\-]{4,10}$`; nullable
`bankAccount.branchCode`	string	Bank branch identifier, where the corridor distinguishes branches separately from the bank code.	pattern `^[A-Za-z0-9\-]{1,20}$`; nullable
`payment`	object	Payment method/purpose metadata for payouts to this payee.	—
`payment.type`	string	Payment method for payouts to this payee, e.g. "bank_transfer".	pattern `^[\p{L}\p{N} \-]{1,50}$`; nullable
`payment.purpose`	string	Default payment purpose for payouts to this payee. Check `GET /payee/purposes` for accepted values.	pattern `^[\p{L}\p{N} \-]{1,100}$`; nullable
`payment.providerFields`	object	Free-form key/value bag for provider-specific fields a particular corridor needs beyond the modeled ones above. Keys and value shapes vary by provider and corridor — confirm with your integration contact before relying on a specific key.	nullable

📤 Response Fields

200 response:

Field	Type	Nullable	Description
`data`	object	No	A saved payee (beneficiary) record.
`data.id`	string (uuid)	No	The payee id — pass this as `{payeeId}` on GET/PUT calls and, elsewhere in the platform, as the beneficiary reference on a payout order.
`data.customerId`	string (uuid)	No	The customer this payee belongs to.
`data.favouriteName`	string	No	The partner-supplied display label for this payee, as given on create/update.
`data.currency`	string	No	The payout currency this payee is set up to receive.
`data.status`	string	Yes	Payee lifecycle status. See the status table above.
`data.beneficiary`	object	No	—
`data.beneficiary.individual`	object	No	Populate this when the beneficiary is a natural person. Mutually exclusive in practice with `business` — supply one or the other.
`data.beneficiary.individual.firstName`	string	Yes	Given name, when the beneficiary is an individual.
`data.beneficiary.individual.middleName`	string	Yes	Middle name, if applicable.
`data.beneficiary.individual.lastName`	string	Yes	Family name, when the beneficiary is an individual.
`data.beneficiary.business`	object	No	Populate this when the beneficiary is a company. Mutually exclusive in practice with `individual`.
`data.beneficiary.business.name`	string	Yes	Registered business name, when the beneficiary is a business rather than an individual.
`data.beneficiary.contact`	object	No	Contact details for the beneficiary, individual or business.
`data.beneficiary.contact.email`	string (email)	Yes	The beneficiary's email address, used for payout notifications where the corridor supports them.
`data.beneficiary.contact.phone`	object	No	The beneficiary's phone number.
`data.beneficiary.contact.phone.countryCode`	string	Yes	Phone country calling code, e.g. "+1".
`data.beneficiary.contact.phone.number`	string	Yes	Local phone number, digits only.
`data.address`	object	No	—
`data.address.line1`	string	Yes	Street address line.
`data.address.city`	string	Yes	City or town.
`data.address.state`	string	Yes	State, province or region, where applicable.
`data.address.postalCode`	string	Yes	Postal or ZIP code.
`data.address.country`	string	Yes	Country name. Check `GET /payee/countries` for the accepted values for a given currency.
`data.kycDetails`	object	No	—
`data.kycDetails.businessType`	string	Yes	Legal business type, e.g. "llc" or "corporation" — required for business beneficiaries in some corridors.
`data.kycDetails.businessRegistrationNumber`	string	Yes	Government-issued business registration number.
`data.bankAccount`	object	No	—
`data.bankAccount.accountType`	string	Yes	Account type at the bank, e.g. "checking" or "savings" — required for some corridors (notably US ACH), ignored for others.
`data.bankAccount.bankName`	string	Yes	Name of the beneficiary bank.
`data.bankAccount.bankCountry`	string	Yes	Country the beneficiary bank is domiciled in.
`data.bankAccount.bankCode`	string	Yes	Local bank identifier where the corridor uses one instead of (or alongside) a SWIFT/BIC code, e.g. a sort-code-style bank code.
`data.bankAccount.accountNumber`	string	Yes	The local account number. Not required where `iban` is supplied instead.
`data.bankAccount.iban`	string	Yes	IBAN, for corridors that use it in place of a local account number.
`data.bankAccount.swiftBic`	string	Yes	SWIFT/BIC code identifying the beneficiary bank for international wires.
`data.bankAccount.routingNumber`	string	Yes	US ABA routing number, for US domestic transfers.
`data.bankAccount.sortCode`	string	Yes	UK sort code, for GBP domestic transfers.
`data.bankAccount.branchCode`	string	Yes	Bank branch identifier, where the corridor distinguishes branches separately from the bank code.
`data.payment`	object	No	—
`data.payment.type`	string	Yes	Payment method for payouts to this payee, e.g. "bank_transfer".
`data.payment.purpose`	string	Yes	Default payment purpose for payouts to this payee. Check `GET /payee/purposes` for accepted values.
`data.payment.providerFields`	object	Yes	Free-form key/value bag for provider-specific fields a particular corridor needs beyond the modeled ones above. Keys and value shapes vary by provider and corridor — confirm with your integration contact before relying on a specific key.
`data.createdAt`	string (date-time)	No	When the payee was created.
`data.updatedAt`	string (date-time)	Yes	When the payee was last updated.
`requestId`	string	Yes	—
`timestamp`	string (date-time)	No	—

⚠️ Required Fields

Optional Fields

📤 Response Fields

Request

Responses

Create a payee for a customer.

⚠️ Required Fields#

Optional Fields#

📤 Response Fields#

Request

Responses

⚠️ Required Fields

Optional Fields

📤 Response Fields