Verify a batch (single customer)

Step 1. 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, so verify as often as the user edits.

This route serves only verify. The action field is optional and defaults to "verify"; initiate, passkey-challenge, and submit are rejected with 403 and belong to the submit route. It’s gated separately from paying a batch, so preparation can be granted without the ability to move money.

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.

initiatorId is ignored here; the path customerId is authoritative. Use POST /v1/batch-payments/verify to target customers by initiatorId.

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 single endpoint POST /v1/customers/{customerId}/batch-payments; the request and response bodies are identical, except that the single endpoint doesn’t accept a file.