Guide

Pay individual recipients

Paying a person through Xtrm takes a handful of calls: find or create their account, tell Xtrm where the money should go, and pay them in a batch, one request that can pay many recipients at once. This guide follows one person, Jane Doe, from first lookup to confirmed payment. You look her up by email, create her account, link her bank account, and pay her into her Xtrm wallet and her bank in the same batch. Then you confirm that each payment landed, with the status endpoints or a webhook. Each request runs on its own against the sandbox, so you can follow along one step at a time.

The same request pays one person or many, up to your account's limit of items per batch. A batch pays existing Xtrm accounts only, by their account numbers, so each person needs an account before you build the batch: you find it in step 1, or create it with CreateUser in step 2. For how Xtrm processes a batch, see How batch payments work. For every send method and option, see Create a batch payment.

#Before you begin

  • Sandbox credentials. Your client ID and secret from Settings → Integrations → Get Credentials in the sandbox web app, with your IP addresses approved. See Sandbox & environments.
  • An access token in the XTRM_ACCESS_TOKEN environment variable. Every request in this guide sends it as Authorization: Bearer <token>. See Authentication.
  • Your company account number. It starts with SPN and goes in IssuerAccountNumber. The samples use SPN1111222.
  • A funded company wallet to pay from, and its wallet ID. The wallet you pay from sets the currency of the whole batch. GetCompanyWallets lists your wallets with their currencies and balances. In the sandbox, Xtrm credits test funds to your wallets after it approves your IP addresses (see Test funds); to add more, see Fund your wallet. The samples use wallet 122181.
  • The person's details: email address, legal first and last name, and country of residence.
  • For the bank payment, the person's bank account: the bank's name, routing number and account number, with the account holder's phone number and address.

#The flow at a glance

StepCallKeep from the response
1CheckUserExistAccountNo, if the person already has an account
2CreateUser, only if neededUserID of the new account
3GetPaymentMethods, optionalThe send method IDs: XTR94502 (wallet) and XTR94500 (bank)
4GetUserWallets, optionalThe WalletID in the batch's currency
5LinkBankBeneficiaryBeneficiaryId of the linked bank
6GetLinkedBankAccountsThe bank's BeneficiaryId and its rails in PaymentMethods
7BatchTransferCustomerBatchId, and which items are in Accepted and Rejected
8Batch statusThe batch's Status and each item's Status
9Payment statusThe item's Status, DeliveryType and Attempts
10GetUserWalletBalance, optionalBalance

#Pay an individual recipient

  1. Check whether the person already has an account

    Look the person up by email with CheckUserExist before you create anything. That way you don't open a second account for an email address that already has one. To page through every individual recipient associated with your company instead, use GetPersonalBeneficiaries.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckUserExist" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CheckUserExist": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "Email": "[email protected]"
        }
      }
    }'

    Jane is new to Xtrm, so no account matches. The call returns HTTP 200 with Success true and Beneficiary set to null:

    Response
    {
      "CheckUserExistResponse": {
        "CheckUserExistResult": {
          "Beneficiary": null,
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    When accounts match the email address exactly, Beneficiary is an array of up to 30 of them, in no set order. Each entry has the account number in AccountNo (a PAT number), Name, State, Country (the full country name), Employer, Status and AccountIdentityLevel, the account's identity verification level: Draft, Basic, Standard or Advanced. If you get more than one, confirm with the person which account to pay rather than picking one.

    Handle the outcomes separately:

    • OperationStatus.Success is true and Beneficiary is null or empty. The person is new. Continue with step 2.
    • Success is true and Beneficiary has an entry. The person already has an account, so don't create another. Use its AccountNo as the RecipientId of your items, skip step 2, and read the note below.
    • Success is false. Log OperationStatus.Errors and stop. Don't call CreateUser until you know why the lookup failed: a failed call doesn't necessarily mean that no account exists.

    If the person already has an account

    You can pay an existing account straight away with a wallet item whose Destination is empty, {}. A batch payment needs no connection to the recipient: it pays any Xtrm account whose status is Active, Email not verified or Account pending approval. Listing the person's wallets (step 4) works without a connection too. Linking and reading their bank account (steps 5 and 6) and reading their balance (step 10) need the account to be connected to your company. An account you create is connected from the start. To connect an existing one, its holder gives you a one-time password: see Connect existing accounts, and for what a connection allows, Connections and manager services.

  2. Create the individual recipient

    If no account exists, create one with CreateUser. The required fields are IssuerAccountNumber, EmailAddress, EmailNotification, LegalFirstName, LegalLastName and the country in Address.CountryISO2. The sample also sends a street address and a date of birth, which takes separate Day, Month and Year strings. You can add MobilePhone (without the country code, which Xtrm derives from the country) and TaxId.

    Set EmailNotification to "true" to email the person that their account was created. Xtrm also creates a wallet for the new account, named Wallet - <currency code>, in the currency of the country you send in Address.CountryISO2, plus a Wallet - USD wallet when that currency isn't USD.

    Each email address can belong to only one personal account, and the sandbox is shared, so in the sandbox use an address of your own that has no Xtrm account yet. If the address already has one, CreateUser answers 400 with Email Already Exists: look the account up as in step 1 and pay it instead.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Register/CreateUser" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CreateUser": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "EmailAddress": "[email protected]",
          "EmailNotification": "true",
          "LegalFirstName": "Jane",
          "LegalLastName": "Doe",
          "Address": {
            "AddressLine1": "123 Main Street",
            "City": "Los Angeles",
            "Region": "CA",
            "PostalCode": "90001",
            "CountryISO2": "US"
          },
          "DateOfBirth": {
            "Day": "15",
            "Month": "08",
            "Year": "1990"
          }
        }
      }
    }'
    Response
    {
      "CreateUserResponse": {
        "CreateUserResult": {
          "UserID": "PAT9999888",
          "AccountIdentityLevel": "Basic",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep UserID, the new account number (PAT9999888). It's the RecipientId of your items. AccountIdentityLevel is the account's identity verification level: Draft, Basic, Standard or Advanced. This sample sends no TaxId, so the new account is Basic; with a tax ID as well as the address and date of birth, it would be Standard. We recommend storing the PAT number with the person's record in your system, so later payments to them can skip steps 1 and 2.

    CreateUser also connects the new account to your company, which steps 5, 6 and 10 need. Xtrm approves an account you create through the API straight away, so you can pay it right away. A batch payment accepts recipients whose account is Active, Email not verified or Account pending approval, which covers a newly created account, and it doesn't wait for the KYC review.

  3. Look up the send method IDs

    Each item in a batch names how the money is delivered in SendMethodId. Take the IDs from GetPaymentMethods: it lists exactly the seven send methods a batch accepts. The call takes an empty JSON object, {}, as the body and returns the same list for every account, so this step is optional: use it to confirm the IDs when you set up your integration.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Payment/GetPaymentMethods" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{}'
    Response
    {
      "GetPaymentMethodsResponse": {
        "PaymentMethodResult": {
          "PaymentMethods": {
            "PaymentMethodDetails": [
              {
                "PaymentMethodId": "XTR94504",
                "PaymentMethodName": "AnyPay Company"
              },
              {
                "PaymentMethodId": "XTR94502",
                "PaymentMethodName": "AnyPay Individual"
              },
              {
                "PaymentMethodId": "XTR94500",
                "PaymentMethodName": "Bank"
              },
              {
                "PaymentMethodId": "XTR94507",
                "PaymentMethodName": "Bank Check"
              },
              {
                "PaymentMethodId": "XTR94505",
                "PaymentMethodName": "Digital Gift Cards"
              },
              {
                "PaymentMethodId": "XTR94503",
                "PaymentMethodName": "Prepaid Virtual Debit Card"
              },
              {
                "PaymentMethodId": "XTR94508",
                "PaymentMethodName": "Rapid Transfer"
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    This guide uses two of them:

    • XTR94502 (AnyPay Individual) pays into the person's Xtrm wallet. Xtrm recommends paying into the wallet, because the person then chooses how to transfer the funds out of Xtrm. It pays individual recipients only: the item's RecipientId must start with PAT, or the item is rejected when you submit. To pay a business recipient's wallet, use XTR94504 (see Pay business recipients).
    • XTR94500 (Bank) pays through to a bank account linked to the person's account.

    Send each ID exactly as listed, in capitals. You can also pay a person by prepaid card (XTR94503), gift card (XTR94505), check (XTR94507, US only) or Rapid Transfer to a card (XTR94508); see Payment methods & destinations. Don't take send method IDs from GetUserPaymentMethods: it lists the ways a person can move their own money, and it includes XTR94506 (Reward Link), which a batch rejects. See Choose a payment method list.

  4. Find the person's wallet

    A wallet item pays into one of the person's wallets, which you name in Destination.WalletId. That field is optional: without it, Xtrm picks the wallet for you (see step 7). To pay into a specific wallet, list the person's wallets with GetUserWallets. Send the PAT number in UserID, and note the capital R in this endpoint's Request object. This call needs no connection to the person.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWallets" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetUserWallets": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "PAT9999888"
        }
      }
    }'
    Response
    {
      "GetUserWalletsResponse": {
        "GetUserWalletsResult": {
          "Wallets": [
            {
              "WalletName": "Wallet - USD",
              "WalletID": 67812,
              "WalletCurrency": "USD"
            }
          ],
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Jane's new account has one wallet, the USD wallet that CreateUser set up for her. An individual recipient has one wallet per currency. Keep the WalletID of the wallet in the batch's currency: 67812 here. You send it as a number in Destination.WalletId too. The response doesn't include balances. Step 10 shows how to get one.

  5. Link the person's bank account

    A bank item pays a bank account linked to the person's account, which you name by its ID. Jane's account is new, so link her bank account with LinkBankBeneficiary, sending her PAT number in UserID. Linking needs her account to be connected to your company, and an account you created with CreateUser is. The body has two parts: BeneficiaryInformation, the account holder and their address, and BeneficiaryBankInformation, the bank account. WithdrawType sets how the money moves to the bank, ACH here. For every field, banks in other countries and IBANs, see Bank accounts & transfers.

    The sandbox has no test bank accounts: send a real bank's routing number or SWIFT-BIC, as the sample does, with a made-up account number in the format the bank's country needs, never a real one. See Test bank accounts.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/LinkBankBeneficiary" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "LinkBankBeneficiary": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "PAT9999888",
          "Beneficiary": {
            "BeneficiaryDetails": {
              "BeneficiaryInformation": {
                "ContactName": "Jane Doe",
                "PhoneNumber": "3105550142",
                "AddressLine1": "123 Main Street",
                "City": "Los Angeles",
                "Region": "CA",
                "PostalCode": "90001",
                "CountryISO2": "US"
              }
            },
            "BankDetails": {
              "BeneficiaryBankInformation": {
                "InstitutionName": "JPMorgan Chase Bank",
                "Currency": "USD",
                "SWIFTBIC": "CHASUS33",
                "AccountNumber": "000123458910",
                "RoutingNumber": "021000021",
                "CountryISO2": "US",
                "WithdrawType": "ACH"
              }
            }
          }
        }
      }
    }'
    Response
    {
      "LinkBankBeneficiaryResponse": {
        "LinkBankBeneficiaryResult": {
          "BeneficiaryId": "907599f594b044d08cf81a2afb0a7967",
          "BankBeneficiaryStatus": "Approved",
          "AccountIdentityLevel": "Basic",
          "ACHDebitApprovalStatus": null,
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    Keep BeneficiaryId, the ID of the linked bank (907599f594b044d08cf81a2afb0a7967). It's the BeneficiaryBankID of your bank item. AccountIdentityLevel is the person's identity verification level. A person can have up to 3 linked banks.

    When the bank's country and currency need fields you didn't send, nothing is linked: the response is HTTP 400 with OperationStatus.Success set to false, and Errors names each field to add or fix. Send the whole request again with those fields, and repeat until the response returns a BeneficiaryId.

  6. Read back the bank's ID and rails

    GetLinkedBankAccounts lists the bank accounts linked to the person in RecipientUserId, each with its ID and the rails it supports. Use it to confirm the bank you linked, and to find the bank again for later payments without linking it twice. Like linking, it needs the account to be connected to your company.

    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": "PAT9999888"
        }
      }
    }'
    Response
    {
      "GetLinkedBankAccountsResponse": {
        "GetLinkedBankAccountsResult": {
          "Beneficiary": {
            "BeneficiaryDetails": [
              {
                "BeneficiaryId": "907599f594b044d08cf81a2afb0a7967",
                "BeneficiaryName": "Jane Doe",
                "Currency": "USD",
                "Country": "United States of America",
                "TransferFee": 0,
                "PaymentMethods": {
                  "Payment": "ACH"
                },
                "BankDetails": {
                  "BeneficiaryBankInformation": {
                    "AccountNumber": "XXXX8910",
                    "BankName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
                    "BranchName": "San Francisco Main",
                    "BankBeneficiaryStatus": "Approved",
                    "ACHDebitApprovalStatus": null,
                    "BankRoutingCode": "021000021",
                    "EntityID": 0,
                    "PaymentMethods": [
                      "ACH"
                    ]
                  }
                }
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep the bank's BeneficiaryId and the PaymentMethods array inside BankDetails, not the PaymentMethods object on the entry. The response has no field named BeneficiaryBankID: BeneficiaryId is the value you send as Destination.BeneficiaryBankID. You can name one of the bank's rails in BeneficiaryBankPaymentMethod (ACH, WIRE or RTP). Without it, Xtrm uses the bank account's primary rail, and a rail the account doesn't support fails during processing with INVALID_PAYMENTMETHOD.

  7. Pay the person in a batch

    Submit the payments with BatchTransfer (POST /API/v4/Fund/BatchTransfer). Unlike the other calls in this guide, the body has no wrapper object: the batch's fields sit at the root.

    FieldSample valueWhat it is
    IssuerAccountNumberSPN1111222Your company account number. Required.
    SourceWalletId122181The company wallet that funds the batch, as an integer. It sets the batch's currency. Required.
    CustomerBatchIdBATCH-USERS-0001Your ID for the batch. Required: Xtrm never generates one, and you need it to check the status.
    Items[].CustomerTransactionIdTXN-USERS-0001Your ID for the item. Required: Xtrm never generates one. You use it to look the item up and match it to your records.
    Items[].RecipientIdPAT9999888The person's account number from step 1 or 2. Required.
    Items[].Amount50The amount, as a JSON number greater than 0. Send at most 2 decimal places. Required.
    Items[].SendMethodIdXTR94502How the money is delivered (step 3). Required.
    Items[].Destination{"WalletId": 67812}Delivery details for the send method. Required on every item: for a wallet item without a WalletId, send {}.
    Items[].DescriptionTXN-USERS-0001 Q3 sales bonusA note for the payment, up to 1,024 characters. Optional. Xtrm copies it to the wallet transactions the payment creates: the debit in your source wallet and the credit in the person's wallet, where the person sees it. Start it with the item's CustomerTransactionId, as the samples do, so you can find those transactions later; see Track & reconcile payments.

    The sample batch makes two payments to Jane:

    • A wallet item (XTR94502) pays USD 50.00 into her USD wallet 67812, from step 4. To let Xtrm choose the wallet instead, send an empty Destination, {}: Xtrm then credits her oldest active Standard wallet in the batch's currency, and creates one named Wallet - <currency code> if she has none. A WalletId you send must be an active wallet of hers in the batch's currency, or the item fails with INVALID_BENEFICIARY_WALLET before any money moves.
    • A bank item (XTR94500) pays USD 100.00 by ACH to her bank account 907599f594b044d08cf81a2afb0a7967, from steps 5 and 6. For an individual recipient, BeneficiaryBankID is required: Xtrm never falls back to a default bank for a person.

    To pay more people, add one item per payment. Every item can use its own send method. Give every payment its own CustomerTransactionId, and never reuse one for a different payment, even in another batch. For the ID rules, see Batch and payment identifiers.

    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-USERS-0001",
      "Items": [
        {
          "CustomerTransactionId": "TXN-USERS-0001",
          "RecipientId": "PAT9999888",
          "Amount": 50,
          "SendMethodId": "XTR94502",
          "Destination": {
            "WalletId": 67812
          },
          "Description": "TXN-USERS-0001 Q3 sales bonus"
        },
        {
          "CustomerTransactionId": "TXN-USERS-0002",
          "RecipientId": "PAT9999888",
          "Amount": 100,
          "SendMethodId": "XTR94500",
          "Destination": {
            "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967",
            "BeneficiaryBankPaymentMethod": "ACH"
          },
          "Description": "TXN-USERS-0002 Q3 sales bonus"
        }
      ]
    }'

    Xtrm checks the request and each item's fields right away. If at least one item passes, it queues the items that passed and responds 202. If none passes, it stores nothing and responds 422, or 409 when an item already exists in this batch; see What can go wrong. When both items pass, the response lists them in Accepted, with the Currency of your source wallet and each Amount as a JSON number with the decimals you sent, so the 50 and 100 here come back as 50.0 and 100.0:

    Response (excerpt)
    {
      "BatchTransferResponse": {
        "CustomerBatchId": "BATCH-USERS-0001",
        "Status": "Accepted",
        "Accepted": [
          {
            "CustomerTransactionId": "TXN-USERS-0001",
            "Amount": 50.0,
            "Currency": "USD",
            "SendMethodId": "XTR94502",
            "RecipientId": "PAT9999888"
          },
          {
            "CustomerTransactionId": "TXN-USERS-0002",
            "Amount": 100.0,
            "Currency": "USD",
            "SendMethodId": "XTR94500",
            "RecipientId": "PAT9999888"
          }
        ],
        "Rejected": []
      }
    }

    Keep CustomerBatchId and each CustomerTransactionId with your payment records. A 202 means Xtrm received the batch, not that anyone has been paid: Xtrm checks your balance and moves the money while it processes the items in the background. Confirm the outcome with the status calls in the next steps. An item in Rejected wasn't stored; its entry names the Field that failed and a Message. To fix and resend such items, see Items rejected at submission.

    Both items credit Jane's Xtrm wallet first. For the bank item, Xtrm then pays the money on to her bank. While it does, the bank item shows RetainedInWallet, usually only briefly, and then moves on to Success, so don't act on RetainedInWallet while the batch is still Processing. If the item is still RetainedInWallet once the batch status is final, the bank payment didn't go through: the money has left your wallet and stays in Jane's Xtrm wallet, the fee isn't refunded, and you can't retry or resubmit the item. Treat it like a wallet payment: Jane can transfer it out herself in the Xtrm web app, or you can request the transfer for her with her one-time password; see When a payment stays RetainedInWallet.

  8. Check the batch status

    Poll the batch status endpoint, GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}, with your own CustomerBatchId. If you've turned on webhooks, use this call to confirm final statuses. It returns a summary of the batch and a page of its items. Page through the items with recordsToSkip and recordsToTake, and set history to true to include each item's processing attempts. The request has no body.

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

    Once Xtrm has processed both items, the history=true response looks like this:

    Response (excerpt)
    {
      "CustomerBatchId": "BATCH-USERS-0001",
      "Status": "Completed",
      "Currency": "USD",
      "ItemsCount": 2,
      "Items": [
        {
          "CustomerTransactionId": "TXN-USERS-0001",
          "Status": "Success",
          "RecipientId": "PAT9999888",
          "SendMethodId": "XTR94502",
          "Amount": "50.00",
          "LastUpdatedAt": "2026-10-27T15:04:12.4410275Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T15:04:12.4362214Z",
              "CompletedAt": "2026-10-27T15:04:12.4410275Z"
            }
          ]
        },
        {
          "CustomerTransactionId": "TXN-USERS-0002",
          "Status": "Success",
          "RecipientId": "PAT9999888",
          "SendMethodId": "XTR94500",
          "Amount": "100.00",
          "LastUpdatedAt": "2026-10-27T15:04:19.8820431Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T15:04:19.8761390Z",
              "CompletedAt": "2026-10-27T15:04:19.8820431Z"
            }
          ]
        }
      ],
      "Pagination": {
        "HasMore": false,
        "NextRecordsToSkip": 0
      }
    }

    How to read it:

    • Batch Status is Processing while items are still being processed, including while a bank item's payment to the bank is under way. It's Completed here because every item is Success; otherwise it ends CompletedWithFailures or Failed.
    • Item Status moves from Accepted to Processing (this endpoint can also show Verified). A bank item then passes through RetainedInWallet while Xtrm pays her bank. Each item ends Success or Failed, except a bank item whose bank payment didn't go through: it is still RetainedInWallet once the batch status is final. For a bank item, Success means the bank provider accepted the payment, not that the funds have settled. For what each status means and what to do next, see Batch and payment statuses.
    • Attempts[].ErrorCode is SUCCESS on a successful attempt, and says why an attempt failed otherwise. See Error codes on attempts.
    • Pagination.HasMore is true when more items remain. Pass Pagination.NextRecordsToSkip as recordsToSkip on your next call.

    Keep each item's Status. To look at one payment on its own, use the next step.

  9. Check one payment's attempts

    To see what happened to a single payment, call the payment status endpoint, GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}, with history=true. The sample checks the bank item, TXN-USERS-0002.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-USERS-0001/Items/TXN-USERS-0002?history=true" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"

    Here is the history=true response for the bank item:

    Response
    {
      "CustomerBatchId": "BATCH-USERS-0001",
      "CustomerTransactionId": "TXN-USERS-0002",
      "Status": "Success",
      "RecipientId": "PAT9999888",
      "SendMethodId": "XTR94500",
      "Amount": "100.00",
      "Currency": "USD",
      "DeliveryType": "Bank",
      "LastUpdatedAt": "2026-10-27T15:04:19.882Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Success",
          "ErrorCode": "SUCCESS",
          "CreatedAt": "2026-10-27T15:03:58.1027734Z",
          "CompletedAt": "2026-10-27T15:04:19.882Z"
        }
      ]
    }
    • Status is the item's current status: here, Success.
    • DeliveryType shows where the money went once the item is Success: Bank for this bank item, Wallet for a wallet item. A RetainedInWallet item shows Wallet, both while the bank payment is under way and after it has stuck, and an Accepted, Processing or Failed item an empty string.
    • Attempts is the item's attempt history, oldest first. This item succeeded on its first attempt. If you resubmit a failed item, each try is a new attempt with the next AttemptNo. This endpoint repeats the item's own times in every attempt's CreatedAt and CompletedAt, so identify and order attempts by AttemptNo. To retry a failed item, see Retrying an item.

    Keep Status, DeliveryType and LastUpdatedAt with your payment record.

  10. Check the wallet balance

    This step is optional. Money from a wallet item is in the person's wallet. GetUserWalletBalance returns the balance of the person's wallet in one currency. Send the PAT number in UserId (lowercase d on this endpoint) and the batch's currency. Like linking a bank, it needs the person's account to be connected to your company.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetUserWalletBalance": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserId": "PAT9999888",
          "Currency": "USD"
        }
      }
    }'
    Response
    {
      "UserWalletBalnceResponse": {
        "UserWalletBalanceResult": {
          "Balance": 50.00,
          "Currency": "USD",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Balance is the wallet's current available balance, as a JSON number. Here it's 50.00: Jane's new wallet holds the wallet item, while the bank item passed through it on its way to her bank. The response wrapper is spelled UserWalletBalnceResponse, so read it exactly as returned.

    The balance covers everything in the wallet, not only your payments, so confirm a specific payment with its payment status (step 9). To find individual payments in wallet transaction lists, see Track & reconcile payments.

#Get updates by webhook

Xtrm can also notify your server with webhooks as it processes each payment, signed with HMAC-SHA256 in X-Signature. Xtrm sets up one endpoint per company account, in the sandbox and in production: send your endpoint URL to your Account Manager or Customer Success Manager, or to [email protected], and Xtrm support configures it and sets up its signing secret with you. See Webhooks for the events, payloads and signature verification. No event reports RetainedInWallet. A bank item's Batch.Item.Completed has Status Success whether or not the bank payment went through, so read its DeliveryType: Bank means it did, and Wallet means it didn't and the item stays RetainedInWallet. Confirm each final status with the payment status endpoint (step 9).

#What can go wrong

#Items are rejected when you submit the batch

Items that fail the first checks come back in Rejected with the Field and a Message, and the other items of the batch are still accepted. For this guide's items, common causes are an XTR94502 item whose RecipientId doesn't start with PAT, a bank item with neither BeneficiaryBankID nor WalletId, a SendMethodId that isn't exactly one of the seven IDs from step 3, a missing Destination, or a CustomerTransactionId used twice in one request. To fix and resend them, see Items rejected at submission.

#The whole request fails

When the batch itself is invalid, or no item passes, Xtrm stores nothing. Common causes are a missing or invalid IssuerAccountNumber, CustomerBatchId or SourceWalletId (422), a source wallet that isn't yours (403), a CustomerBatchId that's already in use (409 CONFLICT_PROCESSING) and more items than your account's limit (422 LIMIT_EXCEEDED). See The whole batch is refused. If a submit call times out, wait and resend the identical request with the same IDs; see A safe retry pattern.

#Linking the bank fails

  • Not authorized to access this resource. Make One Time Password API Call to access this resource (HTTP 400): the person's account isn't connected to your company. Connect it first with Connect existing accounts.
  • Errors names one or more fields (HTTP 400, Success false): the bank needs more information. Add the fields and send the whole request again; see Bank accounts & transfers.

#An item fails during processing

An accepted item can still end Failed, because some checks, such as the bank checks, run only while Xtrm processes the item. Its attempt's ErrorCode says why; for every code, see Error codes on attempts. The ones this guide's items can hit:

  • RECIPIENT_NOT_FOUND: the RecipientId doesn't exist, or its status isn't Active, Email not verified or Account pending approval. Pay the correct account as a new item with a new CustomerTransactionId.
  • BENEFICIARY_BANKID_REQUIRED or BANKID_INVALID: the bank item sent a WalletId but no BeneficiaryBankID, or named a bank that isn't linked to the person's account or was deleted. Both happen before any money moves. Check the ID with GetLinkedBankAccounts (step 6), then resubmit the item.
  • INSUFFICIENT_BALANCE: your source wallet held less than the item's Amount plus its fee when Xtrm paid it. Nothing was debited for that item. Fund the wallet, then resubmit the item. Xtrm doesn't check your balance when you submit, so we recommend checking WalletBalance from GetCompanyWallets first.
  • The bank item stays RetainedInWallet: while the batch is Processing, the bank payment is still under way, so wait. If the item is still RetainedInWallet once the batch status is final, the bank payment didn't go through, and the money is in the person's Xtrm wallet. Record it as final and don't resubmit it: the money has left your wallet, and the fee isn't refunded. Treat it like a wallet payment: the person can transfer it out in the Xtrm web app, or you can request the transfer for them with UserWithdrawFund. That transfer is made only when a response has PaymentStatus Completed and a PaymentTransactionId: the first response, with Success: true, only sends the person a one-time password. See When a payment stays RetainedInWallet.

#Retrying an item

To retry a Failed item, submit it again under its original CustomerBatchId and CustomerTransactionId, with every field: a retry replaces the stored item, and Xtrm records a new attempt with the next AttemptNo. Send only the failed items. If the latest attempt failed with TEMPORARY_ERROR, contact Xtrm support before you retry. For the full rules, see Resubmit failed payments and Retries & idempotency.

#Other things to watch

  • No account matches the email address, or the lookup fails. Treat the person as new only when Success is true and Beneficiary is null or empty; when Success is false, log OperationStatus.Errors and find out why before you call CreateUser. See step 1.
  • Check OperationStatus on every response. For CheckUserExist, CreateUser, GetPaymentMethods, GetUserWallets, LinkBankBeneficiary, GetLinkedBankAccounts and GetUserWalletBalance, we recommend checking OperationStatus.Success as well as the HTTP status, and logging OperationStatus.Errors when it's false. On a successful call, Errors is null or an empty array [], depending on the endpoint, so decide with Success. The batch payment endpoints have no OperationStatus: check the HTTP status and Rejected. See Errors.
  • The balance shows a different currency. CreateUser creates a wallet in the currency of the person's country, but a batch pays in the currency of your source wallet. Ask GetUserWalletBalance for the batch's currency.
  • Field names and types that differ between calls. Send and read names exactly as shown: Request (capital R) and UserID in GetUserWallets, UserID in LinkBankBeneficiary but RecipientUserId in GetLinkedBankAccounts, request and UserId in GetUserWalletBalance, and the UserWalletBalnceResponse wrapper. The samples write the query parameters recordsToSkip, recordsToTake and history in lowercase; Xtrm accepts any case. Amount is a JSON number in the batch request and the 202 response, which echoes the decimals you sent. The status responses return it as a string with 2 decimals: with a thousands separator on the batch status endpoint ("1,234.56") and without one on the payment status endpoint ("1234.56"), so strip separators before you parse it. WalletID in GetUserWallets and WalletId in Destination are both numbers. ItemsCount is an object in the 202 response but a number in the batch status.

#Next steps