Core concepts

Errors

A batch payment reports problems at three points: when you submit it, while Xtrm processes its items in the background, and when you check status (see How batch payments work). Errors at submission come back in the response to BatchTransfer. Failures during processing are recorded on each item and, if webhooks are set up for your account, sent to you as events. The other endpoints report their outcome in an OperationStatus object, covered at the end of this page in Other endpoints. To build, submit and track a batch step by step, see Create a batch payment.

#Where a batch payment reports errors

WhenWhat you getWhere to read more
You submit a batch and the request as a whole is refusedA 4xx HTTP status, and nothing is storedThe whole request is refused
You submit a batch and Xtrm hits an unexpected errorA 500: you can't tell what was stored, so wait and resend the identical requestA safe retry pattern
You submit a batch and some items fail the submission checks202 with Status CompletedWithFailures, and those items listed in Rejected. If no item passes, 422 or 409.Items rejected at submission
You send a CustomerBatchId and CustomerTransactionId that are already storedCONFLICT_DUPLICATE_ITEM in Rejected, or 409 CONFLICT_PROCESSING for the whole requestDuplicate IDs
An item fails while Xtrm processes itItem Status Failed, an ErrorCode on the attempt, and a Batch.Item.Failed webhook. If the delivery from the recipient's wallet to the destination fails, the item stays RetainedInWallet instead, with a Failed attempt, and the webhook is Batch.Item.Completed with DeliveryType Wallet: the money has left your wallet, and the fee isn't refunded (see When a payment stays RetainedInWallet).Errors during processing
You resubmit an item to retry itA new attempt if the item is Failed; otherwise CONFLICT_DUPLICATE_ITEM or 409 CONFLICT_PROCESSINGResubmit failed items
A request for the status of a batch or an item failsA 4xx HTTP status, or 500Errors when you check status

#Errors when you submit a batch payment

Before it responds, Xtrm runs a synchronous check of the request: format, authentication, the source wallet, the IDs, and the fields each send method needs. Checks that look up the recipient and its destination, such as whether the recipient exists or whether the bank account or card SKU is valid, run later, while the item is processed. An item can therefore pass submission and still fail with a code such as RECIPIENT_NOT_FOUND (see Errors during processing).

#The whole request is refused

When the request as a whole fails a check, Xtrm refuses it and stores none of its items. The 415 and token 401 responses have a body of the form {"error": …, "error_message": …}. Every other refusal is a BatchTransferResponse with Status Failed, the code below in Key, the HTTP status as a number in ErrorCode, and a Message; some messages start with a space. Accepted is empty or null, and so is Rejected unless every item was rejected. CustomerBatchId and ItemsCount can also be null.

HTTP statusCodeCause
400BAD_REQUESTThe body is empty or isn't valid JSON.
401invalid_authorization, invalid_authentication_type, invalid_credentials or invalid_token, in errorThe token is missing, empty, unrecognized, revoked or expired, doesn't use the Bearer scheme, or comes from an IP address your company doesn't allow. See Authentication errors.
401UnauthorizedThe token isn't allowed to act for IssuerAccountNumber.
403FORBIDDENSourceWalletId isn't an active wallet owned by IssuerAccountNumber itself, in an active currency, or that account isn't active. A wallet that another company shares with you fails too. This is the only 403 a batch payment returns.
409CONFLICT_PROCESSINGThe CustomerBatchId is already in use, in any Xtrm account, and none of its items is Failed. See Duplicate IDs.
409 or 422None at the top levelNo item passes: every item is listed in Rejected with its own code, and Status is Failed. The HTTP status is 409 if any of them is CONFLICT_DUPLICATE_ITEM, otherwise 422.
413PAYLOAD_TOO_LARGEThe request's Content-Length is over Xtrm's request-size limit, which is the same for every account.
415invalid_media_type, in errorContent-Type is missing or isn't one of the supported media types. Send application/json (a charset parameter is fine).
422INVALID_FIELDIssuerAccountNumber is missing, longer than 20 characters or doesn't start with SPN; Items is empty or missing; CustomerBatchId is missing or breaks the ID rules; or SourceWalletId is missing, 0, negative or not a number.
422LIMIT_EXCEEDEDItems holds more items than your account's limit. Message ends with MaxAllowed: N, where N is your limit.
500TEMPORARY_ERRORXtrm hit an unexpected error, and you can't tell what it stored, so treat it like a timeout.

A 202 can also report a failure. Status Failed with Key TEMPORARY_ERROR means that the items passed the checks but Xtrm couldn't store any of them: that call stored nothing, and Accepted and Rejected are empty. The call may have collided with an earlier request for the same batch that is still running. Wait, then confirm with the batch status endpoint and, for any item that seems missing, with the item status endpoint, repeating the check a few times, at least a minute apart. Then resend the identical request (see A safe retry pattern). A 400 whose body has no BatchTransferResponse, such as one whose Message is Sequence contains no elements, comes from an unexpected error during the checks. You can't tell what it stored, so treat it like a timeout: wait, then resend the identical request.

To send more items than your limit, or a body larger than the size limit, we recommend splitting them across several batches, each with a new CustomerBatchId. For every refused request, we recommend logging the HTTP status and the raw body, reading Key, Message and Rejected whenever the body contains them, and not assuming that the body is JSON.

#Items rejected at submission

If at least one item passes the checks, Xtrm accepts the request and answers 202. The items that passed are queued for processing and listed in Accepted, in no particular order. The items that failed are listed in Rejected and not stored. Status is then CompletedWithFailures, and ItemsCount.Rejected is ItemsCount.Total minus ItemsCount.Accepted.

A successful submission is always 202, never 200. We recommend reading Status, ItemsCount and Rejected in every 202, and confirming the accepted items with the status endpoints, because a 202 doesn't prove that every listed item was stored.

Each entry in Rejected has these fields:

FieldExampleMeaning
CustomerTransactionIdThe identifier of the rejected item, as Xtrm stored it.
KeyINVALID_FIELDThe rejection code (see the table below).
ErrorCode422The HTTP-style code that goes with Key, as an integer: 422, 409 for CONFLICT_DUPLICATE_ITEM or 500 for TEMPORARY_ERROR.
FieldItems[0].Destination.SKUThe path of the field that failed, as Items[i].<path>. For CURRENCY_MISMATCH, Field is "".
MessageA human-readable explanation of why the item was rejected.

Match rejected items by CustomerTransactionId, not by the index in Field: the index skips items that were removed as conflicts, some errors name a related field, and one item can appear more than once. An item in Rejected wasn't stored by this request. With CONFLICT_DUPLICATE_ITEM, it had already been stored by an earlier request.

These are the rejection codes:

CodeErrorCodeCause
INVALID_FIELD422An item field fails a rule: RecipientId is missing, longer than 20 characters, your own IssuerAccountNumber, or the wrong account type for XTR94502 (PAT…) or XTR94504 (SPN…); SendMethodId isn't one of the seven values, in upper case; Amount is missing, not greater than 0, or above 9999999999999999.99; Destination is missing, lacks a field that the send method requires, or has a field that is too long or malformed, such as Email; Destination.WalletId equals SourceWalletId; Description is longer than 1,024 characters after Xtrm HTML-encodes it (each &, for example, counts as 5 characters); or CustomerTransactionId breaks the ID rules.
DUPLICATE_ITEM_IN_REQUEST422The same CustomerTransactionId appears more than once in the request. Xtrm rejects every copy, the first included, and processes none of them.
CONFLICT_DUPLICATE_ITEM409The item is already stored in this batch with a status other than Failed. See Duplicate IDs.
CURRENCY_MISMATCH422A check item (XTR94507) sent from a source wallet that isn't in USD. Field is "".
TEMPORARY_ERROR500Xtrm couldn't store the item. Confirm that it isn't in the batch before you send it again.

Destination is required on every item, whatever the send method: for a wallet item without a WalletId, send {}. Which Destination fields each send method requires is listed in the BatchTransfer reference and in Payment methods & destinations.

To fix an item rejected with INVALID_FIELD, correct the field named in Field; for CURRENCY_MISMATCH, send the check from a USD wallet. Then send the item again. It was never stored, so it has no attempt and can keep its CustomerTransactionId. You can send it under the same CustomerBatchId only if nothing of that batch was stored or the batch has a Failed item; otherwise send it in a new batch with a new CustomerBatchId. The other codes need different handling:

  • CONFLICT_DUPLICATE_ITEM: an earlier request already stored the item. Don't resend it; follow the existing item with the status endpoints.
  • DUPLICATE_ITEM_IN_REQUEST: send each payment once, with its own CustomerTransactionId.
  • TEMPORARY_ERROR: Xtrm couldn't store the item, for example because another request running at the same time stored it first. Wait, then confirm with the item status endpoint that it isn't stored, repeating the check a few times, at least a minute apart, before you send it again. See A safe retry pattern.

#ID rules

A CustomerBatchId that breaks the ID rules refuses the whole request with INVALID_FIELD, and a CustomerTransactionId that breaks them rejects that item with INVALID_FIELD. The rules (length, characters, reserved prefixes, sanitizing and case) are in Batch and payment identifiers.

#Duplicate IDs

Xtrm stores each pair of CustomerBatchId and CustomerTransactionId at most once, so resending the same pair never stores a second item. What each kind of duplicate does is in Duplicate IDs on the Retries & idempotency page. These are the error responses a duplicate can produce:

  • DUPLICATE_ITEM_IN_REQUEST in Rejected: the same CustomerTransactionId appears twice in one request. Xtrm rejects every copy.
  • CONFLICT_DUPLICATE_ITEM in Rejected: the item is already stored in this batch with a status other than Failed, and nothing about it changed.
  • 409 with CONFLICT_PROCESSING in the top-level Key: the whole request was refused and nothing was stored, because the CustomerBatchId is already in use and none of its items is Failed. On a resend after a timeout, it means your first request stored payments of the batch, not that it stored all of them: the first request can have rejected some items, and Xtrm stores a batch of more than 500 payments in groups of 500. Check each payment as described in A safe retry pattern. On the very first send of a batch, it means the CustomerBatchId is already in use, possibly by another account, because CustomerBatchId values are shared across all Xtrm accounts. If the batch status endpoint then answers 401 for that CustomerBatchId, another account used it: send your items under a new CustomerBatchId.
  • 409 with Status Failed and every item in Rejected: no item was accepted, and at least one is CONFLICT_DUPLICATE_ITEM.

Log the full body of every 409, so you can tell the two forms apart.

#Submit a batch payment and handle the response

This sample submits a two-item batch and handles each outcome: no usable response, a refused request, a 409 Conflict, a 202 that stored nothing, and items rejected inside an accepted batch.

CustomerBatchId values are shared across all Xtrm accounts. Replace the sample IDs with your own unique values, for example ones that include your account number or a UUID, before you run this in the sandbox.

response=$(curl -sS --max-time 60 -w '\n%{http_code}' -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "IssuerAccountNumber": "SPN1111222",
  "SourceWalletId": 122181,
  "CustomerBatchId": "BATCH-ERRORS-0001",
  "Items": [
    {
      "CustomerTransactionId": "TXN-ERRORS-0001",
      "RecipientId": "SPN8888777",
      "Amount": 100,
      "SendMethodId": "XTR94500",
      "Destination": {
        "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
        "BeneficiaryBankPaymentMethod": "ACH"
      }
    },
    {
      "CustomerTransactionId": "TXN-ERRORS-0002",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94503",
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      }
    }
  ]
}')
http_status=$(printf '%s\n' "$response" | tail -n 1)
body=$(printf '%s\n' "$response" | sed '$d')

case "$http_status" in
  2??)
    # Xtrm answers 202. Status is Accepted, CompletedWithFailures or Failed.
    status=$(printf '%s' "$body" | grep -o '"Status"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed 's/.*"\([^"]*\)"$/\1/')
    if [ "$status" = "Failed" ]; then
      # TEMPORARY_ERROR: this call stored nothing. Wait, confirm, then resend the identical request.
      echo "Xtrm stored nothing: $body" >&2
    else
      # Items in Rejected weren't stored by this request. CONFLICT_DUPLICATE_ITEM means an earlier request stored them.
      rejected=$(printf '%s' "$body" | grep -o '"Rejected"[[:space:]]*:[[:space:]]*[0-9][0-9]*' | head -n 1 | grep -o '[0-9]*$')
      echo "Batch received ($status). Rejected items: ${rejected:-unknown}"
      echo "$body"
    fi
    ;;
  409)
    # CONFLICT_PROCESSING: this CustomerBatchId is already in use, and nothing was stored.
    # CONFLICT_DUPLICATE_ITEM in Rejected: those items are already stored in this batch. Follow the batch.
    echo "Conflict: $body" >&2
    ;;
  000)
    # No HTTP response arrived, so the batch may or may not have been stored.
    echo "No response from Xtrm. Wait, then send the same request again, with the same IDs." >&2
    ;;
  5??)
    # A server error leaves the outcome unknown, like a timeout.
    echo "HTTP $http_status from Xtrm. Wait, then send the same request again, with the same IDs." >&2
    ;;
  400)
    if printf '%s' "$body" | grep -q '"BatchTransferResponse"'; then
      # Refused as a whole, or every item rejected: read Key, Message and Rejected.
      echo "Batch refused with HTTP 400: $body" >&2
    else
      # A 400 without a BatchTransferResponse body comes from an unexpected error, so the outcome is unknown.
      echo "HTTP 400 from Xtrm. Wait, then send the same request again, with the same IDs." >&2
    fi
    ;;
  *)
    # Refused as a whole, or every item rejected: read Key, Message and Rejected. Don't assume the body is JSON.
    echo "Batch refused with HTTP $http_status: $body" >&2
    ;;
esac

#Errors during processing

Xtrm processes accepted items asynchronously, in stages: it validates each item, debits your source wallet and credits the recipient's wallet, and then, for every send method other than a wallet, delivers the money from the recipient's wallet to the destination (wallet-first delivery). Each attempt with an outcome is recorded in the item's Attempts array, with a Result (Success or Failed) and an ErrorCode (SUCCESS when the attempt succeeds). The item's Status gives its current state. You can read these in three places:

  • Batch status: every item in the batch, page by page. Set history to true to get each item's attempts; otherwise Attempts is empty.
  • Item status: one item. Set history to true to get its attempts.
  • Webhooks: Batch.Item.Failed carries the ErrorCode of an item that failed validation or the wallet credit. A failed delivery sends Batch.Item.Completed with DeliveryType Wallet instead. A webhook's status doesn't always match the item's status, so confirm final statuses with the status endpoints.

A failed delivery isn't a Failed item. Your source wallet is debited Amount plus the fee when the recipient's wallet is credited, before the delivery to the destination. A bank, card, check, gift card or prepaid payment then shows RetainedInWallet while Xtrm delivers it, usually only briefly, and moves on to Success when the delivery goes through. If the delivery fails, the item stays RetainedInWallet, with a Failed attempt: the money is in the recipient's Xtrm wallet, so you can't retry or resubmit the item, and the fee isn't refunded. Don't act on RetainedInWallet while the batch is still Processing: the item has stuck only once the batch status is final. We recommend handling a stuck RetainedInWallet item separately from both Success and Failed; see When a payment stays RetainedInWallet.

Decide with the item's Status, not with an attempt's ErrorCode. An error code describes one attempt. For example, when attempt 1 fails with INSUFFICIENT_BALANCE and attempt 2, resubmitted after you fund the source wallet, succeeds, the item's Status is Success. To find the newest attempt, take the one with the highest AttemptNo: the batch status endpoint lists attempts newest first, and the item status endpoint oldest first.

#Run-time error codes

Each failed attempt carries an ErrorCode. What it means for the item depends on the stage where it failed:

  • Validation, before any money moves: the item becomes Failed, and Xtrm sends Batch.Item.Failed. You can resubmit it after you fix the cause.
  • Wallet credit, when Xtrm debits your source wallet and credits the recipient's wallet: the item becomes Failed, and Xtrm sends Batch.Item.Failed. Your source wallet isn't debited, except that after TEMPORARY_ERROR the money may already have moved.
  • Delivery from the recipient's wallet: the attempt is Failed, and the item stays RetainedInWallet, which you can't resubmit. Xtrm sends Batch.Item.Completed with DeliveryType Wallet, not Batch.Item.Failed.

Common codes are INSUFFICIENT_BALANCE, RECIPIENT_NOT_FOUND, BANKID_INVALID and SKU_NOT_FOUND. For every code and what to do, see Error codes on attempts.

#Resubmit failed items

To retry a Failed item, fix the cause, then resubmit it under the same CustomerBatchId and CustomerTransactionId, with every field. For example, fund the source wallet after INSUFFICIENT_BALANCE, or correct Destination.BeneficiaryBankID after BANKID_INVALID. Its next attempt gets the next AttemptNo. Any other item you include comes back in Rejected as CONFLICT_DUPLICATE_ITEM and nothing about it changes, and a request with no Failed item in its batch gets 409 CONFLICT_PROCESSING. An item that stays RetainedInWallet can't be resubmitted (see When a payment stays RetainedInWallet), and before you retry an item whose newest attempt is TEMPORARY_ERROR, check with Xtrm support: the money may already have moved.

Retry a batch payment covers what a resubmission does for each status and which fields you can change, and A safe retry pattern covers resending after a timeout.

#Errors when you check status

The batch status and item status endpoints return the status object at the root of the body, with no OperationStatus. When a request fails, the body has the form {"StatusCode": …, "Message": …}, with an ErrorKey added for 400, 413 and 422. Token errors have the {"error": …, "error_message": …} body described in Authentication errors. These are their error responses:

HTTP statusErrorKeyEndpointCause
400INVALID_PAGINATIONBatch statusrecordsToSkip is negative, recordsToTake is 0 or negative, or history isn't true or false.
400INVALID_PARAMETERItem statushistory isn't true or false (History value is malformed.).
401NoneBothThe batch was created under an IssuerAccountNumber your token can't act for. Because CustomerBatchId values are shared across all Xtrm accounts, this also tells you that another account used the ID.
401None (error instead)BothThe token is missing, empty, unrecognized, revoked or expired, doesn't use the Bearer scheme, or comes from an IP address your company doesn't allow. See Authentication errors.
404NoneBothNo account has a batch with this CustomerBatchId (Unknown CustomerBatchId.), or, for item status, the batch has no stored item with this CustomerTransactionId (CustomerTransactionId not found within the specified batch.). A failed database read while Xtrm looks up the batch or the item returns the same 404, so it can be temporary.
413LIMIT_EXCEEDEDBothThe response would be larger than your account's response-size limit. For batch status, lower recordsToTake; for either endpoint, leave out history.
422LIMIT_EXCEEDEDBatch statusrecordsToTake is over your account's maximum, which Message states.
500NoneBothThere has been a temporary error. Please try again later. The error is temporary: repeat the check.

A 404 from either endpoint doesn't prove that a batch or a payment is missing. Besides a failed database read, there's timing: right after a submit call times out, the item endpoint can 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, and then follow A safe retry pattern to submit it.

This sample reads TXN-ERRORS-0001, the bank transfer item from the batch above, with its attempt history. It finds the latest attempt and reports the item's outcome. A 404 or 5xx gets a reminder to repeat the check. For a RetainedInWallet item, it also reads the batch status: while the batch is Processing, the delivery is still under way. Once the batch status is final, the sample reads the item again, because the delivery can finish between the two reads: an item that is still RetainedInWallet has stuck.

response=$(curl -sS -w '\n%{http_code}' -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-ERRORS-0001/Items/TXN-ERRORS-0001?history=true" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN")
http_status=$(printf '%s\n' "$response" | tail -n 1)
body=$(printf '%s\n' "$response" | sed '$d')

if [ "$http_status" = "404" ] || [ "$http_status" -ge 500 ]; then
  # Can be temporary: repeat the check a few times, at least a minute apart, before you treat the item as missing.
  echo "HTTP $http_status: $body (can be temporary: repeat the check a few times, at least a minute apart)" >&2
elif [ "$http_status" -lt 200 ] || [ "$http_status" -ge 300 ]; then
  echo "HTTP $http_status: $body" >&2
else
  # The item's Status is the only "Status" key in this response; attempts use "Result".
  status=$(printf '%s' "$body" | grep -o '"Status"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed 's/.*"\([^"]*\)"$/\1/')
  echo "Item status: $status"

  # Each attempt has its own ErrorCode. Use a JSON tool such as jq to pick the highest AttemptNo.
  echo "Attempt error codes:"
  printf '%s' "$body" | grep -o '"ErrorCode"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)"$/  \1/' || true

  if [ "$status" = "RetainedInWallet" ]; then
    # RetainedInWallet passes through on the way to the destination: read the batch status to tell.
    batch=$(curl -sS -f "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-ERRORS-0001?recordsToSkip=0&recordsToTake=1" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN")
    # In the batch response, the first Status is the batch's.
    batch_status=$(printf '%s' "$batch" | grep -o '"Status"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed 's/.*"\([^"]*\)"$/\1/')
    case "$batch_status" in
      Processing)
        echo "RetainedInWallet while the batch is Processing: the delivery is still under way. Check again later." ;;
      Completed | CompletedWithFailures | Failed)
        # The delivery can finish between the two reads, so read the item again.
        again=$(curl -sS -f "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-ERRORS-0001/Items/TXN-ERRORS-0001" \
          -H "Authorization: Bearer $XTRM_ACCESS_TOKEN")
        again_status=$(printf '%s' "$again" | grep -o '"Status"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed 's/.*"\([^"]*\)"$/\1/')
        if [ "$again_status" = "RetainedInWallet" ]; then
          echo "RetainedInWallet after the batch finished: the delivery didn't go through. The money is in the recipient's Xtrm wallet."
        elif [ -n "$again_status" ]; then
          echo "The delivery finished in the meantime: the item is now $again_status."
        else
          echo "Couldn't read the item again. Check it again later." >&2
        fi ;;
      *)
        echo "Couldn't read the batch status. Check it again later." >&2 ;;
    esac
  fi
fi

#Authentication errors

Batch payment endpoints. Every batch payment call needs a valid bearer token. When the token check fails, Xtrm answers 401 with a body of the form {"error": …, "error_message": …}:

Caseerrorerror_message
No Authorization headerinvalid_authorizationAuthorization is missing
The scheme isn't Bearerinvalid_authentication_typeThe authentication type should be bearer
Empty tokeninvalid_credentialsMissing credentials
Unrecognized or revoked token, or a call from an IP address that your company doesn't allowinvalid_authorizationNot authorized to view/access this resource
Expired tokeninvalid_tokenThe Token has expired

A valid token must also be allowed to act for the account concerned. On a submission, a token that can't act for IssuerAccountNumber gets 401 with Key Unauthorized. On a status request, a batch created under an IssuerAccountNumber your token can't act for gets 401 with no key. The batch payment endpoints never answer 403 for a token or scope problem: their only 403 is FORBIDDEN, from the source-wallet check, which also fails when the account in IssuerAccountNumber isn't active. Xtrm checks the token before it stores anything, so after a 401 you can get a new token and submit the same batch again.

Other endpoints. Every call with a bearer token goes through the same token check, so the endpoints outside batch payments answer a missing, unrecognized or expired token, or a call from an IP address your company doesn't allow, with the same 401 responses. The token endpoint answers a failed token request with HTTP 400 and a body of the form {"error": …, "error_description": …}: for example invalid_credentials (Credentials are invalid.) when the client credentials aren't valid, invalid_grant for a refresh_token that Xtrm doesn't accept, and unsupported_grant_type for a grant_type that Xtrm doesn't support.

Token lifetime. Access and refresh tokens expire; Token lifetime and expiry says when, and how to renew them. When a refresh_token grant returns 400 with invalid_grant, get a new token with grant_type=password.

When a call fails and your token may have expired, we recommend getting a new token and trying once more. If a fresh token still fails, check that your server's IP address is allowlisted and that you use the credentials for the right environment (the sandbox is completely separate from production), then contact [email protected]. See Authentication and Sandbox & environments.

#Other endpoints: the OperationStatus envelope

The endpoints outside batch payments, such as wallets, recipients, bank accounts, recipient transfers and funding, wrap their payload in a response object and a result object, and put an OperationStatus object inside the result. A successful call returns HTTP 200 with Success set to true. Validation and business failures return HTTP 400 with the same envelope and Success set to false. There are two exceptions. The one-time password steps of a recipient transfer return HTTP 200, even when the password is wrong. The first call of a mobile-number change on UpdateUser returns HTTP 400 with Success set to true, because Xtrm has texted a one-time password to the new number. So check both the HTTP status and OperationStatus.Success on every call.

#The OperationStatus object

This is the response to a successful CreateUser call:

Response
{
  "CreateUserResponse": {
    "CreateUserResult": {
      "UserID": "PAT9999888",
      "AccountIdentityLevel": "Standard",
      "OperationStatus": {
        "Success": true,
        "Errors": null
      }
    }
  }
}
FieldTypeWhat it tells you
SuccessbooleanWhether the operation succeeded (true) or failed (false). We recommend deciding success or failure with this field.
ErrorsvariesValidation or execution error details when the call fails. On success it's empty, but the empty value varies by endpoint (see below).

Two things vary between endpoints, so don't hard-code them:

  • Wrapper names. They often differ from the operation name, sometimes with typos. For example, GetUserWalletBalance returns UserWalletBalnceResponse > UserWalletBalanceResult. Find OperationStatus by searching for the key rather than by a fixed path. See Requests & responses.
  • Key order. Success comes before Errors on some endpoints and after it on others.

#Errors on a successful call

On success, Errors is empty, but endpoints express "empty" in three different ways:

A non-empty Errors is therefore not a failure: [""] has one element on a successful call. Decide with Success, and treat Errors as detail: it explains a failure, and on a one-time password step it carries the message that a code was sent. On the two recipient transfer endpoints, also check that the transfer was made (see Check every response the same way). When you read it, we recommend normalizing it first: drop null, [] and empty strings, and keep whatever is left.

#Errors on a failed call

On a failed call, Errors is an array of strings, one message per problem: for example Issuer Account Number is Mandatory for a missing field, or CountryISO2 is invalid. Bank linking is the exception. When LinkBankBeneficiary or LinkACHDebitBankBeneficiary needs more information, Errors is an array of objects instead, each with an ErrorMessage, the FieldName and FieldLabel of a field to add or fix (for example RoutingNumber and Routing Number), IsRegulatoryField and valueset. On LinkBankBeneficiary, valueset lists the values a missing regulatory field accepts, each with an id and a text; otherwise it's null. Their other failures return strings.

We recommend logging the complete Errors value and the raw response body for every failure.

#HTTP status codes

HTTP statusWhenBody
200The call succeeded, or one of the one-time password steps of UserWithdrawFund and BeneficiaryCompanyWithdrawFund (see Check every response the same way)The envelope. Check Success.
400A validation or business failure, such as a missing or invalid field, or a bank link that needs more information. Also the first call of a mobile-number change on UpdateUser, which sends a one-time passwordThe envelope, with Success false and the reasons in Errors. For that UpdateUser call, Success is true and Errors holds One Time Password sent to user. Please resubmit with One Time Password. An unexpected error that the endpoint doesn't catch returns {"Error": false, "StatusCode": 400, "Message": …} instead.
401The token is fine, but it isn't allowed to act for the IssuerAccountNumber you sentThe envelope, with Errors ["Not authorized to access this resource."]
401A token or IP address problem{"error": …, "error_message": …}, as in Authentication errors
404A path or API version that doesn't exist, or a GET to an endpoint that accepts only POST{"StatusCode": 404, "Message": "The requested resource is not found"}, with no OperationStatus
409Your company is already connected to the account, on GetOTPAuthorizedVendor and ValidateOTPAuthorizeVendorThe envelope, with Errors ["Already authorized vendor to access this resource"]
415A POST without a supported Content-Type{"error": "invalid_media_type", "error_message": …}
500An unexpected error (some endpoints return 400 instead)The envelope, with Errors ["There has been a temporary error. Please try again later."]
503Xtrm can't get an exchange rate or complete a currency exchange right now, for example on GetExchangeRate and BookExchangeThe envelope, with Errors ["Currency exchange service temporarily unavailable. Please try again later."]. Try again later; before you resend a BookExchange, check the wallet you convert from, as described in Exchange currency.

GetAdvancedContactCountry accepts only POST. A GET returns HTTP 404 with {"StatusCode": 404, "Message": "The requested resource is not found"}, so send a POST with {} as the body. Any endpoint that accepts only POST answers a GET the same way.

Apart from the first call of an UpdateUser mobile-number change, we recommend treating any non-2xx status as a failure, and not assuming that its body is JSON or contains an OperationStatus.

#Responses without OperationStatus

Besides the batch payment endpoints, two endpoints don't use the envelope:

EndpointHow failures are reported
/oAuth/tokenReturns a flat token object. A failed token request returns HTTP 400 with {"error": …, "error_description": …} (see Authentication errors).
GetConnectedCompanyFundRequestReturns CSV text, not JSON. Its first line is the header row Account Number,Name,Credits,Debits,Currency, with no line before it. A failure returns the JSON envelope instead, with HTTP 400 or 500. We recommend checking the HTTP status and that the header row is present.

#Error messages by area

These are the failure messages and signals to plan for on these endpoints, grouped by area.

#Bank accounts and bank debit

Message or signalWhere it appearsWhat it means
HTTP 400 with Success: false and field objects in ErrorsLinkBankBeneficiary, LinkACHDebitBankBeneficiaryThe bank needs more information, and nothing is linked. Send the whole request again with the fields in Errors added or fixed, and repeat until the response returns a BeneficiaryId: a resend can ask for more fields.
ErrorMessage with FieldName, FieldLabel, IsRegulatoryField and valueset, for example RoutingNumber / Routing NumberThe same two endpoints, in OperationStatus.ErrorsFieldName is the parameter to send; FieldLabel is a readable label you can show in your interface. When IsRegulatoryField is true, send the value in RegulatoryFields as a Key/Value pair, with the FieldName as the Key. On LinkBankBeneficiary, valueset lists the values a missing regulatory field accepts. Some currencies need currency-specific information: repeat the request until it links.
Regulatory field values are not required for this request.LinkBankBeneficiary, in OperationStatus.ErrorsYou sent RegulatoryFields for a bank that needs none. Leave it out until a response lists a field whose IsRegulatoryField is true.
IsValid: falseValidateIBANThe IBAN failed the structural and mathematical validity check. Success: true only means the call ran without server errors.
Invalid amount., or the bank provider's messageVerifyACHDebitMicrodeposit, HTTP 400The micro-deposit amounts you sent don't match. An amount of 0 returns Amount_1 must be greater than 0 or Amount_2 must be greater than 0. If the amounts are refused too many times, delete the bank with DeleteBankBeneficiary and link it again.

#Currency exchange

Message or signalWhere it appearsWhat it means
<FromWalletID> - Insufficient balance in the wallet, HTTP 400, for example 12345 - Insufficient balance in the walletBookExchange, in OperationStatus.ErrorsThe wallet in FromWalletID holds less than Amount. Xtrm rejects the exchange before it books anything, so no money is exchanged and nothing leaves the wallet. An Amount equal to the wallet balance is accepted. Add funds to the wallet or lower Amount, then send the request again.

#Profiles and reports

Message or signalWhere it appearsWhat it means
HTTP 400, Missing profile information. Please ensure profile is complete.TransferTaxInformation, in OperationStatus.ErrorsFor a recipient in the United States, Xtrm can't generate the 1099-K until the profile has the recipient's first and last name, email, tax ID (SSN or TIN), date of birth and full address (street, city, state, postal code and country). Recipients outside the United States are sent a CSV statement of their transactions instead, with no profile check.
Message about approval status or missing requirementsCompanyAdvancedProfileA system message about the submission.
HTTP 404, The requested resource is not found, in answer to a GETGetAdvancedContactCountryThe endpoint accepts only POST. Send a POST with an empty JSON object {} as the body.

#Tokens and one-time passwords

Message or signalWhere it appearsWhat it means
HTTP 400, invalid_credentials (Credentials are invalid.) or invalid_grant/oAuth/tokeninvalid_credentials: the client credentials aren't valid. invalid_grant: Xtrm doesn't accept the refresh_token you sent, for example because it has expired (60 days after it was issued). Request a new token with grant_type=password instead.
HTTP 401 with error and error_messageEvery endpoint except /oAuth/tokenA missing, unrecognized or expired access token, or a call from an IP address your company doesn't allow. See Authentication errors.
HTTP 200, Success: false, Invalid one time password. A new one has been sent and the original has been expired. Please use the new one.UserWithdrawFund, BeneficiaryCompanyWithdrawFundThe one-time password was wrong, or it expired: a code expires 10 minutes after Xtrm sends it, counted in whole minutes, so send it back within 9 minutes. No money moved, the old code no longer works, and Xtrm has sent the recipient a new code. Ask the recipient for it and send the same request again with it in OTP.
HTTP 200, Success: true, One Time Password sent to user. Please resubmit with One Time Password.UserWithdrawFund, BeneficiaryCompanyWithdrawFundNot a failure, and not a transfer: this is the response to the first request, or to one whose OTP is blank, 000000 or not a number. Xtrm has sent the recipient a new code, any earlier code no longer works, and no money moved. Send the same request again with the code in OTP. The transfer is made only when a response has PaymentStatus Completed and a PaymentTransactionId.
HTTP 400, One Time Password must be an integer with a maximum length of 6The same two endpointsThe OTP you sent is longer than 6 characters. No code is sent.
HTTP 400, Your previous transfer is in progress. Please wait or try later.The same two endpointsAn earlier transfer from the recipient's wallet hasn't finished. Xtrm checks this before it sends a code and again after it accepts one; in the second case the code is used up. Wait, then start again with a first request.
HTTP 400, Mobile # is not available in the user profileThe same two endpointsYou asked for the code by text message, and the recipient's profile has no mobile number. No code is sent. On UserWithdrawFund, any SendTransferCodeToMobile value that isn't empty asks for a text, "false" included, so leave the field out to get the code by email only.
HTTP 400, Success: true, One Time Password sent to user. Please resubmit with One Time Password.UpdateUserYou sent a MobileNumber that differs from the saved one, with its MobileCountryISO2 and with OTP set to "", and Xtrm texted a six-digit code to the new number. Nothing in the profile was updated. Within 10 minutes, send the same request again with the code in OTP. A wrong or expired code returns HTTP 400 with Success: false and Invalid one time password. A new one has been sent and the original has been expired. Please use the new one., and Xtrm texts a new code.

Some endpoints also report unfinished or failed work in status fields rather than as errors; each endpoint's reference page lists those values. We recommend flagging a value you don't recognize for review instead of treating it as success, and handling any failure you don't recognize by logging it in full and surfacing it to a person, not by retrying it blindly.

#Check every response the same way

We recommend sending every call that uses the envelope through one check:

  1. If the HTTP status is not 2xx, treat the call as failed. Log the status and the raw body, and don't assume the body is JSON.
  2. Parse the JSON and find OperationStatus by searching for the key, because wrapper names vary.
  3. If Success is true, the call succeeded, whatever Errors holds. The two recipient transfer endpoints need one more check, described below.
  4. Otherwise, treat the call as failed. Normalize Errors and keep what is left, together with the raw body, for your logs and for support.

The first, OTP-generating request of UserWithdrawFund and BeneficiaryCompanyWithdrawFund passes this check but moves no money: it returns HTTP 200 with Success set to true, and Errors holds One Time Password sent to user. Please resubmit with One Time Password. An OTP that is blank, 000000 or not a number counts as a first request too: Xtrm sends a new code, and the previous code stops working. On these two endpoints, the transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId; keep that ID to reconcile. After any other 200, get the code from the recipient and send the same request again with it in OTP. The code expires 10 minutes after Xtrm sends it, counted in whole minutes, so send it back within 9 minutes. Each code covers one attempt: once Xtrm accepts it, the code is used up, even if the transfer then fails, so start again with a first request.

The first call of a mobile-number change on UpdateUser, sent with OTP set to "", fails step 1 although nothing went wrong: it returns HTTP 400 with Success set to true and the same One Time Password sent to user. Please resubmit with One Time Password. message. Treat that response as the code being sent, and within 10 minutes send the same request again with the code in OTP.

This sample applies the four steps to GetCompanyWallets:

response=$(curl -sS -w '\n%{http_code}' -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "GetCompanyWallets": {
    "request": {
      "IssuerAccountNumber": "SPN1111222"
    }
  }
}')
http_status=$(printf '%s\n' "$response" | tail -n 1)
body=$(printf '%s\n' "$response" | sed '$d')

# OperationStatus.Success is the signal. Errors can be null, [] or [""] even on success.
# Exception: on UserWithdrawFund and BeneficiaryCompanyWithdrawFund, Success is also true when Xtrm
# only sent a code. There, a transfer is made only when PaymentStatus is Completed.
if [ "$http_status" -lt 200 ] || [ "$http_status" -ge 300 ]; then
  echo "HTTP $http_status: $body" >&2
elif ! printf '%s' "$body" | grep -Eq '"Success"[[:space:]]*:[[:space:]]*true'; then
  echo "Xtrm reported a failure: $body" >&2
else
  echo "$body"
fi

#Handle failures on these endpoints

  • Bank linking. When LinkBankBeneficiary or LinkACHDebitBankBeneficiary returns Success: false with field objects in Errors, ask whoever holds the bank account (the individual or business recipient, or your company when you link a bank for bank debit) for the field named in FieldName, using FieldLabel as the label. Send the whole request again with that field filled in, putting a field whose IsRegulatoryField is true in RegulatoryFields, and repeat until the response returns a BeneficiaryId. See Bank accounts & transfers.
  • IBANs. We recommend calling ValidateIBAN before you link a bank or start a transfer, to prevent failed transactions and routing errors. Check IsValid, not Success.
  • Messages. Show the message in Errors from TransferTaxInformation, and the Message from CompanyAdvancedProfile, to the person who can complete the missing information.
  • Funds. Handle an insufficient-funds failure on a recipient transfer, or on another call outside batch payments, like any other Success: false response: log the messages in Errors and show them to the person who can add funds.
  • Retries. These endpoints take no idempotency key, including the recipient transfers, the funding calls and BookExchange. Before you resend one of them after a timeout or another failure with no clear outcome, check whether the first request took effect, for example in the wallet transactions. Send these calls one at a time, and don't run retries in parallel.
  • Everything else. For any other Success: false response, read the messages in Errors: a missing field, for example, returns a message such as Issuer Account Number is Mandatory. Then check the request against the endpoint's reference page: copy field names exactly as they appear there, including odd spellings such as IsPublicallyTraded, and note that many values are strings even when they hold numbers or booleans, while a few must be real booleans. See Requests & responses.

#Get help

If you can't resolve an error, email [email protected]. We recommend including the endpoint, the HTTP status and the raw response body, and for a batch payment the CustomerBatchId and CustomerTransactionId of the items concerned. See Support.