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
| Stage | What happens | What you see |
|---|---|---|
| 1. Submit | You 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. Notify | If 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.
Don't overlap requests for one batch
Never have two requests for the same CustomerBatchId in flight at once. Wait for the response, or after a timeout follow A safe retry pattern, before you send that batch again. Xtrm accepts requests for different batches at the same time, and processes the payments funded by one source wallet one at a time.
#What's in a batch
A batch payment is one JSON object: a few batch-level fields and an Items array.
| Field | Required | What it is |
|---|---|---|
IssuerAccountNumber | Yes | Your company's Xtrm account number (SPN…), which owns the source funds. |
SourceWalletId | Yes | The 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. |
CustomerBatchId | Yes | Your 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. |
EmailNotification | No | A 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. |
Items | Yes | The payments in the batch, one item each. |
Each item says who gets paid, how much and how:
| Field | Required | What it is |
|---|---|---|
CustomerTransactionId | Yes | Your ID for the payment. Xtrm never generates one. |
RecipientId | Yes | The 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. |
Amount | Yes | A 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. |
SendMethodId | Yes | The payment method, for example XTR94500 (bank). See Payment methods. |
Destination | Yes | Where the payment goes. Which fields apply depends on SendMethodId. It's required for every method: for a wallet payment without a WalletId, send {}. |
Description | No | A 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"
}
}
]
}'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
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',
},
},
],
}),
});
const data = await response.json();
console.log(JSON.stringify(data, null, 2));import os
import requests
response = requests.post(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
json={
"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",
},
},
],
},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN"));
var json = """
{
"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"
}
}
]
}
""";
var response = await client.PostAsync(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer",
new StringContent(json, Encoding.UTF8, "application/json"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String json = """
{
"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"
}
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer"))
.header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());<?php
$ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'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',
],
],
],
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));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.
{
"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) isSuccessas soon as the wallet is credited. For the other methods,Successmeans the provider accepted the payment, not that the funds have settled. - Retained in wallet: for every method other than a wallet, the payment shows
RetainedInWalletwhile Xtrm delivers the money from the recipient's wallet to the destination, usually only briefly, and moves on toSuccesswhen the delivery goes through. Don't act on it while the batch is stillProcessing. If the payment is stillRetainedInWalletonce 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.WalletIdand the recipient has no active wallet in the batch's currency, Xtrm creates one namedWallet - <currency code>, for exampleWallet - 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 withWALLET_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.WalletIdis 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 withINVALID_BENEFICIARY_WALLETbefore any money moves. - Wallet-linked bank. On a bank payment (
XTR94500), sendDestination.BeneficiaryBankID,Destination.WalletIdor both. With neither, the item is rejected when you submit. An individual recipient always needsBeneficiaryBankID: without it, the payment fails withBENEFICIARY_BANKID_REQUIRED, and no default bank is used. A business recipient sent withoutWalletIdalso needsBeneficiaryBankID. For a business recipient sent with aWalletId, the bank linked to that wallet normally replaces anyBeneficiaryBankIDyou send. If the wallet has no linked bank, the payment fails withDEFAULT_BANK_NOT_FOUND, even when you sent a bank. YourBeneficiaryBankIDis 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:
SendMethodId | Method | Destination fields |
|---|---|---|
XTR94500 | Bank: to the recipient's bank account | BeneficiaryBankID, 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) |
XTR94502 | Wallet: an individual recipient's Xtrm wallet | WalletId (optional; without it, the recipient's oldest active Standard wallet in the batch's currency). Send {} if you leave it out. |
XTR94504 | Wallet: a business recipient's Xtrm wallet | WalletId (optional; without it, the recipient's oldest active Standard wallet in the batch's currency). Send {} if you leave it out. |
XTR94503 | Prepaid debit card: a prepaid virtual debit card, for individual recipients only | Email and SKU (both required) |
XTR94505 | Digital gift card, for individual recipients only | Email and SKU (both required) |
XTR94508 | Rapid Transfer: a push to the recipient's card, USD batches only | CardToken (required): a US card linked to the recipient as a transfer card |
XTR94507 | Check: a mailed paper check, US only, from a USD wallet | Required: 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
SourceWalletIdis 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 aCurrencyfield 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) whoseSKUis in another currency fails during processing withCURRENCY_MISMATCH. A prepaid card (XTR94503) whoseSKUisn't a prepaid product for the batch's currency fails withSKU_NOT_FOUND, or withCURRENCY_INVALIDwhen 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
CustomerBatchIdfrom the sameSourceWalletId, retries included. Xtrm doesn't enforce this: a retried item, or a new item added to a batch that has aFailedpayment, takes the currency of theSourceWalletIdin its own request, so one batch can hold payments in different currencies. The batch status endpoint reports a singleCurrency, taken from one of the batch's items, and the payment status endpoint reports each payment's ownCurrency.
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
CurrencyandDeliveryType. Addhistory=trueto either to get each payment's attempts; without it,Attemptsis 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
| Limit | Value |
|---|---|
| Items per batch | Set for your account by Xtrm. The error for a batch over it gives the value as MaxAllowed. |
| Request size | A limit in MiB, the same for every account, checked against the Content-Length header. A larger request gets 413 PAYLOAD_TOO_LARGE. |
CustomerBatchId, CustomerTransactionId | 1 to 128 characters. The allowed characters and the other ID rules are in Batch and payment identifiers. |
Item Description | 1,024 characters, counted after Xtrm HTML-encodes it (an & counts as 5) |
BeneficiaryCheckMemo | 150 characters |
BeneficiaryCheckReference | 75 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.
| Endpoint | Use it to |
|---|---|
POST /API/v4/Fund/BatchTransfer | Submit 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
Get a sandbox token and make your first payment.
GuideCreate a batch paymentBuild a batch, submit it and track every payment to its outcome.
Batch paymentsBatch and payment statusesWhat each batch, payment and attempt status means.
Batch paymentsWebhooksReceive batch and payment events and verify their signatures.
Batch paymentsRetries & idempotencyUse your batch and payment IDs to retry without paying twice.
Batch paymentsPayment methods & destinationsThe fields each payment method needs and where to find them.