Batch payments

How batch payments work

With batch payments, one API request pays many recipients. Each payment in the batch can go to a different recipient, individual or business, by its own method: a bank account, an Xtrm wallet, a prepaid debit card, a digital gift card, a mailed check or a push to a card.

Each batch is one request to POST /API/v4/Fund/BatchTransfer, and each payment in it is an item in Items. Xtrm checks the request, answers with 202 Accepted and processes the payments in the background. You follow their progress with webhooks or by polling two status endpoints.

Every payment goes to an existing Xtrm account, so create each new recipient before you submit the batch.

Payments and currency exchange are executed by regulated financial partners.

If you're a managing platform

A batch you run for a client company is the same request, sent with the client company's pseudo credentials, its SPN in IssuerAccountNumber and its wallet in SourceWalletId. Pseudo credentials require manager services, which Xtrm turns on for your company. The company must be onboarded and approved first. See How managing platforms work.

#How a batch is processed

Submit → validate → 202 Accepted → process in the background → notify

StageWhat happensWhat you see
1. SubmitYou POST one batch: your company's account, the wallet that funds the batch and the payments to make.Nothing until Xtrm responds. Don't send another request with the same CustomerBatchId until then.
2. Validate (synchronous)Xtrm checks the batch's fields, your access to IssuerAccountNumber, that SourceWalletId is your active wallet, whether the batch and item IDs are already in use, and each item's fields for its payment method. It stores the items that pass. It doesn't check the recipients, their banks, cards or SKUs, or your balance, and it doesn't move any money yet.202 Accepted when at least one item passes, with counts of accepted and rejected items. Each rejected item carries a Key, a Field and a Message that explains why.
3. Process (asynchronous)Xtrm processes the accepted payments in the background, one at a time per source wallet. For each one, it checks the recipient and destination, debits your source wallet for the Amount plus its fee, credits the recipient's wallet and delivers the money to the destination.Each payment's status changes as it moves through processing. See Follow a batch.
4. NotifyIf Xtrm has set up a webhook endpoint for your account, it sends events as payments are processed. You can also poll the status endpoints at any time.Webhook events, or the status of the batch and of each payment.

Xtrm validates each item on its own, so one bad item doesn't hold up the rest: the accepted items go on to processing, and the response lists the rejected ones. If the batch itself is invalid (for example, SourceWalletId is missing or Items is empty), Xtrm refuses the whole request with 422 Unprocessable Entity and stores nothing. If no item passes, Xtrm also stores nothing and answers 422, or 409 Conflict when any item was rejected as CONFLICT_DUPLICATE_ITEM. If the items pass validation but Xtrm can't store any of them, the response is a 202 whose Status is Failed, with Key TEMPORARY_ERROR. Other problems with the request return other status codes: for example, a body that isn't valid JSON, an expired token or a SourceWalletId that doesn't belong to your company. The whole request is refused lists every case.

A 202 Accepted confirms that Xtrm received the batch and validated its items. It doesn't mean the payments went through, and it doesn't prove that every item in Accepted was stored. Confirm with Get the status of a batch payment. Many problems surface only during processing. They appear on the payment as an attempt ErrorCode, for example RECIPIENT_NOT_FOUND, BANKID_INVALID on a bank payment or SKU_NOT_FOUND on a prepaid card.

When you submit a batch, Xtrm doesn't check your balance, and it doesn't reserve or debit any funds. During processing, it debits your wallet separately for each payment, for the Amount plus its fee, and credits the recipient's wallet with the full Amount. Fees are charged per payment, never per batch, and no status response or webhook returns a payment's fee. If your wallet's balance can't cover a payment, that payment fails with INSUFFICIENT_BALANCE. Nothing is debited for it, and later payments, such as smaller ones, can still go through.

#What's in a batch

A batch payment is one JSON object: a few batch-level fields and an Items array.

FieldRequiredWhat it is
IssuerAccountNumberYesYour company's Xtrm account number (SPN…), which owns the source funds.
SourceWalletIdYesThe ID of the wallet that funds the batch, as an integer, for example 122181. A numeric string such as "122181" works too. A value that isn't a whole number, such as "abc" or 122181.0, fails the whole request with 422 INVALID_FIELD. Its currency is the currency of every item in the request.
CustomerBatchIdYesYour ID for the batch. Xtrm never generates one, and the value is shared across all Xtrm accounts, so make it unique. See Your IDs, duplicates and retries.
EmailNotificationNoA boolean, false by default. true emails each recipient a payment-received message at their own address when their wallet is credited, for every payment method. It doesn't control card credentials, which always go to Destination.Email. The strings "true" and "false" work too, in any case. Any other string, such as "yes" or "1", is read as false without an error, so send a real boolean.
ItemsYesThe payments in the batch, one item each.

Each item says who gets paid, how much and how:

FieldRequiredWhat it is
CustomerTransactionIdYesYour ID for the payment. Xtrm never generates one.
RecipientIdYesThe recipient's Xtrm account number: PAT… for an individual recipient or SPN… for a business recipient. It must be an existing account, so create a new recipient before the batch; see Who you can pay.
AmountYesA JSON number greater than 0, in the batch's currency, for example 100 or 49.99. A numeric string such as "100.00" works too. A missing amount, or one that isn't a number, is read as 0 and rejects the item with Amount must be greater than zero. Send at most 2 decimal places: Xtrm stores and pays amounts with 2.
SendMethodIdYesThe payment method, for example XTR94500 (bank). See Payment methods.
DestinationYesWhere the payment goes. Which fields apply depends on SendMethodId. It's required for every method: for a wallet payment without a WalletId, send {}.
DescriptionNoA note for the payment, up to 1,024 characters, counted after Xtrm HTML-encodes it, so an & counts as 5 characters. Xtrm copies it to the debit in your source wallet and to the credit in the recipient's wallet, where the recipient sees it. Start it with the payment's CustomerTransactionId to find the payment's money later; see Track & reconcile payments.

Send CustomerBatchId, CustomerTransactionId, RecipientId, SendMethodId and the Destination text fields as JSON strings. A JSON number in one of them is accepted and stored as text (1001 becomes "1001"), so send IDs as strings to keep them exactly as you store them. Numbers and booleans as strings lists the types each batch field accepts.

#Who you can pay

Create recipients before the batch

A batch pays existing Xtrm accounts only, and it never creates one. Before you submit the batch, create each new recipient: a person with CreateUser or a company with CreateBeneficiary. Each call returns the account number to send as RecipientId, and you can pay the new account right away.

Each RecipientId must be an existing account number, or the payment fails during processing with RECIPIENT_NOT_FOUND. To check whether someone already has an account, look them up with CheckUserExist or CheckBeneficiaryExist.

You don't need a connection to pay an account, and paying it doesn't connect it: a wallet payment with an empty Destination can pay any existing account. Once Xtrm has credited the recipient's wallet for a payment, the account appears in your recipient list (GetPersonalBeneficiaries or GetBeneficiaries). A payment to a bank account or card needs that bank or card linked to the recipient, and linking or looking one up needs a connection; recipients you create with CreateUser or CreateBeneficiary are connected to your company. See Connections and manager services.

In the Xtrm web app, you can create a person's account as you pay them, which also connects it to your company, but a company needs more details, so you create it first.

#Example

This batch pays two recipients from wallet 122181: USD 100.00 to a business recipient's bank account and USD 50.00 to an individual recipient as a prepaid debit card.

Note

CustomerBatchId values are shared across all Xtrm accounts. Replace the sample IDs with your own unique values, for example ones that include your account number or a UUID, before you run this in the sandbox.

curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "IssuerAccountNumber": "SPN1111222",
  "SourceWalletId": 122181,
  "CustomerBatchId": "BATCH-OVERVIEW-0001",
  "Items": [
    {
      "CustomerTransactionId": "TXN-OVERVIEW-0001",
      "RecipientId": "SPN8888777",
      "Amount": 100,
      "SendMethodId": "XTR94500",
      "Destination": {
        "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
        "BeneficiaryBankPaymentMethod": "ACH"
      }
    },
    {
      "CustomerTransactionId": "TXN-OVERVIEW-0002",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94503",
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      }
    }
  ]
}'

This sample prints the response and nothing more. For a version that logs the HTTP status and body of a refused request and handles 409 Conflict and rejected items, see Submit a batch payment and handle the response.

The response lists every accepted item with the batch's currency (the currency of SourceWalletId), not necessarily in request order. Amount comes back as a JSON number with the decimals you sent, so the 100 and 50 in this request come back as 100.0 and 50.0. Compare amounts as numbers, not as text. The excerpt below shows the 202 Accepted response's Status and the two accepted items. The full response also carries ItemsCount, the counts of items sent, accepted and rejected. For a complete response, see Create a batch payment.

Response (excerpt)
{
  "BatchTransferResponse": {
    "CustomerBatchId": "BATCH-OVERVIEW-0001",
    "Status": "Accepted",
    "Accepted": [
      {
        "CustomerTransactionId": "TXN-OVERVIEW-0002",
        "Amount": 50.0,
        "Currency": "USD",
        "SendMethodId": "XTR94503",
        "RecipientId": "PAT9999888"
      },
      {
        "CustomerTransactionId": "TXN-OVERVIEW-0001",
        "Amount": 100.0,
        "Currency": "USD",
        "SendMethodId": "XTR94500",
        "RecipientId": "SPN8888777"
      }
    ],
    "Rejected": []
  }
}

A rejected item carries CustomerTransactionId, a general error category in Key (for example INVALID_FIELD), an HTTP-style ErrorCode (for example 422), the dot path of the failing field in Field (for example Items[0].Destination.SKU) and a Message. Match rejected items by CustomerTransactionId, not by the index in Field: the index can skip items, some errors name a related field, one item can be listed more than once, and a check sent from a non-USD wallet has an empty Field.

#Wallet-first delivery

Every payment in a batch lands in the recipient's Xtrm wallet first. Xtrm credits the recipient's wallet in the batch's currency. For every method other than a wallet, it then delivers the money from that wallet to the destination you chose, such as a bank account or a card.

  • Delivered: Xtrm credits the wallet, delivers the money to the destination, and the payment ends as Success. A wallet payment (XTR94502, XTR94504) is Success as soon as the wallet is credited. For the other methods, Success means the provider accepted the payment, not that the funds have settled.
  • Retained in wallet: for every method other than a wallet, the payment shows RetainedInWallet while Xtrm delivers the money from the recipient's wallet to the destination, usually only briefly, and moves on to Success when the delivery goes through. Don't act on it while the batch is still Processing. If the payment is still RetainedInWallet once the batch status is final, the delivery didn't go through and the money stays in the recipient's Xtrm wallet: treat it like a wallet payment. The recipient transfers it out, or, if they're connected to your company, you request the transfer for them with their one-time password. You can't retry or resubmit it, and the fee isn't refunded. See When a payment stays RetainedInWallet.

The payment status endpoint reports DeliveryType. On a Success payment it names how the money was delivered, for example Bank or Wallet. On a RetainedInWallet payment it's Wallet, and while a payment is Accepted, Processing or Failed it's an empty string. The batch status endpoint has no DeliveryType on its items.

#Default wallets and banks

You don't have to manage your recipients' wallets yourself:

  • Wallets are created when needed. If you don't send Destination.WalletId and the recipient has no active wallet in the batch's currency, Xtrm creates one named Wallet - <currency code>, for example Wallet - EUR. If the recipient has active wallets in that currency but none of them is a Standard wallet, Xtrm creates none and the payment fails with WALLET_AUTO_CREATE_FAILED.
  • Recipient wallet. Without Destination.WalletId, Xtrm credits the recipient's oldest active Standard wallet in the batch's currency, not the wallet marked as default in the Xtrm web app. WalletId is an integer that every payment method accepts. When you send it, it must be an active wallet of the recipient in the batch's currency, or the payment fails with INVALID_BENEFICIARY_WALLET before any money moves.
  • Wallet-linked bank. On a bank payment (XTR94500), send Destination.BeneficiaryBankID, Destination.WalletId or both. With neither, the item is rejected when you submit. An individual recipient always needs BeneficiaryBankID: without it, the payment fails with BENEFICIARY_BANKID_REQUIRED, and no default bank is used. A business recipient sent without WalletId also needs BeneficiaryBankID. For a business recipient sent with a WalletId, the bank linked to that wallet normally replaces any BeneficiaryBankID you send. If the wallet has no linked bank, the payment fails with DEFAULT_BANK_NOT_FOUND, even when you sent a bank. Your BeneficiaryBankID is used instead only when the wallet allows its linked bank to be overridden. The linked bank and that setting are managed in the Xtrm web app or by Xtrm staff, not through the API.

#Payment methods

A batch can mix methods and recipients freely. Each item carries its own SendMethodId and a Destination with the fields that method needs:

SendMethodIdMethodDestination fields
XTR94500Bank: to the recipient's bank accountBeneficiaryBankID, or for a business recipient a WalletId with a linked bank (see Default wallets and banks). BeneficiaryBankPaymentMethod (optional: ACH, WIRE or RTP; without it, the bank account's primary rail)
XTR94502Wallet: an individual recipient's Xtrm walletWalletId (optional; without it, the recipient's oldest active Standard wallet in the batch's currency). Send {} if you leave it out.
XTR94504Wallet: a business recipient's Xtrm walletWalletId (optional; without it, the recipient's oldest active Standard wallet in the batch's currency). Send {} if you leave it out.
XTR94503Prepaid debit card: a prepaid virtual debit card, for individual recipients onlyEmail and SKU (both required)
XTR94505Digital gift card, for individual recipients onlyEmail and SKU (both required)
XTR94508Rapid Transfer: a push to the recipient's card, USD batches onlyCardToken (required): a US card linked to the recipient as a transfer card
XTR94507Check: a mailed paper check, US only, from a USD walletRequired: BeneficiaryCheckName, BeneficiaryCheckAddress1, BeneficiaryCheckCity, BeneficiaryCheckState, BeneficiaryCheckPostalCode, BeneficiaryCheckCountryCodeISO2, BeneficiaryCheckMemo, BeneficiaryCheckReference. Optional: BeneficiaryCheckAddress2

Take each item's SendMethodId from GetPaymentMethods: a batch accepts exactly its seven IDs, in capitals. Card SKUs come from GetPrepaidCards and GetDigitalGiftCards, and card tokens from GetLinkedCards: use a card whose LinkCardType is transfer. Payment methods & destinations covers each method, where to find every destination value and what Xtrm checks for each one.

#Currency

  • The source wallet sets the currency. The currency of SourceWalletId is the currency of every item in that request, called the batch's currency on this page. Every payment is debited from your wallet and credited to the recipient's wallet in that currency. You don't send a currency, and a Currency field in the request is ignored.
  • Recipient wallets follow it. Wallets that Xtrm creates for recipients are in the batch's currency.
  • Card SKUs must match it. Gift card and prepaid card catalogs vary by currency. A gift card (XTR94505) whose SKU is in another currency fails during processing with CURRENCY_MISMATCH. A prepaid card (XTR94503) whose SKU isn't a prepaid product for the batch's currency fails with SKU_NOT_FOUND, or with CURRENCY_INVALID when there's no prepaid product in that currency at all. Neither is checked when you submit.
  • Banks can differ. When the bank account's currency differs from the batch's, the amount is converted when it's transferred to the bank. Checks and Rapid Transfer need a USD batch.
  • Keep one currency per batch. We recommend funding every request for a CustomerBatchId from the same SourceWalletId, retries included. Xtrm doesn't enforce this: a retried item, or a new item added to a batch that has a Failed payment, takes the currency of the SourceWalletId in its own request, so one batch can hold payments in different currencies. The batch status endpoint reports a single Currency, taken from one of the batch's items, and the payment status endpoint reports each payment's own Currency.

To pay in several currencies, we recommend one batch per currency, each from a wallet in that currency. See Exchange currency to move funds between your wallets.

#Follow a batch

There are two ways to see what happened to a batch:

  • Webhooks. If Xtrm has set up a webhook endpoint for your account, it notifies your server as payments are processed. Use each event as a signal to check the payment, because a webhook's status doesn't always match the payment's status. See Webhooks.
  • Polling. Get the status of a batch payment returns the batch's status and its payments, page by page. Get the status of a payment in a batch returns one payment, with its Currency and DeliveryType. Add history=true to either to get each payment's attempts; without it, Attempts is empty.

Each payment ends Success or Failed, or stays RetainedInWallet when its delivery didn't go through. Before that, it's Accepted, Processing or Verified, and a payment by any method other than a wallet passes through RetainedInWallet on its way to Success. The batch has its own overall status, computed each time you ask: Processing, Completed, CompletedWithFailures or Failed. The batch reads Processing while any delivery is still under way, so a payment that is still RetainedInWallet once the batch status is final has stuck. Batch and payment statuses explains every value, the error code on each failed attempt, and what to do about each status.

#Your IDs, duplicates and retries

Give every batch a CustomerBatchId and every payment a CustomerTransactionId from your own system. Xtrm echoes them in its responses and webhooks, so you can match payments to your own records, and you use them to look up a batch or a payment. Both are required: Xtrm never generates them. A batch without a CustomerBatchId is refused, and an item without a CustomerTransactionId is rejected. The wallet transaction calls don't return these IDs, so put each payment's CustomerTransactionId at the start of its Description to match the payment to its wallet transactions; see Track & reconcile payments. CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID.

Together, the two IDs make a resubmission safe: Xtrm stores each pair at most once, so the same IDs refer to the same payment. To retry a Failed payment, resubmit it under its original IDs. To resend a request that timed out, send it again unchanged. A payment under new IDs is a new payment, and Xtrm pays it.

Retries & idempotency covers the ID format, what each kind of duplicate does and what you can change on a retry, and A safe retry pattern shows how to resend after a timeout.

#Limits

LimitValue
Items per batchSet for your account by Xtrm. The error for a batch over it gives the value as MaxAllowed.
Request sizeA limit in MiB, the same for every account, checked against the Content-Length header. A larger request gets 413 PAYLOAD_TOO_LARGE.
CustomerBatchId, CustomerTransactionId1 to 128 characters. The allowed characters and the other ID rules are in Batch and payment identifiers.
Item Description1,024 characters, counted after Xtrm HTML-encodes it (an & counts as 5)
BeneficiaryCheckMemo150 characters
BeneficiaryCheckReference75 characters

Xtrm sets the item limit for each account. A batch with more items than your limit is refused as a whole with 422 and LIMIT_EXCEEDED, and nothing is stored. The error Message gives your limit: it ends with MaxAllowed: N. To pay more recipients, split the payments into several batches, each with its own CustomerBatchId. Xtrm can also raise your company's limit, up to a maximum that Xtrm sets: ask Xtrm support.

There's no cap on a batch's total amount. During processing, each payment is checked against your company's send limits, and a payment over them fails with SEND_LIMIT_EXCEEDED.

#The batch payment endpoints

All three endpoints take a bearer token scoped to your company's account. See Authentication.

EndpointUse it to
POST /API/v4/Fund/BatchTransferSubmit a batch. Returns 202 Accepted with the accepted and rejected items.
GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}Get a batch's overall status and its payments, page by page with recordsToSkip and recordsToTake.
GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}Get one payment's status, currency and delivery type.

#Next steps