Guide

Pay business recipients

Paying a business through Xtrm starts with finding the right company account, so you never pay into a duplicate. This guide follows one company, Acme Corporation, from search to confirmed payment: you search Xtrm for it, create its account when the search comes back empty, link its bank account, and pay it in one batch, part into its Xtrm wallet and part to its bank. Xtrm accepts the batch right away and processes the payments in the background, so you finish by confirming each payment's outcome with a status call or a webhook. Every sample runs against the sandbox.

A batch pays existing Xtrm accounts only, by their account numbers, so the company needs an account before you build the batch: you find it in step 1, or create it with CreateBeneficiary 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 and an access token. Store the token in XTRM_ACCESS_TOKEN; every sample reads it from there. See Authentication and Sandbox & environments.
  • Your company's account number, the SPN that owns your API credentials (SPN1111222 in the samples). You send it as IssuerAccountNumber.
  • A funded source wallet. List your wallets with GetCompanyWallets and note the ID of the one you pay from (122181 in the samples). It sets the currency of the whole batch. In the sandbox, Xtrm credits test funds to your wallets after approving your IP addresses; see Test funds. To add money, see Fund your wallet.
  • The company's details: its email domain to search with (or its registered name, if you don't know the domain) and, in case you have to create it, its master administrator's name and email address and the company's country.
  • For the bank payment, the company's bank account: the bank's name, routing number and account number, with the company's phone number and address.

The samples use example values chosen so that one step's output feeds the next: the company you create is Acme Corporation, SPN9999888, with the administrator email [email protected]. Its wallet is 122340 and its linked bank account is 5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d.

#Onboard and pay the company

  1. Search for an existing company account

    Businesses often already have an account in the Xtrm ecosystem, so search before you create anything. CheckBeneficiaryExist searches every company account on Xtrm, not only yours. When you know the company's email domain, search with CompanyEmailDomain on its own, as the sample does. Send the domain (acmecorp.com) or any address at it ([email protected]): Xtrm uses only the part after the @. Search with CompanyName when you don't know the domain. At least one of the two is required.

    Pagination is optional. If you send it, include both RecordsToSkip and RecordsToTake.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckBeneficiaryExist" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CheckBeneficiaryExist": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "CompanyEmailDomain": "acmecorp.com"
        }
      }
    }'

    Acme Corporation is new to Xtrm, so the search finds nothing and Beneficiary is an empty array:

    Response
    {
      "CheckBeneficiaryExistResponse": {
        "CheckBeneficiaryExistResult": {
          "Beneficiary": [],
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    CompanyEmailDomain matches the companies whose account email, the master administrator's sign-in email, is at that domain. Once you create Acme Corporation with [email protected] in step 2, this same search finds it. A company's own domain usually returns just that company. A shared domain can return several, and the match is on text, so acmecorp.com also returns a company whose email is at acmecorp.com.au.

    CompanyName returns every company whose registered name contains the text, so a name search can return several companies, up to 30 per page unless you set Pagination. Xtrm uses the first 50 characters of the name. If you send both CompanyName and CompanyEmailDomain, you get the companies that match either one, so send the domain alone when you have it. Each match in Beneficiary has the company's Name, its AccountNumber, its account Email, its master administrator's first and last name, its Status and its AccountIdentityLevel (Draft, Basic, Standard or Advanced).

    • No match: continue with step 2 and create the company.
    • Match found: check its Email and Name to confirm it's the company you mean. The business already has an Xtrm account, so don't create a second one. Use its AccountNumber as the RecipientId of your items, skip step 2, and read the note below.

    If the company already has an account

    You can pay an existing company straight away with a wallet item (XTR94504) 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. To link and read its bank accounts (steps 4 and 5), connect the company to yours first: its administrator gives you a one-time password. See Connect existing accounts, and for what a connection allows, Connections and manager services. Paying a company doesn't connect it.

  2. Create the business recipient

    If the search found nothing, create the company with CreateBeneficiary. The body has two details that are easy to get wrong:

    • The inner wrapper is Request with a capital R, unlike the request used by the other onboarding calls in this guide. Copy it exactly.
    • EmailNotification is a string, "true" or "false". With "true", Xtrm emails an account creation notification to AdminEmail.

    The required fields are IssuerAccountNumber, BeneficiaryCompanyName (the company's legally registered name) and, inside BeneficiaryCompanyAdminDetails, AdminEmail, EmailNotification, AdminFirstName, AdminLastName and CountryISO2. The sample adds the optional WebAddress, City, PostalCode and Region, and skips AdminMobileNumber and the partner fields in SalesProgramDetails. If you send a mobile number, leave out the country code; it is determined from the country.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CreateBeneficiary" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CreateBeneficiary": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "BeneficiaryCompanyName": "Acme Corporation",
          "WebAddress": "https://www.acmecorp.com",
          "BeneficiaryCompanyAdminDetails": {
            "AdminEmail": "[email protected]",
            "EmailNotification": "true",
            "AdminFirstName": "Marcus",
            "AdminLastName": "Chen",
            "CountryISO2": "US",
            "City": "San Francisco",
            "PostalCode": "94105",
            "Region": "CA"
          }
        }
      }
    }'
    Response
    {
      "CreateBeneficiaryResponse": {
        "CreateBeneficiaryResult": {
          "BeneficiaryID": "SPN9999888",
          "AccountIdentityLevel": "Basic",
          "ClientID": "YOUR_CLIENT_ID",
          "SecretKey": "YOUR_CLIENT_SECRET",
          "OperationStatus": {
            "Success": true,
            "Errors": []
          }
        }
      }
    }

    Keep: BeneficiaryID, the new company's SPN account number (SPN9999888). It's the RecipientId of every item that pays this company, and the account you name in steps 3 to 5. CreateBeneficiary also connects the new company to yours, which steps 4 and 5 need. Xtrm approves a company 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 (Xtrm's identity checks on the account).

    The response's ClientID and SecretKey are your pseudo credentials for the new company, not the company's own credentials (the sample shows placeholders). With them, your company can call the API as the new company, with its SPN as IssuerAccountNumber. Pseudo credentials require manager services, which Xtrm turns on for your company. If you keep them, store them as secrets on your server, as you store your own, and never log them.

    A company you only pay needs no more onboarding than this. If this company will also fund its own wallets and pay recipients, CreateBeneficiary doesn't finish its onboarding, and part of the rest happens in the Xtrm web app, because no API call uploads documents.

    First the company completes its Identity profile to Advanced (100% IDL). That includes its documents, uploaded under Identity > Identity Documents: a government-issued photo ID for its administrator and, for a private company, a company tax document that shows its tax ID, such as a W-9 for a US company. The company can upload them from its own account. Or your company uploads them for it from the company's Connected Manager Services menu, with the Identity Documents manager service, which Xtrm turns on for your company. Then the company, or your company for it, submits its advanced profile, in the web app or with CompanyAdvancedProfile, and Xtrm reviews it before it unlocks funding for the company. See Complete the advanced profile and Onboard a client company.

  3. Find the company's wallet

    A wallet item in a batch pays into the company's Xtrm wallet. Naming the wallet is optional. If you leave out Destination.WalletId, Xtrm credits the company's oldest active Standard wallet in the batch's currency (the currency of your source wallet), which isn't necessarily its default wallet. If the company has no active wallet in that currency, Xtrm creates one named Wallet - <currency code>, for example Wallet - USD. If its only wallets in that currency are of another type, the item fails with WALLET_AUTO_CREATE_FAILED. To choose a wallet yourself, and to see each wallet's bank flags, list the company's wallets with GetBeneficiaryWallets:

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetBeneficiaryWallets" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetBeneficiaryWallets": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "BeneficiaryAccountNumber": "SPN9999888"
        }
      }
    }'
    Response (excerpt)
    {
      "GetBeneficiaryWalletsResponse": {
        "GetBeneficiaryWalletsResult": {
          "Wallets": [
            {
              "Name": "Wallet - USD",
              "ID": 122340,
              "Currency": "USD",
              "Type": "Standard",
              "Balance": 0,
              "IsBankLinked": false,
              "AllowWalletLinkedBankOverride": false,
              "EntityID": 27045
            }
          ],
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Acme Corporation's new account has one wallet, in USD. Pick a wallet in the currency of your source wallet. A company can hold more than one wallet per currency, so match on the Name too if you need to. A WalletId you send must be an active wallet of the company in the batch's currency, or the item fails with INVALID_BENEFICIARY_WALLET before any money moves. To give the company a new wallet, use CreateBeneficiaryCompanyWallet.

    Keep: the wallet's ID (122340), which you send as WalletId, as a number. IsBankLinked and AllowWalletLinkedBankOverride matter only for a bank item that also sends this wallet's WalletId, which can make Xtrm pay the wallet's linked bank instead of the one you name; see Bank transfer. The bank item in this guide sends no WalletId, so Xtrm pays the bank it names.

  4. Link the company's bank account

    A bank item pays a bank account linked to the company, which you name by its ID. Acme Corporation is new, so link its bank account with LinkBankBeneficiary, sending its SPN in UserID. Linking needs the company to be connected to yours, and a company you created with CreateBeneficiary is. BeneficiaryInformation holds the account holder, here the company, with its address, and BeneficiaryBankInformation holds the bank account. AccountType BUSINESS marks it as a business account. 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": "SPN9999888",
          "Beneficiary": {
            "BeneficiaryDetails": {
              "BeneficiaryInformation": {
                "ContactName": "Acme Corporation",
                "PhoneNumber": "4155550188",
                "AddressLine1": "500 Howard Street",
                "City": "San Francisco",
                "Region": "CA",
                "PostalCode": "94105",
                "CountryISO2": "US"
              }
            },
            "BankDetails": {
              "BeneficiaryBankInformation": {
                "InstitutionName": "Wells Fargo Bank",
                "Currency": "USD",
                "SWIFTBIC": "WFBIUS6S",
                "AccountNumber": "000987656543",
                "RoutingNumber": "121000248",
                "CountryISO2": "US",
                "WithdrawType": "ACH",
                "AccountType": "BUSINESS"
              }
            }
          }
        }
      }
    }'
    Response
    {
      "LinkBankBeneficiaryResponse": {
        "LinkBankBeneficiaryResult": {
          "BeneficiaryId": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
          "BankBeneficiaryStatus": "Approved",
          "AccountIdentityLevel": "Basic",
          "ACHDebitApprovalStatus": null,
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    Keep: BeneficiaryId (5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d), the ID of the linked bank. It's the BeneficiaryBankID of your bank item. A company can link up to 25 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.

  5. Read back the bank's ID and rails

    GetLinkedBankAccounts lists the company's linked bank accounts, with the company's account number in RecipientUserId. Use it to confirm the bank you linked and to find it again for later payments without linking it twice. Like linking, it needs the company to be connected to yours.

    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": "SPN9999888"
        }
      }
    }'
    Response (excerpt)
    {
      "GetLinkedBankAccountsResponse": {
        "GetLinkedBankAccountsResult": {
          "Beneficiary": {
            "BeneficiaryDetails": [
              {
                "BeneficiaryId": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
                "BeneficiaryName": "Acme Corporation",
                "Currency": "USD",
                "Country": "United States of America",
                "BankDetails": {
                  "BeneficiaryBankInformation": {
                    "AccountNumber": "XXXX6543",
                    "BankName": "WELLS FARGO BANK, N.A.",
                    "BankBeneficiaryStatus": "Approved",
                    "BankRoutingCode": "121000248",
                    "PaymentMethods": [
                      "ACH"
                    ]
                  }
                }
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep: the bank's BeneficiaryId (5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d), which you send as BeneficiaryBankID. PaymentMethods inside BankDetails lists the rails available for the account (ACH here). You can name the rail 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.

  6. Submit the batch payment

    Now pay the company with BatchTransfer. Unlike the onboarding calls, the batch has no wrapper object: its fields sit at the root of the body. This batch carries two items for Acme Corporation:

    • Wallet item: SendMethodId XTR94504 (AnyPay Company) pays USD 50.00 into the company's Xtrm wallet 122340, from step 3.
    • Bank item: SendMethodId XTR94500 (Bank) pays USD 100.00 by ACH to its bank account 5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d, from steps 4 and 5.

    Both IDs come from GetPaymentMethods. XTR94504 pays business recipients only: its RecipientId must start with SPN, or the item is rejected when you submit. A company can also be paid by check (XTR94507) or Rapid Transfer (XTR94508), but not with the methods for individual recipients, XTR94502, XTR94503 and XTR94505. See Payment methods & destinations.

    Amount is a JSON number greater than 0, with at most 2 decimal places. SourceWalletId and WalletId are integers, and the source wallet sets the currency of the batch. CustomerBatchId and each item's CustomerTransactionId are required, and Xtrm never generates them. Create them before you send, store them with your payment records, and never reuse one for a different payment. For the ID rules, see Batch and payment identifiers.

    Each item's Description is optional, 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 company's wallet, where the company sees it. The samples start each Description with the item's CustomerTransactionId, which we recommend, so you can find those transactions later; see Track & reconcile payments.

    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-BIZ-0001",
      "Items": [
        {
          "CustomerTransactionId": "TXN-BIZ-0001",
          "RecipientId": "SPN9999888",
          "Amount": 50,
          "SendMethodId": "XTR94504",
          "Destination": {
            "WalletId": 122340
          },
          "Description": "TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus"
        },
        {
          "CustomerTransactionId": "TXN-BIZ-0002",
          "RecipientId": "SPN9999888",
          "Amount": 100,
          "SendMethodId": "XTR94500",
          "Destination": {
            "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
            "BeneficiaryBankPaymentMethod": "ACH"
          },
          "Description": "TXN-BIZ-0002 Q3 Regional Referral Program Commission"
        }
      ]
    }'

    Xtrm checks the request and each item's fields right away. When at least one item passes, it queues the items that passed and answers 202. When none passes, it stores nothing and answers 422, or 409 (see What can go wrong). When both items pass, both are listed in Accepted with the values you sent, 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. Rejected is empty:

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

    Keep: CustomerBatchId (BATCH-BIZ-0001) and each CustomerTransactionId, stored with your own payment records so you can reconcile them later. 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.

    The same batch can also pay other companies and individual recipients, each item with a send method that fits its recipient. See Create a batch payment and Payment methods & destinations.

  7. Confirm the payments

    Follow each payment's outcome by polling the status endpoints or by receiving webhooks. To poll, call the batch status endpoint with your CustomerBatchId. Set history=true to include each item's processing attempts in Attempts, and page through the items with recordsToSkip and recordsToTake.

    curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BIZ-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-BIZ-0001",
      "Status": "Completed",
      "Currency": "USD",
      "ItemsCount": 2,
      "Items": [
        {
          "CustomerTransactionId": "TXN-BIZ-0001",
          "Status": "Success",
          "RecipientId": "SPN9999888",
          "SendMethodId": "XTR94504",
          "Amount": "50.00",
          "LastUpdatedAt": "2026-10-27T16:20:44.0208205Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T16:20:44.0159177Z",
              "CompletedAt": "2026-10-27T16:20:44.0208205Z"
            }
          ]
        },
        {
          "CustomerTransactionId": "TXN-BIZ-0002",
          "Status": "Success",
          "RecipientId": "SPN9999888",
          "SendMethodId": "XTR94500",
          "Amount": "100.00",
          "LastUpdatedAt": "2026-10-27T16:20:52.7779235Z",
          "Attempts": [
            {
              "AttemptNo": 1,
              "Result": "Success",
              "ErrorCode": "SUCCESS",
              "CreatedAt": "2026-10-27T16:20:52.7672875Z",
              "CompletedAt": "2026-10-27T16:20:52.7779235Z"
            }
          ]
        }
      ],
      "Pagination": {
        "HasMore": false,
        "NextRecordsToSkip": 0
      }
    }

    Read the outcome payment by payment:

    • TXN-BIZ-0001, the wallet item, is Success: the money is in the company's Xtrm wallet.
    • TXN-BIZ-0002, the bank item, is Success: the bank provider accepted the payment. That doesn't mean the funds have settled in the company's bank account yet.

    The batch's own Status is Completed because every item is Success. While items are still being processed it reads Processing, including while a bank item's payment to the bank is under way, and when items fail it ends CompletedWithFailures or Failed. Batch and payment statuses explains every value and what to do about it. When Pagination.HasMore is true, pass Pagination.NextRecordsToSkip as recordsToSkip to get the next page. To check one payment, call the payment status endpoint with the CustomerBatchId and CustomerTransactionId. It also returns DeliveryType, which is Bank for this bank item and Wallet for the wallet item. While Xtrm pays the money on to the company's bank, the bank item shows RetainedInWallet, with DeliveryType Wallet, usually only briefly. Don't act on it while the batch is still Processing; for what to do if it stays, see What can go wrong.

    Webhooks. 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. 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 final statuses with the status endpoints.

#What can go wrong

While you onboard the company

  • A search with no criteria. CheckBeneficiaryExist needs at least one of CompanyName and CompanyEmailDomain.
  • A search that returns more than you expect. A name search, a shared email domain or a search with both fields can return several companies. Search with the domain alone, and check Email and Name before you use an AccountNumber (see step 1).
  • A second account for the same business. If the search finds the company, pay that account number instead of creating another (see step 1).
  • Linking the bank is refused. Not authorized to access this resource. Make One Time Password API Call to access this resource (HTTP 400) means the company isn't connected to yours: connect it first with Connect existing accounts. An Errors list of fields means the bank needs more information: add them and send the whole request again.
  • Not checking OperationStatus. Each onboarding response carries OperationStatus; we recommend checking OperationStatus.Success before you use a result and logging Errors when it's false. A failed onboarding call, such as a LinkBankBeneficiary request Xtrm can't accept, answers HTTP 400 with Success: false, so check the HTTP status as well. On success, Errors can be null, [] or [""], depending on the endpoint. See Errors.

While you pay it

  • Rejected items, or a refused request. Items that fail the first checks come back in Rejected, and the other items are still accepted. A problem with the batch as a whole refuses the whole request and stores nothing: for example a missing SourceWalletId or CustomerBatchId (422), a source wallet that isn't yours (403) or a CustomerBatchId that's already in use (409 CONFLICT_PROCESSING). See Items rejected at submission and The whole batch is refused.
  • A timeout or a lost response. Wait and resend the identical request with the same CustomerBatchId and CustomerTransactionId values; Xtrm never stores an item twice. See A safe retry pattern.
  • A company that can't be paid. RECIPIENT_NOT_FOUND means the RecipientId doesn't exist or its status isn't Active, Email not verified or Account pending approval, and SENDMETHODID_NOT_FOUND means the send method doesn't fit a company (step 6). Both happen before any money moves. Pay the correct account or method as a new item with a new CustomerTransactionId.
  • A failed item. An item that can't be paid ends Failed, and its attempt's ErrorCode says why (see Error codes on attempts). For example, BANKID_INVALID means the bank you named isn't linked to the company or was deleted, and INSUFFICIENT_BALANCE means your source wallet was short when Xtrm paid the item. Fix the cause, then resubmit only the failed items under the same CustomerBatchId and CustomerTransactionId, with every field. See Resubmit failed payments and Retries & idempotency.
  • A bank item that 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 company'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 company can transfer it out itself in the Xtrm web app, or you can request the transfer for it with BeneficiaryCompanyWithdrawFund and its one-time password. That transfer is made only when a response has PaymentStatus Completed and a PaymentTransactionId: the first response, with Success: true, only sends the code. See When a payment stays RetainedInWallet.
  • The bank you named is ignored. If a bank item also sends a WalletId whose AllowWalletLinkedBankOverride is false, Xtrm pays the wallet's linked bank instead of the BeneficiaryBankID you name, without an error, and fails the item with DEFAULT_BANK_NOT_FOUND if the wallet has none. Leave WalletId out of bank items unless you want the wallet's bank. See Bank transfer.

#Next steps

For every field, see the reference page for batch payments, business recipients or wallets.