Customers

A customer is a saved bank account of yours: a payee you pay, or a payer who pays you. customerId is the id you see as customer.customerId on declarations, transactions, payouts and events.

MethodPathPurpose
GET/v1/customersList active customers
POST/v1/customersCreate a customer
GET/v1/customers/:customerIdRead one
PATCH/v1/customers/:customerIdEdit, or rebind the reference
DELETE/v1/customers/:customerIdSoft-delete. A deleted customer no longer appears, and cannot be used for payouts or declarations

The routes need the Beneficiary permission, shown in the dashboard as Customer. A credential without it is 403 ABILITY_DENIED.

The earlier saved-payee routes are removed. Use these.

List

GET /v1/customers returns active customers, oldest first, paged: { "data", "meta": { "limit", "offset", "total" } }.

QueryDefaultDescription
limit10Page size (minimum 1, maximum 100)
offset0Rows to skip

Unknown query names are 400.

Identity

A customer is one rail, one account identifier and one currency. On swift that is the IBAN with whitespace removed and upper-cased. On local it is the account number and routing number (neither may contain :). Currency is USD, AED, EUR or GBP. Declarations and payouts reuse the oldest active customer with that identity, or create one. A create or identity edit that would duplicate an active customer is 409 CUSTOMER_EXISTS.

Your reference

customerReference is your own identifier (a CRM id, a supplier code). A customer holds at most one. The first declaration or payout that carries a reference for an unbound customer binds it. A different reference afterwards is 409 CUSTOMER_REFERENCE_CONFLICT. Change it on purpose with PATCH and a new customerReference. LEGACY_UNSET means the customer has no reference of yours yet; you can never send that value (400 RESERVED_CUSTOMER_REFERENCE).

Rebinding or deleting a customer expires its open declarations. You are told with deposit.expired and reason rebound or deleted.

What a customer reads as

customerId, customerReference, label, fullName, rail (swift or local), entityType, the identifiers of its rail, address lines, currency, source and whether it is payable. A customer a declaration or an incoming payment created is often not payable until you complete the blank entity type, address and SWIFT code with PATCH.

A customer outside your read scope is { "customerId": "…" } on a write response, and 403 CONDITION_FAILED on a direct read. A withheld field is absent.

Once strict mode is on, rail, IBAN, account number, routing number and a currency that is already set cannot be changed (400 IMMUTABLE_FIELD). Setting a missing currency once is still allowed.


Did this page help you?