A batch sends many payments in one go. It’s a two-endpoint flow: you verify the items on one endpoint, then initiate and pay on the other. They’re separate so a program can grant them separately. A reviewer can upload and check a file without being able to move money. Batch payments are optional per program. program.payments.batch in program capabilities says whether yours has them.

​
The flow

  1. Verify a batch with the items, or with a CSV or pain.001 file and we parse it. Each item is checked against your program’s rules and the payee’s name is checked against the account. You get back a request id to poll with and a batch id for the draft this creates. Nothing is charged or reserved; verify as often as the user edits.
  2. Get verify status until it finishes, or hold a WebSocket open and wait for BATCH_PAYMENT_VERIFICATION_COMPLETED, which carries the requestId, then fetch the status once. The result marks each item valid or invalid, with the reasons, and shows the balances available to cover the batch. Fix or drop the invalid ones.
  3. Pay a batch with the initiate action and the batch id. You get the total, the currency, and a challenge for the customer to authorise against.
  4. The same endpoint with the submit action, the challenge, the batch id, and the customer’s confirmation: a passkey (request the passkey challenge on this endpoint first), a 2FA code, or a PIN. Send exactly the items you initiated with; the challenge is bound to every row’s payee and amount, so any change invalidates it. A draft can be paid once.
  5. Get a batch to watch each item go from queued to success or failed. List batches shows all of a customer’s batches, with per-batch counts and totals on request.
Initiate and submit share one endpoint because the challenge has to round-trip through the user. Initiate issues it, the user authorises against what they can see, submit presents it back. The action field says which step you’re on.

​
Retrying safely

Send a fresh idempotency key on every submit. A batch key is not a replay key: two submissions that share one land on the same batch and run it again, so if a submit response is lost, don’t resend. Track the batch or list the customer’s batches to find out whether it landed. See Idempotency.