Batch payments

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.

StatusWhat it meansFinal?
AcceptedThe payment passed the checks when you submitted the batch and is stored, waiting to be picked up.No
ProcessingXtrm is validating the payment. On the payment status endpoint, Processing also covers Verified.No
VerifiedThe 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
SuccessFor 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
RetainedInWalletXtrm 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
FailedThe 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_ITEM entry means that the item is already stored in this batch. Follow that item instead of sending it again.
  • A 202 response with Status Failed and Key TEMPORARY_ERROR has an empty Rejected array, 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.

StatusWhat it meansFinal?
ProcessingAt least one payment is still in progress.No
CompletedNothing is in progress, and every payment is Success.Yes
CompletedWithFailuresNothing is in progress, and some payments didn't succeed.Yes, but it can change (see below)
FailedNothing 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 batchBatch 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 SuccessCompleted
Nothing is in progress, and every payment failedFailed
Nothing is in progress, in any other case, for example some payments Success and some failedCompletedWithFailures

What this means in practice:

  • Completed means every payment is Success.
  • Items rejected when you submitted the batch aren't counted.
  • A RetainedInWallet payment counts as in progress while Xtrm delivers it or holds its delivery, and as failed once the delivery has failed. So the batch stays Processing until every delivery has finished, and a payment that is still RetainedInWallet in a CompletedWithFailures or Failed batch has stuck.

A batch status that looks final can still change:

  • Resubmitting a Failed payment reopens the batch.
  • Once some payments have passed validation, payments still waiting to be validated count as failed, so the batch can briefly read Failed or CompletedWithFailures before it returns to Processing.

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.

SendMethodIdDeliveryType
XTR94502, XTR94504Wallet
XTR94500Bank
XTR94503Prepaid Virtual Debit Card
XTR94505Digital Gift Cards
XTR94507Bank Check
XTR94508Rapid Transfer
  • On a RetainedInWallet payment, DeliveryType is Wallet, as on a successful wallet payment, both while Xtrm delivers it and once it has stuck, so read it together with Status.
  • On an Accepted, Processing or Failed payment, DeliveryType is 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.

FieldWhat it holds
AttemptNoThe submission the attempt belongs to: 1 for the first submission, then one higher for each accepted resubmission. Two attempts can share a number.
ResultSuccess or Failed.
ErrorCodeSUCCESS for a successful attempt, or an error code such as INSUFFICIENT_BALANCE that says why it failed. See Error codes on attempts.
CreatedAtOn 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.
CompletedAtThe 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 parameterTypeDescription
recordsToSkipintegerThe number of payments to skip, as a 0-based offset. Start with 0. A value past the last payment returns an empty Items.
recordsToTakeintegerThe 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.
historybooleantrue 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"

The response holds:

  • CustomerBatchId, the batch Status and the batch Currency, 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 with Total, Accepted and Rejected counts.
  • Items: the payments in this page, always as an array, each with CustomerTransactionId, Status, RecipientId, SendMethodId, Amount, LastUpdatedAt and Attempts. These items have no Currency and no DeliveryType.
    • Amount is 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.
    • LastUpdatedAt is when the payment was last updated, in UTC. It's null until Xtrm starts processing the payment.
  • Pagination: HasMore and NextRecordsToSkip, 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.

Response (excerpt)
{
  "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

  1. Request the first page with recordsToSkip=0 and the page size you want in recordsToTake.
  2. If Pagination.HasMore is true, request the next page with recordsToSkip set to Pagination.NextRecordsToSkip. Keep recordsToTake and history the same.
  3. Repeat until Pagination.HasMore is false.

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.

  • Status uses the same values as the batch status endpoint, except that a Verified payment shows as Processing.
  • Amount is a plain string with 2 decimals and no thousands separator, for example "1234.56".
  • LastUpdatedAt is 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"

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.

Response
{
  "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 statusWhat to do
Accepted, Processing, VerifiedWait 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.
SuccessRecord 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.
RetainedInWalletWhile 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.
FailedRead 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 elseTreat 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's DeliveryType is Wallet, its LastUpdatedAt is 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. Its DeliveryType names the rail, for example Bank, and its newest attempt is Success.
  • The batch is CompletedWithFailures or Failed, and the payment is still RetainedInWallet: the delivery didn't go through, and the payment has stuck. Xtrm doesn't try the delivery again. Request the payment with history=true: its newest attempt has Result Failed and an ErrorCode that says why, for example RETAINED_IN_WALLET when the provider didn't accept the payment, or INSUFFICIENT_FUNDS_RUNTIME when 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 EmailNotification set to true, Xtrm emailed them when the money reached their wallet, before the delivery was tried.
  • Your company requests the transfer for them. Call UserWithdrawFund for an individual recipient or BeneficiaryCompanyWithdrawFund for 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.

CodeMeaningWhat to do
RECIPIENT_NOT_FOUNDThe 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_WALLETThe 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_FOUNDThe 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_REQUIREDA 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_FOUNDA 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_INVALIDThe 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_FOUNDThe 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_PAYMENTMETHODThe 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_FOUNDThe 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_FOUNDFor 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_AMOUNTThe 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_INVALIDNo prepaid card product exists for the batch currency.Pay the recipient with another method, as a new item with a new CustomerTransactionId.
CURRENCY_MISMATCHThe 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_UNSUPPORTEDThe 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_ERRORAn 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.

CodeMeaningWhat to do
SEND_LIMIT_EXCEEDEDThe 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_BALANCEYour 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_FOUNDXtrm couldn't determine a fee type for the payment method.Contact Xtrm support.
WALLET_AUTO_CREATE_FAILEDYou 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_FAILEDXtrm's credit to the recipient's wallet returned errors.Resubmit.
TEMPORARY_ERRORAn 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.

CodeMeaning
INSUFFICIENT_FUNDS_RUNTIMEThe recipient's wallet balance was below Amount when the delivery started. It doesn't refer to your source wallet.
RETAINED_IN_WALLETThe bank provider declined the payment or returned an error.
TEMPORARY_ERRORAn error occurred during a bank delivery, or a check, card or push-to-card delivery was declined or failed.
SKU_NOT_FOUND, INVALID_CARD_AMOUNTFor 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 methodThe rail wasn't available when the delivery started. This code is a literal string with spaces.
PREVIOUS_TRANSFER_IN_PROGRESSAn earlier transfer was still using the recipient's wallet.