Guide

Fund your wallet

Every batch payment pays from one of your company wallets: the one you name in SourceWalletId. That wallet also sets the batch's currency. In this guide you find that wallet (or create one), fund it, and check its balance before you submit a batch. You can fund it three ways: a bank transfer you send to Xtrm, a bank debit that Xtrm pulls from a bank account you've linked and verified, or a charge to your company's own credit card. Each funding call returns a TransactionID that you can use to track the funding until the money is in the wallet.

If you're a managing platform

Fund each client company's own wallet, with its pseudo credentials and its SPN in IssuerAccountNumber. Pseudo credentials require manager services, which Xtrm turns on for your company. Xtrm unlocks funding for a client company once its advanced profile is approved, which takes 1 to 2 days for a US-only profile and 5 to 7 days for an international one. See Onboard a client company.

#Choose a funding method

All three methods add money to your company's own wallets:

Bank transferBank debitCredit card
EndpointFundWalletUsingBankTransferFundWalletUsingACHDebitFundCompanyWalletUsingCreditCard
How the money movesYou send an ACH or wire to the Xtrm bank account returned in the responseXtrm debits a bank account you linked for bank debitXtrm charges your company's own card
One-time setupNoneLink the bank, verify micro-deposits, wait for approvalLink the card with LinkCard as an identity card to get its CardToken
Timing2–7 business days to be credited, depending on your location3–5 business days to completeAs soon as the card is charged, up to a limit Xtrm sets for your company; above it, 1–3 business days to appear in the wallet
CurrenciesXtrm's receiving bank account varies by currencyUSD, CAD, AUD, GBP and EUR (since release 4.91.6)USD only
Good fitFunding by ACH or wire from your own bank, with an optional emailed invoiceRepeat funding from one verified bank, started entirely through the APIFunding with a company card, with the shortest timing

To move money into a wallet from another of your company's wallets instead, see Move money between your own wallets.

Testing in the sandbox

Once Xtrm approves your IP addresses, it credits test funds to your sandbox wallets, so you can test batch payments without funding a wallet first. WalletBalance in GetCompanyWallets shows what you have, and [email protected] can add more; see Test funds. The funding calls on this page work in the sandbox as they do in production, but no real money moves there. Xtrm credits a bank transfer or bank debit only once it approves the funding request, so in the sandbox those requests stay Pending until Xtrm approves them. Never use real bank or card details in the sandbox: link a bank as Test bank accounts describes, and fund by card with a test card number (see Fund by credit card).

#Before you begin

  • Sandbox credentials and an access token. The samples read the token from the XTRM_ACCESS_TOKEN environment variable. See Authentication.
  • Your company account number. It starts with SPN and goes in IssuerAccountNumber on every call, including your batch payments. The samples use SPN1111222. See Accounts, wallets & IDs.
  • For a bank debit: your company's own business bank account: the bank's name, account number, currency and country, plus its routing number and SWIFT/BIC code where the bank needs them, and your company's name, phone number and address as the account holder.
  • For a credit card: the cardholder's name and billing address, and the card's CardToken. Link the card with LinkCard and set LinkCardType to identity, not transfer: only your company's identity cards can fund a wallet, and transfer cards are for receiving Rapid Transfer payments. LinkCard returns the CardToken, and GetLinkedCards lists each card with its token and LinkCardType.

#Find or create your source wallet

Every funding call takes the WalletID of the wallet to credit, and the same ID goes in SourceWalletId when you submit a batch. Because the source wallet sets the batch's currency, fund a wallet in the currency you pay in. A company can hold more than one wallet in the same currency, so we recommend choosing the wallet by its ID rather than by currency alone. Use one of your own company wallets: a batch whose SourceWalletId doesn't belong to its IssuerAccountNumber is refused with 403 FORBIDDEN.

  1. List your company wallets

    Call GetCompanyWallets with your IssuerAccountNumber. Each entry in CompanyWalletDetails shows the wallet's ID, name, currency, balance and WalletType.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetCompanyWallets": {
        "request": {
          "IssuerAccountNumber": "SPN1111222"
        }
      }
    }'
    Response (excerpt)
    {
      "GetCompanyWalletResponse": {
        "CompanyWalletResult": {
          "CompanyWallets": {
            "CompanyWalletDetails": [
              {
                "WalletID": 122181,
                "WalletName": "USD Wallet for Main Company",
                "WalletCurrency": "USD",
                "WalletBalance": 57715.15,
                "WalletType": "Standard",
                "IsBankLinked": false,
                "AllowWalletLinkedBankOverride": false,
                "EntityID": 12345
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep the WalletID of the wallet you want to fund, for example 122181: it's the wallet your batch payments will pay from. Responses return it as a number. Funding calls send it as a string ("122181"), while a batch sends it as an integer in SourceWalletId (122181). Funding calls take only this numeric ID, never the wallet's name: a request with a name in WalletID is rejected and no money moves. WalletBalance is the balance you check before you submit a batch. The samples on this page fund 122181.

  2. Create a wallet if you need one

    If none of your wallets fits, for example because you want a separate wallet for one program or you pay in a new currency, call CreateCompanyWallet. (To move an existing balance into a wallet in another currency instead, see Exchange currency.) The request fields:

    • WalletName is the wallet's display name. Xtrm doesn't require names to be unique, so we recommend a distinct name for each wallet and identifying wallets by WalletID.
    • WalletCurrency is a three-letter ISO 4217 code such as USD.
    • WalletType is required. Set it to Standard, the only type to use when you create a wallet through the API.
    • EntityID is optional, and this example leaves it out, so the wallet goes into your company's prime entity, its default. To create the wallet in another of your company's entities, send that entity's ID; see Entity IDs. Leave the field out rather than sending it empty: "" fails with EntityID must be an integer.
    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CreateCompanyWallet": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "WalletName": "USD Rewards Wallet",
          "WalletCurrency": "USD",
          "WalletType": "Standard"
        }
      }
    }'
    Response
    {
      "CreateCompanyWalletResponse": {
        "CreateCompanyWalletResult": {
          "WalletID": 122183,
          "WalletName": "USD Rewards Wallet",
          "WalletCurrency": "USD",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep the new WalletID (122183 here). After you create a wallet you can only rename it; its WalletID and currency can't change. This call is only for your own company: individual and business recipients have their own wallet calls on the Wallets page.

#Fund by bank transfer

With a bank transfer, you request Xtrm's bank details through the API, then send an ACH or wire from your own bank. Nothing needs to be set up in advance.

  1. Request Xtrm's bank instructions

    Call FundWalletUsingBankTransfer with the amount (a string such as "500"), the currency and the WalletID to credit. The inner key is spelled Request, with a capital R, but Xtrm matches field names without regard to case, so either spelling works.

    • BeneficiaryAccountNumber is required: the SPN of the company whose wallet you fund. WalletID must be one of that company's wallets, in CurrencyCode. To fund your own wallet, send your own SPN, the same one as in IssuerAccountNumber. Any other company must be connected to yours, or the call returns 401. The samples fund your own wallet, so both fields hold SPN1111222.
    • InvoiceRequired: "true" (a string) has Xtrm generate an invoice for the transaction and send it by email. With it, the amount must be at least 500 USD or the equivalent in CurrencyCode. Send the exact string "true", lowercase and in quotes: Xtrm reads a JSON true as "True", which passes the checks, including the minimum, but doesn't request the invoice.
    • Optional fields include ProgramID, a memo in Additionalinformtaion (spelled exactly like that; the corrected spelling is ignored), and the dates RequiredDepositDate and RequiredPaymentDate. Write both dates as US dates, MM/DD/YYYY: "06/05/2026" is 5 June 2026.
    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingBankTransfer" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "FundWalletUsingBankTransfer": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "BeneficiaryAccountNumber": "SPN1111222",
          "Amount": "500",
          "CurrencyCode": "USD",
          "WalletID": "122181",
          "InvoiceRequired": "true"
        }
      }
    }'
    Response
    {
      "FundWalletUsingBankTransferResponse": {
        "FundWalletUsingBankTransferResult": {
          "TransactionID": "888555",
          "Amount": 500,
          "Fee": 0,
          "TotalAmount": 500,
          "WalletID": 122181,
          "Currency": "USD",
          "Method": "Bank Transfer",
          "BankInformation": "Remit Funds to: Example Bank International<br>Account No: Bank ID: 999 <br/>Transit: 12345 <br/>Account: 987654321098<br>SWIFT: EXBKUS33XXX<br>ABA: 123456789<br>Beneficiary: Example Receiving Account<br>Address: 100 Example Way <br/>Suite 400 San Francisco, CA 94105 <br/>United States",
          "Description": "Fund Request - Bank Transfer (Pending)",
          "Status": "Pending",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep TransactionID to track the funding, and BankInformation: the Xtrm bank account your funds go to. It's a single string whose lines are separated by HTML line breaks (<br> and <br/>), so we recommend converting them before you show it to anyone. The account varies by currency, so read it from each response instead of hard-coding it. TotalAmount is the total amount Xtrm expects to receive, including any fees.

    The call creates a pending fund request in the wallet, and Status stays Pending until the transaction is fully completed and cleared. Next, start an ACH or wire from your bank to the account in BankInformation. The transfer needs no reference. Once Xtrm receives the money, it credits the wallet. Allow 2–7 business days, depending on your location, for the funds to be credited. Until Xtrm credits them, the wallet's balance doesn't change and the funds can't pay a batch.

#Fund by bank debit

With bank debit, Xtrm pulls the money from your company's own bank account, once you've linked and verified it. It used to be called ACH debit, which is why the operations still say ACHDebit. Setup takes four calls and some waiting. After that, funding the wallet takes a single call each time. The samples carry one bank through every step: the link returns its ID, 12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10, and every later call sends it.

Use the bank debit calls below, not LinkBankBeneficiary or GetLinkedBankAccounts. Those link and list the recipient banks that payments go to, such as the BeneficiaryBankID of a bank item in a batch.

  1. Link the bank account

    Call LinkACHDebitBankBeneficiary. Put the account holder in Beneficiary.BeneficiaryDetails.BeneficiaryInformation and the bank account in Beneficiary.BankDetails.BeneficiaryBankInformation.

    • UserID is the Xtrm account the bank is linked to: your own SPN, the same one as in IssuerAccountNumber (SPN1111222 in the samples). FundWalletUsingACHDebit debits only a bank linked to the company in its IssuerAccountNumber, and refuses any other bank with <LinkedBankID> - Invalid Linked Bank ID. Send the same account as UserID in the micro-deposit calls and as RecipientUserId when you list bank-debit banks.
    • CountryISO2 appears twice: for the account holder's address and for the bank's location.
    • ContactName takes 1 to 100 characters and can't contain special characters such as <, >, @, #, $ or %. PhoneNumber takes 1 to 15 characters, counting any spaces or dashes, and City 1 to 100. Region is the two-letter ISO2 code or the full state name.
    • AccountType must be BUSINESS for a bank-debit link, as in the sample, in any case. Any other value is refused with BeneficiaryBankInformation - AccountType must be with value 'BUSINESS'. Personal accounts not supported.
    • RoutingNumber and SWIFTBIC are required only when the bank's country and currency need them. Where they aren't required and you send an IBAN as AccountNumber without them, Xtrm takes them from the IBAN.
    • Leave out RegulatoryFields unless a previous response asks for data to go there (see What can go wrong).
    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "LinkACHDebitBankBeneficiary": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "SPN1111222",
          "Beneficiary": {
            "BeneficiaryDetails": {
              "BeneficiaryInformation": {
                "ContactName": "Main Company",
                "PhoneNumber": "14085556245",
                "AddressLine1": "1234 Market Street",
                "City": "San Francisco",
                "Region": "CA",
                "PostalCode": "94105",
                "CountryISO2": "US"
              }
            },
            "BankDetails": {
              "BeneficiaryBankInformation": {
                "InstitutionName": "Wells Fargo Bank",
                "AccountType": "BUSINESS",
                "Currency": "USD",
                "SWIFTBIC": "WFBIUS6S",
                "AccountNumber": "1234567890",
                "RoutingNumber": "121000248",
                "CountryISO2": "US"
              }
            }
          }
        }
      }
    }'
    Response
    {
      "LinkACHDebitBankBeneficiaryResponse": {
        "LinkACHDebitBankBeneficiaryResult": {
          "ACHDebitApprovalStatus": "Pending - Microdeposit verfication",
          "AccountIdentityLevel": "Advanced",
          "BankBeneficiaryStatus": "Pending",
          "BeneficiaryId": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10",
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    Keep BeneficiaryId (12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10 here). It's the only ID the response returns, and every later bank-debit call takes it: as BeneficiaryBankID in the micro-deposit calls and as LinkedBankID when you fund. The link starts with ACHDebitApprovalStatus set to Pending - Microdeposit verfication (spelled that way) for a bank that Xtrm verifies with micro-deposits, as in this example, or Pending for any other bank. You can fund from it only once it's approved.

    Linking can take more than one request. Xtrm checks each request against what a bank debit needs for the bank's country and currency. When a field is missing or in the wrong format, the response is HTTP 400, with LinkACHDebitBankBeneficiaryResponse.LinkACHDebitBankBeneficiaryResult.OperationStatus.Success set to false and each field to add or fix in Errors. Send the whole request again with those fields filled in, and repeat until the response returns a BeneficiaryId. See What can go wrong and Errors.

  2. Send the micro-deposits

    Micro-deposits apply only to a bank whose link returned ACHDebitApprovalStatus Pending - Microdeposit verfication. For any other bank, skip this step and the next, and check that the bank is approved.

    Call ReleaseACHDebitMicrodeposit with the linked bank's ID as BeneficiaryBankID. Xtrm sends two small deposits to the bank account to confirm that it's connected to the correct account. They can take up to 3 business days to show on the statement. You release them once per bank: a second call returns Microdeposits were released. Please check your bank account.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/ReleaseACHDebitMicrodeposit" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "ReleaseACHDebitMicrodeposit": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "SPN1111222",
          "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10"
        }
      }
    }'
    Response
    {
      "ReleaseACHDebitMicrodepositResponse": {
        "ReleaseACHDebitMicrodepositResult": {
          "Message": "We have sent micro deposit to your account XXXX7890 successfully.",
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }

    There's nothing new to keep: Message confirms the deposits and shows the last four digits of the bank account number.

  3. Verify the deposit amounts

    Once the micro-deposits show up on the bank statement, call VerifyACHDebitMicrodeposit with the same BeneficiaryBankID and the two amounts that appeared, as Amount_1 and Amount_2. Send each amount as a decimal string such as "0.04", not as a number. A successful call confirms account ownership and that the bank is linked correctly: Message reads We have verified your bank successfully. and the bank's ACHDebitApprovalStatus turns Approved.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/VerifyACHDebitMicrodeposit" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "VerifyACHDebitMicrodeposit": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "UserID": "SPN1111222",
          "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10",
          "Amount_1": "0.04",
          "Amount_2": "0.07"
        }
      }
    }'
    Response
    {
      "VerifyACHDebitMicrodepositResponse": {
        "VerifyACHDebitMicrodepositResult": {
          "Message": "We have verified your bank successfully.",
          "OperationStatus": {
            "Errors": null,
            "Success": true
          }
        }
      }
    }
  4. Check that the bank is approved

    Call GetACHDebitLinkedBankAccounts. This call names the account field RecipientUserId rather than UserID. Each bank in BeneficiaryDetails has a BeneficiaryId, and its BankDetails.BeneficiaryBankInformation.ACHDebitApprovalStatus says whether it's approved for bank debit. It reads Approved once you can fund from the bank. Until then it reads Pending, Pending Verification or Pending Approval; a bank whose status is Incomplete or Deactive can't be debited. The bank's BankBeneficiaryStatus is Approved or Pending. This list shows only bank-debit banks, not the banks linked to receive payments.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/GetACHDebitLinkedBankAccounts" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetACHDebitLinkedBankAccounts": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "RecipientUserId": "SPN1111222"
        }
      }
    }'
    Response
    {
      "GetACHDebitLinkedBankAccountsResponse": {
        "GetACHDebitLinkedBankAccountsResult": {
          "Beneficiary": {
            "BeneficiaryDetails": [
              {
                "BeneficiaryId": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10",
                "BeneficiaryName": "Main Company",
                "Currency": "USD",
                "Country": "United States of America",
                "TransferFee": 0,
                "PaymentMethods": {
                  "Payment": "ACH"
                },
                "BankDetails": {
                  "BeneficiaryBankInformation": {
                    "AccountNumber": "XXXX7890",
                    "BankName": "Wells Fargo Bank",
                    "BranchName": "San Francisco Main",
                    "BankBeneficiaryStatus": "Approved",
                    "ACHDebitApprovalStatus": "Approved",
                    "BankRoutingCode": "121000248",
                    "EntityID": 12345,
                    "PaymentMethods": null
                  }
                }
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Find the bank by the BeneficiaryId that the link returned (12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10 here) and check its ACHDebitApprovalStatus. Here it's Approved, after the micro-deposits were verified, so you can fund from it. If it's still pending, check again later rather than in a tight loop.

  5. Fund the wallet

    Call FundWalletUsingACHDebit with the amount, the currency, the WalletID to credit and the approved bank in LinkedBankID: the same BeneficiaryId (12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10). A bank that isn't approved yet is refused with a pending-status message, such as <LinkedBankID> - Linked Bank ID is in pending status. The root key is FundWalletUsingACHDebitRequest and the inner key is Request. Release 4.91.6 added bank debit funding in USD, CAD, AUD, GBP and EUR.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingACHDebit" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "FundWalletUsingACHDebitRequest": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "Amount": "50",
          "CurrencyCode": "USD",
          "WalletID": "122181",
          "LinkedBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10"
        }
      }
    }'
    Response
    {
      "FundWalletUsingACHDebitResponse": {
        "FundWalletUsingACHDebitResult": {
          "Amount": "50.00",
          "Currency": "USD",
          "Fee": "2.25",
          "OperationStatus": {
            "Errors": null,
            "Success": true
          },
          "Status": "Bank debit fund request in process (Pending). You will be notified once completed.",
          "TotalAmount": "52.25",
          "TransactionID": "888444"
        }
      }
    }

    Keep TransactionID to track the funding. TotalAmount is the total debited from the bank, the amount plus the fee. Status describes the request, which starts as pending. Bank debit can take 3 to 5 business days to complete, and the funds can pay a batch only once Xtrm approves the funding and credits the wallet. Xtrm emails your company once the funding completes. To follow it, see Check the balance before you submit a batch.

#Fund by credit card

Charge your company's own card. This call is only for funding your own company wallets: it isn't intended for taking payments from consumers.

  1. Charge your company card

    Call FundCompanyWalletUsingCreditCard. The root key is FundCompanyWalletUsingCreditCardRequest, and the fields sit in four groups:

    • PaymentDetails: IssuerAccountNumber, Amount (a string such as "50"), CurrencyCode and the WalletID to credit.
    • PayerInformation: the cardholder's legal FirstName and LastName, 2–40 characters each.
    • PayerBillingAddress: the card's billing address, with a City of 1–25 characters.
    • CreditCardDetails: the card's CardToken.

    CardToken identifies the linked card. It's a 15-character string of digits and capital letters A to F, such as F2AA507CD01E4EC, so store it as a string, exactly as LinkCard or GetLinkedCards returns it. When you send it, Xtrm charges that card and ignores the other CreditCardDetails fields, so the sample sends only the token. Leave CardToken out and Xtrm charges the card in CreditCardNumber, CVV, CreditCardType, ExpireMonth ("1" to "12") and four-digit ExpireYear instead, and they're required then. Xtrm doesn't fall back to a default card, so a request with neither a token nor card details is refused. Funding with card details also links the card to your company, which counts toward the three cards an account can link. We recommend linking the card once and funding with its CardToken, which must belong to one of your company's identity cards. Card funding is in USD only.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/FundCompanyWalletUsingCreditCard" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "FundCompanyWalletUsingCreditCardRequest": {
        "Request": {
          "PaymentDetails": {
            "IssuerAccountNumber": "SPN1111222",
            "Amount": "50",
            "CurrencyCode": "USD",
            "WalletID": "122181"
          },
          "PayerInformation": {
            "FirstName": "Sam",
            "LastName": "Taylor"
          },
          "PayerBillingAddress": {
            "AddressLine1": "500 Howard Street",
            "City": "San Francisco",
            "State": "CA",
            "CountryISO2": "US",
            "PostalCode": "94105"
          },
          "CreditCardDetails": {
            "CardToken": "F2AA507CD01E4EC"
          }
        }
      }
    }'
    Response
    {
      "FundCompanyWalletUsingCreditCardResponse": {
        "FundCompanyWalletUsingCreditCardResult": {
          "Amount": "50.00",
          "Currency": "USD",
          "Fee": "2.25",
          "OperationStatus": {
            "Errors": null,
            "Success": true
          },
          "TotalAmount": "52.25",
          "TransactionID": "888333"
        }
      }
    }

    Keep TransactionID to track the funding. Xtrm charges your card the Amount you send and credits that full Amount to the wallet. Fee is the card funding fee for this amount on your company's pricing, and TotalAmount is Amount plus Fee. The card is charged Amount, not TotalAmount. Amounts come back as strings with two decimals, and amounts of 1,000 or more include a thousands separator, such as "1,250.00", so strip separators before you parse them. When the amount is within a card funding limit that Xtrm sets for your company, Xtrm credits the wallet as soon as the card is charged. Otherwise the funds can take 1–3 business days to appear in the wallet.

#Move money between your own wallets

When one of your wallets is short and another has money to spare, move it across in the Xtrm web app. The API has no call for moving money between your own wallets. A batch payment can't pay your own account: an item whose RecipientId is your own IssuerAccountNumber is rejected with 422 INVALID_FIELD and From Account no and To Account no cannot be same.

  1. In the web app, open your company's wallets and choose Move on the wallet you're moving money from.
  2. Under To Wallet, pick the wallet that receives the money. The list shows your company's other wallets in the same currency; if there isn't one, create it first.
  3. Enter the Amount and an optional Description, then choose Continue.

Xtrm debits one wallet and credits the other in a single step, and charges no fee for the move. The amount can't be more than the source wallet's balance. If your company has a secondary approver set for wallet transfers, a move above their threshold waits for that approval instead. Team members need the Move Funds permission.

#Check the balance before you submit a batch

Funding responses don't include the wallet's new balance. To see when the money lands, call GetCompanyWallets again and check WalletBalance, or list the wallet's transactions with GetCompanyWalletTransactions. Until Xtrm approves a funding request, the request is listed as a Pending transaction (the Pending value of Filters.TransactionType selects these) and the balance doesn't change. Once Xtrm approves it, a credit appears, with the PaymentType Company Wallet Funding.

Before you submit a batch, we recommend confirming that the source wallet's WalletBalance covers the total of the batch's item Amount values plus their fees: each recipient receives the full Amount, and the fee comes from your wallet. Fees are charged per item and follow each item's send method. GetCompanyFees returns your fees for wallet items (XTR94502 and XTR94504), in USD, when you send your own SPN in BeneficiaryAccountNumber. No endpoint returns the fees for bank, check, card or Rapid Transfer items, so we recommend leaving headroom in the source wallet.

When the balance covers the batch, submit it with BatchTransfer and pass the wallet's ID as an integer in SourceWalletId, for example 122181. Create a batch payment walks through the whole call.

#What can go wrong

A funding call that fails returns HTTP 400 with OperationStatus.Success set to false and the reasons in Errors. Decide with OperationStatus.Success on every response, not with Errors, which is null on success from the calls on this page but [] from DeleteBankBeneficiary. See Errors for the other statuses and the general pattern.

  • A batch item fails with INSUFFICIENT_BALANCE. The source wallet held less than the item's Amount plus its fee when Xtrm processed the item, so nothing was debited for it, and Xtrm went on to the next item. Fund the same wallet, wait until WalletBalance shows the funds, then resubmit only the failed items under their original IDs, with every field as before. See Resubmit failed payments.
  • The money isn't in the wallet yet. Funding takes time: allow 2–7 business days for a bank transfer, 3–5 for a bank debit and 1–3 for a credit card charge above the card funding limit Xtrm sets for your company. In the sandbox, a bank transfer or bank debit stays Pending until Xtrm approves it. We recommend waiting until WalletBalance shows the funds before you submit a batch that depends on them.
  • A bank transfer with an invoice is refused. With InvoiceRequired set to "true", the amount must be at least 500 USD, or the equivalent in CurrencyCode, or the call returns 400 with Minimum bank transfer amount is …. A value that isn't true or false, such as "yes", returns InvoiceRequired must be true/false.
  • Linking a bank returns HTTP 400 with Success: false. The bank needs more information; requirements vary by country and currency. Errors lists each field to add or fix with an ErrorMessage, its FieldName, the parameter to send, a FieldLabel you can show in your interface, and IsRegulatoryField, which is true when the value goes in RegulatoryFields as a Key/Value pair, with the FieldName as the Key. Send the whole LinkACHDebitBankBeneficiary request again with those fields, and repeat until it returns a BeneficiaryId. Other failures, such as a bank that's already linked, return messages as strings in Errors. See Errors on a failed call.
  • The bank isn't approved yet. You can only debit a bank that is linked for bank debit and approved. Check ACHDebitApprovalStatus before you call FundWalletUsingACHDebit.
  • <LinkedBankID> - Invalid Linked Bank ID. The bank isn't linked for bank debit to the company in IssuerAccountNumber, or it was removed. Fund only from a bank you linked to your own SPN, by the BeneficiaryId that GetACHDebitLinkedBankAccounts lists for it.
  • You've reached the linked-bank limit. A personal account can have up to 3 banks linked to receive payments, and a company account more, up to a limit Xtrm sets. Bank-debit banks don't count toward that limit, but once an account has reached it, LinkACHDebitBankBeneficiary refuses a new bank-debit link with You can link maximum N banks.
  • The micro-deposit amounts don't match. VerifyACHDebitMicrodeposit returns Invalid amount. or the bank provider's message, and each amount must be greater than 0. Check the two amounts on the bank statement and try again. If the amounts are refused too many times, remove the bank with DeleteBankBeneficiary, then link it again.
  • The card can't fund the wallet. Only cards linked as identity cards can fund a wallet; transfer cards are for receiving funds.
  • Funding with card details is refused. A request without CardToken links the card it describes to your company. So it returns You can link maximum 3 Cards once three cards are linked to your account, and Card already linked. for a card that's already linked as an identity card. Fund with the CardToken of one of your linked identity cards instead.
  • A funding call times out. The funding calls take no idempotency key, so a retry can create a second funding request. Before you retry, we recommend checking the wallet's transactions with GetCompanyWalletTransactions for the original request. A batch payment is different: you can resend it safely with the same IDs (see A safe retry pattern).

#Next steps