Batch and payment statuses
Statuses tell you where every payment stands. Each payment in a batch has its own status, the batch has an overall status, and each payment keeps a history of its processing attempts, with an error code for every failure.
Xtrm processes batch payments asynchronously (see How batch payments work). When you submit a batch, Xtrm validates it, responds with 202 Accepted, and then processes each payment in the background.
This page lists every status, shows how to read statuses with the two status endpoints, and recommends what to do about each one.
#Where to find statuses
- Status endpoints. The batch status endpoint, Get the status of a batch payment, returns the batch status and a paginated list of its payments. The payment status endpoint, Get the status of a payment, returns a single payment. See Read statuses with the API.
- Webhooks. Xtrm can also notify your server as each payment is processed. Use an event as the signal to check the payment, and book the status the status endpoints return: a webhook's status doesn't always match the payment's status, and no event carries
RetainedInWallet. See Webhooks.
Statuses identify batches and payments by CustomerBatchId and CustomerTransactionId. Both IDs are required when you submit a batch, and Xtrm never generates them, so you can look up any payment straight from your records.
#Payment statuses
Each item in a batch is one payment to one recipient. Every payment lands in the recipient's Xtrm wallet first (see wallet-first delivery). Xtrm credits the wallet, creating one if the recipient has no active wallet in the batch currency, and then delivers the money to the destination you chose, such as a bank account or a card. A payment's status tells you how far that got.
| Status | What it means | Final? |
|---|---|---|
Accepted | The payment passed the checks when you submitted the batch and is stored, waiting to be picked up. | No |
Processing | Xtrm is validating the payment. On the payment status endpoint, Processing also covers Verified. | No |
Verified | The payment passed validation and is waiting for Xtrm to credit the recipient's wallet. Only the batch status endpoint returns Verified; the payment status endpoint shows Processing. | No |
Success | For a wallet method (XTR94502, XTR94504), the recipient's wallet was credited. For every other method, the provider accepted the payment, which doesn't mean it has settled: a bank transfer may not have settled yet, a check has been created but not necessarily printed or mailed, a gift card or prepaid card has been ordered and emailed but not necessarily claimed, and a push-to-card payment (XTR94508) has been approved by the card network. A later return doesn't change the status: if the recipient's bank returns a bank payment, Xtrm credits the money back to your wallet by hand, and no webhook is sent; see Returned bank payments. | Yes |
RetainedInWallet | Xtrm has credited the money to the recipient's Xtrm wallet and is delivering it to the bank account, card, check or gift card. Every bank transfer, push-to-card, check, prepaid card and gift card payment passes through this status, 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 payment stays in this status: see When a payment stays RetainedInWallet. | Once the batch is final |
Failed | The payment failed before any money moved, or when Xtrm tried to debit your wallet and credit the recipient's. The latest attempt's ErrorCode says why. | Yes, until you resubmit the payment |
No payment has the status Completed; Completed is only a batch status (see Batch statuses). The final statuses are Success, Failed, and RetainedInWallet once the batch status is final. While the batch is Processing, RetainedInWallet is still open, like Accepted, Processing and Verified. We recommend treating any value you don't recognize as still open too.
Base your logic on the payment's Status. The Result of an attempt describes that attempt only.
Items that fail the checks when you submit the batch normally come back in the Rejected array of the create response, with the Field and Message that explain why. Xtrm doesn't store them, so they get no attempts. There are two exceptions:
- A
CONFLICT_DUPLICATE_ITEMentry means that the item is already stored in this batch. Follow that item instead of sending it again. - A
202response withStatusFailedandKeyTEMPORARY_ERRORhas an emptyRejectedarray, even for items that failed the checks. Confirm what was stored with the batch status endpoint.
Correct the other rejected items before you send them again. Retry a batch payment says which batch they can go in, and Items rejected at submission explains each rejection code.
#Batch statuses
The batch status endpoint returns one of these values.
| Status | What it means | Final? |
|---|---|---|
Processing | At least one payment is still in progress. | No |
Completed | Nothing is in progress, and every payment is Success. | Yes |
CompletedWithFailures | Nothing is in progress, and some payments didn't succeed. | Yes, but it can change (see below) |
Failed | Nothing is in progress, and every payment failed. | Yes, but it can change (see below) |
The batch status endpoint never returns Accepted. The Status in the create response is different: there, Accepted, CompletedWithFailures or Failed describe only which items passed the checks when you submitted the batch. For example, CompletedWithFailures in a 202 means that some items were rejected, not that anything was paid. A 202 doesn't prove that every item in Accepted was stored, so confirm what was stored with the batch status endpoint.
#How the batch status is derived
Xtrm computes the batch status each time you read the batch, from its own processing records for the payments, not from the payment statuses the endpoint returns.
| What Xtrm finds when you read the batch | Batch status |
|---|---|
| At least one payment passed validation and Xtrm is still processing it. While no payment of the batch has passed validation yet, a payment that is waiting or being validated also counts as in progress. | Processing |
Nothing is in progress, and every payment is Success | Completed |
| Nothing is in progress, and every payment failed | Failed |
Nothing is in progress, in any other case, for example some payments Success and some failed | CompletedWithFailures |
What this means in practice:
Completedmeans every payment isSuccess.- Items rejected when you submitted the batch aren't counted.
- A
RetainedInWalletpayment counts as in progress while Xtrm delivers it or holds its delivery, and as failed once the delivery has failed. So the batch staysProcessinguntil every delivery has finished, and a payment that is stillRetainedInWalletin aCompletedWithFailuresorFailedbatch has stuck.
A batch status that looks final can still change:
- Resubmitting a
Failedpayment reopens the batch. - Once some payments have passed validation, payments still waiting to be validated count as failed, so the batch can briefly read
FailedorCompletedWithFailuresbefore it returns toProcessing.
For example, the batch in Get a batch and its payments reads Completed: all six of its payments are Success, including one whose first attempt failed and which succeeded when it was resubmitted. Had any payment ended Failed, or stuck in RetainedInWallet, the batch would read CompletedWithFailures.
We recommend basing your own logic on payment statuses and treating the batch status as a summary. Before you close out a batch in your records, check that none of its payments is still open.
#Delivery type
The payment status endpoint also returns DeliveryType. The payments in the batch status endpoint don't have it, so request the payment on its own when you need its DeliveryType.
On a Success payment, DeliveryType depends on the payment method. The values contain spaces.
SendMethodId | DeliveryType |
|---|---|
XTR94502, XTR94504 | Wallet |
XTR94500 | Bank |
XTR94503 | Prepaid Virtual Debit Card |
XTR94505 | Digital Gift Cards |
XTR94507 | Bank Check |
XTR94508 | Rapid Transfer |
- On a
RetainedInWalletpayment,DeliveryTypeisWallet, as on a successful wallet payment, both while Xtrm delivers it and once it has stuck, so read it together withStatus. - On an
Accepted,ProcessingorFailedpayment,DeliveryTypeis an empty string.
We recommend storing the DeliveryType of each Success payment in your records.
#Attempts and history
Xtrm records an attempt each time a processing stage records an outcome for a payment. A payment's Attempts array is its history: the result of the first submission and of every resubmission.
| Field | What it holds |
|---|---|
AttemptNo | The submission the attempt belongs to: 1 for the first submission, then one higher for each accepted resubmission. Two attempts can share a number. |
Result | Success or Failed. |
ErrorCode | SUCCESS for a successful attempt, or an error code such as INSUFFICIENT_BALANCE that says why it failed. See Error codes on attempts. |
CreatedAt | On the batch status endpoint, when the attempt's outcome was recorded. On the payment status endpoint, the payment's latest submission time, the same on every attempt. |
CompletedAt | The payment's last update, the same on every attempt. It isn't the time the attempt finished. |
An attempt appears only once a stage records its outcome, so an attempt in progress has no entry yet. Validation records an attempt only when it fails, and a successful wallet credit records one only for a wallet payment, so when a bank transfer, push-to-card, check, prepaid card or gift card payment gets through validation and the wallet credit, its attempt for that submission appears when the delivery finishes.
LastUpdatedAt, CreatedAt and CompletedAt are ISO 8601 date-times with up to seven fractional digits, for example 2026-06-05T20:50:36.2431. Parse them as UTC whether or not they end in Z.
#The history flag
Both status endpoints take an optional history query parameter. Set history=true to get the attempts in Attempts. Without it, or with false, Attempts is []. true and false are accepted in any case.
The batch status endpoint lists attempts newest first, and the payment status endpoint lists them oldest first. Sort them by AttemptNo before you pick the latest one. When two attempts share the highest AttemptNo, neither endpoint orders them reliably: use the batch status endpoint, where CreatedAt is when each attempt was recorded, to tell which came last.
History makes each payment larger in the response. On a large batch, we recommend asking for smaller pages when you turn it on.
#Read statuses with the API
Both status endpoints are GET requests with no body. Authenticate with your access token as for every other call (see Authentication), and identify the batch by its CustomerBatchId and a payment by its CustomerTransactionId.
Both examples below read the example batch BATCH-2026-Q3-01: six payments from source wallet 122181. One of them, TXN-2026-9912A, is a USD 100.00 bank payment to Jane Doe (PAT9999888). Its first attempt failed with INSUFFICIENT_BALANCE because the source wallet couldn't cover it, and it succeeded when it was resubmitted under the same IDs after the wallet was funded.
#Get a batch and its payments
GET /API/v4/Fund/BatchTransfer/{CustomerBatchId} returns the batch status and one page of its payments, each with its own status.
| Query parameter | Type | Description |
|---|---|---|
recordsToSkip | integer | The number of payments to skip, as a 0-based offset. Start with 0. A value past the last payment returns an empty Items. |
recordsToTake | integer | The maximum number of payments to return in this page, for example 50. Without it, a page holds up to your account's maximum; a value over the maximum fails with 422 (LIMIT_EXCEEDED), and the message states the maximum. |
history | boolean | true to include every attempt in each payment's Attempts; otherwise Attempts is []. |
Use your own CustomerBatchId. This request reads the first 50 payments of the example batch with their attempt history:
curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
},
});
const data = await response.json();
console.log(JSON.stringify(data, null, 2));import os
import requests
response = requests.get(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN"));
var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true");
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;
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true"))
.header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN"))
.GET()
.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/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));The response holds:
CustomerBatchId, the batchStatusand the batchCurrency, the three-letter code of the source wallet's currency.ItemsCount: the number of payments stored in the batch, including payments added by later requests. Items rejected when you submitted the batch aren't counted. Here it's a number; in the create response it's an object withTotal,AcceptedandRejectedcounts.Items: the payments in this page, always as an array, each withCustomerTransactionId,Status,RecipientId,SendMethodId,Amount,LastUpdatedAtandAttempts. These items have noCurrencyand noDeliveryType.Amountis the payment amount before fees, as a string with 2 decimals and a thousands separator, for example"1,234.56". Remove the separators before you parse it. After a resubmission, it's the amount of the latest submission.LastUpdatedAtis when the payment was last updated, in UTC. It'snulluntil Xtrm starts processing the payment.
Pagination:HasMoreandNextRecordsToSkip, always present.
The excerpt below shows 3 of the batch's 6 payments, from a history=true response. TXN-2026-9912A lists its two attempts newest first.
{
"CustomerBatchId": "BATCH-2026-Q3-01",
"Status": "Completed",
"Currency": "USD",
"ItemsCount": 6,
"Items": [
{
"CustomerTransactionId": "TXN-2026-9902A",
"Status": "Success",
"RecipientId": "SPN8888776",
"SendMethodId": "XTR94504",
"Amount": "50.00",
"LastUpdatedAt": "2026-06-05T20:49:44.0208205Z",
"Attempts": [
{
"AttemptNo": 1,
"Result": "Success",
"ErrorCode": "SUCCESS",
"CreatedAt": "2026-06-05T20:49:44.0159177Z",
"CompletedAt": "2026-06-05T20:49:44.0208205Z"
}
]
},
{
"CustomerTransactionId": "TXN-2026-9905A",
"Status": "Success",
"RecipientId": "SPN9999888",
"SendMethodId": "XTR94508",
"Amount": "50.00",
"LastUpdatedAt": "2026-06-05T20:49:48.6328481Z",
"Attempts": [
{
"AttemptNo": 1,
"Result": "Success",
"ErrorCode": "SUCCESS",
"CreatedAt": "2026-06-05T20:49:48.6328481Z",
"CompletedAt": "2026-06-05T20:49:48.6328481Z"
}
]
},
{
"CustomerTransactionId": "TXN-2026-9912A",
"Status": "Success",
"RecipientId": "PAT9999888",
"SendMethodId": "XTR94500",
"Amount": "100.00",
"LastUpdatedAt": "2026-06-05T21:15:09.4470000Z",
"Attempts": [
{
"AttemptNo": 2,
"Result": "Success",
"ErrorCode": "SUCCESS",
"CreatedAt": "2026-06-05T21:15:09.4402213Z",
"CompletedAt": "2026-06-05T21:15:09.447Z"
},
{
"AttemptNo": 1,
"Result": "Failed",
"ErrorCode": "INSUFFICIENT_BALANCE",
"CreatedAt": "2026-06-05T20:49:44.6127730Z",
"CompletedAt": "2026-06-05T21:15:09.447Z"
}
]
}
],
"Pagination": {
"HasMore": false,
"NextRecordsToSkip": 0
}
}#Page through the payments
- Request the first page with
recordsToSkip=0and the page size you want inrecordsToTake. - If
Pagination.HasMoreistrue, request the next page withrecordsToSkipset toPagination.NextRecordsToSkip. KeeprecordsToTakeandhistorythe same. - Repeat until
Pagination.HasMoreisfalse.
Decide whether to continue from HasMore alone: on the last page, NextRecordsToSkip is 0. Payments are listed in the order Xtrm stored them: a resubmitted payment keeps its place, and payments added to the batch later come at the end. While a batch is still processing, payment statuses can change between your page requests, so we recommend reading the whole batch again once it reaches a final status.
This endpoint can briefly show changes that are still in progress. Before you act on a payment, for example to submit it again, confirm it with the payment status endpoint, which reads only committed data. A 404 from it doesn't prove that the payment is missing, so read When a status request fails before you submit the payment again.
#Get one payment
GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId} returns a single payment: its status, recipient, payment method, amount, currency, DeliveryType, LastUpdatedAt and, with history=true, its attempts. Use it to check one payment, for example when a webhook arrives or a recipient asks about a payment.
Statususes the same values as the batch status endpoint, except that aVerifiedpayment shows asProcessing.Amountis a plain string with 2 decimals and no thousands separator, for example"1234.56".LastUpdatedAtis when the payment was last updated, in UTC, or when it was submitted if it hasn't been updated yet.
This request reads payment TXN-2026-9912A of the example batch BATCH-2026-Q3-01 with its attempts. Use your own CustomerBatchId and CustomerTransactionId.
curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
},
});
const data = await response.json();
console.log(JSON.stringify(data, null, 2));import os
import requests
response = requests.get(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN"));
var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true");
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;
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true"))
.header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN"))
.GET()
.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/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));In this history=true example, the first attempt failed with INSUFFICIENT_BALANCE at the wallet-credit stage, so nothing was debited. After the source wallet was funded, the payment was resubmitted under the same IDs, and the second attempt succeeded: the payment's Status is Success and its DeliveryType is Bank. Both attempts show the same CreatedAt and CompletedAt, because on this endpoint those are the payment's own times: its latest submission and its last update.
{
"CustomerBatchId": "BATCH-2026-Q3-01",
"CustomerTransactionId": "TXN-2026-9912A",
"Status": "Success",
"RecipientId": "PAT9999888",
"SendMethodId": "XTR94500",
"Amount": "100.00",
"Currency": "USD",
"DeliveryType": "Bank",
"LastUpdatedAt": "2026-06-05T21:15:09.447Z",
"Attempts": [
{
"AttemptNo": 1,
"Result": "Failed",
"ErrorCode": "INSUFFICIENT_BALANCE",
"CreatedAt": "2026-06-05T21:15:02.1180436Z",
"CompletedAt": "2026-06-05T21:15:09.447Z"
},
{
"AttemptNo": 2,
"Result": "Success",
"ErrorCode": "SUCCESS",
"CreatedAt": "2026-06-05T21:15:02.1180436Z",
"CompletedAt": "2026-06-05T21:15:09.447Z"
}
]
}#When a status request fails
A failed status request returns a body with StatusCode and Message, plus an ErrorKey for 400, 413 and 422, and a token problem returns error and error_message instead. Errors when you check status lists every failure and its cause.
A 404 from either status endpoint doesn't prove that a batch or a payment is missing. When the database read behind the check fails, both endpoints return the same 404 as for an unknown ID: Unknown CustomerBatchId. from the batch endpoint, and that message or CustomerTransactionId not found within the specified batch. from the payment endpoint. Right after a submit call times out, the payment endpoint can also return 404 while the original request is still storing the batch. Repeat the check a few times, at least a minute apart, before you conclude that a payment wasn't stored. Until then, resend only under the same CustomerBatchId and the same CustomerTransactionId values: Xtrm's duplicate check works only within one CustomerBatchId, so it protects a resend under the original IDs and never one under new IDs. A safe retry pattern says how to submit a payment that you've confirmed wasn't stored.
A 409 CONFLICT_PROCESSING on a resend of a batch of more than 500 payments doesn't prove that every payment was stored; see A safe retry pattern.
#What to do for each status
We recommend handling payment statuses like this:
| Payment status | What to do |
|---|---|
Accepted, Processing, Verified | Wait for a webhook, if Xtrm has set up webhooks for your account, or check again later. When polling, we recommend increasing the interval between calls rather than polling in a tight loop. Don't resubmit the payment: only a Failed payment can be retried (see Retry a batch payment). If a payment stays open for longer than you expect (compare the payment status endpoint's LastUpdatedAt with the current time), contact Xtrm support with the CustomerBatchId and CustomerTransactionId. |
Success | Record the payment as paid, with its DeliveryType and LastUpdatedAt. Don't submit it again: under the same IDs Xtrm doesn't pay it again, but under new IDs it's paid twice. |
RetainedInWallet | While the batch is Processing, wait: the delivery is still under way, and the payment normally moves on to Success. Once the batch is final, record the payment as final and follow When a payment stays RetainedInWallet. At either stage, don't submit it again: under the same IDs Xtrm doesn't accept it, and under new IDs it's paid a second time. |
Failed | Read the latest attempt's ErrorCode (see Error codes on attempts), fix the cause, and resubmit the payment. If the code is TEMPORARY_ERROR, check with Xtrm support first. |
| Anything else | Treat the payment as still open and flag it for review, instead of treating it as paid or failed. |
Whether you use webhooks or polling, we recommend confirming final statuses with the status endpoints before you close out a batch in your own records. See Event order and Retries and duplicates for how events arrive.
#When a payment stays RetainedInWallet
Every bank transfer, push-to-card, check, prepaid card and gift card payment is credited to the recipient's Xtrm wallet first, and shows RetainedInWallet while Xtrm delivers it from there to the destination. When the delivery goes through, the payment moves on to Success, so for most payments the status lasts only briefly. You'll see payments enter RetainedInWallet as they pass through, so don't act on the status as soon as you see it: wait to see whether the payment moves on or stays.
The batch status tells you which, because Xtrm counts a delivery as in progress until it finishes:
- The batch is
Processing: the delivery is still under way, so wait. Until it finishes, the payment'sDeliveryTypeisWallet, itsLastUpdatedAtis the time of the wallet credit, and its current submission has no attempt yet, because a successful wallet credit records an attempt only for wallet payments. - The payment moves on to
Success: the delivery went through. ItsDeliveryTypenames the rail, for exampleBank, and its newest attempt isSuccess. - The batch is
CompletedWithFailuresorFailed, and the payment is stillRetainedInWallet: the delivery didn't go through, and the payment has stuck. Xtrm doesn't try the delivery again. Request the payment withhistory=true: its newest attempt hasResultFailedand anErrorCodethat says why, for exampleRETAINED_IN_WALLETwhen the provider didn't accept the payment, orINSUFFICIENT_FUNDS_RUNTIMEwhen the recipient's wallet no longer held the amount (see Delivery stage).
When the batch status leaves Processing, read it again after a short pause before you act, because the batch status endpoint can briefly show changes that are still in progress. Go by the batch status, and use the attempts for the reason: a resubmitted payment keeps the Failed attempts of its earlier submissions, so its newest attempt can read Failed while the new delivery is still under way.
When Xtrm holds a delivery. If the batch stays Processing and a payment stays RetainedInWallet with no new attempt and an unchanged LastUpdatedAt, Xtrm is holding the delivery, for example for a compliance review or because the provider couldn't take it. It stays that way until Xtrm support resolves it. The payment then moves on to Success, or stays RetainedInWallet with a Failed attempt. Meanwhile the money is reserved in the recipient's wallet and can't be transferred out. If a payment stays like this for more than one business day, contact Xtrm support with the CustomerBatchId and CustomerTransactionId.
When a payment has stuck, treat it like a wallet payment. The money is in the recipient's Xtrm wallet, in the batch currency, and reaches the recipient's bank account or card in one of two ways:
- The recipient moves it. The recipient signs in to the Xtrm web app and transfers the money out of their wallet. If you sent the batch with
EmailNotificationset totrue, Xtrm emailed them when the money reached their wallet, before the delivery was tried. - Your company requests the transfer for them. Call
UserWithdrawFundfor an individual recipient orBeneficiaryCompanyWithdrawFundfor a business recipient. Each transfer needs a one-time password that Xtrm sends to the recipient, and your company must be connected to the recipient's account.
Either way, the transfer is a new transaction from the recipient's wallet, separate from the batch payment. You can't retry the payment as a batch payment: under the same IDs Xtrm doesn't accept it, and under new IDs it's paid a second time. The fee you paid for the payment isn't refunded: Xtrm charges it when it credits the recipient's wallet, and a delivery that doesn't go through doesn't reverse that charge. If the recipient doesn't see the money in their wallet, contact Xtrm support with the CustomerBatchId and CustomerTransactionId.
#Resubmit failed payments
To retry a Failed payment, submit it again with Create a batch payment, under the same CustomerBatchId and CustomerTransactionId and with every field. Xtrm queues the payment again, and its next attempt gets the next AttemptNo; the earlier attempts stay in its history. Only a Failed payment can be resubmitted. Retry a batch payment covers what happens to payments in every other status, which fields you can change, and when a corrected destination takes effect.
To follow a resubmitted payment, read its history: request it with history=true on either status endpoint. Its Status shows where it stands, and the attempts of the resubmission carry the new AttemptNo, as in Get one payment.
If a submit call times out, don't build a new batch: follow A safe retry pattern.
#Error codes on attempts
When an attempt fails, its ErrorCode says why. For failures at the validation and wallet-credit stages, the Batch.Item.Failed webhook carries the same code; a failed delivery doesn't send Batch.Item.Failed (see Events for a delivery). The tables below list the codes that Xtrm's processing stages record, grouped by stage, with what each one means and what we recommend doing about it. SUCCESS marks a successful attempt.
These codes come from processing, after Xtrm accepted the item. For the errors in the Rejected array of the create response, and for errors on other calls, see Errors.
Some codes, such as SKU_NOT_FOUND, INVALID_CARD_AMOUNT and TEMPORARY_ERROR, can come from more than one stage. On a Failed payment, the latest attempt comes from the validation or wallet-credit stage.
We recommend treating any code you don't recognize as a failure that needs review: log it with the payment's CustomerBatchId and CustomerTransactionId, flag the payment, and don't retry it automatically.
#Validation stage
Xtrm checks the recipient, wallet, destination and payment method. A failure here leaves the payment Failed, and nothing is debited. You can resubmit the payment under the same IDs after you fix the cause.
| Code | Meaning | What to do |
|---|---|---|
RECIPIENT_NOT_FOUND | The RecipientId doesn't match an account, or the account's status is something other than active, email not verified or pending approval, for example closed or suspended. | Check the RecipientId (PAT… or SPN…) against your individual recipients and business recipients. You can also look up an account number by email with CheckUserExist, or by the company's email domain or name with CheckBeneficiaryExist. If the account is closed or suspended, check with the recipient or Xtrm support. If the ID was wrong, or you had to create the recipient (with CreateUser or CreateBeneficiary), pay the correct account number as a new item with a new CustomerTransactionId. Don't resubmit the old item with a corrected RecipientId: Xtrm would apply the change, but a different recipient should be a new payment with its own ID. |
INVALID_BENEFICIARY_WALLET | The WalletId you sent isn't an active wallet of the recipient in the batch currency. | Look up the recipient's wallets with GetUserWallets for an individual recipient or GetBeneficiaryWallets for a business recipient, or leave WalletId out so that Xtrm uses the recipient's oldest active Standard wallet in the batch currency, or creates one if the recipient has no active wallet in that currency. For a bank transfer (XTR94500), send a BeneficiaryBankID when you leave WalletId out. Then resubmit. |
SENDMETHODID_NOT_FOUND | The payment method doesn't fit the recipient: individual wallet (XTR94502), prepaid card (XTR94503) and gift card (XTR94505) payments need an individual (PAT…) recipient, and business wallet (XTR94504) payments need a business (SPN…) recipient. | Pay the recipient with a method that fits, as a new item with a new CustomerTransactionId. |
BENEFICIARY_BANKID_REQUIRED | A bank transfer (XTR94500) has no BeneficiaryBankID, and it needs one: an individual recipient always does, and so does a business recipient sent without WalletId. | Send the BeneficiaryBankID of one of the recipient's linked bank accounts from GetLinkedBankAccounts, then resubmit. |
DEFAULT_BANK_NOT_FOUND | A bank transfer for a business recipient was sent with a WalletId, and that wallet has no linked bank. This also happens when you sent a BeneficiaryBankID, if the wallet is set to use its own linked bank. | Have a bank linked to that wallet, or leave WalletId out and send the BeneficiaryBankID, then resubmit. |
BANKID_INVALID | The BeneficiaryBankID, or the bank linked to the wallet you sent, isn't a pending or approved bank account of the recipient: for example, it's mistyped, deleted or belongs to someone else. | Check that BeneficiaryBankID is one of the recipient's linked bank accounts, using GetLinkedBankAccounts. Then resubmit. |
BANK_NOT_FOUND | The bank provider doesn't recognize the bank account, or an error occurred while Xtrm checked it. | Check the bank account with the recipient, then resubmit. Contact Xtrm support if the failure repeats. |
INVALID_PAYMENTMETHOD | The BeneficiaryBankPaymentMethod you asked for isn't allowed for this bank account. | Ask for a rail the bank account supports, or leave BeneficiaryBankPaymentMethod out to use the bank account's primary rail, then resubmit. |
TOKEN_NOT_FOUND | The push-to-card CardToken isn't an active transfer card linked to the recipient's account: for example, it's an identity card, someone else's card, or a deleted card. | Get the recipient's current transfer card token from GetLinkedCards and resubmit. |
SKU_NOT_FOUND | For a gift card (XTR94505), the SKU isn't in Xtrm's catalog. For a prepaid card (XTR94503), it isn't one of the prepaid products for the batch currency. | Look up a valid SKU in the batch currency with GetPrepaidCards or GetDigitalGiftCards, then resubmit with the new SKU. |
INVALID_CARD_AMOUNT | The Amount doesn't fit the card: a fixed-value card needs exactly its face value, and a variable-value card needs an amount between its minimum and maximum. | Resubmit with an amount the card allows. |
CURRENCY_INVALID | No prepaid card product exists for the batch currency. | Pay the recipient with another method, as a new item with a new CustomerTransactionId. |
CURRENCY_MISMATCH | The gift card's currency doesn't match the batch currency, which is the currency of your source wallet, or the card isn't a gift card or donation product. A push-to-card (XTR94508) or check (XTR94507) payment that isn't in USD also fails with this code. | For a gift card, choose a SKU in the batch currency and resubmit with the new SKU. For push to card or a check, pay from a USD source wallet, as a new item with a new CustomerTransactionId. |
COUNTRY_UNSUPPORTED | The check's BeneficiaryCheckCountryCodeISO2 isn't US. | Xtrm mails checks in the US only. Pay the recipient with another method, as a new item. |
INTERNAL_SERVICE_ERROR | An unexpected error occurred during validation. | Resubmit later, and contact Xtrm support if the failure repeats. |
#Wallet-credit stage
Xtrm checks your send limits and your source wallet's balance, debits your source wallet for Amount plus the fee, and credits the recipient's wallet. A failure here leaves the payment Failed. Your source wallet isn't debited, except possibly with TEMPORARY_ERROR.
| Code | Meaning | What to do |
|---|---|---|
SEND_LIMIT_EXCEEDED | The payment would exceed one of your account's send limits. Earlier payments, including ones from the same batch, count toward the limits. | Resubmit once your limits allow it. Contact Xtrm support about your limits. |
INSUFFICIENT_BALANCE | Your source wallet's balance was below Amount plus the fee when Xtrm processed the payment. Nothing was debited. The balance isn't checked when you submit the batch. | Fund your wallet, then resubmit. We recommend checking the balance with GetCompanyWallets before you submit a batch. |
SENDMETHODID_NOT_FOUND | Xtrm couldn't determine a fee type for the payment method. | Contact Xtrm support. |
WALLET_AUTO_CREATE_FAILED | You didn't send a WalletId, and the recipient has wallets in the batch currency but no active Standard one, so Xtrm neither picked nor created a wallet. | Resubmit with the WalletId of an active wallet of the recipient in the batch currency, or contact Xtrm support. |
SEND_FAILED | Xtrm's credit to the recipient's wallet returned errors. | Resubmit. |
TEMPORARY_ERROR | An unexpected error occurred. The money may already have moved. | Check with Xtrm support before you resubmit, so that the payment isn't made twice. |
#Delivery stage
After the recipient's wallet is credited, Xtrm delivers the payment from that wallet to the destination, and the payment shows RetainedInWallet until the delivery finishes. Wallet payments (XTR94502, XTR94504) have no delivery stage. A failure here records a Failed attempt with one of the codes below, and the payment stays RetainedInWallet: it has stuck, and the batch counts it as failed. The money has left your wallet, the fee isn't refunded, and the money is in the recipient's Xtrm wallet, so you can't retry or resubmit the payment. Whatever the code, the next step is the same: treat the payment like a wallet payment, as described in When a payment stays RetainedInWallet. The codes tell you why the delivery didn't go through, which helps when you choose a destination for the recipient's transfer.
| Code | Meaning |
|---|---|
INSUFFICIENT_FUNDS_RUNTIME | The recipient's wallet balance was below Amount when the delivery started. It doesn't refer to your source wallet. |
RETAINED_IN_WALLET | The bank provider declined the payment or returned an error. |
TEMPORARY_ERROR | An error occurred during a bank delivery, or a check, card or push-to-card delivery was declined or failed. |
SKU_NOT_FOUND, INVALID_CARD_AMOUNT | For a gift card, the card no longer passed Xtrm's catalog check. For a prepaid card, no prepaid product was available for the batch currency (SKU_NOT_FOUND). |
Invalid payment method | The rail wasn't available when the delivery started. This code is a literal string with spaces. |
PREVIOUS_TRANSFER_IN_PROGRESS | An earlier transfer was still using the recipient's wallet. |