Mass payments
Mass Payments let your business send funds to up to 250 recipients in one batch. This is useful for treasury, accounts payable, payroll, or other internal payment workflows that need to coordinate multiple payouts. The batch creates one contract with a single contract number, while each payment keeps its own clientReference for tracking and reconciliation. You fund the entire batch with one transaction, then XE distributes the individual payments to the recipients.
Implementation note: Store the contractNumber and each payment’s clientReference with your internal treasury or payment record. Use these identifiers for later updates, approval, invoice retrieval, and reconciliation. The API sequence can remain the same whether the batch starts in an ERP, accounts-payable system, treasury platform, or another internal workflow.
API Endpoints
Create Batch Transfer
Creates a batch and validates each recipient, bank account, and payment against XE’s requirements and limits. If every payment passes, the response returns an unapproved contract and an indicative quote that your finance or treasury workflow can review. If validation fails, use the returned errors to correct the affected payments before continuing.
POST /v2/paymentsUpdate Recipient
Updates the recipient details for one payment in the unapproved contract. Use the payment’s clientReference to identify the payment, for example when your ERP or treasury workflow supplies corrected beneficiary or bank information. Re-quote the batch after making the change.
PUT /v2/contracts/{contractNumber}/payments/{clientReference}/recipientUpdate Payment
Updates the amount, currency, or other payment details for one payment in the unapproved contract. Use clientReference to identify the payment, then re-quote the batch so the exchange rate, totals, and funding amount reflect the change.
PUT /v2/contracts/{contractNumber}/payments/{clientReference}Update Settlement Method
Changes how your business funds the batch—for example, the bank transfer method or account details used to send the required funds to XE. This does not change the individual payment amounts or recipients.
PUT /v2/contracts/{contractNumber}/settlementDetailsExclude Payment
Removes one payment from the unapproved contract. Use this when your internal payment run changes or a recipient should no longer be paid. Re-quote the batch afterwards so the exchange rate, totals, and amount to fund remain accurate.
DELETE /v2/contracts/{contractNumber}/payments/{clientReference}Cancel Contract
Cancels an unapproved contract when the batch is no longer needed. Once approved, the contract is legally binding and cannot be cancelled through this endpoint; contact XE if an approved contract needs attention.
DELETE /v2/contracts/{contractNumber}Re-quote Batch
Recalculates the batch quote after you add, change, or remove payments or recipients. Use the latest quote to confirm the exchange rate, amounts, fees, and total funding requirement before approval.
POST /v2/contracts/{contractNumber}/quoteApprove Contract
Approves the batch, locks in the quote, and creates a legally binding contract with XE. After approval, the batch is no longer an editable draft. XE generates an invoice showing how much your business must fund and where to send the funds.
POST /v2/contracts/{contractNumber}/approveDownload Invoice
Downloads the invoice for the approved contract. The invoice contains the funding amount and payment instructions your treasury, accounts-payable, or banking workflow needs to arrange the transfer to XE. XE also emails the invoice to your registered email address.
GET /v2/contracts/{contractNumber}/invoiceSequence diagram
This sequence shows the API calls and contract states from batch creation through approval and invoice retrieval. Keep your internal approval, ERP, and reconciliation steps around this sequence as needed.
Process flow
This flow can be used as an implementation checklist: validate the batch, correct any errors, update or exclude payments as needed, re-quote, approve, and fund. The surrounding business approvals and reconciliation can remain in your existing finance systems.