Acting on a customer

​

Accounts

• GET /v1/accounts?programId=…&customerId=… — accounts with balances and bank details. Filter and paginate with customerId, accountId, currency, status, page, limit, sortBy, sortOrder (the list filters accept comma-separated values), and resultType=file returns a CSV export instead of JSON. In sandbox, most providers return mock data.
  Operators use /v1/accounts, not /v1/customers/{customerId}/accounts. The path-scoped route is the consumer form: a back-office token that sends customerId in the path is rejected with Backoffice request should not include customerId in path. Pass the customer as the customerId query parameter instead. The same split applies to GET /v1/transactions.
• POST /v1/customers/{customerId}/accounts — open an additional account; body currency. This one is path-scoped.

​

Payments

• POST /v1/customers/{customerId}/accounts/{accountId}/payments — send a payment for the customer. Required: amount (decimal string, max 2 dp) and purpose (purpose code). Also accepted: beneficiaryId (a saved payee — required unless you send a cryptoQuote), currency (defaults to the account currency), reference (statement reference; the field allows 140 characters but some programs accept as few as 35), chargeBearer (SHA / OUR / BEN), debtorViban, and scheduledDate + frequency for scheduled/recurring. P2P transfers are detected automatically from the destination identifiers.
  waiveFee is accepted by the schema on this endpoint but has no effect — nothing reads it on the create path, and the fee is charged anyway. It only does something on the fee-preview endpoint below.
  Send an Idempotency-Key header so a retry can’t double-send.
  {
    "amount": "150.00",
    "purpose": "PP001",
    "beneficiaryId": "ben_4b8e1c9d",
    "reference": "Invoice 1024",
    "chargeBearer": "SHA"
  }
  
• GET /v1/customers/{customerId}/accounts/{accountId}/payments/fee?amount=150.00 — preview the fee; returns feeAmount. Optional waiveFee query parameter (true or 1) returns the fee as waived — note this is not restricted to a subset of operators; any caller who can reach the endpoint may pass it. Programs and providers without fee preview respond 503 SERVICE_UNAVAILABLE (only ClearBank, Banking Circle and EasyPayment support it) — branch on 503, and don’t treat it as a transient outage to retry.
  This was a POST with the amount in the body on the old surface. On /v1 it is a GET with amount as a query parameter.
• GET /v1/customers/{customerId}/accounts/{accountId}/scheduled-payments — the account’s scheduled and recurring payments. GET /v1/customers/{customerId}/scheduled-payments gives the same across all the customer’s accounts.
• DELETE /v1/customers/{customerId}/accounts/{accountId}/scheduled-payments/{scheduleId} — cancel one.
• POST /v1/customers/{customerId}/accounts/{accountId}/payments/international — an international (SWIFT / cross-currency) transfer.

​

Beneficiaries

• POST /v1/customers/{customerId}/beneficiaries — create a payee. Body: accountId (which of the customer’s accounts the payee is linked to), name, and an account object matching the program’s rails (UK { type: "uk", sortCode, accountNumber }, EU { type: "iban", iban, bic }). Optional isCorporate, address. Customer sessions must also send a confirmation object (step-up). Back-office and SSO calls skip the step-up and can omit it. Accepts an Idempotency-Key header.
• GET /v1/customers/{customerId}/beneficiaries — list payees; paginate with limit and nextToken.
• GET /v1/customers/{customerId}/beneficiaries/{beneficiaryId} — one payee.
• DELETE /v1/customers/{customerId}/beneficiaries/{beneficiaryId} — remove a payee. Blocked while pending, scheduled, or batch payments still reference it.
  The old path carried an accountId and a trailing /delete (DELETE /customers/{customerId}/accounts/{accountId}/beneficiaries/{beneficiaryId}/delete). The /v1 path is customer-scoped with no /delete suffix.

​

Name check (CoP / VoP)

{
  "beneficiary": { "name": "Ada Lovelace" },
  "account": { "type": "uk", "sortCode": "040506", "accountNumber": "87654321" }
}

​

Batch payments

1. action: "verify" — validates items and runs the name check (CoP for UK, VoP for EU). Large batches verify asynchronously: poll GET /v1/batch-payments/verify/{requestId} until it completes.
2. action: "initiate" — returns the scaChallenge (hash, nonce, timestamp).
3. action: "submit" — sends the batch with the challenge and confirmation. Reuse the same idempotencyKey body field across retries of this step; batch payments take the key in the body rather than the header.

​

Idempotency

​

Payments, international payments, beneficiaries

• The mismatch check hashes a subset of the request, not all of it. Payments hash amount, accountId, beneficiaryId, currency, paymentRef and purpose (plus scheduledDate / frequency for scheduled payments); beneficiaries hash name, accountNumber, iban, sortCode, bic and accountId. Changing a field outside that set — chargeBearer or debtorViban, say — and reusing the key silently replays the original instead of returning 400. Use a fresh key when you change the request.
• Only payments reserve the key up front. Beneficiary create is an exists-then-compare with no reservation, so two concurrent creates with the same key both proceed. The replay check also runs after the step-up, so a keyed retry on a customer session still needs a fresh confirmation.

​

Batch submit