Support
For any question about the Xtrm API or your batch payments, email [email protected]. This page tells you who else to contact, what to check first and what to send so Xtrm can find your batch quickly. It helps when you're waiting for sandbox access or webhooks, or seeing a batch or payment status you don't expect.
#Contact Xtrm
| Contact | Use it for |
|---|---|
| [email protected] | Any question about the Xtrm API and batch payments: sandbox access, IP approval, turning on webhooks, integration questions, and batches or payments you can't explain. Also feedback and requests, and access to API calls that need special access rights. |
| Your Account Manager or Customer Success Manager | Turning on webhooks: give them the URL of your webhook endpoint, and Xtrm support takes it from there. |
#Turn on webhooks
Xtrm can notify your server with webhooks (Batch.Started, Batch.Item.Processing, Batch.Item.Completed, Batch.Item.Failed, Batch.Completed and Batch.Failed), signed with HMAC-SHA256 in X-Signature. There's one endpoint per company account, in the sandbox and in production. Webhooks are set up by hand, with the help of Xtrm support. To set one up, send your endpoint URL to [email protected] or to your Account Manager or Customer Success Manager.
We recommend including these details in your request:
- Your company's account number (
IssuerAccountNumber), such asSPN1111222. - The environment the endpoint is for: sandbox or production.
- The URL of your endpoint. Register an
httpsURL: Xtrm doesn't check the scheme for you.
Xtrm support sets up the endpoint and its signing secret with you when it configures the webhook, and you use the secret to verify every delivery. To rotate the secret, contact Xtrm support and agree a switch-over time. Xtrm replaces the secret in one step, so during the switch-over, accept a delivery that verifies with either the old or the new secret.
Xtrm records events only while your company's webhook subscription is active, so have Xtrm set up your endpoint before you submit the batches you want events for. Follow your batches with the batch status and payment status endpoints whether or not webhooks are on. No webhook carries the status RetainedInWallet, so confirm final statuses with the status endpoints. See Webhooks for the payloads, signature verification and retries, and for how to build a receiver.
#Sandbox access and IP approval
The Xtrm team completes two steps of your sandbox setup for you:
- Account approval. After you sign up and click the validation link in your email, the Xtrm team approves your sandbox company account and completes its setup.
- IP approval. In the sandbox web app, go to Settings > Integrations > Get Credentials to get your API credentials and request the IP addresses you want allowlisted. The Xtrm team approves the IP addresses and then adds test funds to your sandbox wallets.
If either step is taking longer than you expect, email [email protected]. Sandbox & environments covers signup and allowlisting in full.
#Batch size limits
Xtrm sets the maximum number of items in a batch for each account. A batch over it is refused with 422 LIMIT_EXCEEDED, and the message ends with your limit (MaxAllowed: N). The request body also has a size limit, the same for every account: Xtrm refuses a request whose Content-Length header exceeds it with 413 PAYLOAD_TOO_LARGE. Xtrm staff can set a higher items-per-batch limit for your company, within a maximum Xtrm sets. To request a higher limit, email [email protected] or ask your Account Manager.
#Going live
After you finish testing in the sandbox, Xtrm holds a call with its ops team to verify that you're ready for production. Send questions about going live to [email protected].
You get production credentials in your live company account, the same way as in the sandbox, and request your production IP addresses there. The production token URL is https://xapi.xtrm.com/oAuth/token. We also recommend registering your production webhook URL as part of the same process. See Sandbox & environments for the full checklist.
#Before you contact support
These checks answer many common questions.
#Batch payments and payments
| What you see | Check first |
|---|---|
202 Accepted, but the payments haven't arrived | 202 Accepted confirms only that Xtrm took the payments listed in Accepted for processing; it isn't proof that each one was stored. Payments in Rejected aren't processed, and a 202 doesn't mean the accepted payments will succeed. Xtrm processes the queued payments in the background (see How batch payments work), so follow them with the batch status and payment status endpoints. Webhooks can tell you sooner, but confirm final statuses with the status endpoints. The batch endpoint can briefly show changes that aren't saved yet, so confirm a single payment with the payment endpoint before you act on it. |
Payments listed in Rejected | Read each entry's Key first. A validation rejection (INVALID_FIELD, DUPLICATE_ITEM_IN_REQUEST or CURRENCY_MISMATCH) explains what failed in its Message, and usually names the field in Field. That payment isn't stored and gets no attempts, so after you correct it you can resubmit it with the same CustomerTransactionId (for DUPLICATE_ITEM_IN_REQUEST, use each ID for one payment only). Put it in a new batch with a new CustomerBatchId, unless the original batch stored nothing or has a Failed payment; otherwise the whole request gets 409 CONFLICT_PROCESSING. A CONFLICT_DUPLICATE_ITEM entry means the payment is already stored: don't resubmit it, follow it. For a TEMPORARY_ERROR entry, first confirm with the payment status endpoint that the payment isn't stored, and repeat the check a few times, at least a minute apart, because a 404 from it doesn't prove the payment is missing; see A safe retry pattern. |
The whole request is rejected with 422 | Either a batch-level field failed validation or every payment was rejected, so nothing was stored. Check that IssuerAccountNumber is present and starts with SPN, that SourceWalletId and CustomerBatchId are present and valid, and that Items isn't empty or over your batch limit (LIMIT_EXCEEDED). |
401 or 403 on the whole request | 401 with an error such as invalid_token means the bearer token is missing, invalid or expired, or the request came from an IP address that isn't on your allowlist: get a new token and check the allowlist. 401 with Key Unauthorized means your token can't act for IssuerAccountNumber. 403 (FORBIDDEN) means SourceWalletId isn't an active wallet of IssuerAccountNumber itself; a wallet that another company shares with you doesn't qualify. |
A payment's Status is Failed | Get the payment with history=true and read the ErrorCode of the attempt with the highest AttemptNo, for example BANKID_INVALID on a bank transfer payment, SKU_NOT_FOUND on a card payment or RECIPIENT_NOT_FOUND. For what each code means and what to do, see Error codes on attempts. Fix the cause, then resubmit only that payment under its original CustomerBatchId and CustomerTransactionId, with every field: a retry replaces the whole stored item, and Xtrm keeps the earlier attempts. To follow the resubmitted payment, get it again with history=true and read its newest attempt. Keep its RecipientId and SendMethodId. Xtrm would apply a change without an error, so pay a different recipient or method as a new payment with a new CustomerTransactionId, in a new batch. After a failure at the wallet-credit stage, such as INSUFFICIENT_BALANCE, a changed Destination isn't used. If the newest attempt's code is TEMPORARY_ERROR, contact Xtrm support before you resubmit: the money may already have moved. See how to resubmit failed payments. |
A payment's Status is RetainedInWallet | Check the batch status first. RetainedInWallet is a pass-through status for bank, push-to-card, check, prepaid card and gift card payments: while the batch is Processing, Xtrm is still delivering the payment, so wait. If the payment is still RetainedInWallet once the batch is final, the delivery didn't go through, the money stays in the recipient's Xtrm wallet, and the fee isn't refunded. Don't resubmit it at either stage: that returns CONFLICT_DUPLICATE_ITEM or 409 CONFLICT_PROCESSING. The recipient signs in to the Xtrm web app to move the money out, or your company requests the transfer with the recipient's one-time password, which needs a connection. If the batch stays Processing for more than one business day with the payment RetainedInWallet, no new attempt and an unchanged LastUpdatedAt, Xtrm is holding the delivery: contact Xtrm support with the CustomerBatchId and CustomerTransactionId. See When a payment stays RetainedInWallet. |
| A credit in your wallet that you don't recognize | It can be a bank payment that the recipient's bank returned after the payment reached Success. Xtrm credits that money back to your wallet by hand, as a separate Credit with a note from Xtrm as its Description; the payment stays Success, and no webhook is sent. Xtrm emails you the reason and the original transaction ID. See Returned bank payments. |
A payment's Status is Verified | The payment passed validation and is waiting for the wallet credit. Only the batch status endpoint shows Verified; the payment endpoint shows the same payment as Processing. Treat it as in progress. See payment statuses. |
| You don't know whether Xtrm received a batch | Wait, then resend exactly the same body with the same CustomerBatchId and CustomerTransactionId values: Xtrm never stores an item twice. A 409 CONFLICT_PROCESSING, or CONFLICT_DUPLICATE_ITEM entries in Rejected, mean the first request got through, so follow the batch. For a batch of more than 500 payments, a 409 CONFLICT_PROCESSING doesn't prove that every payment was stored, so check each one as A safe retry pattern describes. Never have two requests for the same CustomerBatchId in flight at once. See Retries & idempotency. |
A 409 response | Read the body of the 409 to see which code it carries. CONFLICT_PROCESSING as the top-level Key means the CustomerBatchId is already in use, in your account or another one, and has no Failed payment, so Xtrm stored nothing. Follow that batch, and put new payments in a new batch with a new, unique CustomerBatchId. CONFLICT_DUPLICATE_ITEM in Rejected means that payment already exists in the batch with a status other than Failed, so it isn't stored again. A CustomerTransactionId reused in a different batch isn't refused: it's paid again, so give every new payment a new ID. Don't send a retried payment with a new ID. |
| The batch status lists only some payments | Payments come back a page at a time. When Pagination.HasMore is true, send Pagination.NextRecordsToSkip as recordsToSkip to get the next page. |
| A field is ignored or rejected | Compare every field name with the batch payments reference, character by character: Xtrm matches batch field names without regard to case, but silently ignores a misspelled field. Send SourceWalletId and Destination.WalletId as integers, Amount as a number and EmailNotification as a boolean, for example 122181, 122311, 100 and true. Destination fields that don't apply to the payment's SendMethodId are discarded. |
| You're looking for sandbox test values | The sandbox works the same as production and runs the same batch payment processing. For cards, use the standard test numbers, such as Visa 4111111111111111 or Mastercard 5555555555554444, with a future expiry date and a three-digit CVV. Bank, routing and IBAN numbers and SKUs work the same as in production, with no sandbox-only values. There are no test bank accounts: use a real bank's routing number or SWIFT-BIC with a made-up account number in the right format, as Test bank accounts describes. Never use real financial data in the sandbox. Some failures are predictable, in the sandbox as in production: an unknown or inactive RecipientId, a BeneficiaryBankID that isn't linked to the recipient, an amount above your balance, an unknown SKU, and a check outside the US or from a non-USD wallet. See Sandbox & environments. |
#Webhooks
| What you see | Check first |
|---|---|
| No webhooks arrive | Make sure Xtrm has turned webhooks on for your endpoint URL in the environment you're using; see Turn on webhooks. Webhooks work the same way in the sandbox as in production. Check that the endpoint is reachable from the internet at the URL you registered. If your logs show deliveries that your endpoint answered with an error, fix the endpoint; Retries and duplicates explains how Xtrm retries them. In the meantime, follow the batch with the batch status endpoint. |
| Missing events for a batch from before webhooks were turned on | Xtrm records events only while your company has an active subscription, so don't count on events for a batch that Xtrm finished processing before then. A batch still being processed at the time, for example with a delivery Xtrm is holding, can be missing some. Follow those batches with the batch status and payment status endpoints. See Enable webhooks. |
| The same event arrives more than once | The same webhook event can be delivered more than once, and the same outcome can also arrive as two separate events ; see Retries and duplicates for how to skip repeats. |
| A signature doesn't verify | Follow Verify the signature step by step: it explains what Xtrm signs and has verification code for every language. |
#Gather the details
Before you write to Xtrm, get the current status of the affected payment with its full attempt history. Set history to true.
The samples read payment TXN-2026-9912A of the example batch BATCH-2026-Q3-01. Use your own CustomerBatchId and CustomerTransactionId. The response below is the example response for that payment.
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));The response has the values support needs: the payment's Status, DeliveryType and LastUpdatedAt, and every attempt with its Result and ErrorCode:
{
"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"
}
]
}On the payment endpoint, every attempt repeats the payment's latest submission time as CreatedAt and its last update as CompletedAt, so order the attempts by AttemptNo.
For a problem with several payments, call Get the status of a batch payment with history=true instead, and page through all of its payments.
#What to include in a support request
Send as many of these details as you have:
| Detail | Example |
|---|---|
| Environment | Sandbox (https://xapisandbox.xtrm.com) or production (https://xapi.xtrm.com) |
| Endpoint | Method and path, such as POST /API/v4/Fund/BatchTransfer or GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId} |
| Request time | Date, time and time zone of the request, taken from your own logs. We recommend UTC. For a processing problem, also include the payment's LastUpdatedAt and each attempt's CreatedAt and CompletedAt. |
| Your company account | The IssuerAccountNumber and SourceWalletId you sent, such as SPN1111222 and 122181 |
| Batch payment | The CustomerBatchId, such as BATCH-SUPPORT-0001, and the batch Status, such as CompletedWithFailures |
| Payments | The CustomerTransactionId of each affected payment, such as TXN-SUPPORT-0001, with its RecipientId, SendMethodId, Amount and Status |
| Attempts | The payment's Attempts from a status call with history=true: each AttemptNo, Result and ErrorCode |
| Create response | The HTTP status, the body's Status, ItemsCount and every Rejected entry (Key, ErrorCode, Field and Message), plus the top-level Key, ErrorCode and Message if the whole request failed, or error and error_message for a token error |
| Webhook events | The event type, such as Batch.Item.Failed, when it arrived at your endpoint, and the HTTP status your endpoint returned |
| Request and response | Both bodies, sanitized as described below |
| Expected and actual | What you expected to happen and what happened instead, and whether you have already resubmitted the batch |
If you can reproduce the problem in the sandbox, say so and send the sandbox request. The sandbox holds only test data.
Never send credentials
Remove your client_secret, any access_token or refresh_token, the Authorization header and your webhook signing secret from everything you send, including logs and screenshots. Response bodies can hold credentials too: for a company with manager services, CreateBeneficiary returns your pseudo credentials for the new company in ClientID and SecretKey , and gift card and prepaid card transfers with UserWithdrawFund return reward credentials in RedemptionDetails.Reward, such as a PIN and serial number or a redemption link and digital token. Remove the whole Reward object. Prepaid virtual debit card and digital gift card payments in a batch deliver their credentials to the Destination.Email address, so never forward those emails or screenshots of them. If you think a credential has been exposed, email [email protected] right away.
We also recommend masking personal and financial data before you send a request or response: bank account and routing numbers, card details, tax IDs and dates of birth, and in a batch, the recipients' Destination.Email addresses and check mailing addresses. Keep the last four digits if Xtrm needs them to identify a record. Leave identifiers such as CustomerBatchId, CustomerTransactionId, RecipientId and BeneficiaryBankID as they are, so Xtrm can find the payment.
The example request below reports payment TXN-SUPPORT-0001 of a two-payment batch, BATCH-SUPPORT-0001. The payment named a prepaid card SKU, PREP0000, that isn't in Xtrm's catalog; the batch's other payment succeeded.
Subject: Payment failed in a batch (sandbox, BATCH-SUPPORT-0001 / TXN-SUPPORT-0001)
Environment: Sandbox (https://xapisandbox.xtrm.com)
Endpoint: POST /API/v4/Fund/BatchTransfer
Request time: 2026-06-05 20:50 UTC (from our application logs)
Company account: IssuerAccountNumber SPN1111222, SourceWalletId 122181
Batch payment: CustomerBatchId BATCH-SUPPORT-0001, Status CompletedWithFailures
Payment: CustomerTransactionId TXN-SUPPORT-0001
RecipientId PAT9999888, SendMethodId XTR94503, SKU PREP0000,
Amount 50.00 USD
Status Failed
Attempts: AttemptNo 1, Result Failed, ErrorCode SKU_NOT_FOUND,
CreatedAt 2026-06-05T20:50:36.2476557Z,
CompletedAt 2026-06-05T20:50:36.2535086Z
Create response: 202 Accepted, ItemsCount Total 2, Accepted 2, Rejected 0
Webhook: Batch.Item.Failed, received 2026-06-05 20:50 UTC,
our endpoint returned 200
Expected: A 50.00 USD prepaid virtual debit card emailed to the recipient's
Destination.Email (masked in the attachments).
Actual: The item failed with SKU_NOT_FOUND. We have not resubmitted it.
Attached: request and response bodies and the item status response
(history=true), with credentials removed and personal and bank data masked.#Release notes and versions
This site documents the Xtrm API v4, version 4.92.6, the current live version. Batch payments were added in 4.92.4. Version 5.0 is listed as coming soon, and versions 1.0 and 2.0 are no longer supported. The changelog lists every release from 3.0 to 4.92.6, newest first, with new endpoints, changed fields and behavior changes. Check it when you upgrade an integration or when something behaves differently from what you remember.
Some operations in older release notes have since been renamed or replaced, so look them up under their current names. For example, GetCompanyType is now GetAdvancedContactCompanyType, and CreateBankBeneficiary was replaced by LinkBankBeneficiary. "ACH Debit" is now called "Bank Debit", but endpoint names still use ACHDebit.
#More resources
The batch lifecycle, wallet-first delivery, payment methods and limits.
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, and what to do next.
Batch paymentsWebhooksReceive batch and payment events and verify their signatures.
Batch paymentsRetries & idempotencyUse your batch and payment IDs to retry without paying twice.
API referenceBatch paymentsPOST /Fund/BatchTransfer and both status endpoints in full.