Pay a batch (multi-customer)

Steps 3 and 4, multi-customer form. Pays a verified batch. The SCA challenge has to round-trip through the user, so this is a multi-step exchange against this one route and the action field says which step you’re on:

1. initiate returns totalAmount, currency, and an scaChallenge for the items you send.
2. passkey-challenge (only if the user confirms with a passkey) returns a passkeySession and fido2options to complete on the device. Send the Origin header; it’s carried into the WebAuthn ceremony and a mismatch fails verification.
3. submit sends the same items back with the scaChallenge and a confirmation: { "method": "passkey", "passkeySession", "assertion" }, { "method": "totp", "totp", "accessToken" } (the access_token from sign-in), or { "method": "pin", "pin" } on programs with PIN step-up. Returns the batchId.

Send exactly the items you sent to initiate. The challenge is bound to every row’s payee account and amount, in order, so adding, removing, reordering, or re-pricing a row between the two calls invalidates it. verify is rejected with 403; it belongs to the verify route.

A verified batch is required. batchId, the id verify returned, is required on both initiate and submit here; omitting it is a 400, not a new batch. The draft is checked for expiry and ownership and can be paid once: a second submit of the same draft is rejected before any money moves. passkey-challenge needs no batchId. The single endpoint keeps the older contract, where batchId is optional and omitting it creates a new batch.

Retries. Pass idempotencyKey (a UUID) as a body field; this route doesn’t read an Idempotency-Key header. Mint a fresh UUID for every batch. A batch key is not a replay key and isn’t scoped to the customer: two submissions that share a key land on the same batchId and run the submission again, reserving funds and sending the payments a second time, and a reused key with a different list of payments isn’t rejected. If a submit response is lost, don’t resend; fetch the batch, or list the customer’s batches, to see whether it landed. Optional today, required in a future release.

Rollout. The split verify and submit routes are enabled per program and return 403 until yours is. Until then, send the same action to the path-less single endpoint POST /v1/batch-payments; the request and response bodies are identical, except that the single endpoint doesn’t accept a file.

Back office only, multi-customer. No customerId in the path: each item’s payer account is resolved globally and authorised per item against the caller, so one batch can pay from the accounts of any customers the caller is responsible for. An account the caller isn’t responsible for, including an unassigned account, is rejected with 401, as is a management role that resolves to no customers. A non-management caller can’t use this route.

The passkey is always the operator’s own. The challenge is issued against the signed-in user, never the customer being paid. The ceremony is identical to the single-customer route; only the tenant the credential is looked up in differs: a customer’s passkey is resolved against their own program (honouring the sandbox flag), a management operator’s against the shared management pool, production only. So a management passkey ceremony always resolves to production, even for a sandbox batch.