Batch payments let you send many payments in one go. It’s a multi-step flow across two endpoints: you verify the items on one, then initiate and submit on the other.
The two are separate so that preparing a batch and paying one can be granted independently — a reviewer can be allowed to upload and check a file without being able to move the money.
Batch payments are an optional capability, enabled per program. If your program doesn’t have it, the endpoints aren’t available to you. See Program capabilities. Every call uses the user’s bearer token.
Availability. The /verify and /submit routes are rolled out per program. Until your program is enabled for them they return 403, and the single-endpoint flow described under Using the older single endpoint remains available. Check with your integration contact before switching.

​
The items

Each item is one payment. Send the destination fields your program uses:
  • UK programs use accountNumber + sortCode.
  • EU programs use iban + bic.
A reference (6–64 chars) and amount are required. Add scheduledDate (YYYY/MM/DD) to send an item on a future date.

​
The flow

  1. Verify — POST .../batch-payments/verify with the items. We validate each one and run a name check on the payee (Confirmation of Payee for UK, Verification of Payee for EU). You get a requestId and a batchId — the latter identifies the draft this creates, which is what lets someone else pay it later.
  2. Check status — poll until validation finishes. The result marks each item valid or invalid, with errors.
  3. Initiate — POST .../batch-payments/submit with action: "initiate" and the batchId to get the totalAmount, currency, and an scaChallenge.
  4. Submit — same endpoint with action: "submit", the challenge, a confirmation object (passkey, 2FA code, or PIN on supported programs), and the batchId from step 1 to pay that draft.
  5. Track — fetch the batch to watch each item move through QUEUED → SUCCESS or FAILED.

​
Why initiate and submit share one endpoint

The authentication challenge has to round-trip through the user: initiate issues it, the user authenticates against the amount and payee they can see, then submit presents it back. Both steps are the same privilege — authorising a payment — so they sit on the same endpoint and the action field says which step you’re on. /verify rejects initiate, passkey-challenge and submit with 403, and /submit rejects verify with 403. On /verify the action field is optional, since the route only serves one. The split routes require a verified batch. batchId is mandatory on initiate and submit there, so the pay route cannot be used without going through verify first. The unsuffixed routes keep the older contract, where it is optional.

​
Using the older single endpoint

The original endpoint still works and still accepts all four actions:
Send action: "verify", "initiate", "passkey-challenge" or "submit" against it. The request and response bodies are identical to the split routes — only the URL and the permission differ. It remains supported for existing integrations; new integrations should use the split routes.

​
Status

A batch reports an overall status: CREATED, FUNDING_PENDING, FUNDED, PROCESSING, QUEUED, and the failure states FUNDING_FAILED and PARTIALLY_FAILED. Individual items are QUEUED, SUCCESS, or FAILED.
Pass a fresh idempotencyKey (a UUID) on every submit — optional today, required in a future release. Unlike the single-resource creates, a batch key is not a replay key: don’t resend a batch after a lost response, track it instead. See Idempotency.