Mass payments
Mass Payments let your platform send money to up to 250 recipients in one batch transfer. The batch creates a single mass payment contract, identified by one contract number, while retaining each payment's client reference. You can fund the entire batch with one transaction instead of funding each payment separately. Use this flow when your software needs to collect, validate, and submit multiple payouts together.
API Endpoints
Implementation tip: store the returned contractNumber and each payment's clientReference in your application state. The contract number identifies the batch; the client reference identifies an individual payment when you update or exclude it.
Create Batch Transfer
Creates a batch and validates each payment before you submit it. Validation checks recipient information, bank account details, and payment limits. If every payment passes, the API returns an unapproved contract with an indicative quote (an estimated exchange rate and cost). If any payment fails, use the returned error details to correct the relevant data before continuing.
POST /v2/paymentsUpdate Recipient
Replaces the recipient details for one payment in the unapproved contract. Use the payment's clientReference to target the payment, for example when a customer corrects a name or bank account detail. Validate the replacement data before approving the contract.
PUT /v2/contracts/{contractNumber}/payments/{clientReference}/recipientUpdate Payment
Updates the amount or currency details for one payment in the unapproved contract. Use the payment's clientReference to identify the payment. After changing a payment, re-quote the batch so the exchange rate and total cost reflect the new details.
PUT /v2/contracts/{contractNumber}/payments/{clientReference}Update Settlement Method
Changes how XE receives the funds for the batch, such as the bank transfer method. Use this when your platform or customer needs a different funding option. Confirm the resulting funding requirements before approving the contract.
PUT /v2/contracts/{contractNumber}/settlementDetailsExclude Payment
Removes one payment from the unapproved contract. Identify it with the payment's clientReference. After excluding a payment, re-quote the batch so the quote and total amount match the remaining payments.
DELETE /v2/contracts/{contractNumber}/payments/{clientReference}Cancel Contract
Cancels an unapproved contract and its remaining payments. Use this when the batch should not proceed. Contact XE to cancel an approved contract, because approval makes the contract legally binding.
DELETE /v2/contracts/{contractNumber}Re-quote Batch
Requests a new quote after you change or remove payments or recipient details in the batch. The updated quote recalculates the exchange rate, amounts, and total cost for the current set of payments. Show the new quote to the customer before approval.
POST /v2/contracts/{contractNumber}/quoteApprove Contract
Approves the batch, locks in the quoted exchange rate and amounts, and creates a legally binding contract with XE. Approval is the point at which the batch moves from an editable draft to a committed transaction. The API also generates an invoice with the instructions for funding the batch.
POST /v2/contracts/{contractNumber}/approveDownload Invoice
Downloads the invoice for an approved contract. The invoice contains the funding instructions your platform or customer needs to send the batch funds to XE. XE also emails the invoice to the registered email address. Retrieve and store it with the contract record so your system can guide the payer through funding.
GET /v2/contracts/{contractNumber}/invoiceSequence diagram
The sequence below shows the recommended API order, from creating and refining the batch through approval and funding. Treat the unapproved contract as an editable draft; after approval, the quote is locked and the batch is legally binding.
Process flow
Use this flow as an implementation checklist: validate the batch, correct or remove individual payments as needed, re-quote after changes, then approve and use the invoice to fund the contract.