Resources

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

ContactUse 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 ManagerTurning 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 as SPN1111222.
  • The environment the endpoint is for: sandbox or production.
  • The URL of your endpoint. Register an https URL: 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:

  1. 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.
  2. 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 seeCheck first
202 Accepted, but the payments haven't arrived202 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 RejectedRead 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 422Either 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 request401 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 FailedGet 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 RetainedInWalletCheck 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 recognizeIt 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 VerifiedThe 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 batchWait, 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 responseRead 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 paymentsPayments 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 rejectedCompare 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 valuesThe 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 seeCheck first
No webhooks arriveMake 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 onXtrm 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 onceThe 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 verifyFollow 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"

The response has the values support needs: the payment's Status, DeliveryType and LastUpdatedAt, and every attempt with its Result and ErrorCode:

Response (history=true)
{
  "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:

DetailExample
EnvironmentSandbox (https://xapisandbox.xtrm.com) or production (https://xapi.xtrm.com)
EndpointMethod and path, such as POST /API/v4/Fund/BatchTransfer or GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}
Request timeDate, 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 accountThe IssuerAccountNumber and SourceWalletId you sent, such as SPN1111222 and 122181
Batch paymentThe CustomerBatchId, such as BATCH-SUPPORT-0001, and the batch Status, such as CompletedWithFailures
PaymentsThe CustomerTransactionId of each affected payment, such as TXN-SUPPORT-0001, with its RecipientId, SendMethodId, Amount and Status
AttemptsThe payment's Attempts from a status call with history=true: each AttemptNo, Result and ErrorCode
Create responseThe 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 eventsThe event type, such as Batch.Item.Failed, when it arrived at your endpoint, and the HTTP status your endpoint returned
Request and responseBoth bodies, sanitized as described below
Expected and actualWhat 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.

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.

Example support request
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