API reference

Funding

Funding endpoints put money into your company's own wallets. There are three ways to fund: bank transfer, where you move money by ACH or wire to an Xtrm bank account that the API returns; bank debit, where Xtrm debits a bank account you linked for bank debit; and credit card, where you charge your company's own card. The credit card call is only for funding your own wallets, not for taking payments from consumers.

Bank transfers can take 2 to 7 business days to be credited, bank debits 3 to 5 business days to complete, and credit card funds 1 to 3 business days to appear in the wallet, unless the amount is within a card funding limit that Xtrm sets for your company: then Xtrm credits the wallet as soon as the card is charged. Each call returns a TransactionID that you can use to track the funding transaction.

Bank debit was formerly called ACH debit, so its operations keep the ACHDebit name (for example, FundWalletUsingACHDebit). The sandbox works the same as production, and it has no sandbox-only test bank, routing or IBAN numbers. For a card in the sandbox, use a standard test number: Visa 4111111111111111 or Mastercard 5555555555554444, with a future expiry date and a three-digit CVV. No real money moves in the sandbox, and you should never use real financial data there.

#Fund a wallet by bank transfer

POST/API/v4/Wallet/FundWalletUsingBankTransfer

Funds one of your company wallets by bank transfer. The call creates a pending fund request in the wallet and returns, in BankInformation, the Xtrm bank account that receives the funds. This bank account varies by currency. Start an ACH or wire from your bank to that account. The transfer needs no reference. Once Xtrm receives the money, it credits the wallet. Until then, the funds can't pay a batch.

Set InvoiceRequired to "true", a lowercase string, to have 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. Use ProgramID to link the funding to one of your programs.

Body parameters

  • FundWalletUsingBankTransferobjectRequired

    Root wrapper for the request.

    Child parameters1
    • RequestobjectRequired

      The funding request.

      Child parameters10
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • BeneficiaryAccountNumberstringRequired

        The SPN of the company whose wallet you fund. To fund your own wallet, send your own SPN. WalletID must be one of this company's wallets in CurrencyCode. Any other company must be connected to yours, or the call returns 401.

      • AmountstringRequired

        The amount to fund into the wallet, passed as a string (for example, "500").

      • CurrencyCodestringRequired

        Three-letter ISO 4217 currency code of the funding transaction, for example USD.

      • WalletIDstringRequired

        The WalletID of the wallet to fund, as a string, for example "122181". It takes only the wallet's numeric ID: a request with a wallet name is rejected with Wallet ID is mandatory, and no money moves.

      • AdditionalinformtaionstringOptional

        An optional memo or routing instructions for the bank transfer, for example "Q3 Partner Funding Replenishment". The field name is spelled exactly this way.

      • InvoiceRequiredstringOptional

        Send "true", lowercase and in quotes, to have Xtrm generate an invoice for the transaction and send it by email. Send "false" or leave the field out for no invoice. With "true", the amount must be at least 500 USD, or the equivalent in CurrencyCode. Send the exact string "true": Xtrm reads a JSON true as "True", which passes the checks, including the minimum, but doesn't request the invoice. A value other than true or false, in any letter case, such as "yes", returns 400 with InvoiceRequired must be true/false.

      • ProgramIDstringOptional

        The identifier of a rewards, payment or budget program to link this funding transaction to, for example "1024".

      • RequiredDepositDatestringOptional

        The date you request for the funds to arrive and clear, as a US date in MM/DD/YYYY format: "06/05/2026" is 5 June 2026.

      • RequiredPaymentDatestringOptional

        The requested date for the payment to be initiated, as a US date in MM/DD/YYYY format: "06/05/2026" is 5 June 2026.

Response fields

  • FundWalletUsingBankTransferResponseobject

    Root wrapper for the response.

    Child parameters1
    • FundWalletUsingBankTransferResultobject

      The funding result.

      Child parameters11
      • TransactionIDstring

        Unique identifier of this funding transaction. Use it to track the transaction.

      • Amountnumber

        The amount of the fund request, before fees.

      • Feenumber

        The processing fee applied to the bank transfer.

      • TotalAmountnumber

        The total amount expected to be received, including any applicable fees.

      • WalletIDinteger

        The WalletID of the destination wallet, as a number, for example 122181.

      • Currencystring

        Three-letter ISO 4217 currency code of the funded amount.

      • Methodstring

        The payment method used for the transaction, for example Bank Transfer.

      • BankInformationstring

        The bank routing and account details of the Xtrm account that receives the funds, returned as a single string. In the example, lines are separated by HTML line-break tags.

      • Descriptionstring

        A description of the transaction, 1 to 100 characters, for example Fund Request - Bank Transfer (Pending).

      • Statusstring

        The current state of the funding request. It stays Pending until the transaction is fully completed and cleared.

      • OperationStatusobject

        The outcome of the call.

        Child parameters2
        • Errorsstring[]

          Validation or execution error details when the call fails. null when the call succeeds, so decide with Success.

        • Successboolean

          true if the operation succeeded, otherwise false.

Related: List company wallets · List your company's programs · List company wallet transactions · Get the details of a company wallet transaction · Fund a wallet by bank debit · Fund a wallet with a credit card

#Fund a wallet by bank debit

POST/API/v4/Wallet/FundWalletUsingACHDebit

Funds one of your company wallets by debiting a bank account linked for bank debit (ACH or a similar system). Pass the linked bank's BeneficiaryId, from LinkACHDebitBankBeneficiary or GetACHDebitLinkedBankAccounts, in LinkedBankID.

The response returns the amount, the processing fee, the total amount debited from the bank (amount plus fee), a TransactionID to track the transaction, and a Status describing the state of the request, which starts as pending. Xtrm credits the wallet when it approves the funding; until then, the funds can't pay a batch. Xtrm emails your company once the funding completes.

Bank debit was formerly called ACH debit, which is why the operation and related calls keep the ACHDebit name.

Note

You can only debit a bank account linked for bank debit with LinkACHDebitBankBeneficiary and approved for bank debit. Check the approval status with GetACHDebitLinkedBankAccounts.

Note

Release 4.91.6 added bank debit funding in USD, CAD, AUD, GBP and EUR.

Body parameters

  • FundWalletUsingACHDebitRequestobjectRequired

    Root wrapper for the request.

    Child parameters1
    • RequestobjectRequired

      The funding request.

      Child parameters5
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • AmountstringRequired

        The amount to fund into the wallet, passed as a string (for example, "50").

      • CurrencyCodestringRequired

        Three-letter ISO 4217 currency code of the funding transaction, for example USD.

      • WalletIDstringRequired

        The WalletID of the wallet to fund, as a string, for example "122181". It takes only the wallet's numeric ID: a request with a wallet name is rejected with HTTP 400 and WalletID is Mandatory and must be an integer, and no money moves.

      • LinkedBankIDstringRequired

        The BeneficiaryId of the linked bank account to debit, as LinkACHDebitBankBeneficiary and GetACHDebitLinkedBankAccounts return it. The bank must be linked for bank debit to your own company, the account in IssuerAccountNumber, and approved: any other bank is refused with <LinkedBankID> - Invalid Linked Bank ID, and a bank that isn't approved yet with a pending-status message, such as <LinkedBankID> - Linked Bank ID is in pending status.

Response fields

  • FundWalletUsingACHDebitResponseobject

    Root wrapper for the response.

    Child parameters1
    • FundWalletUsingACHDebitResultobject

      The funding result.

      Child parameters7
      • Amountstring

        The base amount funded into the wallet, as a decimal string (for example, "50.00").

      • Currencystring

        Three-letter ISO 4217 currency code of the funded amount.

      • Feestring

        The processing fee applied to the bank debit, as a decimal string (for example, "2.25").

      • OperationStatusobject

        The outcome of the call.

        Child parameters2
        • Errorsstring[]

          Validation or execution error details when the call fails. null when the call succeeds, so decide with Success.

        • Successboolean

          true if the operation succeeded, otherwise false.

      • Statusstring

        Text describing the current state of the bank debit fund request, for example Pending, Completed, or Failed.

      • TotalAmountstring

        The total amount debited from the bank (amount plus fees), as a decimal string (for example, "52.25").

      • TransactionIDstring

        Unique identifier of this funding transaction. Use it to track the transaction.

Related: Link a bank account for bank debit funding · Send micro-deposits to a linked bank · Verify micro-deposit amounts · List bank accounts linked for bank debit · List company wallets · Get the details of a company wallet transaction

#Fund a wallet with a credit card

POST/API/v4/Wallet/FundCompanyWalletUsingCreditCard

Funds one of your company wallets by charging the company's own credit card. Pass the payment details (amount, currency and destination wallet), the cardholder's name, the card's billing address, and the card's CardToken (or, without a token, the card's details, which also links that card to your company). Card funding is in USD only. A CardToken must belong to a card your company linked as an identity card.

Xtrm charges the card the Amount you send and credits that full Amount to the wallet. The response returns Amount, the card funding Fee for that amount on your company's pricing, TotalAmount (Amount plus Fee), and a TransactionID to track the transaction. The card is charged Amount, not TotalAmount.

Note

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 to 3 business days to appear in the wallet.

Tip

To use a linked card, get its CardToken from GetLinkedCards. Only cards linked as identity cards can fund a wallet; transfer cards are for receiving Rapid Transfer payments.

Body parameters

  • FundCompanyWalletUsingCreditCardRequestobjectRequired

    Root wrapper for the request.

    Child parameters1
    • RequestobjectRequired

      The funding request.

      Child parameters4
      • PaymentDetailsobjectRequired

        The amount to fund and the destination wallet.

        Child parameters4
        • IssuerAccountNumberstringRequired

          Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

        • AmountstringRequired

          The amount to fund into the wallet, passed as a string. The example on this page sends the number 50.

        • CurrencyCodestringRequired

          Three-letter ISO 4217 currency code of the funding transaction, for example USD.

        • WalletIDstringRequired

          The WalletID of the wallet to fund, as a string, for example "122181". It takes only the wallet's numeric ID: a request with a wallet name is rejected with HTTP 400 and WalletID is Mandatory and must be an integer, and no money moves.

      • PayerInformationobjectRequired

        The cardholder's name.

        Child parameters2
        • FirstNamestringRequired

          The cardholder's legal first name, 2 to 40 characters.

        • LastNamestringRequired

          The cardholder's legal last name, 2 to 40 characters.

      • PayerBillingAddressobjectRequired

        The billing address of the credit card.

        Child parameters5
        • AddressLine1stringRequired

          The primary billing street address associated with the card.

        • CitystringRequired

          The billing city, 1 to 25 characters.

        • StatestringRequired

          The billing state, province, or region.

        • CountryISO2stringRequired

          Two-letter ISO 3166-1 alpha-2 country code of the billing address, for example US.

        • PostalCodestringRequired

          The ZIP or postal code of the billing address.

      • CreditCardDetailsobjectRequired

        The credit card to charge: its CardToken, or its details when you don't send a token.

        Child parameters6
        • CardTokenstringOptional

          The token of a card your company linked as an identity card, as LinkCard and GetLinkedCards return it: a 15-character string of digits and capital letters A to F, for example F2AA507CD01E4EC. When you send it, Xtrm charges that card and ignores the other CreditCardDetails fields. When you leave it out, Xtrm doesn't fall back to a default or previously linked card. It charges the card you describe in CreditCardNumber, CreditCardType, ExpireMonth, ExpireYear and CVV, which are required then, and links that card to your company. Because of that, funding with card details is refused with You can link maximum 3 Cards once three cards are linked to your account. A card that's already linked as an identity card must be sent by its token: sending its details returns Card already linked. We recommend linking the card once and sending its token.

        • ExpireMonthstringOptional

          Required when you don't send CardToken. The card expiration month as a numeric string from 1 to 12 (for example, "5").

        • ExpireYearstringOptional

          Required when you don't send CardToken. The card expiration year as a four-digit string (for example, "2031").

        • CreditCardNumberstringOptional

          Required when you don't send CardToken. The primary account number (PAN) of the card, 13 to 19 characters.

        • CreditCardTypestringOptional

          Required when you don't send CardToken. The card brand: Master Card, Visa Card or Amex Card, in any case. The example sends Master Card.

        • CVVstringOptional

          Required when you don't send CardToken. The 3- or 4-digit card verification value, as a string.

Response fields

  • FundCompanyWalletUsingCreditCardResponseobject

    Root wrapper for the response.

    Child parameters1
    • FundCompanyWalletUsingCreditCardResultobject

      The funding result.

      Child parameters6
      • Amountstring

        The amount charged to the card and credited to the wallet, as a string with two decimals, for example "50.00". Amounts of 1,000 or more include a thousands separator, for example "1,250.00", so strip separators before you parse them.

      • Currencystring

        Three-letter ISO 4217 currency code of the funded amount.

      • Feestring

        The card funding fee for this amount on your company's pricing, in USD, as a string with two decimals, for example "2.25".

      • OperationStatusobject

        The outcome of the call.

        Child parameters2
        • Errorsstring[]

          Validation or execution error details when the call fails. null when the call succeeds, so decide with Success.

        • Successboolean

          true if the operation succeeded, otherwise false.

      • TotalAmountstring

        Amount plus Fee, as a string with two decimals, for example "52.25". The card is charged Amount, not this total.

      • TransactionIDstring

        Unique identifier of this funding transaction. Use it to track the transaction.

Related: List a recipient's linked cards · Link a card to a recipient · List company wallets · Get the details of a company wallet transaction · Fund a wallet by bank transfer