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.
Fund the wallet before you submit a batch
Xtrm doesn't check the balance when you submit a batch. It debits each item, for its Amount plus its fee, when it processes the item, and an item the wallet can't cover fails with INSUFFICIENT_BALANCE. Funding takes time (see the timing for each method below), so we recommend funding the wallet well ahead of a batch payment and checking its balance before you submit. See How a batch is processed.
#Choose a funding method
All three methods add money to your company's own wallets:
| Bank transfer | Bank debit | Credit card | |
|---|---|---|---|
| Endpoint | FundWalletUsingBankTransfer | FundWalletUsingACHDebit | FundCompanyWalletUsingCreditCard |
| How the money moves | You send an ACH or wire to the Xtrm bank account returned in the response | Xtrm debits a bank account you linked for bank debit | Xtrm charges your company's own card |
| One-time setup | None | Link the bank, verify micro-deposits, wait for approval | Link the card with LinkCard as an identity card to get its CardToken |
| Timing | 2–7 business days to be credited, depending on your location | 3–5 business days to complete | As 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 |
| Currencies | Xtrm's receiving bank account varies by currency | USD, CAD, AUD, GBP and EUR (since release 4.91.6) | USD only |
| Good fit | Funding by ACH or wire from your own bank, with an optional emailed invoice | Repeat funding from one verified bank, started entirely through the API | Funding 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_TOKENenvironment variable. See Authentication. - Your company account number. It starts with
SPNand goes inIssuerAccountNumberon every call, including your batch payments. The samples useSPN1111222. 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 withLinkCardand setLinkCardTypetoidentity, nottransfer: only your company'sidentitycards can fund a wallet, andtransfercards are for receiving Rapid Transfer payments.LinkCardreturns theCardToken, andGetLinkedCardslists each card with its token andLinkCardType.
#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.
- List your company wallets
Call
GetCompanyWalletswith yourIssuerAccountNumber. Each entry inCompanyWalletDetailsshows the wallet's ID, name, currency, balance andWalletType.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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyWallets: { request: { IssuerAccountNumber: 'SPN1111222', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyWallets' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));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
WalletIDof the wallet you want to fund, for example122181: 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 inSourceWalletId(122181). Funding calls take only this numeric ID, never the wallet's name: a request with a name inWalletIDis rejected and no money moves.WalletBalanceis the balance you check before you submit a batch. The samples on this page fund122181. - 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:WalletNameis 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 byWalletID.WalletCurrencyis a three-letter ISO 4217 code such asUSD.WalletTypeis required. Set it toStandard, the only type to use when you create a wallet through the API.EntityIDis 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 withEntityID 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ CreateCompanyWallet: { request: { IssuerAccountNumber: 'SPN1111222', WalletName: 'USD Rewards Wallet', WalletCurrency: 'USD', WalletType: 'Standard', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "USD Rewards Wallet", "WalletCurrency": "USD", "WalletType": "Standard", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "USD Rewards Wallet", "WalletCurrency": "USD", "WalletType": "Standard" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "USD Rewards Wallet", "WalletCurrency": "USD", "WalletType": "Standard" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'CreateCompanyWallet' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'WalletName' => 'USD Rewards Wallet', 'WalletCurrency' => 'USD', 'WalletType' => 'Standard', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "CreateCompanyWalletResponse": { "CreateCompanyWalletResult": { "WalletID": 122183, "WalletName": "USD Rewards Wallet", "WalletCurrency": "USD", "OperationStatus": { "Success": true, "Errors": null } } } }Keep the new
WalletID(122183here). After you create a wallet you can only rename it; itsWalletIDand 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.
- Request Xtrm's bank instructions
Call
FundWalletUsingBankTransferwith the amount (a string such as"500"), the currency and theWalletIDto credit. The inner key is spelledRequest, with a capital R, but Xtrm matches field names without regard to case, so either spelling works.BeneficiaryAccountNumberis required: theSPNof the company whose wallet you fund.WalletIDmust be one of that company's wallets, inCurrencyCode. To fund your own wallet, send your ownSPN, the same one as inIssuerAccountNumber. Any other company must be connected to yours, or the call returns401. The samples fund your own wallet, so both fields holdSPN1111222.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 inCurrencyCode. Send the exact string"true", lowercase and in quotes: Xtrm reads a JSONtrueas"True", which passes the checks, including the minimum, but doesn't request the invoice.- Optional fields include
ProgramID, a memo inAdditionalinformtaion(spelled exactly like that; the corrected spelling is ignored), and the datesRequiredDepositDateandRequiredPaymentDate. 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingBankTransfer', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ FundWalletUsingBankTransfer: { Request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryAccountNumber: 'SPN1111222', Amount: '500', CurrencyCode: 'USD', WalletID: '122181', InvoiceRequired: 'true', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingBankTransfer", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "FundWalletUsingBankTransfer": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "Amount": "500", "CurrencyCode": "USD", "WalletID": "122181", "InvoiceRequired": "true", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "FundWalletUsingBankTransfer": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "Amount": "500", "CurrencyCode": "USD", "WalletID": "122181", "InvoiceRequired": "true" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingBankTransfer", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "FundWalletUsingBankTransfer": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "Amount": "500", "CurrencyCode": "USD", "WalletID": "122181", "InvoiceRequired": "true" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingBankTransfer")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingBankTransfer'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'FundWalletUsingBankTransfer' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryAccountNumber' => 'SPN1111222', 'Amount' => '500', 'CurrencyCode' => 'USD', 'WalletID' => '122181', 'InvoiceRequired' => 'true', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, 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
TransactionIDto track the funding, andBankInformation: 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.TotalAmountis the total amount Xtrm expects to receive, including any fees.The call creates a pending fund request in the wallet, and
StatusstaysPendinguntil the transaction is fully completed and cleared. Next, start an ACH or wire from your bank to the account inBankInformation. 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.
- Link the bank account
Call
LinkACHDebitBankBeneficiary. Put the account holder inBeneficiary.BeneficiaryDetails.BeneficiaryInformationand the bank account inBeneficiary.BankDetails.BeneficiaryBankInformation.UserIDis the Xtrm account the bank is linked to: your ownSPN, the same one as inIssuerAccountNumber(SPN1111222in the samples).FundWalletUsingACHDebitdebits only a bank linked to the company in itsIssuerAccountNumber, and refuses any other bank with<LinkedBankID> - Invalid Linked Bank ID. Send the same account asUserIDin the micro-deposit calls and asRecipientUserIdwhen you list bank-debit banks.CountryISO2appears twice: for the account holder's address and for the bank's location.ContactNametakes 1 to 100 characters and can't contain special characters such as<,>,@,#,$or%.PhoneNumbertakes 1 to 15 characters, counting any spaces or dashes, andCity1 to 100.Regionis the two-letter ISO2 code or the full state name.AccountTypemust beBUSINESSfor a bank-debit link, as in the sample, in any case. Any other value is refused withBeneficiaryBankInformation - AccountType must be with value 'BUSINESS'. Personal accounts not supported.RoutingNumberandSWIFTBICare required only when the bank's country and currency need them. Where they aren't required and you send an IBAN asAccountNumberwithout them, Xtrm takes them from the IBAN.- Leave out
RegulatoryFieldsunless 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" } } } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }, }, }, }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "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.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "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" } } } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "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" } } } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ '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', ], ], ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "LinkACHDebitBankBeneficiaryResponse": { "LinkACHDebitBankBeneficiaryResult": { "ACHDebitApprovalStatus": "Pending - Microdeposit verfication", "AccountIdentityLevel": "Advanced", "BankBeneficiaryStatus": "Pending", "BeneficiaryId": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10", "OperationStatus": { "Errors": null, "Success": true } } } }Keep
BeneficiaryId(12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10here). It's the only ID the response returns, and every later bank-debit call takes it: asBeneficiaryBankIDin the micro-deposit calls and asLinkedBankIDwhen you fund. The link starts withACHDebitApprovalStatusset toPending - Microdeposit verfication(spelled that way) for a bank that Xtrm verifies with micro-deposits, as in this example, orPendingfor 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, withLinkACHDebitBankBeneficiaryResponse.LinkACHDebitBankBeneficiaryResult.OperationStatus.Successset tofalseand each field to add or fix inErrors. Send the whole request again with those fields filled in, and repeat until the response returns aBeneficiaryId. See What can go wrong and Errors. - Send the micro-deposits
Micro-deposits apply only to a bank whose link returned
ACHDebitApprovalStatusPending - Microdeposit verfication. For any other bank, skip this step and the next, and check that the bank is approved.Call
ReleaseACHDebitMicrodepositwith the linked bank's ID asBeneficiaryBankID. 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 returnsMicrodeposits 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/ReleaseACHDebitMicrodeposit', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ ReleaseACHDebitMicrodeposit: { Request: { IssuerAccountNumber: 'SPN1111222', UserID: 'SPN1111222', BeneficiaryBankID: '12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Bank/ReleaseACHDebitMicrodeposit", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "ReleaseACHDebitMicrodeposit": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN1111222", "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "ReleaseACHDebitMicrodeposit": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN1111222", "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/ReleaseACHDebitMicrodeposit", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "ReleaseACHDebitMicrodeposit": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN1111222", "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/ReleaseACHDebitMicrodeposit")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Bank/ReleaseACHDebitMicrodeposit'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'ReleaseACHDebitMicrodeposit' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'SPN1111222', 'BeneficiaryBankID' => '12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));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:
Messageconfirms the deposits and shows the last four digits of the bank account number. - Verify the deposit amounts
Once the micro-deposits show up on the bank statement, call
VerifyACHDebitMicrodepositwith the sameBeneficiaryBankIDand the two amounts that appeared, asAmount_1andAmount_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:MessagereadsWe have verified your bank successfully.and the bank'sACHDebitApprovalStatusturnsApproved.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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/VerifyACHDebitMicrodeposit', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ VerifyACHDebitMicrodeposit: { Request: { IssuerAccountNumber: 'SPN1111222', UserID: 'SPN1111222', BeneficiaryBankID: '12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10', Amount_1: '0.04', Amount_2: '0.07', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Bank/VerifyACHDebitMicrodeposit", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "VerifyACHDebitMicrodeposit": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN1111222", "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10", "Amount_1": "0.04", "Amount_2": "0.07", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "VerifyACHDebitMicrodeposit": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN1111222", "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10", "Amount_1": "0.04", "Amount_2": "0.07" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/VerifyACHDebitMicrodeposit", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "VerifyACHDebitMicrodeposit": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN1111222", "BeneficiaryBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10", "Amount_1": "0.04", "Amount_2": "0.07" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/VerifyACHDebitMicrodeposit")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Bank/VerifyACHDebitMicrodeposit'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'VerifyACHDebitMicrodeposit' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'SPN1111222', 'BeneficiaryBankID' => '12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10', 'Amount_1' => '0.04', 'Amount_2' => '0.07', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "VerifyACHDebitMicrodepositResponse": { "VerifyACHDebitMicrodepositResult": { "Message": "We have verified your bank successfully.", "OperationStatus": { "Errors": null, "Success": true } } } } - Check that the bank is approved
Call
GetACHDebitLinkedBankAccounts. This call names the account fieldRecipientUserIdrather thanUserID. Each bank inBeneficiaryDetailshas aBeneficiaryId, and itsBankDetails.BeneficiaryBankInformation.ACHDebitApprovalStatussays whether it's approved for bank debit. It readsApprovedonce you can fund from the bank. Until then it readsPending,Pending VerificationorPending Approval; a bank whose status isIncompleteorDeactivecan't be debited. The bank'sBankBeneficiaryStatusisApprovedorPending. 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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/GetACHDebitLinkedBankAccounts', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetACHDebitLinkedBankAccounts: { request: { IssuerAccountNumber: 'SPN1111222', RecipientUserId: 'SPN1111222', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Bank/GetACHDebitLinkedBankAccounts", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetACHDebitLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "SPN1111222", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetACHDebitLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "SPN1111222" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/GetACHDebitLinkedBankAccounts", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetACHDebitLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "SPN1111222" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/GetACHDebitLinkedBankAccounts")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Bank/GetACHDebitLinkedBankAccounts'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetACHDebitLinkedBankAccounts' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'RecipientUserId' => 'SPN1111222', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));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
BeneficiaryIdthat the link returned (12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10here) and check itsACHDebitApprovalStatus. Here it'sApproved, 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. - Fund the wallet
Call
FundWalletUsingACHDebitwith the amount, the currency, theWalletIDto credit and the approved bank inLinkedBankID: the sameBeneficiaryId(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 isFundWalletUsingACHDebitRequestand the inner key isRequest. Release 4.91.6 added bank debit funding inUSD,CAD,AUD,GBPandEUR.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" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingACHDebit', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ FundWalletUsingACHDebitRequest: { Request: { IssuerAccountNumber: 'SPN1111222', Amount: '50', CurrencyCode: 'USD', WalletID: '122181', LinkedBankID: '12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingACHDebit", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "FundWalletUsingACHDebitRequest": { "Request": { "IssuerAccountNumber": "SPN1111222", "Amount": "50", "CurrencyCode": "USD", "WalletID": "122181", "LinkedBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "FundWalletUsingACHDebitRequest": { "Request": { "IssuerAccountNumber": "SPN1111222", "Amount": "50", "CurrencyCode": "USD", "WalletID": "122181", "LinkedBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingACHDebit", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "FundWalletUsingACHDebitRequest": { "Request": { "IssuerAccountNumber": "SPN1111222", "Amount": "50", "CurrencyCode": "USD", "WalletID": "122181", "LinkedBankID": "12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingACHDebit")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/FundWalletUsingACHDebit'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'FundWalletUsingACHDebitRequest' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'Amount' => '50', 'CurrencyCode' => 'USD', 'WalletID' => '122181', 'LinkedBankID' => '12e6f8ac5d3b4c2a9e1f7b6d8c4a2e10', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));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
TransactionIDto track the funding.TotalAmountis the total debited from the bank, the amount plus the fee.Statusdescribes 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.
- Charge your company card
Call
FundCompanyWalletUsingCreditCard. The root key isFundCompanyWalletUsingCreditCardRequest, and the fields sit in four groups:PaymentDetails:IssuerAccountNumber,Amount(a string such as"50"),CurrencyCodeand theWalletIDto credit.PayerInformation: the cardholder's legalFirstNameandLastName, 2–40 characters each.PayerBillingAddress: the card's billing address, with aCityof 1–25 characters.CreditCardDetails: the card'sCardToken.
CardTokenidentifies the linked card. It's a 15-character string of digits and capital letters A to F, such asF2AA507CD01E4EC, so store it as a string, exactly asLinkCardorGetLinkedCardsreturns it. When you send it, Xtrm charges that card and ignores the otherCreditCardDetailsfields, so the sample sends only the token. LeaveCardTokenout and Xtrm charges the card inCreditCardNumber,CVV,CreditCardType,ExpireMonth("1"to"12") and four-digitExpireYearinstead, 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 itsCardToken, which must belong to one of your company'sidentitycards. Card funding is inUSDonly.Important
Never use real card data in the sandbox. Use a standard test number instead: Visa
4111111111111111or Mastercard5555555555554444, with a future expiry date and a three-digit CVV. In production, we recommend that you never log or store the card number or CVV in your own systems.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" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/FundCompanyWalletUsingCreditCard', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }, }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/FundCompanyWalletUsingCreditCard", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "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.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "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" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/FundCompanyWalletUsingCreditCard", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "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" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/FundCompanyWalletUsingCreditCard")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/FundCompanyWalletUsingCreditCard'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ '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', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "FundCompanyWalletUsingCreditCardResponse": { "FundCompanyWalletUsingCreditCardResult": { "Amount": "50.00", "Currency": "USD", "Fee": "2.25", "OperationStatus": { "Errors": null, "Success": true }, "TotalAmount": "52.25", "TransactionID": "888333" } } }Keep
TransactionIDto track the funding. Xtrm charges your card theAmountyou send and credits that fullAmountto the wallet.Feeis the card funding fee for this amount on your company's pricing, andTotalAmountisAmountplusFee. The card is chargedAmount, notTotalAmount. 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.
- In the web app, open your company's wallets and choose Move on the wallet you're moving money from.
- 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.
- 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'sAmountplus 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 untilWalletBalanceshows 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
Pendinguntil Xtrm approves it. We recommend waiting untilWalletBalanceshows the funds before you submit a batch that depends on them. - A bank transfer with an invoice is refused. With
InvoiceRequiredset to"true", the amount must be at least 500 USD, or the equivalent inCurrencyCode, or the call returns400withMinimum bank transfer amount is …. A value that isn't true or false, such as"yes", returnsInvoiceRequired must be true/false. - Linking a bank returns HTTP 400 with
Success: false. The bank needs more information; requirements vary by country and currency.Errorslists each field to add or fix with anErrorMessage, itsFieldName, the parameter to send, aFieldLabelyou can show in your interface, andIsRegulatoryField, which istruewhen the value goes inRegulatoryFieldsas aKey/Valuepair, with theFieldNameas theKey. Send the wholeLinkACHDebitBankBeneficiaryrequest again with those fields, and repeat until it returns aBeneficiaryId. Other failures, such as a bank that's already linked, return messages as strings inErrors. 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
ACHDebitApprovalStatusbefore you callFundWalletUsingACHDebit. <LinkedBankID> - Invalid Linked Bank ID. The bank isn't linked for bank debit to the company inIssuerAccountNumber, or it was removed. Fund only from a bank you linked to your ownSPN, by theBeneficiaryIdthatGetACHDebitLinkedBankAccountslists 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,
LinkACHDebitBankBeneficiaryrefuses a new bank-debit link withYou can link maximum N banks. - The micro-deposit amounts don't match.
VerifyACHDebitMicrodepositreturnsInvalid amount.or the bank provider's message, and each amount must be greater than0. Check the two amounts on the bank statement and try again. If the amounts are refused too many times, remove the bank withDeleteBankBeneficiary, then link it again. - The card can't fund the wallet. Only cards linked as
identitycards can fund a wallet;transfercards are for receiving funds. - Funding with card details is refused. A request without
CardTokenlinks the card it describes to your company. So it returnsYou can link maximum 3 Cardsonce three cards are linked to your account, andCard already linked.for a card that's already linked as anidentitycard. Fund with theCardTokenof one of your linkedidentitycards 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
GetCompanyWalletTransactionsfor the original request. A batch payment is different: you can resend it safely with the same IDs (see A safe retry pattern).
#Next steps
Pay many recipients from the wallet you just funded, in one request.
How batch payments workThe batch lifecycle, wallet-first delivery and how the source wallet sets the batch's currency.
Batch and payment statusesFollow each item to a final status and spot failures such as INSUFFICIENT_BALANCE.
Read wallet transactions and match them to your own records.
Exchange currencyMove an existing balance into a wallet in another currency.
Funding referenceEvery field of the three funding calls, with full examples.