Guide

Bank accounts & transfers

This guide pays a recipient's bank account in a batch. You find and check Jane Doe's bank, link it to her account, read back the ID of the bank you linked, and pay that same bank with a batch item that uses the Bank Transfer send method (XTR94500). The same batch pays a business recipient's bank by its ID. The guide also covers what happens when a bank payment doesn't complete, how money gets from a recipient's wallet to their bank, and how to remove a bank.

#How money reaches a bank

A batch payment is wallet-first. For each bank item, Xtrm credits the recipient's wallet in the batch's currency, then debits the payment from that wallet and sends it to the bank. When the bank account's currency differs from the batch's, the amount is converted when it's transferred to the bank. While Xtrm pays the money on to the bank, the item shows RetainedInWallet, usually only briefly, and it moves on to Success when the bank payment goes through. 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 the recipient's Xtrm wallet, and Xtrm doesn't credit your source wallet back or refund the fee. Treat it like a wallet payment; see When a bank payment doesn't complete.

For how Xtrm processes a batch, see How batch payments work. For every send method and option, see Create a batch payment.

You want toUseMoney comes from
Pay a recipient's bankA BatchTransfer item with SendMethodId XTR94500Your company wallet (SourceWalletId)
Transfer money from an individual recipient's wallet to their bank, on their behalfUserWithdrawFund, confirmed with the recipient's one-time passwordThe individual recipient's Xtrm wallet
Transfer money from a business recipient's wallet to its bank, on its behalfBeneficiaryCompanyWithdrawFund, confirmed with the recipient's one-time passwordThe business recipient's own wallet

#Before you begin

  • Credentials and a token. Sandbox credentials in XTRM_CLIENT_ID and XTRM_CLIENT_SECRET (see Sandbox & environments) and an access token in XTRM_ACCESS_TOKEN (see Authentication).
  • Your company's account number (SPN…), sent as IssuerAccountNumber. The samples use SPN1111222.
  • A funded source wallet. GetCompanyWallets lists your wallets with their IDs, currencies and balances. The wallet you pay from sets the currency of the batch. The samples use your USD wallet 122181. To add money, see Fund your wallet.
  • The recipients' account numbers. The samples pay Jane Doe, an individual recipient (PAT9999888), and a business recipient (SPN8888777). A batch pays existing Xtrm accounts only, so create each recipient before you link its bank and pay it: with CreateUser for a person or CreateBeneficiary for a business. See Pay individual recipients or Pay business recipients.
  • The bank details the recipient gives you: the account holder's name, phone number and address, and the bank's name, account number, currency and country, plus its routing number and SWIFT-BIC where the bank needs them.
  • A connection to each recipient whose bank you link or read back. LinkBankBeneficiary, GetLinkedBankAccounts and transfers out of a recipient's wallet all need the recipient's account to be connected to your company. A recipient you created with CreateUser or CreateBeneficiary is already connected; for an existing account, see Connections and manager services. Your company created every recipient in the samples, so they're all connected. The batch itself doesn't need a connection, but the bank you pay must be linked to the recipient.

Each sample uses literal values so it runs on its own. In your integration, carry the IDs forward from step to step.

#Pay a bank in a batch

Steps 1 to 3 are alternatives: run the one that matches the identifier the recipient gave you. For a bank in an IBAN country, we recommend validating the IBAN before you link the bank, to prevent failed payments and routing errors.

  1. Look up a US bank by routing number

    SearchBankByNationalID searches a country's banks by national routing code, such as a US routing number or a sort code. Note the capital R in the Request wrapper, which both search endpoints use. Paging fields are strings: RecordsToTake is the page size, and RecordsToSkip is the page number, "1" for the first page, "2" for the second, and so on.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByNationalID" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "SearchBankByNationalID": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "BankCountryISO2": "US",
          "NationalID": "021000021",
          "Pagination": {
            "RecordsToSkip": "1",
            "RecordsToTake": "25"
          }
        }
      }
    }'

    One routing number can return several branches. Abridged to two results:

    Response (excerpt)
    {
      "SearchBankByNationalIDResponse": {
        "SearchBankByNationalIDResult": {
          "Banks": [
            {
              "NationalIdentifier": "021000021",
              "NationalIdType": "USBC",
              "BankDetails": {
                "InstitutionName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
                "BranchInformation": null,
                "AddressLine1": "225 HAVEMEYER ST",
                "AddressLine2": "",
                "City": "BROOKLYN",
                "CountryISO2": "US",
                "CountryName": "UNITED STATES",
                "PostalCode": "11211",
                "BranchName": "HAVEMEYER AND BROADWAY",
                "Region": "NEW YORK"
              }
            },
            {
              "NationalIdentifier": "021000021",
              "NationalIdType": "USBC",
              "BankDetails": {
                "InstitutionName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
                "BranchInformation": null,
                "AddressLine1": "560 MISSION ST",
                "AddressLine2": "",
                "City": "SAN FRANCISCO",
                "CountryISO2": "US",
                "CountryName": "UNITED STATES",
                "PostalCode": "94105",
                "BranchName": "SAN FRANCISCO MAIN",
                "Region": "CALIFORNIA"
              }
            }
          ],
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    Keep: BankDetails.InstitutionName, to confirm the bank with Jane Doe. PaginationTotal.RecordsTotal (left out above) gives the total number of matches.

  2. Or look up a bank by SWIFT-BIC

    SearchBankByBIC does the same for a SWIFT-BIC code and pages the same way. Each result is a flat record that includes the branch's NationalId routing number. The response wrapper is spelled SearchBankbyBICResponse, with a lowercase by.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByBIC" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "SearchBankByBIC": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "BankCountryISO2": "US",
          "SWIFTBIC": "CHASUS33",
          "Pagination": {
            "RecordsToSkip": "1",
            "RecordsToTake": "25"
          }
        }
      }
    }'

    This example matches 4,227 branches. Abridged to one:

    Response (excerpt)
    {
      "SearchBankbyBICResponse": {
        "SearchBankbyBICResult": {
          "Banks": [
            {
              "InstitutionName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
              "BIC": null,
              "Region": "NEW YORK",
              "NationalId": "021000021",
              "BranchName": "HAVEMEYER AND BROADWAY",
              "BranchCode": null,
              "AddressLine1": "225 HAVEMEYER ST",
              "AddressLine2": "",
              "City": "BROOKLYN",
              "CountryName": "UNITED STATES",
              "CountryCode": "US",
              "PostalCode": "11211"
            }
          ],
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    Keep: InstitutionName and NationalId, to confirm against the details the recipient gave you.

  3. Or validate an IBAN

    ValidateIBAN checks that an IBAN is structurally and mathematically valid for the country in BankCountryISO2. When the BIC can be derived, it also returns SWIFTBIC.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/ValidateIBAN" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "ValidateIBAN": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "IBAN": "GB33BUKB20201555555555",
          "BankCountryISO2": "GB"
        }
      }
    }'
    Response
    {
      "ValidateIBANResponse": {
        "ValidateIBANResult": {
          "IsValid": true,
          "SWIFTBIC": "BUKBGB22XXX",
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    Keep: IsValid, and SWIFTBIC for the link request.

  4. Check the transfer types for the country

    GetBankWithdrawTypes lists the bank transfer types available in a country, such as wire and ACH. Country codes come from GetCountry.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/GetBankWithdrawTypes" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetBankWithdrawTypes": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "CountryISO2": "US"
        }
      }
    }'
    Response
    {
      "GetBankWithdrawTypesResponse": {
        "GetBankWithdrawTypesResult": {
          "OperationStatus": {
            "Errors": null,
            "Success": true
          },
          "WithdrawTypes": [
            "WIRE",
            "ACH"
          ]
        }
      }
    }

    Keep: WithdrawTypes. The next step's example sends one of them, ACH, as WithdrawType.

  5. Link the bank account

    LinkBankBeneficiary links the bank to the recipient in UserID, a PAT or SPN account number. A bank has to be linked to a recipient before a batch payment can pay it by ID. The recipient must be connected to your company, or be your own company: any other UserID gets 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource. The sample links Jane Doe's Chase account to her account, PAT9999888. The body has two parts, each with its own CountryISO2:

    • BeneficiaryInformation: the account holder and their address. ContactName is 1 to 100 characters and can't contain special characters such as <, >, @, #, $ or %. PhoneNumber is 1 to 15 characters, counting any spaces or dashes; leave out a leading +, because a number that starts with + is refused with Please remove country codes from mobile numbers. City is 1 to 100 characters. Region is the two-letter ISO code or the full state name.
    • BeneficiaryBankInformation: the bank account, with the bank's country. WithdrawType sets how the money moves to the bank: ACH, WIRE, LV (the same as ACH) or HV (the same as WIRE), in any case. Without it, Xtrm uses WIRE when the account's currency isn't the country's own, otherwise ACH where the country supports it, otherwise WIRE. A US bank for a US account holder in USD always uses ACH. Optionally set AccountType to BUSINESS, SAVINGS or CHECKING.

    This example links a US bank, with the routing number from step 1. In the sandbox, use a real bank's routing number like this one with a made-up account number in the right format, never a real account. For a bank in an IBAN country, send the IBAN as AccountNumber: Xtrm checks it and finds the bank from it. RoutingNumber and SWIFTBIC are required only where the bank's country, currency and transfer type call for them. Where they aren't required and you leave them out, Xtrm takes them from the IBAN. If the bank needs more information, the response names the fields to send, and you send the request again (see the callout below).

    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 profile (907599f594b044d08cf81a2afb0a7967 here), and BankBeneficiaryStatus. An individual recipient can have up to 3 linked banks, and a company account more, up to a limit Xtrm sets.

    For example, a request that leaves out a routing number the bank needs gets this response:

    Response when the bank needs more information (example)
    {
      "LinkBankBeneficiaryResponse": {
        "LinkBankBeneficiaryResult": {
          "BeneficiaryId": null,
          "BankBeneficiaryStatus": null,
          "AccountIdentityLevel": null,
          "ACHDebitApprovalStatus": null,
          "OperationStatus": {
            "Errors": [
              {
                "ErrorMessage": "Bank routing code is required.",
                "FieldName": "RoutingNumber",
                "FieldLabel": "Routing Number",
                "IsRegulatoryField": false,
                "valueset": null
              }
            ],
            "Success": false
          }
        }
      }
    }

    Each entry in Errors names one field:

    • ErrorMessage: what's missing or wrong.
    • FieldName: the parameter to send, such as RoutingNumber.
    • FieldLabel: a readable label you can show in your interface.
    • IsRegulatoryField: true when the value goes in BeneficiaryBankInformation.RegulatoryFields, as a Key / Value pair with the FieldName as the Key.
    • valueset: for a missing regulatory field, the values it accepts, each with an id and a text. Otherwise it's null.

    Leave out RegulatoryFields until a response asks for one: sending it for a bank that needs none fails with Regulatory field values are not required for this request. Other failures, such as an invalid IBAN or a bank that's already linked, return messages as strings in Errors. See Errors on a failed call.

  6. Read back the bank's ID and payment methods

    GetLinkedBankAccounts lists the banks linked to RecipientUserId. Each entry gives you the two values a bank payment uses:

    • BeneficiaryId, the bank's ID. You send it as Destination.BeneficiaryBankID in a batch item, and as UserLinkedBankID or BeneficiaryLinkedBankID in a recipient transfer.
    • BankDetails.BeneficiaryBankInformation.PaymentMethods, the payment methods available for the bank account, such as ACH.
    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: BeneficiaryId and the PaymentMethods array inside BankDetails. The BeneficiaryId is 907599f594b044d08cf81a2afb0a7967, the same ID the link returned, so this is the bank you just linked. If the list holds more than one bank, pick yours by that ID. The next step pays this bank.

    Two things to watch

    The response has no field named BeneficiaryBankID: BeneficiaryId is the only ID it returns for each bank. Take payment methods from the array inside BankDetails, not from the PaymentMethods object on the entry.

  7. Pay the bank in a batch

    BatchTransfer pays every item in one request from the wallet in SourceWalletId. For a bank payment, set the item's SendMethodId to XTR94500 (Bank Transfer) and put the bank's BeneficiaryId in Destination.BeneficiaryBankID. During processing, before any money moves, it must be a pending or approved bank linked to the recipient's account, or the item fails with BANKID_INVALID. Optionally, set BeneficiaryBankPaymentMethod to one of the rails in the bank's PaymentMethods array, such as ACH. Bank transfer: XTR94500 lists every Destination field, including WalletId and how a business wallet's linked bank can replace the bank you send.

    This batch has two bank items, and each names its bank by ID:

    • TXN-BANK-0001 pays Jane Doe's Chase account, 907599f594b044d08cf81a2afb0a7967, the bank you linked and read back in the previous steps, over ACH.
    • TXN-BANK-0002 pays the business recipient SPN8888777 at its own bank, 41953ec32f3e4765a35a902c82bdd995. You read that ID back with GetLinkedBankAccounts the same way, with SPN8888777 in RecipientUserId, which needs the business to be connected to your company. The item sends no WalletId, so Xtrm pays exactly this bank.

    The body has no wrapper object. SourceWalletId is an integer and Amount a JSON number. The batch uses this guide's own IDs: BATCH-BANK-0001, with items TXN-BANK-0001 and TXN-BANK-0002. CustomerBatchId values are shared across all Xtrm accounts, so replace them with your own unique values before you run this in the sandbox; see Batch and payment identifiers. One batch can also mix bank items with other send methods; see Create a batch payment.

    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-BANK-0001",
      "Items": [
        {
          "CustomerTransactionId": "TXN-BANK-0001",
          "RecipientId": "PAT9999888",
          "Amount": 100,
          "SendMethodId": "XTR94500",
          "Destination": {
            "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967",
            "BeneficiaryBankPaymentMethod": "ACH"
          }
        },
        {
          "CustomerTransactionId": "TXN-BANK-0002",
          "RecipientId": "SPN8888777",
          "Amount": 100,
          "SendMethodId": "XTR94500",
          "Destination": {
            "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995"
          }
        }
      ]
    }'

    Xtrm validates each item and responds right away with 202 Accepted; the payments are processed in the background. The response lists each accepted item, not necessarily in request order, with its Amount echoed as a JSON number with the decimals you sent, so 100 comes back as 100.0; the excerpt leaves out the ItemsCount totals:

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

    Keep: CustomerBatchId and the CustomerTransactionId of each bank item. A 202 means the batch was received and validated, not that any bank has been paid yet. If items come back in Rejected, see Paying the bank.

  8. Check the bank item's outcome

    GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId} returns one item's Status and its DeliveryType: Bank once a bank item is Success, Wallet when it's RetainedInWallet, and an empty string while it's Accepted, Processing or Failed. Set history=true to get every processing attempt in Attempts; without it, Attempts is []. To read all the items of a batch page by page, use GET /Fund/BatchTransfer/{CustomerBatchId} instead.

    If Xtrm has set up webhooks for your account, it also notifies your server as items progress. No event reports RetainedInWallet: a bank item's Batch.Item.Completed has Status Success whether or not the bank payment went through, with DeliveryType Bank when it did and Wallet when it didn't. So read DeliveryType, and confirm a bank item's final status with this endpoint. See Event types.

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

    In this history=true response, the item's only attempt succeeded and DeliveryType is Bank: the bank provider accepted the payment to Jane Doe's bank. If an item has more than one attempt, order them by AttemptNo.

    Response (excerpt)
    {
      "CustomerBatchId": "BATCH-BANK-0001",
      "CustomerTransactionId": "TXN-BANK-0001",
      "Status": "Success",
      "RecipientId": "PAT9999888",
      "SendMethodId": "XTR94500",
      "Amount": "100.00",
      "Currency": "USD",
      "DeliveryType": "Bank",
      "LastUpdatedAt": "2026-06-04T13:02:23.259Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Success",
          "ErrorCode": "SUCCESS",
          "CreatedAt": "2026-06-04T13:01:35.0055683Z",
          "CompletedAt": "2026-06-04T13:02:23.259Z"
        }
      ]
    }

    Until the recipient's wallet is credited, a bank item's Status is Accepted or Processing. Then, while Xtrm pays the money from the recipient's wallet on to the bank, it reads RetainedInWallet, with DeliveryType Wallet, usually only briefly. Don't act on it yet: read it together with the batch status from GET /Fund/BatchTransfer/{CustomerBatchId}, which stays Processing while any bank payment in the batch is under way. The item ends in one of three ways:

    • Success, with DeliveryType Bank: the bank provider accepted the payment from the recipient's wallet. That doesn't mean the ACH, wire or RTP payment has settled. If the recipient's bank returns it later, the item stays Success, no webhook is sent, and Xtrm credits the money back to your wallet by hand; see Returned bank payments.
    • RetainedInWallet, with DeliveryType Wallet, once the batch status is final (CompletedWithFailures or Failed): the bank payment didn't go through, and the item's newest attempt has Result Failed with an ErrorCode that says why. See When a bank payment doesn't complete.
    • Failed, with an empty DeliveryType: the item failed before any money moved. Read its latest attempt's ErrorCode; see What can go wrong.

    Keep: Status, DeliveryType and LastUpdatedAt for your records. For every status value, see Batch and payment statuses.

#When a bank payment doesn't complete

Every bank item passes through RetainedInWallet on its way to the bank. A bank item that is still RetainedInWallet, with DeliveryType Wallet, once its batch status is final (CompletedWithFailures or Failed) has stuck: Xtrm tried the bank payment, it didn't go through, and Xtrm won't try again. The money has left your wallet and stays in the recipient's Xtrm wallet: Xtrm doesn't return it to your source wallet or refund the item's fee, and you can't retry or resubmit the item. Request the item with history=true: its newest attempt has Result Failed and an ErrorCode that says why, for example RETAINED_IN_WALLET when the bank provider didn't accept the payment. See Delivery stage for every code.

Treat it like a wallet payment. The recipient signs in to the Xtrm web app and transfers the money out of their wallet. If the batch set EmailNotification to true, Xtrm emailed them when the money reached their wallet. Or your company requests the transfer on their behalf, confirmed with the recipient's one-time password, which needs a connection to the recipient: see Transfer from a recipient's wallet. If the recipient doesn't see the money in their wallet, contact Xtrm support with the CustomerBatchId and CustomerTransactionId. When a payment stays RetainedInWallet covers both ways, and what it means when the batch stays Processing because Xtrm is holding the bank payment.

#Transfer from a recipient's wallet

Money in a recipient's Xtrm wallet belongs to the recipient, whether a batch credited it to a wallet item or a bank item stayed RetainedInWallet. Recipients transfer it out themselves in the Xtrm web app. Your company can also request a transfer on a recipient's behalf through the API: the transfer debits the recipient's own wallet, never yours, and pays a bank or another payment method of theirs. Each one needs a connection to the recipient and the recipient's one-time password (OTP), so the recipient takes part in every transfer.

Send transfer requests one at a time: wait for a successful response to the current call before you send the next one.

#From an individual recipient's wallet

UserWithdrawFund moves money out of an individual recipient's Xtrm wallet. Every transfer is confirmed with a six-digit one-time password (OTP) that Xtrm sends to the account holder, so a transfer takes two requests. The samples transfer USD 5.00 from Jane Doe's USD wallet to the Chase account you linked for her earlier in this guide.

UserID and Currency identify the wallet to debit. For a transfer to a bank, set PaymentMethodID to XTR94500 and send the bank's ID as UserLinkedBankID and one of its payment methods as BankPaymentMethod, both from GetLinkedBankAccounts. Xtrm pays exactly the bank you send. It's required, and it must be one of the recipient's own banks with BankBeneficiaryStatus Approved: a transfer without it is refused with <UserID> - User BankID is mandatory, another account's bank with <UserLinkedBankID> - Invalid User Linked Bank ID, and a bank that's still pending with <UserLinkedBankID> - User Linked Bank ID is in pending status. EmailNotification is a JSON boolean and is off by default.

UserWithdrawFund accepts four PaymentMethodID values: XTR94500 (bank account), XTR94503 (prepaid card), XTR94505 (digital gift card) and XTR94508 (Rapid Transfer, USD only). Send the ID in capitals, exactly as shown: any other value is refused with <id> - Invalid Payment Method Id. GetUserPaymentMethods also lists XTR94502 (Xtrm wallet) and XTR94506 (Reward Link, a reward card that recipients choose in the Xtrm web app), which UserWithdrawFund doesn't accept. For the other methods (Rapid Transfer, prepaid card and digital gift card), see the UserWithdrawFund reference page.

  1. Request the transfer

    Send the request with OTP left blank, or without OTP. Xtrm generates a six-digit OTP and sends it to the account holder by email and, when their profile has a mobile number, by text message, unless you choose one channel with SendTransferCodeToEmail or SendTransferCodeToMobile. Nothing is transferred yet.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "UserWithdrawFund": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "PAT9999888",
          "Amount": "5.00",
          "Currency": "USD",
          "PaymentMethodID": "XTR94500",
          "OTP": "",
          "BankPaymentMethod": "ACH",
          "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967",
          "EmailNotification": true
        }
      }
    }'

    The response to this first request is HTTP 200 with OperationStatus.Success set to true, and Errors holds the message One Time Password sent to user. Please resubmit with One Time Password. No money has moved: PaymentTransactionId, PaymentDate and PaymentStatus are null, and so are the amounts.

    Response (first request)
    {
      "UserWithdrawFundResponse": {
        "UserWithdrawFundResult": {
          "PaymentTransactionId": null,
          "PaymentDate": null,
          "PaymentStatus": null,
          "Amount": null,
          "Fee": null,
          "TotalAmount": null,
          "Currency": null,
          "PayDirectTransactionDetails": null,
          "RedemptionDetails": null,
          "OperationStatus": {
            "Success": true,
            "Errors": [
              "One Time Password sent to user. Please resubmit with One Time Password."
            ]
          }
        }
      }
    }

    Keep: the request body, to resubmit it with the OTP.

  2. Confirm the transfer with the OTP

    Retrieve the OTP from the account holder in your application, then resubmit the same request with OTP filled in to complete the transfer. The OTP expires 10 minutes after Xtrm sends it, and Xtrm counts 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. An OTP that is blank, 000000 or not a number counts as a first request: Xtrm sends a new code, the previous code stops working, and you get the code-sent message again.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "UserWithdrawFund": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "PAT9999888",
          "Amount": "5.00",
          "Currency": "USD",
          "PaymentMethodID": "XTR94500",
          "OTP": "123456",
          "BankPaymentMethod": "ACH",
          "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967",
          "EmailNotification": true
        }
      }
    }'
    Response
    {
      "UserWithdrawFundResponse": {
        "UserWithdrawFundResult": {
          "PaymentTransactionId": "397785",
          "PaymentDate": "2026-06-05T16:33:26.385963Z",
          "PaymentStatus": "Completed",
          "Amount": "4.50",
          "Fee": "0.50",
          "TotalAmount": "5.00",
          "Currency": "USD",
          "PayDirectTransactionDetails": null,
          "RedemptionDetails": null,
          "OperationStatus": {
            "Success": true,
            "Errors": []
          }
        }
      }
    }

    Don't decide with Success alone, because the first request also returns Success: true. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId, as here, with Errors as an empty array []. Read any other 200 response from Errors:

    • One Time Password sent to user. Please resubmit with One Time Password. (Success: true): no money moved. Get the code from the account holder and send the same request again with it in OTP.
    • Invalid one time password. A new one has been sent and the original has been expired. Please use the new one. (Success: false): the code was wrong or had expired. No money moved, the old code no longer works, and Xtrm has sent the account holder a new one. Send the same request again with the new code.

    Keep: PaymentTransactionId (a string) for reconciliation, plus PaymentStatus, Amount, Fee and TotalAmount.

Not the connection OTP

This OTP comes from UserWithdrawFund itself. GetOTPAuthorizedVendor issues a different OTP, which connects your company to an account. Don't use it for transfers. See Connect existing accounts.

#From a business recipient's wallet

BeneficiaryCompanyWithdrawFund is the parallel call for a business recipient. It debits the business recipient's own wallet, never yours, and your company must be connected to the recipient. The sample transfers USD 50.00 from Acme Corporation's (SPN9999888) USD wallet 122340 to its own bank, 5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d. Your company created Acme Corporation in Pay business recipients, so it's connected. BeneficiaryAccountNumber (SPN…) and BeneficiaryWalletID (the ID that GetBeneficiaryWallets returns) identify the wallet to debit, which must be the recipient's own wallet in Currency. BeneficiaryWalletID takes only the wallet's numeric ID: a wallet name is rejected with BeneficiaryWalletID is Mandatory and must be an integer, and no money moves. It accepts two of the methods that GetBeneficiaryCompanyPaymentMethods lists: XTR94500 (Bank, with BeneficiaryLinkedBankID and BankPaymentMethod) and XTR94508 (Rapid Transfer in USD only, with BeneficiaryCardToken). The bank or card must be the recipient's own.

It takes two requests, like UserWithdrawFund. Send the first without OTP: Xtrm sends a six-digit OTP to the business recipient and answers HTTP 200 with Success: true, the code-sent message in Errors, and PaymentTransactionId, PaymentDate and PaymentStatus set to null. The recipient gives you the code, and you resubmit the same request with OTP filled in, as in this sample. The OTP rules are the same as for UserWithdrawFund: the code expires after 10 minutes, a wrong or expired code gets a new one sent, an OTP that is blank, 000000 or not a number counts as a first request, and each code covers one attempt. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId, as below. EmailNotification is a JSON boolean, while the optional SendTransferCodeToEmail and SendTransferCodeToMobile are strings ("true" / "false").

curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BeneficiaryCompanyWithdrawFund" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "BeneficiaryCompanyWithdrawFund": {
    "request": {
      "IssuerAccountNumber": "SPN1111222",
      "Currency": "USD",
      "Amount": "50.00",
      "PaymentMethodID": "XTR94500",
      "BeneficiaryAccountNumber": "SPN9999888",
      "BeneficiaryWalletID": "122340",
      "OTP": "123456",
      "BankPaymentMethod": "ACH",
      "BeneficiaryLinkedBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
      "EmailNotification": true
    }
  }
}'
Response
{
  "BeneficiaryCompanyWithdrawFundResponse": {
    "BeneficiaryCompanyWithdrawFundResult": {
      "PaymentTransactionId": "879538",
      "PaymentDate": "2026-06-08T16:21:43.4155509Z",
      "PaymentStatus": "Completed",
      "OperationStatus": {
        "Success": true,
        "Errors": []
      },
      "PayDirectTransactionDetails": null
    }
  }
}

Keep: PaymentTransactionId and PaymentStatus. PaymentTransactionId is a string in the example; we recommend storing it as a string.

For a transfer to a bank, Xtrm pays exactly the bank in BeneficiaryLinkedBankID, whatever bank is linked to the wallet. It's required, and it must be one of the recipient's own banks with BankBeneficiaryStatus Approved: a transfer without it is refused with <BeneficiaryAccountNumber> Beneficiary Linked BankID is mandatory, another account's bank with <BeneficiaryLinkedBankID> - Invalid Beneficiary Linked BankID, and a bank that's still pending with <BeneficiaryLinkedBankID> - Beneficiary Linked BankID is in pending status.

Fees come from the recipient's schedule

Xtrm applies the business recipient's own fee schedule to this transfer and takes the fee out of Amount.

#Remove a linked bank

DeleteBankBeneficiary removes a linked bank. Send the recipient's account number as RecipientAccountNumber and the bank's ID as BeneficiaryBankID, from GetLinkedBankAccounts (or GetACHDebitLinkedBankAccounts for a bank-debit bank). An individual recipient can link up to 3 banks, and a company account more, up to a limit Xtrm sets, so we recommend removing the ones a recipient no longer uses. Once a bank is removed, don't send its ID in new batch items. This example removes Acme Corporation's bank, for example once it stops using that account.

curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/DeleteBankBeneficiary" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "DeleteBankBeneficiary": {
    "request": {
      "IssuerAccountNumber": "SPN1111222",
      "RecipientAccountNumber": "SPN9999888",
      "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d"
    }
  }
}'
Response
{
  "DeleteBankBeneficiary": {
    "DeleteBankBeneficiaryResult": {
      "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
      "OperationStatus": {
        "Errors": [],
        "Success": true
      }
    }
  }
}

The response echoes the deleted BeneficiaryBankID. Its root key has no Response suffix.

#What can go wrong

See Errors for the general rules.

#Linking the bank

  • Not linked yet. When LinkBankBeneficiary needs more information, it returns HTTP 400 with Success: false and the fields to add or fix in Errors. Send the whole request again with those fields, and repeat until it returns a BeneficiaryId. See Errors on a failed call.
  • Regulatory field values are not required for this request. You sent RegulatoryFields for a bank that needs none. Leave it out until a response lists a field whose IsRegulatoryField is true.
  • Valid call, invalid IBAN. ValidateIBAN can return Success: true with IsValid: false.
  • Too many banks. Individual recipients can link up to 3 banks, and company accounts more, up to a limit Xtrm sets. Past the limit, LinkBankBeneficiary refuses the link with You can link maximum N banks.
  • WithdrawType is refused. It accepts only ACH, WIRE, LV (low value, the same as ACH) and HV (high value, the same as WIRE), in any case. Any other value returns WithdrawType is invalid. WithdrawType must be ACH, WIRE, HV or LV. ACH or LV is also refused when the bank's country doesn't support ACH, or the currency isn't the country's own.

#Paying the bank

  • Item rejected at submission. A bank item is rejected when it has neither BeneficiaryBankID nor WalletId, a BeneficiaryBankID over 40 characters (its Field then says Items[i].RecipientId), or a BeneficiaryBankPaymentMethod other than ACH, WIRE or RTP. The other items are still processed, and a rejected item is never stored. See Errors for the Rejected entries, and Payment statuses for when to resubmit a rejected item in the same batch or a new one.

  • Item failed. Read the ErrorCode of the item's latest attempt. These bank codes fail the item during processing, before any money moves:

    • BANKID_INVALID: the bank isn't a pending or approved bank linked to the recipient's account. It's mistyped, deleted or another account's bank. Check with GetLinkedBankAccounts that the BeneficiaryBankID belongs to that RecipientId.
    • BENEFICIARY_BANKID_REQUIRED: the item has no BeneficiaryBankID where one is needed, that is, for an individual recipient or for a business recipient without WalletId.
    • BANK_NOT_FOUND: the bank provider doesn't recognize the recipient's bank, or bank validation raised an error.
    • INVALID_PAYMENTMETHOD: the rail you asked for isn't allowed for this bank account.
    • DEFAULT_BANK_NOT_FOUND or INVALID_BENEFICIARY_WALLET: the item sent a WalletId that has no linked bank or isn't an active wallet of the recipient in the batch's currency. See Bank transfer: XTR94500.

    For every code and what to do, see Error codes on attempts.

  • Retrying a failed item. Fix the cause, then resubmit the item under its original CustomerBatchId and CustomerTransactionId, with every field, including the corrected BeneficiaryBankID. A corrected bank takes effect after a failure in the bank checks above, but not after a failure at the wallet credit, such as INSUFFICIENT_BALANCE. See Resubmit failed payments and What you can change on a retry.

  • A different bank was paid. A business recipient's item sent with a WalletId can pay the bank linked to that wallet instead of the BeneficiaryBankID you sent, without an error. To pay a specific bank, send its BeneficiaryBankID without WalletId, as this guide does. See Bank transfer: XTR94500.

  • The item is RetainedInWallet. While the batch is Processing, the bank payment is still under way: 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 recipient's Xtrm wallet. See When a bank payment doesn't complete.

  • IDs, duplicates and batch size. See Retries & idempotency and Limits.

#Recipient transfers

  • Not authorized to access this resource. Make One Time Password API Call to access this resource. The recipient isn't connected to your company, so you can't request a transfer on their behalf. The recipient can still transfer the money in the Xtrm web app. See Connections and manager services.
  • Nothing was transferred, yet Success is true. The first request only sends the OTP, and so does a request whose OTP is blank, 000000 or not a number: Errors holds One Time Password sent to user. Please resubmit with One Time Password. and PaymentStatus is null. Resubmit with the code. A transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId.
  • Your previous transfer is in progress. Please wait or try later. (HTTP 400). An 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.
  • The bank is refused. A transfer to a bank needs the bank's ID, and the bank must be the recipient's own and approved. A bank that's still pending, which a batch can pay, can't take a transfer until it's approved. Check its BankBeneficiaryStatus with GetLinkedBankAccounts.
  • Fees don't add up. On a UserWithdrawFund transfer to a bank, the fee comes out of Amount: the bank account receives Amount minus Fee, the response's Amount is that net figure, and TotalAmount is the Amount you sent (in the bank example, 4.50 + 0.50 = 5.00). Rapid Transfer fees also come out of Amount. Gift card and prepaid card transfers carry no fee for the recipient: the card is worth the full Amount. BeneficiaryCompanyWithdrawFund takes the fee out of Amount. Read Amount, Fee and TotalAmount from each response.
  • The OTP was wrong or expired. An OTP expires 10 minutes after Xtrm sends it, counted in whole minutes, so send it back within 9 minutes. A wrong or expired code gets HTTP 200 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 sends a new OTP. Resubmit with the new one. See Error messages by area.
  • <id> - Invalid Payment Method Id. UserWithdrawFund accepts only XTR94500, XTR94503, XTR94505 and XTR94508, in capitals, and BeneficiaryCompanyWithdrawFund only XTR94500 and XTR94508.
  • Types and casing. EmailNotification is a JSON boolean on the transfer calls, as it is on BatchTransfer. Copy keys exactly, including Request versus request. On the calls that link and list bank accounts, Errors is null or an empty array [] on success, depending on the endpoint, so test Success instead. The transfer calls are different: Success is true on the code-sent response too, so decide by PaymentStatus Completed and PaymentTransactionId.

#Any call

  • Calls overlap. Never have two BatchTransfer requests for the same CustomerBatchId in flight at once. Separate batches can be sent at the same time. Send transfer requests one at a time: wait for a successful response before you send the next one.
  • Sandbox results. The sandbox works the same as production, and it has no test bank accounts. Link a bank there as in production, with a real bank's routing number or SWIFT-BIC and a made-up account number in the right format, never a real account. A BeneficiaryBankID that belongs to no account, such as 00000000000000000000000000000000, fails with BANKID_INVALID every time, so you can use one to test a failed item. See How the sandbox behaves.

#Next steps