Verify a batch (multi-customer)

Step 1, multi-customer form. Submits the items for validation against your program’s rules and a name check on the payee (Confirmation of Payee in the UK, Verification of Payee in the EU). Returns a requestId, a batchId, and expiresAt. Validation runs in the background; poll Get verify status with the requestId. Nothing is charged or reserved.

This route serves only verify. initiate, passkey-challenge, and submit are rejected with 403 and belong to the submit route. It’s gated separately from paying a batch.

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.

Items. Each item is one payment. UK programs send accountNumber and sortCode; EU programs send iban and bic. A reference (6 to 64 characters) and amount are required. Add scheduledDate (YYYY/MM/DD) to send an item on a future date.

Drafts. Verifying creates a draft and returns its batchId and expiresAt. The draft records that these items are prepared and awaiting submission, which is what lets one person prepare a batch and another pay it. Send the same batchId back to re-verify after edits and the draft is updated in place, keeping its original creation time. A draft expires after 7 days, or at the end of its earliest scheduledDate, whichever comes first. After that it can’t be submitted; verify the items again for a new draft.

Sending a file. Post a CSV or an ISO 20022 pain.001 file as file: { content, format } instead of payments (one or the other, not both) and we parse it. format is optional; omitted, it’s detected from the content. Each row becomes an item and is validated the same way, so a bad row comes back in invalidPayments rather than being dropped. Only verify takes a file, and only on the split verify routes.

pain.001 is accepted in any version from .03 to .09. Namespace prefixes, BIC and BICFI, and all three ReqdExctnDt forms (bare, Dt, DtTm) are handled. UK sort codes are read from CdtrAgt/FinInstnId/ClrSysMmbId/MmbId only when ClrSysId/Cd is GBDSC, or when no scheme is named and the payee has no IBAN, so a German DEBLZ Bankleitzahl isn’t mistaken for one. The reference comes from RmtInf/Ustrd (joined if it repeats), falling back to RmtInf/Strd/CdtrRefInf/Ref. A past ReqdExctnDt is kept, not corrected, so the draft’s expiresAt is already elapsed and submit fails on expiry. InstdAmt/@Ccy is ignored; payments settle in the payer account’s currency. camt.053 is a statement, not a payment file, and is rejected.

CSV is the published batch template. The header row is found by looking for the Payee Name column, so a title row above it is fine, and quoted fields are honoured. Amount must be dot-decimal (1234.56); a decimal comma in an unquoted cell splits the row. Dates must be YYYY-MM-DD or YYYY/MM/DD (single-digit month or day is padded); anything else comes back as an invalid row rather than being guessed at.

Anything the parser couldn’t use (an unrecognised Payee AccountType, an EndToEndId outside 2 to 35 characters, a row whose column count differs from the header) is reported in a warnings array. The payments are still queued; the field is absent when there’s nothing to report.

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.