Guide

Create a batch payment

One request can pay a whole list of people and businesses, each the way that suits them: straight to a bank account, into an Xtrm wallet or onto a prepaid card. In this guide you choose the wallet that funds the batch, submit a batch that does all three, follow it until every payment has an outcome, and fix and retry a payment that fails, without ever paying anyone twice.

Xtrm processes a batch asynchronously. When you submit it, Xtrm checks the request and each payment's fields, stores the payments that pass and answers 202 Accepted. It doesn't check your balance or move any money at that point. It then processes the stored payments in the background, and the status endpoints report each payment's progress. For the model behind this flow, see How batch payments work.

#What you'll do

StepCallWhat you keep
1. Choose the source walletGetCompanyWalletsThe WalletID you pay from
2. Build and submit the batchPOST /Fund/BatchTransferYour CustomerBatchId and the accepted and rejected payments
3. Track the batchGET /Fund/BatchTransfer/{CustomerBatchId}Each payment's Status
4. Inspect a paymentGET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}The payment's attempts and DeliveryType
5. Retry a failed paymentGetLinkedBankAccounts, POST /Fund/BatchTransferA new attempt for the retried payment

#Before you begin

You need:

  • An access token in the XTRM_ACCESS_TOKEN environment variable. Each sample in the steps reads it from there; the full example requests its own token with XTRM_CLIENT_ID and XTRM_CLIENT_SECRET. See Authentication.

  • Your company's account number. It starts with SPN, and the samples use SPN1111222. You send it as IssuerAccountNumber.

  • A funded wallet in the currency you want to pay in. In the sandbox, Xtrm adds test funds to your wallets once your IP addresses are approved. To add money, see Fund your wallet.

  • Your recipients and their destinations. This guide pays three recipients:

    RecipientAccountPaid toWhere the destination comes from
    A businessSPN8888777Its linked bank account 41953ec32f3e4765a35a902c82bdd995The BeneficiaryId that LinkBankBeneficiary returns when you link the bank, or that GetLinkedBankAccounts lists
    Another businessSPN8888776Its Xtrm wallet 122311The wallet's ID from GetBeneficiaryWallets
    Jane Doe, an individualPAT9999888A prepaid virtual debit card, emailed to [email protected]The sku PREP9001 from GetPrepaidCards

    Create every recipient before you submit the batch. A batch pays existing Xtrm accounts only, by their account numbers, and a RecipientId with no account fails during processing with RECIPIENT_NOT_FOUND. If a recipient doesn't have an account yet, create it first: with CreateUser for a person, or CreateBeneficiary for a business. In the Xtrm web app you can add a person while you make a payment, but through the API you create each recipient first. Paying a recipient needs no connection to your company, but linking or listing a recipient's bank accounts and listing a business's wallets do. A recipient your company creates through the API is connected from the start; for an existing account, see Connections and manager services. To link a recipient's bank account and read back its ID, see Bank accounts.

  • cURL, or one of Node.js 18+, Python 3 with requests, .NET 8, Java 17+ or PHP 8 with the curl extension. The cURL samples use bash syntax.

#Create and track a batch

  1. Choose the source wallet

    Every payment in a batch comes out of one of your company wallets, the source wallet, and that wallet sets the currency of the whole batch. List your wallets with GetCompanyWallets and pick one in the currency you want to pay in.

    curl -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"
        }
      }
    }'
    Response
    {
      "GetCompanyWalletResponse": {
        "CompanyWalletResult": {
          "CompanyWallets": {
            "CompanyWalletDetails": [
              {
                "WalletID": 122181,
                "WalletName": "USD Wallet for Main Company",
                "WalletCurrency": "USD",
                "WalletBalance": 57715.15,
                "WalletType": "Standard",
                "IsBankLinked": false,
                "AllowWalletLinkedBankOverride": false,
                "EntityID": 12345
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Your USD wallet is 122181, with USD 57,715.15. The batch in this guide pays USD 200.00, plus a fee for each payment, which Xtrm charges to the source wallet on top of the payment's Amount. The submit call doesn't check your balance. Xtrm debits each payment when it processes it, and a payment the wallet can't cover at that point fails with INSUFFICIENT_BALANCE, so we recommend comparing WalletBalance with the batch's total, plus fees, before you submit.

    Keep for later:

    • The WalletID, 122181. You send it as SourceWalletId, a JSON number.
    • Its WalletCurrency, USD: every Amount in the batch is in this currency.
  2. Build and submit the batch

    A batch payment is one JSON object. Unlike most Xtrm requests, it has no wrapper object: these fields sit at the root of the body.

    FieldRequiredDescription
    IssuerAccountNumberYesYour company's account number.
    SourceWalletIdYesThe WalletID from step 1, as a JSON number. It must be an active wallet your company owns.
    CustomerBatchIdYesYour ID for the batch: 1 to 128 letters, digits and . _ - : @. Xtrm never generates one, and you need it to track the batch and retry its payments. CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID. See Batch and payment identifiers for every rule.
    EmailNotificationNoA JSON boolean. true emails each recipient a "payment received" message when their wallet is credited. false by default.
    ItemsYesThe payments: at least one, and no more than your account's limit.

    Each entry in Items is one payment:

    FieldRequiredDescription
    CustomerTransactionIdYesYour ID for the payment, with the same characters as CustomerBatchId. Xtrm never generates one. Give every payment its own.
    RecipientIdYesThe recipient's account number: PAT… for an individual, SPN… for a business.
    AmountYesA positive JSON number in the batch's currency, with at most 2 decimal places.
    SendMethodIdYesThe payment method. Take it from GetPaymentMethods: a batch accepts exactly its seven IDs, in capitals.
    DestinationYesThe fields the payment method needs. Send it on every item, even when all of its fields are optional.
    DescriptionNoA note for the payment, up to 1,024 characters. Xtrm copies it to the wallet transactions the payment creates: the debit in your source wallet and the credit in the recipient's wallet, where the recipient sees it. Start it with the payment's CustomerTransactionId, as the samples do, so you can find those transactions with SearchParam; see Track & reconcile payments.

    Send each value with the JSON type shown, as the samples do: SourceWalletId and Destination.WalletId as integers, Amount as a JSON number, EmailNotification as a boolean, and CustomerBatchId, CustomerTransactionId, RecipientId, SendMethodId, Description and the Destination text fields as strings. The batch endpoint also converts numeric strings, such as "100.00" and "122181", and the strings "true" and "false". A value it can't convert is read as empty, without a type error: an Amount of "abc" rejects the payment with Amount must be greater than zero., a SourceWalletId of "abc" refuses the whole batch with Invalid source wallet id., and an EmailNotification of "yes" is read as false. A text field sent as a JSON number is stored as text, so a CustomerTransactionId of 1001 becomes "1001". See Numbers and booleans as strings.

    The Destination fields for the three payment methods in this batch:

    Payment methodSendMethodIdDestination fields
    BankXTR94500BeneficiaryBankID: the ID of a bank account linked to the recipient. BeneficiaryBankPaymentMethod (optional): ACH, WIRE or RTP; without it, Xtrm uses the bank's primary rail.
    Business walletXTR94504WalletId (optional): the business's wallet to credit, in the batch's currency. Without it, Xtrm credits the business's oldest active Standard wallet in that currency, or creates one.
    Prepaid virtual debit cardXTR94503Email, which receives the card, and SKU, a card offered in the batch's currency. Both required. Individual recipients only.

    Individual wallets, digital gift cards, Rapid Transfer and checks work the same way. See Payment methods & destinations for every method's fields.

    This request pays the three recipients from wallet 122181. Replace the sample IDs with your own unique values before you run it in the sandbox.

    curl -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-GUIDE-0001",
      "Items": [
        {
          "CustomerTransactionId": "TXN-GUIDE-0001",
          "RecipientId": "SPN8888777",
          "Amount": 100,
          "SendMethodId": "XTR94500",
          "Destination": {
            "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
            "BeneficiaryBankPaymentMethod": "ACH"
          },
          "Description": "TXN-GUIDE-0001 Q3 Executive Sales Performance Incentive"
        },
        {
          "CustomerTransactionId": "TXN-GUIDE-0002",
          "RecipientId": "SPN8888776",
          "Amount": 50,
          "SendMethodId": "XTR94504",
          "Destination": {
            "WalletId": 122311
          },
          "Description": "TXN-GUIDE-0002 Q3 Channel Partner Marketing Bonus"
        },
        {
          "CustomerTransactionId": "TXN-GUIDE-0003",
          "RecipientId": "PAT9999888",
          "Amount": 50,
          "SendMethodId": "XTR94503",
          "Destination": {
            "Email": "[email protected]",
            "SKU": "PREP9001"
          },
          "Description": "TXN-GUIDE-0003 Q3 Top Performer Contractor Reward"
        }
      ]
    }'

    Xtrm checks the fields of every payment before it answers. When at least one passes, it answers 202 Accepted, with the result wrapped in BatchTransferResponse:

    Response
    {
      "BatchTransferResponse": {
        "CustomerBatchId": "BATCH-GUIDE-0001",
        "Status": "Accepted",
        "ItemsCount": {
          "Total": 3,
          "Accepted": 3,
          "Rejected": 0
        },
        "Accepted": [
          {
            "CustomerTransactionId": "TXN-GUIDE-0003",
            "Amount": 50.0,
            "Currency": "USD",
            "SendMethodId": "XTR94503",
            "RecipientId": "PAT9999888"
          },
          {
            "CustomerTransactionId": "TXN-GUIDE-0002",
            "Amount": 50.0,
            "Currency": "USD",
            "SendMethodId": "XTR94504",
            "RecipientId": "SPN8888776"
          },
          {
            "CustomerTransactionId": "TXN-GUIDE-0001",
            "Amount": 100.0,
            "Currency": "USD",
            "SendMethodId": "XTR94500",
            "RecipientId": "SPN8888777"
          }
        ],
        "Rejected": []
      }
    }

    Status Accepted means all three payments passed the checks and are queued, listed in Accepted in no particular order. Each entry echoes the payment's Amount as a JSON number with the decimals you sent, so the 100 and 50 here come back as 100.0 and 50.0. The status endpoints later return it as a string with 2 decimals, such as "100.00". Nobody has been paid yet, and a 202 doesn't prove that every payment in Accepted was stored, so confirm them in step 3. When some payments fail the checks, Status is CompletedWithFailures and Rejected lists each one with a Key, the Field that failed and a Message; see Items rejected at submission. A 202 whose Status is Failed stored nothing; see A safe retry pattern. Any other HTTP status means Xtrm refused the whole batch; see The whole batch is refused.

    Keep for later:

    • Your CustomerBatchId. Both status calls take it in the path.
    • The CustomerTransactionId of every payment, accepted or rejected.
  3. Track the batch until processing is over

    Xtrm processes the accepted payments in the background. To follow them, poll GET /Fund/BatchTransfer/{CustomerBatchId}. It returns the batch's Status, its Currency, the number of stored payments in ItemsCount and one page of Items, each with its own Status. recordsToSkip and recordsToTake page through the payments, and history=true adds each payment's attempts.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-GUIDE-0001?recordsToSkip=0&recordsToTake=50&history=true" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"

    The status object comes back at the root of the body, with no wrapper, and lists the payments in the order Xtrm stored them:

    Response
    {
      "CustomerBatchId": "BATCH-GUIDE-0001",
      "Status": "Completed",
      "Currency": "USD",
      "ItemsCount": 3,
      "Items": [
        {
          "CustomerTransactionId": "TXN-GUIDE-0001",
          "Status": "Success",
          "RecipientId": "SPN8888777",
          "SendMethodId": "XTR94500",
          "Amount": "100.00",
          "LastUpdatedAt": "2026-10-27T15:12:48.6410000Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T15:12:48.6370000Z",
              "CompletedAt": "2026-10-27T15:12:48.6410000Z"
            }
          ]
        },
        {
          "CustomerTransactionId": "TXN-GUIDE-0002",
          "Status": "Success",
          "RecipientId": "SPN8888776",
          "SendMethodId": "XTR94504",
          "Amount": "50.00",
          "LastUpdatedAt": "2026-10-27T15:12:41.0230000Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T15:12:41.0190000Z",
              "CompletedAt": "2026-10-27T15:12:41.0230000Z"
            }
          ]
        },
        {
          "CustomerTransactionId": "TXN-GUIDE-0003",
          "Status": "Success",
          "RecipientId": "PAT9999888",
          "SendMethodId": "XTR94503",
          "Amount": "50.00",
          "LastUpdatedAt": "2026-10-27T15:12:46.3080000Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T15:12:46.3040000Z",
              "CompletedAt": "2026-10-27T15:12:46.3080000Z"
            }
          ]
        }
      ],
      "Pagination": {
        "HasMore": false,
        "NextRecordsToSkip": 0
      }
    }

    All three payments read Success, so the batch reads Completed. For the business wallet, Success means Xtrm credited the wallet. For the bank payment and the prepaid card, it means the provider accepted the payment: the bank transfer may not have settled yet, and Jane has been emailed her card but may not have claimed it.

    We recommend this polling loop:

    1. On each poll, read every page: while Pagination.HasMore is true, call again with recordsToSkip set to Pagination.NextRecordsToSkip.
    2. Stop when the batch reads Completed, CompletedWithFailures or Failed and no payment on any page is Accepted, Processing or Verified. Check both. The batch can briefly read Failed or CompletedWithFailures while payments are still being validated. A payment by any method other than a wallet reads RetainedInWallet as soon as Xtrm credits the recipient's wallet, while Xtrm is still delivering it to the destination, and the batch reads Processing until that delivery is over. So while the batch reads Processing, count a RetainedInWallet payment as still in progress, and don't act on it. Wait longer between polls each time, and cap their number.
    3. Record each payment's Status against its CustomerTransactionId, and collect any Failed payments for step 5.

    For what each batch and payment status means and what to do about it, see Batch and payment statuses. Instead of polling, you can also have Xtrm notify your server as payments complete; see Webhooks, and confirm final statuses with the status endpoints.

    Keep for later: each payment's CustomerTransactionId and Status, and the IDs of any Failed payments.

  4. Inspect a payment and its attempts

    To answer a recipient's question about one payment, or to see why it failed, call GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}. It reads only committed data, so it's also the call to confirm a payment's status before you act on it, for example before you resend it. A 404 from it can be temporary, so repeat the check a few times, at least a minute apart, before you conclude that a payment wasn't stored; see A safe retry pattern. This request reads TXN-GUIDE-0001, the bank payment.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-GUIDE-0001/Items/TXN-GUIDE-0001?history=true" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"
    Response
    {
      "CustomerBatchId": "BATCH-GUIDE-0001",
      "CustomerTransactionId": "TXN-GUIDE-0001",
      "Status": "Success",
      "RecipientId": "SPN8888777",
      "SendMethodId": "XTR94500",
      "Amount": "100.00",
      "Currency": "USD",
      "DeliveryType": "Bank",
      "LastUpdatedAt": "2026-10-27T15:12:48.6410000Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Success",
          "ErrorCode": "SUCCESS",
          "CreatedAt": "2026-10-27T15:12:40.1170000Z",
          "CompletedAt": "2026-10-27T15:12:48.6410000Z"
        }
      ]
    }

    Besides the fields in the batch's list, this endpoint returns the payment's Currency and its DeliveryType: Bank here, because the money went on from SPN8888777's wallet to its bank account. Each attempt has its AttemptNo, its Result and an ErrorCode, which is SUCCESS when the attempt worked. Judge a payment by its Status, not by a single attempt: a payment can fail once and succeed when you retry it, as step 5 shows. See Attempts and history and Delivery type.

    Keep for later: the DeliveryType and LastUpdatedAt for your records.

  5. Retry a failed payment

    Every payment in BATCH-GUIDE-0001 succeeded, but sooner or later one won't. Say your next batch, BATCH-GUIDE-0002, pays SPN8888777 another USD 100.00 as TXN-GUIDE-0004, with a mistyped bank ID, 00000000000000000000000000000000, that isn't linked to anyone. The payment passes the submit checks, then fails validation. Step 4's call for TXN-GUIDE-0004 shows why:

    Response
    {
      "CustomerBatchId": "BATCH-GUIDE-0002",
      "CustomerTransactionId": "TXN-GUIDE-0004",
      "Status": "Failed",
      "RecipientId": "SPN8888777",
      "SendMethodId": "XTR94500",
      "Amount": "100.00",
      "Currency": "USD",
      "DeliveryType": "",
      "LastUpdatedAt": "2026-10-27T16:20:05.1180000Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Failed",
          "ErrorCode": "BANKID_INVALID",
          "CreatedAt": "2026-10-27T16:20:04.9950000Z",
          "CompletedAt": "2026-10-27T16:20:05.1180000Z"
        }
      ]
    }

    BANKID_INVALID means the BeneficiaryBankID isn't one of the recipient's linked bank accounts. No money moved, and the payment is Failed, so you can fix it and retry it under the same IDs. Xtrm then records a new attempt instead of a new payment, so nobody is paid twice.

    First, look up the bank accounts linked to SPN8888777 with GetLinkedBankAccounts. It needs SPN8888777 to be connected to your company, as it is when your company created it with CreateBeneficiary; to connect an existing account, see Connections and manager services.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/GetLinkedBankAccounts" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetLinkedBankAccounts": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "RecipientUserId": "SPN8888777"
        }
      }
    }'
    Response
    {
      "GetLinkedBankAccountsResponse": {
        "GetLinkedBankAccountsResult": {
          "Beneficiary": {
            "BeneficiaryDetails": [
              {
                "BeneficiaryId": "41953ec32f3e4765a35a902c82bdd995",
                "BeneficiaryName": "Northwind Traders LLC",
                "Currency": "USD",
                "Country": "United States of America",
                "TransferFee": 0,
                "PaymentMethods": {
                  "Payment": "ACH"
                },
                "BankDetails": {
                  "BeneficiaryBankInformation": {
                    "AccountNumber": "XXXX4321",
                    "BankName": "WELLS FARGO BANK, N.A.",
                    "BranchName": "Main Branch",
                    "BankBeneficiaryStatus": "Approved",
                    "ACHDebitApprovalStatus": null,
                    "BankRoutingCode": "121000248",
                    "EntityID": 0,
                    "PaymentMethods": [
                      "ACH"
                    ]
                  }
                }
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    SPN8888777's bank account is 41953ec32f3e4765a35a902c82bdd995, the BeneficiaryId. Now resubmit TXN-GUIDE-0004 under its original CustomerBatchId, BATCH-GUIDE-0002, with the corrected BeneficiaryBankID. A retry replaces the whole stored payment with the values you send, so send every field again, and keep the same RecipientId, SendMethodId, SourceWalletId and IssuerAccountNumber.

    curl -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-GUIDE-0002",
      "Items": [
        {
          "CustomerTransactionId": "TXN-GUIDE-0004",
          "RecipientId": "SPN8888777",
          "Amount": 100,
          "SendMethodId": "XTR94500",
          "Destination": {
            "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
            "BeneficiaryBankPaymentMethod": "ACH"
          },
          "Description": "TXN-GUIDE-0004 Q4 Executive Sales Performance Incentive"
        }
      ]
    }'

    Xtrm answers 202, with TXN-GUIDE-0004 in Accepted, and processes the payment again. The corrected bank ID takes effect because BANKID_INVALID is a validation failure. Once Xtrm has finished, step 4's call for TXN-GUIDE-0004 shows both attempts:

    Response
    {
      "CustomerBatchId": "BATCH-GUIDE-0002",
      "CustomerTransactionId": "TXN-GUIDE-0004",
      "Status": "Success",
      "RecipientId": "SPN8888777",
      "SendMethodId": "XTR94500",
      "Amount": "100.00",
      "Currency": "USD",
      "DeliveryType": "Bank",
      "LastUpdatedAt": "2026-10-27T16:41:37.5520000Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Failed",
          "ErrorCode": "BANKID_INVALID",
          "CreatedAt": "2026-10-27T16:41:30.8030000Z",
          "CompletedAt": "2026-10-27T16:41:37.5520000Z"
        },
        {
          "AttemptNo": 2,
          "Result": "Success",
          "ErrorCode": "SUCCESS",
          "CreatedAt": "2026-10-27T16:41:30.8030000Z",
          "CompletedAt": "2026-10-27T16:41:37.5520000Z"
        }
      ]
    }

    The payment is now Success, and the failed first attempt stays in its history. On this endpoint every attempt repeats the payment's latest submission and update times, so go by AttemptNo, not the timestamps.

    Retry other failures the same way, once you've fixed the cause. A few things to know:

    • Only a Failed payment can be retried. Resend only the payments you're retrying: any other payment you include comes back in Rejected as CONFLICT_DUPLICATE_ITEM and isn't paid again.
    • A corrected Destination takes effect only after a validation failure, as here. After a failure at the wallet-credit stage, such as INSUFFICIENT_BALANCE, add funds and resend the payment unchanged: Xtrm keeps the destination it resolved the first time.
    • To pay a different recipient or use a different payment method, send a new payment with a new CustomerTransactionId instead of changing the failed one.
    • Before you retry a payment whose latest attempt failed with TEMPORARY_ERROR, contact Xtrm support: the money may already have moved.

    For every rule, see Resubmit failed payments and Retry a batch payment.

    Keep for later: the CustomerTransactionId of each retried payment, to track its new attempt.

#What can go wrong

#The whole batch is refused

When the request fails a check on the whole batch, or none of its payments pass, Xtrm refuses the batch and stores nothing. For example:

  • A SourceWalletId that isn't an active wallet of your company, such as 999999, gets 403 Forbidden.
  • A missing IssuerAccountNumber or CustomerBatchId, an empty Items list, more payments than your account's limit (LIMIT_EXCEEDED), or a batch whose every payment is rejected, gets 422 Unprocessable Entity. When every payment is rejected and one of them is CONFLICT_DUPLICATE_ITEM, the status is 409 instead.
  • A CustomerBatchId that is already in use, with none of its payments Failed, gets 409 CONFLICT_PROCESSING. See Duplicate IDs and refused retries.
  • A missing or expired token gets 401 Unauthorized. Get a new token and send the same request again; see Authentication.

Log the full response body: it carries the reason in Key and Message, or error and error_message for a token problem. Fix the request and send it again. For every status and its body, see The whole request is refused.

#Items rejected at submission

A payment that fails the submit checks comes back in Rejected, with a Key, the Field that failed and a Message, while the rest of the batch goes ahead. For example, an Amount of 0, or a SendMethodId that isn't one of the seven batch methods, such as XTR99999, is rejected with INVALID_FIELD. What to do depends on the Key:

  • INVALID_FIELD, DUPLICATE_ITEM_IN_REQUEST or CURRENCY_MISMATCH. Xtrm didn't store the payment. Fix it and submit it in a new batch with a new CustomerBatchId; it can keep its CustomerTransactionId.
  • CONFLICT_DUPLICATE_ITEM. The payment is already stored in this batch, for example by an earlier request whose response you lost. Don't send it again, in this batch or a new one; follow it with the status endpoints.
  • TEMPORARY_ERROR. Xtrm couldn't store the payment, but another request may have. Confirm with the payment status endpoint that it isn't stored, repeating the check a few times, at least a minute apart, before you submit it again; see A safe retry pattern.

See Items rejected at submission for every check.

#Duplicate IDs and refused retries

Xtrm uses your CustomerBatchId and CustomerTransactionId to tell a new payment from a resubmitted one. The same CustomerTransactionId twice in one request rejects every copy with DUPLICATE_ITEM_IN_REQUEST. Resending a stored payment under its original CustomerBatchId retries it if it's Failed, and otherwise returns CONFLICT_DUPLICATE_ITEM. A CustomerTransactionId you already used in a different batch is a new payment, and Xtrm pays it. So give every new payment a new CustomerTransactionId and every new batch a new CustomerBatchId, and never reuse an ID for a different payment. See Duplicate IDs.

#Payments that fail during processing

An accepted payment can still fail when Xtrm processes it. The latest attempt's ErrorCode says why. For example:

  • A RecipientId that isn't an Xtrm account, such as PAT0000001, fails with RECIPIENT_NOT_FOUND. Pay the right account as a new payment, with a new CustomerTransactionId.
  • A BeneficiaryBankID that isn't linked to the recipient fails with BANKID_INVALID. Step 5 shows the fix.
  • A prepaid card SKU that isn't offered in the batch's currency, such as PREP0000, fails with SKU_NOT_FOUND. Take the SKU from GetPrepaidCards and retry.
  • A payment your source wallet can't cover, with its fee, when Xtrm processes it fails with INSUFFICIENT_BALANCE. Add funds and retry it unchanged.

For every code and what to do about it, see Error codes on attempts. We recommend sending any code you don't recognize to manual review, and contacting support when you can't tell the cause from the code.

#Payments retained in a wallet

A bank, card, check, gift card or prepaid payment shows RetainedInWallet while Xtrm delivers it from the recipient's wallet, usually only briefly, before it moves on to Success. Don't act on it while its batch still reads Processing: it may still be on its way to the destination. If the payment is still RetainedInWallet once the batch status is final, the delivery didn't go through, and its newest attempt's ErrorCode says why. The money is in the recipient's Xtrm wallet, so treat it like a wallet payment: the recipient signs in to transfer it out (Xtrm emailed them when the money reached their wallet, if the batch set EmailNotification to true), or, if the recipient is connected to your company, you can request the transfer for them with their one-time password. You can't retry or resubmit the payment, and the fee isn't refunded. See When a payment stays RetainedInWallet.

#The batch stays in progress

A batch reads Processing while at least one of its payments is still in progress. We recommend capping your polling loop, as the full example does, so it can't run forever. If a batch is still Processing when your loop gives up, check it again later. A batch also stays Processing while Xtrm holds a payment's delivery, for example for a compliance review: the payment stays RetainedInWallet with no new attempt. If that lasts more than one business day, contact Xtrm support with the CustomerBatchId and CustomerTransactionId; see When a payment stays RetainedInWallet.

#Limits and other rules

  • Batch size. Your account has a maximum number of payments per batch, and every request has a maximum size. Split a larger set of payments into several batches, each with its own CustomerBatchId. See Limits.
  • One currency per batch. The source wallet sets the currency. To pay in several currencies, submit one batch per wallet. To move money into a wallet in another currency, see Exchange currency.
  • One request per batch at a time. Xtrm accepts different batches at the same time, but never send two requests with the same CustomerBatchId at once. See Don't overlap requests for one batch.

#Full example

This program runs the whole flow. It gets an access token and submits the three-payment batch from step 2. It then polls the batch's status, reading every page each time, until the batch reads final and no payment is still Accepted, Processing or Verified (waiting 5 seconds, then twice as long each time up to 60 seconds, for at most 20 polls). While the batch reads Processing, it counts a RetainedInWallet payment as still in progress. Finally, it reads every payment again with its attempts and prints each payment's status with a note: paid, failed with the newest attempt's ErrorCode, in wallet, not delivered with the newest attempt's ErrorCode for a payment that stayed RetainedInWallet, or in progress. It reads XTRM_CLIENT_ID and XTRM_CLIENT_SECRET from the environment. Replace SPN1111222, the wallet ID and the recipients with your own values before you run it. CustomerBatchId values are shared across all Xtrm accounts, so also replace the sample IDs with your own unique values, for example ones that include your account number or a UUID.

#!/usr/bin/env bash
# Save as batch-payment.sh and run: bash batch-payment.sh
set -euo pipefail

BATCH_ID="BATCH-GUIDE-0001" # the CustomerBatchId in the body below
MAX_POLLS=20

# 1. Get an access token.
TOKEN_RESPONSE=$(curl -sS -X POST "https://xapisandbox.xtrm.com/oAuth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=$XTRM_CLIENT_ID" \
  --data-urlencode "client_secret=$XTRM_CLIENT_SECRET")
ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"access_token" *: *"\([^"]*\)".*/\1/p')
if [ -z "$ACCESS_TOKEN" ]; then
  echo "Token request failed: $TOKEN_RESPONSE" >&2
  exit 1
fi

# 2. Submit the batch. Xtrm answers 202 Accepted when at least one item passes validation.
SUBMIT=$(curl -sS -w '\n%{http_code}' -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "IssuerAccountNumber": "SPN1111222",
  "SourceWalletId": 122181,
  "CustomerBatchId": "BATCH-GUIDE-0001",
  "Items": [
    {
      "CustomerTransactionId": "TXN-GUIDE-0001",
      "RecipientId": "SPN8888777",
      "Amount": 100,
      "SendMethodId": "XTR94500",
      "Destination": {
        "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
        "BeneficiaryBankPaymentMethod": "ACH"
      },
      "Description": "TXN-GUIDE-0001 Q3 Executive Sales Performance Incentive"
    },
    {
      "CustomerTransactionId": "TXN-GUIDE-0002",
      "RecipientId": "SPN8888776",
      "Amount": 50,
      "SendMethodId": "XTR94504",
      "Destination": {
        "WalletId": 122311
      },
      "Description": "TXN-GUIDE-0002 Q3 Channel Partner Marketing Bonus"
    },
    {
      "CustomerTransactionId": "TXN-GUIDE-0003",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94503",
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      },
      "Description": "TXN-GUIDE-0003 Q3 Top Performer Contractor Reward"
    }
  ]
}')
HTTP_STATUS=$(printf '%s' "$SUBMIT" | tail -n 1)
SUBMIT_BODY=$(printf '%s' "$SUBMIT" | sed '$d' | tr -d '\r\n')
# In the documented response, the first Status is the batch's.
SUBMIT_STATUS=$( (printf '%s' "$SUBMIT_BODY" | grep -o '"Status" *: *"[^"]*"' || true) | sed -n '1s/.*"\([^"]*\)"$/\1/p')
case "$HTTP_STATUS" in
  2??)
    if [ "$SUBMIT_STATUS" = "Failed" ]; then
      # TEMPORARY_ERROR: this call stored nothing, but an earlier request may have. Wait, then confirm
      # what was stored with the batch status endpoint before you run the program again.
      echo "This call stored nothing: $SUBMIT_BODY" >&2
      exit 1
    fi
    echo "Submitted $BATCH_ID: $( (printf '%s' "$SUBMIT_BODY" | grep -o '"ItemsCount" *: *{[^}]*}' || true) | sed 's/^"ItemsCount" *: *//')"
    # The pattern skips brackets inside strings, such as the item index in a rejected Field path.
    echo "Rejected: $( (printf '%s' "$SUBMIT_BODY" | grep -oE '"Rejected" *: *\[([^]"]|"[^"]*")*\]' || true) | sed 's/^"Rejected" *: *//')"
    ;;
  409)
    # The batch ID is already in use, for example by an earlier batch of this program: track that batch.
    echo "$BATCH_ID is already in use (HTTP 409): $SUBMIT_BODY"
    ;;
  *) echo "Batch not accepted (HTTP $HTTP_STATUS): $SUBMIT_BODY" >&2; exit 1 ;;
esac

# Gets one page of the batch status, as a single line of JSON. $1 is recordsToSkip, $2 is history.
get_page() {
  curl -sS -f "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/$BATCH_ID?recordsToSkip=$1&recordsToTake=50&history=$2" \
    -H "Authorization: Bearer $ACCESS_TOKEN" | tr -d '\r\n'
}

# Reads every page of the batch status. Prints the batch Status on the first line,
# then one line per item, with its attempts. $1 is history (true or false).
read_batch() {
  local page next
  page=$(get_page 0 "$1") || return 1
  # In the documented response, the batch Status comes before the Items array.
  echo "$( (printf '%s' "$page" | grep -o '"Status" *: *"[^"]*"' || true) | sed -n '1s/.*"\([^"]*\)"$/\1/p')"
  while :; do
    # Start a new line at each item, then drop the part before the first item.
    printf '%s\n' "$page" | awk '{ gsub(/"CustomerTransactionId"/, "\n&"); print }' | sed '1d'
    if [ "$( (printf '%s' "$page" | grep -o '"HasMore" *: *[a-z]*' || true) | sed 's/.*: *//')" != "true" ]; then
      break
    fi
    next=$( (printf '%s' "$page" | grep -o '"NextRecordsToSkip" *: *[0-9]*' || true) | sed 's/.*: *//')
    page=$(get_page "$next" "$1") || return 1
  done
}

# Prints the first value of a string field in one line of JSON. $1 is the line, $2 the field name.
field() {
  (printf '%s' "$1" | grep -o "\"$2\" *: *\"[^\"]*\"" || true) | sed -n '1s/.*"\([^"]*\)"$/\1/p'
}

# 3. Poll until the batch status is final and no item is still in progress, waiting longer
#    between polls. A batch can read Failed or CompletedWithFailures while some items are
#    still being validated, so check the items too.
DELAY=5
POLL=1
while :; do
  BATCH=$(read_batch false)
  BATCH_STATUS=$(printf '%s\n' "$BATCH" | sed -n '1p')
  # While the batch reads Processing, a RetainedInWallet item is still on its way to the destination.
  OPEN_STATUSES='Accepted|Processing|Verified'
  if [ "$BATCH_STATUS" = "Processing" ]; then
    OPEN_STATUSES="$OPEN_STATUSES|RetainedInWallet"
  fi
  # Each item line has one Status, the item's (attempts use Result).
  OPEN=$(printf '%s\n' "$BATCH" | sed '1d' | grep -cE "\"Status\" *: *\"($OPEN_STATUSES)\"" || true)
  echo "Poll $POLL: batch is $BATCH_STATUS, $OPEN item(s) still in progress"
  case "$BATCH_STATUS" in
    Completed | CompletedWithFailures | Failed)
      if [ "$OPEN" -eq 0 ]; then
        break
      fi
      ;;
  esac
  if [ "$POLL" -ge "$MAX_POLLS" ]; then
    echo "Batch still in progress after $MAX_POLLS polls. Check it again later." >&2
    exit 1
  fi
  sleep "$DELAY"
  DELAY=$(( DELAY * 2 > 60 ? 60 : DELAY * 2 ))
  POLL=$(( POLL + 1 ))
done

# 4. Read every item again with its attempts, and print its status with a note.
read_batch true | sed '1d' | while IFS= read -r ITEM; do
  STATUS=$(field "$ITEM" Status)
  # The newest attempt is the one with the highest AttemptNo. In the documented response,
  # each attempt lists AttemptNo, Result and ErrorCode in that order.
  NEWEST=$( (printf '%s' "$ITEM" | grep -oE '"AttemptNo" *: *[0-9]+ *, *"Result" *: *"[^"]*" *, *"ErrorCode" *: *"[^"]*"' || true) \
    | sed -E 's/"AttemptNo" *: *([0-9]+) *, *"Result" *: *"([^"]*)" *, *"ErrorCode" *: *"([^"]*)"/\1 \2 \3/' \
    | sort -n | tail -n 1)
  CODE=$(printf '%s' "$NEWEST" | cut -s -d ' ' -f 3)
  # The batch is final here, so a RetainedInWallet item has stuck: its delivery didn't go through.
  case "$STATUS" in
    Success) NOTE="paid" ;;
    Failed) NOTE="failed: $CODE" ;;
    RetainedInWallet) NOTE="in wallet, not delivered: $CODE" ;;
    *) NOTE="in progress" ;;
  esac
  echo "$(field "$ITEM" CustomerTransactionId)  $STATUS  $(field "$ITEM" Amount)  $(field "$ITEM" RecipientId)  $NOTE"
done

The cURL version reads the responses with grep, sed and awk; for anything more, use a JSON tool such as jq. The Java version reads fields with regular expressions to avoid dependencies; we recommend a JSON library such as Jackson in production code.

Act on the notes the program prints. Fix and retry failed payments as in step 5. The note in wallet, not delivered marks a payment that stayed RetainedInWallet after the batch finished: the money is in the recipient's Xtrm wallet, and you can't retry the payment; see Payments retained in a wallet.

The program sends fixed IDs, so running it again resends BATCH-GUIDE-0001 instead of creating a new batch. Xtrm retries any Failed payment as a new attempt and returns the others in Rejected as CONFLICT_DUPLICATE_ITEM without paying them again. If no payment in the batch is Failed, Xtrm answers 409, and the program tracks the existing batch. If Xtrm answers 202 with Status Failed, that call stored nothing and the program stops; see A safe retry pattern. To create a new batch, change CustomerBatchId and every CustomerTransactionId.

#Next steps