Bank accounts & transfers
This guide pays a recipient's bank account in a batch. You find and check Jane Doe's bank, link it to her account, read back the ID of the bank you linked, and pay that same bank with a batch item that uses the Bank Transfer send method (XTR94500). The same batch pays a business recipient's bank by its ID. The guide also covers what happens when a bank payment doesn't complete, how money gets from a recipient's wallet to their bank, and how to remove a bank.
#How money reaches a bank
A batch payment is wallet-first. For each bank item, Xtrm credits the recipient's wallet in the batch's currency, then debits the payment from that wallet and sends it to the bank. When the bank account's currency differs from the batch's, the amount is converted when it's transferred to the bank. While Xtrm pays the money on to the bank, the item shows RetainedInWallet, usually only briefly, and it moves on to Success when the bank payment goes through. So don't act on RetainedInWallet while the batch is still Processing. If the item is still RetainedInWallet once the batch status is final, the bank payment didn't go through: the money has left your wallet and stays in the recipient's Xtrm wallet, and Xtrm doesn't credit your source wallet back or refund the fee. Treat it like a wallet payment; see When a bank payment doesn't complete.
For how Xtrm processes a batch, see How batch payments work. For every send method and option, see Create a batch payment.
| You want to | Use | Money comes from |
|---|---|---|
| Pay a recipient's bank | A BatchTransfer item with SendMethodId XTR94500 | Your company wallet (SourceWalletId) |
| Transfer money from an individual recipient's wallet to their bank, on their behalf | UserWithdrawFund, confirmed with the recipient's one-time password | The individual recipient's Xtrm wallet |
| Transfer money from a business recipient's wallet to its bank, on its behalf | BeneficiaryCompanyWithdrawFund, confirmed with the recipient's one-time password | The business recipient's own wallet |
#Before you begin
- Credentials and a token. Sandbox credentials in
XTRM_CLIENT_IDandXTRM_CLIENT_SECRET(see Sandbox & environments) and an access token inXTRM_ACCESS_TOKEN(see Authentication). - Your company's account number (
SPN…), sent asIssuerAccountNumber. The samples useSPN1111222. - A funded source wallet.
GetCompanyWalletslists your wallets with their IDs, currencies and balances. The wallet you pay from sets the currency of the batch. The samples use yourUSDwallet122181. To add money, see Fund your wallet. - The recipients' account numbers. The samples pay Jane Doe, an individual recipient (
PAT9999888), and a business recipient (SPN8888777). A batch pays existing Xtrm accounts only, so create each recipient before you link its bank and pay it: withCreateUserfor a person orCreateBeneficiaryfor a business. See Pay individual recipients or Pay business recipients. - The bank details the recipient gives you: the account holder's name, phone number and address, and the bank's name, account number, currency and country, plus its routing number and SWIFT-BIC where the bank needs them.
- A connection to each recipient whose bank you link or read back.
LinkBankBeneficiary,GetLinkedBankAccountsand transfers out of a recipient's wallet all need the recipient's account to be connected to your company. A recipient you created withCreateUserorCreateBeneficiaryis already connected; for an existing account, see Connections and manager services. Your company created every recipient in the samples, so they're all connected. The batch itself doesn't need a connection, but the bank you pay must be linked to the recipient.
Each sample uses literal values so it runs on its own. In your integration, carry the IDs forward from step to step.
#Pay a bank in a batch
Steps 1 to 3 are alternatives: run the one that matches the identifier the recipient gave you. For a bank in an IBAN country, we recommend validating the IBAN before you link the bank, to prevent failed payments and routing errors.
- Look up a US bank by routing number
SearchBankByNationalIDsearches a country's banks by national routing code, such as a US routing number or a sort code. Note the capitalRin theRequestwrapper, which both search endpoints use. Paging fields are strings:RecordsToTakeis the page size, andRecordsToSkipis the page number,"1"for the first page,"2"for the second, and so on.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByNationalID" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "SearchBankByNationalID": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "NationalID": "021000021", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByNationalID', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ SearchBankByNationalID: { Request: { IssuerAccountNumber: 'SPN1111222', BankCountryISO2: 'US', NationalID: '021000021', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, }, }, }), }); 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/SearchBankByNationalID", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "SearchBankByNationalID": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "NationalID": "021000021", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, }, }, }, ) 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 = """ { "SearchBankByNationalID": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "NationalID": "021000021", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByNationalID", 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 = """ { "SearchBankByNationalID": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "NationalID": "021000021", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByNationalID")) .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/SearchBankByNationalID'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'SearchBankByNationalID' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BankCountryISO2' => 'US', 'NationalID' => '021000021', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));One routing number can return several branches. Abridged to two results:
Response (excerpt){ "SearchBankByNationalIDResponse": { "SearchBankByNationalIDResult": { "Banks": [ { "NationalIdentifier": "021000021", "NationalIdType": "USBC", "BankDetails": { "InstitutionName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION", "BranchInformation": null, "AddressLine1": "225 HAVEMEYER ST", "AddressLine2": "", "City": "BROOKLYN", "CountryISO2": "US", "CountryName": "UNITED STATES", "PostalCode": "11211", "BranchName": "HAVEMEYER AND BROADWAY", "Region": "NEW YORK" } }, { "NationalIdentifier": "021000021", "NationalIdType": "USBC", "BankDetails": { "InstitutionName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION", "BranchInformation": null, "AddressLine1": "560 MISSION ST", "AddressLine2": "", "City": "SAN FRANCISCO", "CountryISO2": "US", "CountryName": "UNITED STATES", "PostalCode": "94105", "BranchName": "SAN FRANCISCO MAIN", "Region": "CALIFORNIA" } } ], "OperationStatus": { "Errors": null, "Success": true } } } }Keep:
BankDetails.InstitutionName, to confirm the bank with Jane Doe.PaginationTotal.RecordsTotal(left out above) gives the total number of matches. - Or look up a bank by SWIFT-BIC
SearchBankByBICdoes the same for a SWIFT-BIC code and pages the same way. Each result is a flat record that includes the branch'sNationalIdrouting number. The response wrapper is spelledSearchBankbyBICResponse, with a lowercaseby.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByBIC" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "SearchBankByBIC": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "SWIFTBIC": "CHASUS33", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByBIC', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ SearchBankByBIC: { Request: { IssuerAccountNumber: 'SPN1111222', BankCountryISO2: 'US', SWIFTBIC: 'CHASUS33', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, }, }, }), }); 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/SearchBankByBIC", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "SearchBankByBIC": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "SWIFTBIC": "CHASUS33", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, }, }, }, ) 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 = """ { "SearchBankByBIC": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "SWIFTBIC": "CHASUS33", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByBIC", 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 = """ { "SearchBankByBIC": { "Request": { "IssuerAccountNumber": "SPN1111222", "BankCountryISO2": "US", "SWIFTBIC": "CHASUS33", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/SearchBankByBIC")) .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/SearchBankByBIC'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'SearchBankByBIC' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BankCountryISO2' => 'US', 'SWIFTBIC' => 'CHASUS33', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));This example matches 4,227 branches. Abridged to one:
Response (excerpt){ "SearchBankbyBICResponse": { "SearchBankbyBICResult": { "Banks": [ { "InstitutionName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION", "BIC": null, "Region": "NEW YORK", "NationalId": "021000021", "BranchName": "HAVEMEYER AND BROADWAY", "BranchCode": null, "AddressLine1": "225 HAVEMEYER ST", "AddressLine2": "", "City": "BROOKLYN", "CountryName": "UNITED STATES", "CountryCode": "US", "PostalCode": "11211" } ], "OperationStatus": { "Errors": null, "Success": true } } } }Keep:
InstitutionNameandNationalId, to confirm against the details the recipient gave you. - Or validate an IBAN
ValidateIBANchecks that an IBAN is structurally and mathematically valid for the country inBankCountryISO2. When the BIC can be derived, it also returnsSWIFTBIC.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/ValidateIBAN" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ValidateIBAN": { "request": { "IssuerAccountNumber": "SPN1111222", "IBAN": "GB33BUKB20201555555555", "BankCountryISO2": "GB" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/ValidateIBAN', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ ValidateIBAN: { request: { IssuerAccountNumber: 'SPN1111222', IBAN: 'GB33BUKB20201555555555', BankCountryISO2: 'GB', }, }, }), }); 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/ValidateIBAN", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "ValidateIBAN": { "request": { "IssuerAccountNumber": "SPN1111222", "IBAN": "GB33BUKB20201555555555", "BankCountryISO2": "GB", }, }, }, ) 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 = """ { "ValidateIBAN": { "request": { "IssuerAccountNumber": "SPN1111222", "IBAN": "GB33BUKB20201555555555", "BankCountryISO2": "GB" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/ValidateIBAN", 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 = """ { "ValidateIBAN": { "request": { "IssuerAccountNumber": "SPN1111222", "IBAN": "GB33BUKB20201555555555", "BankCountryISO2": "GB" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/ValidateIBAN")) .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/ValidateIBAN'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'ValidateIBAN' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'IBAN' => 'GB33BUKB20201555555555', 'BankCountryISO2' => 'GB', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "ValidateIBANResponse": { "ValidateIBANResult": { "IsValid": true, "SWIFTBIC": "BUKBGB22XXX", "OperationStatus": { "Errors": null, "Success": true } } } }Keep:
IsValid, andSWIFTBICfor the link request.Success isn't validity
Success: trueonly means the call ran without server errors. CheckIsValidto know whether the IBAN is valid. - Check the transfer types for the country
GetBankWithdrawTypeslists the bank transfer types available in a country, such as wire and ACH. Country codes come fromGetCountry.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/GetBankWithdrawTypes" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetBankWithdrawTypes": { "request": { "IssuerAccountNumber": "SPN1111222", "CountryISO2": "US" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/GetBankWithdrawTypes', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetBankWithdrawTypes: { request: { IssuerAccountNumber: 'SPN1111222', 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/GetBankWithdrawTypes", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetBankWithdrawTypes": { "request": { "IssuerAccountNumber": "SPN1111222", "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 = """ { "GetBankWithdrawTypes": { "request": { "IssuerAccountNumber": "SPN1111222", "CountryISO2": "US" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/GetBankWithdrawTypes", 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 = """ { "GetBankWithdrawTypes": { "request": { "IssuerAccountNumber": "SPN1111222", "CountryISO2": "US" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/GetBankWithdrawTypes")) .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/GetBankWithdrawTypes'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetBankWithdrawTypes' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', '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{ "GetBankWithdrawTypesResponse": { "GetBankWithdrawTypesResult": { "OperationStatus": { "Errors": null, "Success": true }, "WithdrawTypes": [ "WIRE", "ACH" ] } } }Keep:
WithdrawTypes. The next step's example sends one of them,ACH, asWithdrawType. - Link the bank account
LinkBankBeneficiarylinks the bank to the recipient inUserID, aPATorSPNaccount number. A bank has to be linked to a recipient before a batch payment can pay it by ID. The recipient must be connected to your company, or be your own company: any otherUserIDgets400withNot authorized to access this resource. Make One Time Password API Call to access this resource. The sample links Jane Doe's Chase account to her account,PAT9999888. The body has two parts, each with its ownCountryISO2:BeneficiaryInformation: the account holder and their address.ContactNameis 1 to 100 characters and can't contain special characters such as<,>,@,#,$or%.PhoneNumberis 1 to 15 characters, counting any spaces or dashes; leave out a leading+, because a number that starts with+is refused withPlease remove country codes from mobile numbers.Cityis 1 to 100 characters.Regionis the two-letter ISO code or the full state name.BeneficiaryBankInformation: the bank account, with the bank's country.WithdrawTypesets how the money moves to the bank:ACH,WIRE,LV(the same asACH) orHV(the same asWIRE), in any case. Without it, Xtrm usesWIREwhen the account's currency isn't the country's own, otherwiseACHwhere the country supports it, otherwiseWIRE. A US bank for a US account holder inUSDalways usesACH. Optionally setAccountTypetoBUSINESS,SAVINGSorCHECKING.
This example links a US bank, with the routing number from step 1. In the sandbox, use a real bank's routing number like this one with a made-up account number in the right format, never a real account. For a bank in an IBAN country, send the IBAN as
AccountNumber: Xtrm checks it and finds the bank from it.RoutingNumberandSWIFTBICare required only where the bank's country, currency and transfer type call for them. Where they aren't required and you leave them out, Xtrm takes them from the IBAN. If the bank needs more information, the response names the fields to send, and you send the request again (see the callout below).curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/LinkBankBeneficiary" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "LinkBankBeneficiary": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Jane Doe", "PhoneNumber": "3105550142", "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US" } }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "JPMorgan Chase Bank", "Currency": "USD", "SWIFTBIC": "CHASUS33", "AccountNumber": "000123458910", "RoutingNumber": "021000021", "CountryISO2": "US", "WithdrawType": "ACH" } } } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/LinkBankBeneficiary', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ LinkBankBeneficiary: { request: { IssuerAccountNumber: 'SPN1111222', UserID: 'PAT9999888', Beneficiary: { BeneficiaryDetails: { BeneficiaryInformation: { ContactName: 'Jane Doe', PhoneNumber: '3105550142', AddressLine1: '123 Main Street', City: 'Los Angeles', Region: 'CA', PostalCode: '90001', CountryISO2: 'US', }, }, BankDetails: { BeneficiaryBankInformation: { InstitutionName: 'JPMorgan Chase Bank', Currency: 'USD', SWIFTBIC: 'CHASUS33', AccountNumber: '000123458910', RoutingNumber: '021000021', CountryISO2: 'US', WithdrawType: 'ACH', }, }, }, }, }, }), }); 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/LinkBankBeneficiary", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "LinkBankBeneficiary": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Jane Doe", "PhoneNumber": "3105550142", "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US", }, }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "JPMorgan Chase Bank", "Currency": "USD", "SWIFTBIC": "CHASUS33", "AccountNumber": "000123458910", "RoutingNumber": "021000021", "CountryISO2": "US", "WithdrawType": "ACH", }, }, }, }, }, }, ) response.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 = """ { "LinkBankBeneficiary": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Jane Doe", "PhoneNumber": "3105550142", "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US" } }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "JPMorgan Chase Bank", "Currency": "USD", "SWIFTBIC": "CHASUS33", "AccountNumber": "000123458910", "RoutingNumber": "021000021", "CountryISO2": "US", "WithdrawType": "ACH" } } } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/LinkBankBeneficiary", 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 = """ { "LinkBankBeneficiary": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Jane Doe", "PhoneNumber": "3105550142", "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US" } }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "JPMorgan Chase Bank", "Currency": "USD", "SWIFTBIC": "CHASUS33", "AccountNumber": "000123458910", "RoutingNumber": "021000021", "CountryISO2": "US", "WithdrawType": "ACH" } } } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/LinkBankBeneficiary")) .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/LinkBankBeneficiary'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'LinkBankBeneficiary' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT9999888', 'Beneficiary' => [ 'BeneficiaryDetails' => [ 'BeneficiaryInformation' => [ 'ContactName' => 'Jane Doe', 'PhoneNumber' => '3105550142', 'AddressLine1' => '123 Main Street', 'City' => 'Los Angeles', 'Region' => 'CA', 'PostalCode' => '90001', 'CountryISO2' => 'US', ], ], 'BankDetails' => [ 'BeneficiaryBankInformation' => [ 'InstitutionName' => 'JPMorgan Chase Bank', 'Currency' => 'USD', 'SWIFTBIC' => 'CHASUS33', 'AccountNumber' => '000123458910', 'RoutingNumber' => '021000021', 'CountryISO2' => 'US', 'WithdrawType' => 'ACH', ], ], ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "LinkBankBeneficiaryResponse": { "LinkBankBeneficiaryResult": { "BeneficiaryId": "907599f594b044d08cf81a2afb0a7967", "BankBeneficiaryStatus": "Approved", "AccountIdentityLevel": "Basic", "ACHDebitApprovalStatus": null, "OperationStatus": { "Errors": null, "Success": true } } } }Keep:
BeneficiaryId, the ID of the linked bank profile (907599f594b044d08cf81a2afb0a7967here), andBankBeneficiaryStatus. An individual recipient can have up to 3 linked banks, and a company account more, up to a limit Xtrm sets.Linking can take more than one request
Xtrm checks every link request against what the bank's country and currency need for this type of recipient, individual or business. When a field is missing or in the wrong format, nothing is linked: the response is HTTP
400withOperationStatus.Successset tofalse, andErrorslists each field to add or fix. Send the whole request again with those fields filled in, and repeat until the response returns aBeneficiaryId. A resend can ask for more fields.For example, a request that leaves out a routing number the bank needs gets this response:
Response when the bank needs more information (example){ "LinkBankBeneficiaryResponse": { "LinkBankBeneficiaryResult": { "BeneficiaryId": null, "BankBeneficiaryStatus": null, "AccountIdentityLevel": null, "ACHDebitApprovalStatus": null, "OperationStatus": { "Errors": [ { "ErrorMessage": "Bank routing code is required.", "FieldName": "RoutingNumber", "FieldLabel": "Routing Number", "IsRegulatoryField": false, "valueset": null } ], "Success": false } } } }Each entry in
Errorsnames one field:ErrorMessage: what's missing or wrong.FieldName: the parameter to send, such asRoutingNumber.FieldLabel: a readable label you can show in your interface.IsRegulatoryField:truewhen the value goes inBeneficiaryBankInformation.RegulatoryFields, as aKey/Valuepair with theFieldNameas theKey.valueset: for a missing regulatory field, the values it accepts, each with anidand atext. Otherwise it'snull.
Leave out
RegulatoryFieldsuntil a response asks for one: sending it for a bank that needs none fails withRegulatory field values are not required for this request.Other failures, such as an invalid IBAN or a bank that's already linked, return messages as strings inErrors. See Errors on a failed call. - Read back the bank's ID and payment methods
GetLinkedBankAccountslists the banks linked toRecipientUserId. Each entry gives you the two values a bank payment uses:BeneficiaryId, the bank's ID. You send it asDestination.BeneficiaryBankIDin a batch item, and asUserLinkedBankIDorBeneficiaryLinkedBankIDin a recipient transfer.BankDetails.BeneficiaryBankInformation.PaymentMethods, the payment methods available for the bank account, such asACH.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/GetLinkedBankAccounts" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT9999888" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/GetLinkedBankAccounts', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetLinkedBankAccounts: { request: { IssuerAccountNumber: 'SPN1111222', RecipientUserId: 'PAT9999888', }, }, }), }); 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/GetLinkedBankAccounts", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT9999888", }, }, }, ) 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 = """ { "GetLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT9999888" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Bank/GetLinkedBankAccounts", 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 = """ { "GetLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT9999888" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/GetLinkedBankAccounts")) .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/GetLinkedBankAccounts'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetLinkedBankAccounts' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'RecipientUserId' => 'PAT9999888', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetLinkedBankAccountsResponse": { "GetLinkedBankAccountsResult": { "Beneficiary": { "BeneficiaryDetails": [ { "BeneficiaryId": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryName": "Jane Doe", "Currency": "USD", "Country": "United States of America", "TransferFee": 0, "PaymentMethods": { "Payment": "ACH" }, "BankDetails": { "BeneficiaryBankInformation": { "AccountNumber": "XXXX8910", "BankName": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION", "BranchName": "San Francisco Main", "BankBeneficiaryStatus": "Approved", "ACHDebitApprovalStatus": null, "BankRoutingCode": "021000021", "EntityID": 0, "PaymentMethods": [ "ACH" ] } } } ] }, "OperationStatus": { "Success": true, "Errors": null } } } }Keep:
BeneficiaryIdand thePaymentMethodsarray insideBankDetails. TheBeneficiaryIdis907599f594b044d08cf81a2afb0a7967, the same ID the link returned, so this is the bank you just linked. If the list holds more than one bank, pick yours by that ID. The next step pays this bank.Two things to watch
The response has no field named
BeneficiaryBankID:BeneficiaryIdis the only ID it returns for each bank. Take payment methods from the array insideBankDetails, not from thePaymentMethodsobject on the entry. - Pay the bank in a batch
BatchTransferpays every item in one request from the wallet inSourceWalletId. For a bank payment, set the item'sSendMethodIdtoXTR94500(Bank Transfer) and put the bank'sBeneficiaryIdinDestination.BeneficiaryBankID. During processing, before any money moves, it must be a pending or approved bank linked to the recipient's account, or the item fails withBANKID_INVALID. Optionally, setBeneficiaryBankPaymentMethodto one of the rails in the bank'sPaymentMethodsarray, such asACH. Bank transfer: XTR94500 lists everyDestinationfield, includingWalletIdand how a business wallet's linked bank can replace the bank you send.This batch has two bank items, and each names its bank by ID:
TXN-BANK-0001pays Jane Doe's Chase account,907599f594b044d08cf81a2afb0a7967, the bank you linked and read back in the previous steps, overACH.TXN-BANK-0002pays the business recipientSPN8888777at its own bank,41953ec32f3e4765a35a902c82bdd995. You read that ID back withGetLinkedBankAccountsthe same way, withSPN8888777inRecipientUserId, which needs the business to be connected to your company. The item sends noWalletId, so Xtrm pays exactly this bank.
The body has no wrapper object.
SourceWalletIdis an integer andAmounta JSON number. The batch uses this guide's own IDs:BATCH-BANK-0001, with itemsTXN-BANK-0001andTXN-BANK-0002.CustomerBatchIdvalues are shared across all Xtrm accounts, so replace them with your own unique values before you run this in the sandbox; see Batch and payment identifiers. One batch can also mix bank items with other send methods; see Create a batch payment.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "IssuerAccountNumber": "SPN1111222", "SourceWalletId": 122181, "CustomerBatchId": "BATCH-BANK-0001", "Items": [ { "CustomerTransactionId": "TXN-BANK-0001", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH" } }, { "CustomerTransactionId": "TXN-BANK-0002", "RecipientId": "SPN8888777", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995" } } ] }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ IssuerAccountNumber: 'SPN1111222', SourceWalletId: 122181, CustomerBatchId: 'BATCH-BANK-0001', Items: [ { CustomerTransactionId: 'TXN-BANK-0001', RecipientId: 'PAT9999888', Amount: 100, SendMethodId: 'XTR94500', Destination: { BeneficiaryBankID: '907599f594b044d08cf81a2afb0a7967', BeneficiaryBankPaymentMethod: 'ACH', }, }, { CustomerTransactionId: 'TXN-BANK-0002', RecipientId: 'SPN8888777', Amount: 100, SendMethodId: 'XTR94500', Destination: { BeneficiaryBankID: '41953ec32f3e4765a35a902c82bdd995', }, }, ], }), }); 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/Fund/BatchTransfer", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "IssuerAccountNumber": "SPN1111222", "SourceWalletId": 122181, "CustomerBatchId": "BATCH-BANK-0001", "Items": [ { "CustomerTransactionId": "TXN-BANK-0001", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH", }, }, { "CustomerTransactionId": "TXN-BANK-0002", "RecipientId": "SPN8888777", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995", }, }, ], }, ) 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 = """ { "IssuerAccountNumber": "SPN1111222", "SourceWalletId": 122181, "CustomerBatchId": "BATCH-BANK-0001", "Items": [ { "CustomerTransactionId": "TXN-BANK-0001", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH" } }, { "CustomerTransactionId": "TXN-BANK-0002", "RecipientId": "SPN8888777", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995" } } ] } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer", 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 = """ { "IssuerAccountNumber": "SPN1111222", "SourceWalletId": 122181, "CustomerBatchId": "BATCH-BANK-0001", "Items": [ { "CustomerTransactionId": "TXN-BANK-0001", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH" } }, { "CustomerTransactionId": "TXN-BANK-0002", "RecipientId": "SPN8888777", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995" } } ] } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer")) .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/Fund/BatchTransfer'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'IssuerAccountNumber' => 'SPN1111222', 'SourceWalletId' => 122181, 'CustomerBatchId' => 'BATCH-BANK-0001', 'Items' => [ [ 'CustomerTransactionId' => 'TXN-BANK-0001', 'RecipientId' => 'PAT9999888', 'Amount' => 100, 'SendMethodId' => 'XTR94500', 'Destination' => [ 'BeneficiaryBankID' => '907599f594b044d08cf81a2afb0a7967', 'BeneficiaryBankPaymentMethod' => 'ACH', ], ], [ 'CustomerTransactionId' => 'TXN-BANK-0002', 'RecipientId' => 'SPN8888777', 'Amount' => 100, 'SendMethodId' => 'XTR94500', 'Destination' => [ 'BeneficiaryBankID' => '41953ec32f3e4765a35a902c82bdd995', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Xtrm validates each item and responds right away with
202 Accepted; the payments are processed in the background. The response lists each accepted item, not necessarily in request order, with itsAmountechoed as a JSON number with the decimals you sent, so100comes back as100.0; the excerpt leaves out theItemsCounttotals:Response (excerpt){ "BatchTransferResponse": { "CustomerBatchId": "BATCH-BANK-0001", "Status": "Accepted", "Accepted": [ { "CustomerTransactionId": "TXN-BANK-0002", "Amount": 100.0, "Currency": "USD", "SendMethodId": "XTR94500", "RecipientId": "SPN8888777" }, { "CustomerTransactionId": "TXN-BANK-0001", "Amount": 100.0, "Currency": "USD", "SendMethodId": "XTR94500", "RecipientId": "PAT9999888" } ], "Rejected": [] } }Keep:
CustomerBatchIdand theCustomerTransactionIdof each bank item. A202means the batch was received and validated, not that any bank has been paid yet. If items come back inRejected, see Paying the bank. - Check the bank item's outcome
GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}returns one item'sStatusand itsDeliveryType:Bankonce a bank item isSuccess,Walletwhen it'sRetainedInWallet, and an empty string while it'sAccepted,ProcessingorFailed. Sethistory=trueto get every processing attempt inAttempts; without it,Attemptsis[]. To read all the items of a batch page by page, useGET /Fund/BatchTransfer/{CustomerBatchId}instead.If Xtrm has set up webhooks for your account, it also notifies your server as items progress. No event reports
RetainedInWallet: a bank item'sBatch.Item.CompletedhasStatusSuccesswhether or not the bank payment went through, withDeliveryTypeBankwhen it did andWalletwhen it didn't. So readDeliveryType, and confirm a bank item's final status with this endpoint. See Event types.curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BANK-0001/Items/TXN-BANK-0001?history=true" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BANK-0001/Items/TXN-BANK-0001?history=true', { method: 'GET', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, }, }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.get( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BANK-0001/Items/TXN-BANK-0001?history=true", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BANK-0001/Items/TXN-BANK-0001?history=true"); 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; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BANK-0001/Items/TXN-BANK-0001?history=true")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .GET() .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/Fund/BatchTransfer/BATCH-BANK-0001/Items/TXN-BANK-0001?history=true'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));In this
history=trueresponse, the item's only attempt succeeded andDeliveryTypeisBank: the bank provider accepted the payment to Jane Doe's bank. If an item has more than one attempt, order them byAttemptNo.Response (excerpt){ "CustomerBatchId": "BATCH-BANK-0001", "CustomerTransactionId": "TXN-BANK-0001", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94500", "Amount": "100.00", "Currency": "USD", "DeliveryType": "Bank", "LastUpdatedAt": "2026-06-04T13:02:23.259Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-06-04T13:01:35.0055683Z", "CompletedAt": "2026-06-04T13:02:23.259Z" } ] }Until the recipient's wallet is credited, a bank item's
StatusisAcceptedorProcessing. Then, while Xtrm pays the money from the recipient's wallet on to the bank, it readsRetainedInWallet, withDeliveryTypeWallet, usually only briefly. Don't act on it yet: read it together with the batch status fromGET /Fund/BatchTransfer/{CustomerBatchId}, which staysProcessingwhile any bank payment in the batch is under way. The item ends in one of three ways:Success, withDeliveryTypeBank: the bank provider accepted the payment from the recipient's wallet. That doesn't mean the ACH, wire or RTP payment has settled. If the recipient's bank returns it later, the item staysSuccess, no webhook is sent, and Xtrm credits the money back to your wallet by hand; see Returned bank payments.RetainedInWallet, withDeliveryTypeWallet, once the batch status is final (CompletedWithFailuresorFailed): the bank payment didn't go through, and the item's newest attempt hasResultFailedwith anErrorCodethat says why. See When a bank payment doesn't complete.Failed, with an emptyDeliveryType: the item failed before any money moved. Read its latest attempt'sErrorCode; see What can go wrong.
Keep:
Status,DeliveryTypeandLastUpdatedAtfor your records. For every status value, see Batch and payment statuses.
#When a bank payment doesn't complete
Every bank item passes through RetainedInWallet on its way to the bank. A bank item that is still RetainedInWallet, with DeliveryType Wallet, once its batch status is final (CompletedWithFailures or Failed) has stuck: Xtrm tried the bank payment, it didn't go through, and Xtrm won't try again. The money has left your wallet and stays in the recipient's Xtrm wallet: Xtrm doesn't return it to your source wallet or refund the item's fee, and you can't retry or resubmit the item. Request the item with history=true: its newest attempt has Result Failed and an ErrorCode that says why, for example RETAINED_IN_WALLET when the bank provider didn't accept the payment. See Delivery stage for every code.
Treat it like a wallet payment. The recipient signs in to the Xtrm web app and transfers the money out of their wallet. If the batch set EmailNotification to true, Xtrm emailed them when the money reached their wallet. Or your company requests the transfer on their behalf, confirmed with the recipient's one-time password, which needs a connection to the recipient: see Transfer from a recipient's wallet. If the recipient doesn't see the money in their wallet, contact Xtrm support with the CustomerBatchId and CustomerTransactionId. When a payment stays RetainedInWallet covers both ways, and what it means when the batch stays Processing because Xtrm is holding the bank payment.
#Transfer from a recipient's wallet
Money in a recipient's Xtrm wallet belongs to the recipient, whether a batch credited it to a wallet item or a bank item stayed RetainedInWallet. Recipients transfer it out themselves in the Xtrm web app. Your company can also request a transfer on a recipient's behalf through the API: the transfer debits the recipient's own wallet, never yours, and pays a bank or another payment method of theirs. Each one needs a connection to the recipient and the recipient's one-time password (OTP), so the recipient takes part in every transfer.
Send transfer requests one at a time: wait for a successful response to the current call before you send the next one.
#From an individual recipient's wallet
UserWithdrawFund moves money out of an individual recipient's Xtrm wallet. Every transfer is confirmed with a six-digit one-time password (OTP) that Xtrm sends to the account holder, so a transfer takes two requests. The samples transfer USD 5.00 from Jane Doe's USD wallet to the Chase account you linked for her earlier in this guide.
UserID and Currency identify the wallet to debit. For a transfer to a bank, set PaymentMethodID to XTR94500 and send the bank's ID as UserLinkedBankID and one of its payment methods as BankPaymentMethod, both from GetLinkedBankAccounts. Xtrm pays exactly the bank you send. It's required, and it must be one of the recipient's own banks with BankBeneficiaryStatus Approved: a transfer without it is refused with <UserID> - User BankID is mandatory, another account's bank with <UserLinkedBankID> - Invalid User Linked Bank ID, and a bank that's still pending with <UserLinkedBankID> - User Linked Bank ID is in pending status. EmailNotification is a JSON boolean and is off by default.
UserWithdrawFund accepts four PaymentMethodID values: XTR94500 (bank account), XTR94503 (prepaid card), XTR94505 (digital gift card) and XTR94508 (Rapid Transfer, USD only). Send the ID in capitals, exactly as shown: any other value is refused with <id> - Invalid Payment Method Id. GetUserPaymentMethods also lists XTR94502 (Xtrm wallet) and XTR94506 (Reward Link, a reward card that recipients choose in the Xtrm web app), which UserWithdrawFund doesn't accept. For the other methods (Rapid Transfer, prepaid card and digital gift card), see the UserWithdrawFund reference page.
- Request the transfer
Send the request with
OTPleft blank, or withoutOTP. Xtrm generates a six-digit OTP and sends it to the account holder by email and, when their profile has a mobile number, by text message, unless you choose one channel withSendTransferCodeToEmailorSendTransferCodeToMobile. Nothing is transferred yet.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": true } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ UserWithdrawFund: { request: { IssuerAccountNumber: 'SPN1111222', UserID: 'PAT9999888', Amount: '5.00', Currency: 'USD', PaymentMethodID: 'XTR94500', OTP: '', BankPaymentMethod: 'ACH', UserLinkedBankID: '907599f594b044d08cf81a2afb0a7967', EmailNotification: 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/Fund/UserWithdrawFund", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": 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 = """ { "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": true } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund", 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 = """ { "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": true } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund")) .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/Fund/UserWithdrawFund'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'UserWithdrawFund' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT9999888', 'Amount' => '5.00', 'Currency' => 'USD', 'PaymentMethodID' => 'XTR94500', 'OTP' => '', 'BankPaymentMethod' => 'ACH', 'UserLinkedBankID' => '907599f594b044d08cf81a2afb0a7967', 'EmailNotification' => true, ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The response to this first request is HTTP
200withOperationStatus.Successset totrue, andErrorsholds the messageOne Time Password sent to user. Please resubmit with One Time Password.No money has moved:PaymentTransactionId,PaymentDateandPaymentStatusarenull, and so are the amounts.Response (first request){ "UserWithdrawFundResponse": { "UserWithdrawFundResult": { "PaymentTransactionId": null, "PaymentDate": null, "PaymentStatus": null, "Amount": null, "Fee": null, "TotalAmount": null, "Currency": null, "PayDirectTransactionDetails": null, "RedemptionDetails": null, "OperationStatus": { "Success": true, "Errors": [ "One Time Password sent to user. Please resubmit with One Time Password." ] } } } }Keep: the request body, to resubmit it with the OTP.
- Confirm the transfer with the OTP
Retrieve the OTP from the account holder in your application, then resubmit the same request with
OTPfilled in to complete the transfer. The OTP expires 10 minutes after Xtrm sends it, and Xtrm counts in whole minutes, so send it back within 9 minutes. Each code covers one attempt: once Xtrm accepts it, the code is used up, even if the transfer then fails, so start again with a first request. AnOTPthat is blank,000000or not a number counts as a first request: Xtrm sends a new code, the previous code stops working, and you get the code-sent message again.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "123456", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": true } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ UserWithdrawFund: { request: { IssuerAccountNumber: 'SPN1111222', UserID: 'PAT9999888', Amount: '5.00', Currency: 'USD', PaymentMethodID: 'XTR94500', OTP: '123456', BankPaymentMethod: 'ACH', UserLinkedBankID: '907599f594b044d08cf81a2afb0a7967', EmailNotification: 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/Fund/UserWithdrawFund", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "123456", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": 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 = """ { "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "123456", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": true } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund", 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 = """ { "UserWithdrawFund": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "Amount": "5.00", "Currency": "USD", "PaymentMethodID": "XTR94500", "OTP": "123456", "BankPaymentMethod": "ACH", "UserLinkedBankID": "907599f594b044d08cf81a2afb0a7967", "EmailNotification": true } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/UserWithdrawFund")) .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/Fund/UserWithdrawFund'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'UserWithdrawFund' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT9999888', 'Amount' => '5.00', 'Currency' => 'USD', 'PaymentMethodID' => 'XTR94500', 'OTP' => '123456', 'BankPaymentMethod' => 'ACH', 'UserLinkedBankID' => '907599f594b044d08cf81a2afb0a7967', 'EmailNotification' => true, ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "UserWithdrawFundResponse": { "UserWithdrawFundResult": { "PaymentTransactionId": "397785", "PaymentDate": "2026-06-05T16:33:26.385963Z", "PaymentStatus": "Completed", "Amount": "4.50", "Fee": "0.50", "TotalAmount": "5.00", "Currency": "USD", "PayDirectTransactionDetails": null, "RedemptionDetails": null, "OperationStatus": { "Success": true, "Errors": [] } } } }Don't decide with
Successalone, because the first request also returnsSuccess: true. The transfer is made only when the response hasPaymentStatusCompletedand aPaymentTransactionId, as here, withErrorsas an empty array[]. Read any other200response fromErrors:One Time Password sent to user. Please resubmit with One Time Password.(Success: true): no money moved. Get the code from the account holder and send the same request again with it inOTP.Invalid one time password. A new one has been sent and the original has been expired. Please use the new one.(Success: false): the code was wrong or had expired. No money moved, the old code no longer works, and Xtrm has sent the account holder a new one. Send the same request again with the new code.
Keep:
PaymentTransactionId(a string) for reconciliation, plusPaymentStatus,Amount,FeeandTotalAmount.
Not the connection OTP
This OTP comes from UserWithdrawFund itself. GetOTPAuthorizedVendor issues a different OTP, which connects your company to an account. Don't use it for transfers. See Connect existing accounts.
#From a business recipient's wallet
BeneficiaryCompanyWithdrawFund is the parallel call for a business recipient. It debits the business recipient's own wallet, never yours, and your company must be connected to the recipient. The sample transfers USD 50.00 from Acme Corporation's (SPN9999888) USD wallet 122340 to its own bank, 5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d. Your company created Acme Corporation in Pay business recipients, so it's connected. BeneficiaryAccountNumber (SPN…) and BeneficiaryWalletID (the ID that GetBeneficiaryWallets returns) identify the wallet to debit, which must be the recipient's own wallet in Currency. BeneficiaryWalletID takes only the wallet's numeric ID: a wallet name is rejected with BeneficiaryWalletID is Mandatory and must be an integer, and no money moves. It accepts two of the methods that GetBeneficiaryCompanyPaymentMethods lists: XTR94500 (Bank, with BeneficiaryLinkedBankID and BankPaymentMethod) and XTR94508 (Rapid Transfer in USD only, with BeneficiaryCardToken). The bank or card must be the recipient's own.
It takes two requests, like UserWithdrawFund. Send the first without OTP: Xtrm sends a six-digit OTP to the business recipient and answers HTTP 200 with Success: true, the code-sent message in Errors, and PaymentTransactionId, PaymentDate and PaymentStatus set to null. The recipient gives you the code, and you resubmit the same request with OTP filled in, as in this sample. The OTP rules are the same as for UserWithdrawFund: the code expires after 10 minutes, a wrong or expired code gets a new one sent, an OTP that is blank, 000000 or not a number counts as a first request, and each code covers one attempt. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId, as below. EmailNotification is a JSON boolean, while the optional SendTransferCodeToEmail and SendTransferCodeToMobile are strings ("true" / "false").
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BeneficiaryCompanyWithdrawFund" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"BeneficiaryCompanyWithdrawFund": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"Currency": "USD",
"Amount": "50.00",
"PaymentMethodID": "XTR94500",
"BeneficiaryAccountNumber": "SPN9999888",
"BeneficiaryWalletID": "122340",
"OTP": "123456",
"BankPaymentMethod": "ACH",
"BeneficiaryLinkedBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
"EmailNotification": true
}
}
}'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BeneficiaryCompanyWithdrawFund', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
BeneficiaryCompanyWithdrawFund: {
request: {
IssuerAccountNumber: 'SPN1111222',
Currency: 'USD',
Amount: '50.00',
PaymentMethodID: 'XTR94500',
BeneficiaryAccountNumber: 'SPN9999888',
BeneficiaryWalletID: '122340',
OTP: '123456',
BankPaymentMethod: 'ACH',
BeneficiaryLinkedBankID: '5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d',
EmailNotification: 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/Fund/BeneficiaryCompanyWithdrawFund",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
json={
"BeneficiaryCompanyWithdrawFund": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"Currency": "USD",
"Amount": "50.00",
"PaymentMethodID": "XTR94500",
"BeneficiaryAccountNumber": "SPN9999888",
"BeneficiaryWalletID": "122340",
"OTP": "123456",
"BankPaymentMethod": "ACH",
"BeneficiaryLinkedBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
"EmailNotification": 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 = """
{
"BeneficiaryCompanyWithdrawFund": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"Currency": "USD",
"Amount": "50.00",
"PaymentMethodID": "XTR94500",
"BeneficiaryAccountNumber": "SPN9999888",
"BeneficiaryWalletID": "122340",
"OTP": "123456",
"BankPaymentMethod": "ACH",
"BeneficiaryLinkedBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
"EmailNotification": true
}
}
}
""";
var response = await client.PostAsync(
"https://xapisandbox.xtrm.com/API/v4/Fund/BeneficiaryCompanyWithdrawFund",
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 = """
{
"BeneficiaryCompanyWithdrawFund": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"Currency": "USD",
"Amount": "50.00",
"PaymentMethodID": "XTR94500",
"BeneficiaryAccountNumber": "SPN9999888",
"BeneficiaryWalletID": "122340",
"OTP": "123456",
"BankPaymentMethod": "ACH",
"BeneficiaryLinkedBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
"EmailNotification": true
}
}
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BeneficiaryCompanyWithdrawFund"))
.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/Fund/BeneficiaryCompanyWithdrawFund');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'BeneficiaryCompanyWithdrawFund' => [
'request' => [
'IssuerAccountNumber' => 'SPN1111222',
'Currency' => 'USD',
'Amount' => '50.00',
'PaymentMethodID' => 'XTR94500',
'BeneficiaryAccountNumber' => 'SPN9999888',
'BeneficiaryWalletID' => '122340',
'OTP' => '123456',
'BankPaymentMethod' => 'ACH',
'BeneficiaryLinkedBankID' => '5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d',
'EmailNotification' => true,
],
],
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));{
"BeneficiaryCompanyWithdrawFundResponse": {
"BeneficiaryCompanyWithdrawFundResult": {
"PaymentTransactionId": "879538",
"PaymentDate": "2026-06-08T16:21:43.4155509Z",
"PaymentStatus": "Completed",
"OperationStatus": {
"Success": true,
"Errors": []
},
"PayDirectTransactionDetails": null
}
}
}Keep: PaymentTransactionId and PaymentStatus. PaymentTransactionId is a string in the example; we recommend storing it as a string.
For a transfer to a bank, Xtrm pays exactly the bank in BeneficiaryLinkedBankID, whatever bank is linked to the wallet. It's required, and it must be one of the recipient's own banks with BankBeneficiaryStatus Approved: a transfer without it is refused with <BeneficiaryAccountNumber> Beneficiary Linked BankID is mandatory, another account's bank with <BeneficiaryLinkedBankID> - Invalid Beneficiary Linked BankID, and a bank that's still pending with <BeneficiaryLinkedBankID> - Beneficiary Linked BankID is in pending status.
Fees come from the recipient's schedule
Xtrm applies the business recipient's own fee schedule to this transfer and takes the fee out of Amount.
#Remove a linked bank
DeleteBankBeneficiary removes a linked bank. Send the recipient's account number as RecipientAccountNumber and the bank's ID as BeneficiaryBankID, from GetLinkedBankAccounts (or GetACHDebitLinkedBankAccounts for a bank-debit bank). An individual recipient can link up to 3 banks, and a company account more, up to a limit Xtrm sets, so we recommend removing the ones a recipient no longer uses. Once a bank is removed, don't send its ID in new batch items. This example removes Acme Corporation's bank, for example once it stops using that account.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/DeleteBankBeneficiary" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"DeleteBankBeneficiary": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"RecipientAccountNumber": "SPN9999888",
"BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d"
}
}
}'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Bank/DeleteBankBeneficiary', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
DeleteBankBeneficiary: {
request: {
IssuerAccountNumber: 'SPN1111222',
RecipientAccountNumber: 'SPN9999888',
BeneficiaryBankID: '5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d',
},
},
}),
});
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/DeleteBankBeneficiary",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
json={
"DeleteBankBeneficiary": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"RecipientAccountNumber": "SPN9999888",
"BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
},
},
},
)
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 = """
{
"DeleteBankBeneficiary": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"RecipientAccountNumber": "SPN9999888",
"BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d"
}
}
}
""";
var response = await client.PostAsync(
"https://xapisandbox.xtrm.com/API/v4/Bank/DeleteBankBeneficiary",
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 = """
{
"DeleteBankBeneficiary": {
"request": {
"IssuerAccountNumber": "SPN1111222",
"RecipientAccountNumber": "SPN9999888",
"BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d"
}
}
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Bank/DeleteBankBeneficiary"))
.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/DeleteBankBeneficiary');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'DeleteBankBeneficiary' => [
'request' => [
'IssuerAccountNumber' => 'SPN1111222',
'RecipientAccountNumber' => 'SPN9999888',
'BeneficiaryBankID' => '5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d',
],
],
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));{
"DeleteBankBeneficiary": {
"DeleteBankBeneficiaryResult": {
"BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d",
"OperationStatus": {
"Errors": [],
"Success": true
}
}
}
}The response echoes the deleted BeneficiaryBankID. Its root key has no Response suffix.
#What can go wrong
See Errors for the general rules.
#Linking the bank
- Not linked yet. When
LinkBankBeneficiaryneeds more information, it returns HTTP400withSuccess: falseand the fields to add or fix inErrors. Send the whole request again with those fields, and repeat until it returns aBeneficiaryId. See Errors on a failed call. Regulatory field values are not required for this request.You sentRegulatoryFieldsfor a bank that needs none. Leave it out until a response lists a field whoseIsRegulatoryFieldistrue.- Valid call, invalid IBAN.
ValidateIBANcan returnSuccess: truewithIsValid: false. - Too many banks. Individual recipients can link up to 3 banks, and company accounts more, up to a limit Xtrm sets. Past the limit,
LinkBankBeneficiaryrefuses the link withYou can link maximum N banks. WithdrawTypeis refused. It accepts onlyACH,WIRE,LV(low value, the same asACH) andHV(high value, the same asWIRE), in any case. Any other value returnsWithdrawType is invalid. WithdrawType must be ACH, WIRE, HV or LV.ACHorLVis also refused when the bank's country doesn't support ACH, or the currency isn't the country's own.
#Paying the bank
Item rejected at submission. A bank item is rejected when it has neither
BeneficiaryBankIDnorWalletId, aBeneficiaryBankIDover 40 characters (itsFieldthen saysItems[i].RecipientId), or aBeneficiaryBankPaymentMethodother thanACH,WIREorRTP. The other items are still processed, and a rejected item is never stored. See Errors for theRejectedentries, and Payment statuses for when to resubmit a rejected item in the same batch or a new one.Item failed. Read the
ErrorCodeof the item's latest attempt. These bank codes fail the item during processing, before any money moves:BANKID_INVALID: the bank isn't a pending or approved bank linked to the recipient's account. It's mistyped, deleted or another account's bank. Check withGetLinkedBankAccountsthat theBeneficiaryBankIDbelongs to thatRecipientId.BENEFICIARY_BANKID_REQUIRED: the item has noBeneficiaryBankIDwhere one is needed, that is, for an individual recipient or for a business recipient withoutWalletId.BANK_NOT_FOUND: the bank provider doesn't recognize the recipient's bank, or bank validation raised an error.INVALID_PAYMENTMETHOD: the rail you asked for isn't allowed for this bank account.DEFAULT_BANK_NOT_FOUNDorINVALID_BENEFICIARY_WALLET: the item sent aWalletIdthat has no linked bank or isn't an active wallet of the recipient in the batch's currency. See Bank transfer: XTR94500.
For every code and what to do, see Error codes on attempts.
Retrying a failed item. Fix the cause, then resubmit the item under its original
CustomerBatchIdandCustomerTransactionId, with every field, including the correctedBeneficiaryBankID. A corrected bank takes effect after a failure in the bank checks above, but not after a failure at the wallet credit, such asINSUFFICIENT_BALANCE. See Resubmit failed payments and What you can change on a retry.A different bank was paid. A business recipient's item sent with a
WalletIdcan pay the bank linked to that wallet instead of theBeneficiaryBankIDyou sent, without an error. To pay a specific bank, send itsBeneficiaryBankIDwithoutWalletId, as this guide does. See Bank transfer: XTR94500.The item is
RetainedInWallet. While the batch isProcessing, the bank payment is still under way: wait. If the item is stillRetainedInWalletonce the batch status is final, the bank payment didn't go through and the money is in the recipient's Xtrm wallet. See When a bank payment doesn't complete.IDs, duplicates and batch size. See Retries & idempotency and Limits.
#Recipient transfers
Not authorized to access this resource. Make One Time Password API Call to access this resource. The recipient isn't connected to your company, so you can't request a transfer on their behalf. The recipient can still transfer the money in the Xtrm web app. See Connections and manager services.- Nothing was transferred, yet
Successistrue. The first request only sends the OTP, and so does a request whoseOTPis blank,000000or not a number:ErrorsholdsOne Time Password sent to user. Please resubmit with One Time Password.andPaymentStatusisnull. Resubmit with the code. A transfer is made only when the response hasPaymentStatusCompletedand aPaymentTransactionId. Your previous transfer is in progress. Please wait or try later.(HTTP400). An earlier transfer from the recipient's wallet hasn't finished. Xtrm checks this before it sends a code and again after it accepts one; in the second case the code is used up. Wait, then start again with a first request.- The bank is refused. A transfer to a bank needs the bank's ID, and the bank must be the recipient's own and approved. A bank that's still pending, which a batch can pay, can't take a transfer until it's approved. Check its
BankBeneficiaryStatuswithGetLinkedBankAccounts. - Fees don't add up. On a
UserWithdrawFundtransfer to a bank, the fee comes out ofAmount: the bank account receivesAmountminusFee, the response'sAmountis that net figure, andTotalAmountis theAmountyou sent (in the bank example,4.50+0.50=5.00). Rapid Transfer fees also come out ofAmount. Gift card and prepaid card transfers carry no fee for the recipient: the card is worth the fullAmount.BeneficiaryCompanyWithdrawFundtakes the fee out ofAmount. ReadAmount,FeeandTotalAmountfrom each response. - The OTP was wrong or expired. An OTP expires 10 minutes after Xtrm sends it, counted in whole minutes, so send it back within 9 minutes. A wrong or expired code gets HTTP
200withSuccess: falseandInvalid one time password. A new one has been sent and the original has been expired. Please use the new one., and Xtrm sends a new OTP. Resubmit with the new one. See Error messages by area. <id> - Invalid Payment Method Id.UserWithdrawFundaccepts onlyXTR94500,XTR94503,XTR94505andXTR94508, in capitals, andBeneficiaryCompanyWithdrawFundonlyXTR94500andXTR94508.- Types and casing.
EmailNotificationis a JSON boolean on the transfer calls, as it is onBatchTransfer. Copy keys exactly, includingRequestversusrequest. On the calls that link and list bank accounts,Errorsisnullor an empty array[]on success, depending on the endpoint, so testSuccessinstead. The transfer calls are different:Successistrueon the code-sent response too, so decide byPaymentStatusCompletedandPaymentTransactionId.
#Any call
- Calls overlap. Never have two
BatchTransferrequests for the sameCustomerBatchIdin flight at once. Separate batches can be sent at the same time. Send transfer requests one at a time: wait for a successful response before you send the next one. - Sandbox results. The sandbox works the same as production, and it has no test bank accounts. Link a bank there as in production, with a real bank's routing number or SWIFT-BIC and a made-up account number in the right format, never a real account. A
BeneficiaryBankIDthat belongs to no account, such as00000000000000000000000000000000, fails withBANKID_INVALIDevery time, so you can use one to test a failed item. See How the sandbox behaves.
#Next steps
Pay many recipients in one request with mixed send methods, and track every item.
How batch payments workThe batch lifecycle, wallet-first processing and how your IDs are used.
Batch and payment statusesWhat each batch, payment and attempt status means.
WebhooksGet notified as items succeed or fail instead of polling.
Bank accounts referenceEvery bank endpoint, with all fields and example responses.