Pay business recipients
Paying a business through Xtrm starts with finding the right company account, so you never pay into a duplicate. This guide follows one company, Acme Corporation, from search to confirmed payment: you search Xtrm for it, create its account when the search comes back empty, link its bank account, and pay it in one batch, part into its Xtrm wallet and part to its bank. Xtrm accepts the batch right away and processes the payments in the background, so you finish by confirming each payment's outcome with a status call or a webhook. Every sample runs against the sandbox.
A batch pays existing Xtrm accounts only, by their account numbers, so the company needs an account before you build the batch: you find it in step 1, or create it with CreateBeneficiary in step 2. For how Xtrm processes a batch, see How batch payments work. For every send method and option, see Create a batch payment.
#Before you begin
- Sandbox credentials and an access token. Store the token in
XTRM_ACCESS_TOKEN; every sample reads it from there. See Authentication and Sandbox & environments. - Your company's account number, the
SPNthat owns your API credentials (SPN1111222in the samples). You send it asIssuerAccountNumber. - A funded source wallet. List your wallets with
GetCompanyWalletsand note the ID of the one you pay from (122181in the samples). It sets the currency of the whole batch. In the sandbox, Xtrm credits test funds to your wallets after approving your IP addresses; see Test funds. To add money, see Fund your wallet. - The company's details: its email domain to search with (or its registered name, if you don't know the domain) and, in case you have to create it, its master administrator's name and email address and the company's country.
- For the bank payment, the company's bank account: the bank's name, routing number and account number, with the company's phone number and address.
The samples use example values chosen so that one step's output feeds the next: the company you create is Acme Corporation, SPN9999888, with the administrator email [email protected]. Its wallet is 122340 and its linked bank account is 5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d.
#Onboard and pay the company
- Search for an existing company account
Businesses often already have an account in the Xtrm ecosystem, so search before you create anything.
CheckBeneficiaryExistsearches every company account on Xtrm, not only yours. When you know the company's email domain, search withCompanyEmailDomainon its own, as the sample does. Send the domain (acmecorp.com) or any address at it ([email protected]): Xtrm uses only the part after the@. Search withCompanyNamewhen you don't know the domain. At least one of the two is required.Paginationis optional. If you send it, include bothRecordsToSkipandRecordsToTake.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckBeneficiaryExist" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "CheckBeneficiaryExist": { "request": { "IssuerAccountNumber": "SPN1111222", "CompanyEmailDomain": "acmecorp.com" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckBeneficiaryExist', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ CheckBeneficiaryExist: { request: { IssuerAccountNumber: 'SPN1111222', CompanyEmailDomain: 'acmecorp.com', }, }, }), }); 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/Beneficiary/CheckBeneficiaryExist", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "CheckBeneficiaryExist": { "request": { "IssuerAccountNumber": "SPN1111222", "CompanyEmailDomain": "acmecorp.com", }, }, }, ) 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 = """ { "CheckBeneficiaryExist": { "request": { "IssuerAccountNumber": "SPN1111222", "CompanyEmailDomain": "acmecorp.com" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckBeneficiaryExist", 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 = """ { "CheckBeneficiaryExist": { "request": { "IssuerAccountNumber": "SPN1111222", "CompanyEmailDomain": "acmecorp.com" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckBeneficiaryExist")) .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/Beneficiary/CheckBeneficiaryExist'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'CheckBeneficiaryExist' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'CompanyEmailDomain' => 'acmecorp.com', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Acme Corporation is new to Xtrm, so the search finds nothing and
Beneficiaryis an empty array:Response{ "CheckBeneficiaryExistResponse": { "CheckBeneficiaryExistResult": { "Beneficiary": [], "OperationStatus": { "Success": true, "Errors": null } } } }CompanyEmailDomainmatches the companies whose account email, the master administrator's sign-in email, is at that domain. Once you create Acme Corporation with[email protected]in step 2, this same search finds it. A company's own domain usually returns just that company. A shared domain can return several, and the match is on text, soacmecorp.comalso returns a company whose email is atacmecorp.com.au.CompanyNamereturns every company whose registered name contains the text, so a name search can return several companies, up to 30 per page unless you setPagination. Xtrm uses the first 50 characters of the name. If you send bothCompanyNameandCompanyEmailDomain, you get the companies that match either one, so send the domain alone when you have it. Each match inBeneficiaryhas the company'sName, itsAccountNumber, its accountEmail, its master administrator's first and last name, itsStatusand itsAccountIdentityLevel(Draft,Basic,StandardorAdvanced).- No match: continue with step 2 and create the company.
- Match found: check its
EmailandNameto confirm it's the company you mean. The business already has an Xtrm account, so don't create a second one. Use itsAccountNumberas theRecipientIdof your items, skip step 2, and read the note below.
If the company already has an account
You can pay an existing company straight away with a wallet item (
XTR94504) whoseDestinationis empty,{}. A batch payment needs no connection to the recipient: it pays any Xtrm account whose status is Active, Email not verified or Account pending approval. To link and read its bank accounts (steps 4 and 5), connect the company to yours first: its administrator gives you a one-time password. See Connect existing accounts, and for what a connection allows, Connections and manager services. Paying a company doesn't connect it. - Create the business recipient
If the search found nothing, create the company with
CreateBeneficiary. The body has two details that are easy to get wrong:- The inner wrapper is
Requestwith a capital R, unlike therequestused by the other onboarding calls in this guide. Copy it exactly. EmailNotificationis a string,"true"or"false". With"true", Xtrm emails an account creation notification toAdminEmail.
The required fields are
IssuerAccountNumber,BeneficiaryCompanyName(the company's legally registered name) and, insideBeneficiaryCompanyAdminDetails,AdminEmail,EmailNotification,AdminFirstName,AdminLastNameandCountryISO2. The sample adds the optionalWebAddress,City,PostalCodeandRegion, and skipsAdminMobileNumberand the partner fields inSalesProgramDetails. If you send a mobile number, leave out the country code; it is determined from the country.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CreateBeneficiary" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "CreateBeneficiary": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryCompanyName": "Acme Corporation", "WebAddress": "https://www.acmecorp.com", "BeneficiaryCompanyAdminDetails": { "AdminEmail": "[email protected]", "EmailNotification": "true", "AdminFirstName": "Marcus", "AdminLastName": "Chen", "CountryISO2": "US", "City": "San Francisco", "PostalCode": "94105", "Region": "CA" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Beneficiary/CreateBeneficiary', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ CreateBeneficiary: { Request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryCompanyName: 'Acme Corporation', WebAddress: 'https://www.acmecorp.com', BeneficiaryCompanyAdminDetails: { AdminEmail: '[email protected]', EmailNotification: 'true', AdminFirstName: 'Marcus', AdminLastName: 'Chen', CountryISO2: 'US', City: 'San Francisco', PostalCode: '94105', Region: 'CA', }, }, }, }), }); 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/Beneficiary/CreateBeneficiary", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "CreateBeneficiary": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryCompanyName": "Acme Corporation", "WebAddress": "https://www.acmecorp.com", "BeneficiaryCompanyAdminDetails": { "AdminEmail": "[email protected]", "EmailNotification": "true", "AdminFirstName": "Marcus", "AdminLastName": "Chen", "CountryISO2": "US", "City": "San Francisco", "PostalCode": "94105", "Region": "CA", }, }, }, }, ) response.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 = """ { "CreateBeneficiary": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryCompanyName": "Acme Corporation", "WebAddress": "https://www.acmecorp.com", "BeneficiaryCompanyAdminDetails": { "AdminEmail": "[email protected]", "EmailNotification": "true", "AdminFirstName": "Marcus", "AdminLastName": "Chen", "CountryISO2": "US", "City": "San Francisco", "PostalCode": "94105", "Region": "CA" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CreateBeneficiary", 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 = """ { "CreateBeneficiary": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryCompanyName": "Acme Corporation", "WebAddress": "https://www.acmecorp.com", "BeneficiaryCompanyAdminDetails": { "AdminEmail": "[email protected]", "EmailNotification": "true", "AdminFirstName": "Marcus", "AdminLastName": "Chen", "CountryISO2": "US", "City": "San Francisco", "PostalCode": "94105", "Region": "CA" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Beneficiary/CreateBeneficiary")) .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/Beneficiary/CreateBeneficiary'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'CreateBeneficiary' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryCompanyName' => 'Acme Corporation', 'WebAddress' => 'https://www.acmecorp.com', 'BeneficiaryCompanyAdminDetails' => [ 'AdminEmail' => '[email protected]', 'EmailNotification' => 'true', 'AdminFirstName' => 'Marcus', 'AdminLastName' => 'Chen', 'CountryISO2' => 'US', 'City' => 'San Francisco', 'PostalCode' => '94105', 'Region' => 'CA', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "CreateBeneficiaryResponse": { "CreateBeneficiaryResult": { "BeneficiaryID": "SPN9999888", "AccountIdentityLevel": "Basic", "ClientID": "YOUR_CLIENT_ID", "SecretKey": "YOUR_CLIENT_SECRET", "OperationStatus": { "Success": true, "Errors": [] } } } }Keep:
BeneficiaryID, the new company'sSPNaccount number (SPN9999888). It's theRecipientIdof every item that pays this company, and the account you name in steps 3 to 5.CreateBeneficiaryalso connects the new company to yours, which steps 4 and 5 need. Xtrm approves a company you create through the API straight away, so you can pay it right away. A batch payment accepts recipients whose account is Active, Email not verified or Account pending approval, which covers a newly created account, and it doesn't wait for the KYC review (Xtrm's identity checks on the account).The response's
ClientIDandSecretKeyare your pseudo credentials for the new company, not the company's own credentials (the sample shows placeholders). With them, your company can call the API as the new company, with itsSPNasIssuerAccountNumber. Pseudo credentials require manager services, which Xtrm turns on for your company. If you keep them, store them as secrets on your server, as you store your own, and never log them.Production creates real, reviewed accounts
Xtrm reviews every business recipient you create with identity checks (KYC), so submit real and accurate information. Don't create test companies or test email addresses on production servers; use the sandbox.
A company you only pay needs no more onboarding than this. If this company will also fund its own wallets and pay recipients,
CreateBeneficiarydoesn't finish its onboarding, and part of the rest happens in the Xtrm web app, because no API call uploads documents.First the company completes its Identity profile to
Advanced(100% IDL). That includes its documents, uploaded under Identity > Identity Documents: a government-issued photo ID for its administrator and, for a private company, a company tax document that shows its tax ID, such as a W-9 for a US company. The company can upload them from its own account. Or your company uploads them for it from the company's Connected Manager Services menu, with the Identity Documents manager service, which Xtrm turns on for your company. Then the company, or your company for it, submits its advanced profile, in the web app or withCompanyAdvancedProfile, and Xtrm reviews it before it unlocks funding for the company. See Complete the advanced profile and Onboard a client company. - The inner wrapper is
- Find the company's wallet
A wallet item in a batch pays into the company's Xtrm wallet. Naming the wallet is optional. If you leave out
Destination.WalletId, Xtrm credits the company's oldest active Standard wallet in the batch's currency (the currency of your source wallet), which isn't necessarily its default wallet. If the company has no active wallet in that currency, Xtrm creates one namedWallet - <currency code>, for exampleWallet - USD. If its only wallets in that currency are of another type, the item fails withWALLET_AUTO_CREATE_FAILED. To choose a wallet yourself, and to see each wallet's bank flags, list the company's wallets withGetBeneficiaryWallets:curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetBeneficiaryWallets" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetBeneficiaryWallets": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetBeneficiaryWallets', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetBeneficiaryWallets: { request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryAccountNumber: 'SPN9999888', }, }, }), }); 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/GetBeneficiaryWallets", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetBeneficiaryWallets": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888", }, }, }, ) 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 = """ { "GetBeneficiaryWallets": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetBeneficiaryWallets", 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 = """ { "GetBeneficiaryWallets": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetBeneficiaryWallets")) .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/GetBeneficiaryWallets'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetBeneficiaryWallets' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryAccountNumber' => 'SPN9999888', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response (excerpt){ "GetBeneficiaryWalletsResponse": { "GetBeneficiaryWalletsResult": { "Wallets": [ { "Name": "Wallet - USD", "ID": 122340, "Currency": "USD", "Type": "Standard", "Balance": 0, "IsBankLinked": false, "AllowWalletLinkedBankOverride": false, "EntityID": 27045 } ], "OperationStatus": { "Success": true, "Errors": null } } } }Acme Corporation's new account has one wallet, in USD. Pick a wallet in the currency of your source wallet. A company can hold more than one wallet per currency, so match on the
Nametoo if you need to. AWalletIdyou send must be an active wallet of the company in the batch's currency, or the item fails withINVALID_BENEFICIARY_WALLETbefore any money moves. To give the company a new wallet, useCreateBeneficiaryCompanyWallet.Keep: the wallet's
ID(122340), which you send asWalletId, as a number.IsBankLinkedandAllowWalletLinkedBankOverridematter only for a bank item that also sends this wallet'sWalletId, which can make Xtrm pay the wallet's linked bank instead of the one you name; see Bank transfer. The bank item in this guide sends noWalletId, so Xtrm pays the bank it names. - Link the company's bank account
A bank item pays a bank account linked to the company, which you name by its ID. Acme Corporation is new, so link its bank account with
LinkBankBeneficiary, sending itsSPNinUserID. Linking needs the company to be connected to yours, and a company you created withCreateBeneficiaryis.BeneficiaryInformationholds the account holder, here the company, with its address, andBeneficiaryBankInformationholds the bank account.AccountTypeBUSINESSmarks it as a business account. For every field, banks in other countries and IBANs, see Bank accounts & transfers.The sandbox has no test bank accounts: send a real bank's routing number or SWIFT-BIC, as the sample does, with a made-up account number in the format the bank's country needs, never a real one. See Test bank accounts.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/LinkBankBeneficiary" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "LinkBankBeneficiary": { "request": { "IssuerAccountNumber": "SPN1111222", "UserID": "SPN9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Acme Corporation", "PhoneNumber": "4155550188", "AddressLine1": "500 Howard Street", "City": "San Francisco", "Region": "CA", "PostalCode": "94105", "CountryISO2": "US" } }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "Wells Fargo Bank", "Currency": "USD", "SWIFTBIC": "WFBIUS6S", "AccountNumber": "000987656543", "RoutingNumber": "121000248", "CountryISO2": "US", "WithdrawType": "ACH", "AccountType": "BUSINESS" } } } } } }'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: 'SPN9999888', Beneficiary: { BeneficiaryDetails: { BeneficiaryInformation: { ContactName: 'Acme Corporation', PhoneNumber: '4155550188', AddressLine1: '500 Howard Street', City: 'San Francisco', Region: 'CA', PostalCode: '94105', CountryISO2: 'US', }, }, BankDetails: { BeneficiaryBankInformation: { InstitutionName: 'Wells Fargo Bank', Currency: 'USD', SWIFTBIC: 'WFBIUS6S', AccountNumber: '000987656543', RoutingNumber: '121000248', CountryISO2: 'US', WithdrawType: 'ACH', AccountType: 'BUSINESS', }, }, }, }, }, }), }); 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": "SPN9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Acme Corporation", "PhoneNumber": "4155550188", "AddressLine1": "500 Howard Street", "City": "San Francisco", "Region": "CA", "PostalCode": "94105", "CountryISO2": "US", }, }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "Wells Fargo Bank", "Currency": "USD", "SWIFTBIC": "WFBIUS6S", "AccountNumber": "000987656543", "RoutingNumber": "121000248", "CountryISO2": "US", "WithdrawType": "ACH", "AccountType": "BUSINESS", }, }, }, }, }, }, ) response.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": "SPN9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Acme Corporation", "PhoneNumber": "4155550188", "AddressLine1": "500 Howard Street", "City": "San Francisco", "Region": "CA", "PostalCode": "94105", "CountryISO2": "US" } }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "Wells Fargo Bank", "Currency": "USD", "SWIFTBIC": "WFBIUS6S", "AccountNumber": "000987656543", "RoutingNumber": "121000248", "CountryISO2": "US", "WithdrawType": "ACH", "AccountType": "BUSINESS" } } } } } } """; 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": "SPN9999888", "Beneficiary": { "BeneficiaryDetails": { "BeneficiaryInformation": { "ContactName": "Acme Corporation", "PhoneNumber": "4155550188", "AddressLine1": "500 Howard Street", "City": "San Francisco", "Region": "CA", "PostalCode": "94105", "CountryISO2": "US" } }, "BankDetails": { "BeneficiaryBankInformation": { "InstitutionName": "Wells Fargo Bank", "Currency": "USD", "SWIFTBIC": "WFBIUS6S", "AccountNumber": "000987656543", "RoutingNumber": "121000248", "CountryISO2": "US", "WithdrawType": "ACH", "AccountType": "BUSINESS" } } } } } } """; 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' => 'SPN9999888', 'Beneficiary' => [ 'BeneficiaryDetails' => [ 'BeneficiaryInformation' => [ 'ContactName' => 'Acme Corporation', 'PhoneNumber' => '4155550188', 'AddressLine1' => '500 Howard Street', 'City' => 'San Francisco', 'Region' => 'CA', 'PostalCode' => '94105', 'CountryISO2' => 'US', ], ], 'BankDetails' => [ 'BeneficiaryBankInformation' => [ 'InstitutionName' => 'Wells Fargo Bank', 'Currency' => 'USD', 'SWIFTBIC' => 'WFBIUS6S', 'AccountNumber' => '000987656543', 'RoutingNumber' => '121000248', 'CountryISO2' => 'US', 'WithdrawType' => 'ACH', 'AccountType' => 'BUSINESS', ], ], ], ], ], ]), 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": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d", "BankBeneficiaryStatus": "Approved", "AccountIdentityLevel": "Basic", "ACHDebitApprovalStatus": null, "OperationStatus": { "Errors": null, "Success": true } } } }Keep:
BeneficiaryId(5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d), the ID of the linked bank. It's theBeneficiaryBankIDof your bank item. A company can link up to 25 banks.When the bank's country and currency need fields you didn't send, nothing is linked: the response is HTTP
400withOperationStatus.Successset tofalse, andErrorsnames each field to add or fix. Send the whole request again with those fields, and repeat until the response returns aBeneficiaryId. - Read back the bank's ID and rails
GetLinkedBankAccountslists the company's linked bank accounts, with the company's account number inRecipientUserId. Use it to confirm the bank you linked and to find it again for later payments without linking it twice. Like linking, it needs the company to be connected to yours.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Bank/GetLinkedBankAccounts" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetLinkedBankAccounts": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "SPN9999888" } } }'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: 'SPN9999888', }, }, }), }); 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": "SPN9999888", }, }, }, ) 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": "SPN9999888" } } } """; 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": "SPN9999888" } } } """; 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' => 'SPN9999888', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response (excerpt){ "GetLinkedBankAccountsResponse": { "GetLinkedBankAccountsResult": { "Beneficiary": { "BeneficiaryDetails": [ { "BeneficiaryId": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d", "BeneficiaryName": "Acme Corporation", "Currency": "USD", "Country": "United States of America", "BankDetails": { "BeneficiaryBankInformation": { "AccountNumber": "XXXX6543", "BankName": "WELLS FARGO BANK, N.A.", "BankBeneficiaryStatus": "Approved", "BankRoutingCode": "121000248", "PaymentMethods": [ "ACH" ] } } } ] }, "OperationStatus": { "Success": true, "Errors": null } } } }Keep: the bank's
BeneficiaryId(5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d), which you send asBeneficiaryBankID.PaymentMethodsinsideBankDetailslists the rails available for the account (ACHhere). You can name the rail inBeneficiaryBankPaymentMethod:ACH,WIREorRTP. Without it, Xtrm uses the bank account's primary rail, and a rail the account doesn't support fails during processing withINVALID_PAYMENTMETHOD. - Submit the batch payment
Now pay the company with
BatchTransfer. Unlike the onboarding calls, the batch has no wrapper object: its fields sit at the root of the body. This batch carries two items for Acme Corporation:- Wallet item:
SendMethodIdXTR94504(AnyPay Company) pays USD50.00into the company's Xtrm wallet122340, from step 3. - Bank item:
SendMethodIdXTR94500(Bank) pays USD100.00by ACH to its bank account5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d, from steps 4 and 5.
Both IDs come from
GetPaymentMethods.XTR94504pays business recipients only: itsRecipientIdmust start withSPN, or the item is rejected when you submit. A company can also be paid by check (XTR94507) or Rapid Transfer (XTR94508), but not with the methods for individual recipients,XTR94502,XTR94503andXTR94505. See Payment methods & destinations.Amountis a JSON number greater than 0, with at most 2 decimal places.SourceWalletIdandWalletIdare integers, and the source wallet sets the currency of the batch.CustomerBatchIdand each item'sCustomerTransactionIdare required, and Xtrm never generates them. Create them before you send, store them with your payment records, and never reuse one for a different payment. For the ID rules, see Batch and payment identifiers.Each item's
Descriptionis optional, up to 1,024 characters. Xtrm copies it to the wallet transactions the payment creates: the debit in your source wallet and the credit in the company's wallet, where the company sees it. The samples start eachDescriptionwith the item'sCustomerTransactionId, which we recommend, so you can find those transactions later; see Track & reconcile payments.Use your own unique IDs
CustomerBatchIdvalues are shared across all Xtrm accounts. Replace the sample IDs with your own unique values, for example ones that include your account number or a UUID, before you run this in the sandbox. Never send two requests with the sameCustomerBatchIdat the same time.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "IssuerAccountNumber": "SPN1111222", "SourceWalletId": 122181, "CustomerBatchId": "BATCH-BIZ-0001", "Items": [ { "CustomerTransactionId": "TXN-BIZ-0001", "RecipientId": "SPN9999888", "Amount": 50, "SendMethodId": "XTR94504", "Destination": { "WalletId": 122340 }, "Description": "TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus" }, { "CustomerTransactionId": "TXN-BIZ-0002", "RecipientId": "SPN9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d", "BeneficiaryBankPaymentMethod": "ACH" }, "Description": "TXN-BIZ-0002 Q3 Regional Referral Program Commission" } ] }'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-BIZ-0001', Items: [ { CustomerTransactionId: 'TXN-BIZ-0001', RecipientId: 'SPN9999888', Amount: 50, SendMethodId: 'XTR94504', Destination: { WalletId: 122340, }, Description: 'TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus', }, { CustomerTransactionId: 'TXN-BIZ-0002', RecipientId: 'SPN9999888', Amount: 100, SendMethodId: 'XTR94500', Destination: { BeneficiaryBankID: '5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d', BeneficiaryBankPaymentMethod: 'ACH', }, Description: 'TXN-BIZ-0002 Q3 Regional Referral Program Commission', }, ], }), }); 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-BIZ-0001", "Items": [ { "CustomerTransactionId": "TXN-BIZ-0001", "RecipientId": "SPN9999888", "Amount": 50, "SendMethodId": "XTR94504", "Destination": { "WalletId": 122340, }, "Description": "TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus", }, { "CustomerTransactionId": "TXN-BIZ-0002", "RecipientId": "SPN9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d", "BeneficiaryBankPaymentMethod": "ACH", }, "Description": "TXN-BIZ-0002 Q3 Regional Referral Program Commission", }, ], }, ) 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-BIZ-0001", "Items": [ { "CustomerTransactionId": "TXN-BIZ-0001", "RecipientId": "SPN9999888", "Amount": 50, "SendMethodId": "XTR94504", "Destination": { "WalletId": 122340 }, "Description": "TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus" }, { "CustomerTransactionId": "TXN-BIZ-0002", "RecipientId": "SPN9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d", "BeneficiaryBankPaymentMethod": "ACH" }, "Description": "TXN-BIZ-0002 Q3 Regional Referral Program Commission" } ] } """; 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-BIZ-0001", "Items": [ { "CustomerTransactionId": "TXN-BIZ-0001", "RecipientId": "SPN9999888", "Amount": 50, "SendMethodId": "XTR94504", "Destination": { "WalletId": 122340 }, "Description": "TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus" }, { "CustomerTransactionId": "TXN-BIZ-0002", "RecipientId": "SPN9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d", "BeneficiaryBankPaymentMethod": "ACH" }, "Description": "TXN-BIZ-0002 Q3 Regional Referral Program Commission" } ] } """; 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-BIZ-0001', 'Items' => [ [ 'CustomerTransactionId' => 'TXN-BIZ-0001', 'RecipientId' => 'SPN9999888', 'Amount' => 50, 'SendMethodId' => 'XTR94504', 'Destination' => [ 'WalletId' => 122340, ], 'Description' => 'TXN-BIZ-0001 Q3 Channel Partner Marketing Bonus', ], [ 'CustomerTransactionId' => 'TXN-BIZ-0002', 'RecipientId' => 'SPN9999888', 'Amount' => 100, 'SendMethodId' => 'XTR94500', 'Destination' => [ 'BeneficiaryBankID' => '5b8e2c1d4f6a4e9b8c7d6e5f4a3b2c1d', 'BeneficiaryBankPaymentMethod' => 'ACH', ], 'Description' => 'TXN-BIZ-0002 Q3 Regional Referral Program Commission', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Xtrm checks the request and each item's fields right away. When at least one item passes, it queues the items that passed and answers
202. When none passes, it stores nothing and answers422, or409(see What can go wrong). When both items pass, both are listed inAcceptedwith the values you sent, eachAmountas a JSON number with the decimals you sent, so the50and100here come back as50.0and100.0.Rejectedis empty:Response (excerpt){ "BatchTransferResponse": { "CustomerBatchId": "BATCH-BIZ-0001", "Status": "Accepted", "Accepted": [ { "CustomerTransactionId": "TXN-BIZ-0001", "Amount": 50.0, "Currency": "USD", "SendMethodId": "XTR94504", "RecipientId": "SPN9999888" }, { "CustomerTransactionId": "TXN-BIZ-0002", "Amount": 100.0, "Currency": "USD", "SendMethodId": "XTR94500", "RecipientId": "SPN9999888" } ], "Rejected": [] } }Keep:
CustomerBatchId(BATCH-BIZ-0001) and eachCustomerTransactionId, stored with your own payment records so you can reconcile them later. An item inRejectedwasn't stored; its entry names theFieldthat failed and aMessage. To fix and resend such items, see Items rejected at submission.Accepted isn't paid
A
202means Xtrm received the batch and queued the items that passed its first checks. It hasn't checked your balance or moved any money yet: it does that in the background. Don't tell the company it has been paid until its items reachSuccess.The same batch can also pay other companies and individual recipients, each item with a send method that fits its recipient. See Create a batch payment and Payment methods & destinations.
- Wallet item:
- Confirm the payments
Follow each payment's outcome by polling the status endpoints or by receiving webhooks. To poll, call the batch status endpoint with your
CustomerBatchId. Sethistory=trueto include each item's processing attempts inAttempts, and page through the items withrecordsToSkipandrecordsToTake.curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BIZ-0001?recordsToSkip=0&recordsToTake=50&history=true" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-BIZ-0001?recordsToSkip=0&recordsToTake=50&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-BIZ-0001?recordsToSkip=0&recordsToTake=50&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-BIZ-0001?recordsToSkip=0&recordsToTake=50&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-BIZ-0001?recordsToSkip=0&recordsToTake=50&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-BIZ-0001?recordsToSkip=0&recordsToTake=50&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));Once Xtrm has processed both items, the
history=trueresponse looks like this:Response (excerpt){ "CustomerBatchId": "BATCH-BIZ-0001", "Status": "Completed", "Currency": "USD", "ItemsCount": 2, "Items": [ { "CustomerTransactionId": "TXN-BIZ-0001", "Status": "Success", "RecipientId": "SPN9999888", "SendMethodId": "XTR94504", "Amount": "50.00", "LastUpdatedAt": "2026-10-27T16:20:44.0208205Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-10-27T16:20:44.0159177Z", "CompletedAt": "2026-10-27T16:20:44.0208205Z" } ] }, { "CustomerTransactionId": "TXN-BIZ-0002", "Status": "Success", "RecipientId": "SPN9999888", "SendMethodId": "XTR94500", "Amount": "100.00", "LastUpdatedAt": "2026-10-27T16:20:52.7779235Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-10-27T16:20:52.7672875Z", "CompletedAt": "2026-10-27T16:20:52.7779235Z" } ] } ], "Pagination": { "HasMore": false, "NextRecordsToSkip": 0 } }Read the outcome payment by payment:
TXN-BIZ-0001, the wallet item, isSuccess: the money is in the company's Xtrm wallet.TXN-BIZ-0002, the bank item, isSuccess: the bank provider accepted the payment. That doesn't mean the funds have settled in the company's bank account yet.
The batch's own
StatusisCompletedbecause every item isSuccess. While items are still being processed it readsProcessing, including while a bank item's payment to the bank is under way, and when items fail it endsCompletedWithFailuresorFailed. Batch and payment statuses explains every value and what to do about it. WhenPagination.HasMoreistrue, passPagination.NextRecordsToSkipasrecordsToSkipto get the next page. To check one payment, call the payment status endpoint with theCustomerBatchIdandCustomerTransactionId. It also returnsDeliveryType, which isBankfor this bank item andWalletfor the wallet item. While Xtrm pays the money on to the company's bank, the bank item showsRetainedInWallet, withDeliveryTypeWallet, usually only briefly. Don't act on it while the batch is stillProcessing; for what to do if it stays, see What can go wrong.Webhooks. Xtrm can also notify your server with webhooks as it processes each payment, signed with HMAC-SHA256 in
X-Signature. Xtrm sets up one endpoint per company account, in the sandbox and in production: send your endpoint URL to your Account Manager or Customer Success Manager, or to [email protected], and Xtrm support configures it and sets up its signing secret with you. See Webhooks. No event reportsRetainedInWallet. A bank item'sBatch.Item.CompletedhasStatusSuccesswhether or not the bank payment went through, so read itsDeliveryType:Bankmeans it did, andWalletmeans it didn't and the item staysRetainedInWallet. Confirm final statuses with the status endpoints.
#What can go wrong
While you onboard the company
- A search with no criteria.
CheckBeneficiaryExistneeds at least one ofCompanyNameandCompanyEmailDomain. - A search that returns more than you expect. A name search, a shared email domain or a search with both fields can return several companies. Search with the domain alone, and check
EmailandNamebefore you use anAccountNumber(see step 1). - A second account for the same business. If the search finds the company, pay that account number instead of creating another (see step 1).
- Linking the bank is refused.
Not authorized to access this resource. Make One Time Password API Call to access this resource(HTTP400) means the company isn't connected to yours: connect it first with Connect existing accounts. AnErrorslist of fields means the bank needs more information: add them and send the whole request again. - Not checking
OperationStatus. Each onboarding response carriesOperationStatus; we recommend checkingOperationStatus.Successbefore you use a result and loggingErrorswhen it'sfalse. A failed onboarding call, such as aLinkBankBeneficiaryrequest Xtrm can't accept, answers HTTP400withSuccess: false, so check the HTTP status as well. On success,Errorscan benull,[]or[""], depending on the endpoint. See Errors.
While you pay it
- Rejected items, or a refused request. Items that fail the first checks come back in
Rejected, and the other items are still accepted. A problem with the batch as a whole refuses the whole request and stores nothing: for example a missingSourceWalletIdorCustomerBatchId(422), a source wallet that isn't yours (403) or aCustomerBatchIdthat's already in use (409 CONFLICT_PROCESSING). See Items rejected at submission and The whole batch is refused. - A timeout or a lost response. Wait and resend the identical request with the same
CustomerBatchIdandCustomerTransactionIdvalues; Xtrm never stores an item twice. See A safe retry pattern. - A company that can't be paid.
RECIPIENT_NOT_FOUNDmeans theRecipientIddoesn't exist or its status isn't Active, Email not verified or Account pending approval, andSENDMETHODID_NOT_FOUNDmeans the send method doesn't fit a company (step 6). Both happen before any money moves. Pay the correct account or method as a new item with a newCustomerTransactionId. - A failed item. An item that can't be paid ends
Failed, and its attempt'sErrorCodesays why (see Error codes on attempts). For example,BANKID_INVALIDmeans the bank you named isn't linked to the company or was deleted, andINSUFFICIENT_BALANCEmeans your source wallet was short when Xtrm paid the item. Fix the cause, then resubmit only the failed items under the sameCustomerBatchIdandCustomerTransactionId, with every field. See Resubmit failed payments and Retries & idempotency. - A bank item that stays
RetainedInWallet. While the batch isProcessing, the bank payment is still under way, so wait. If the item is stillRetainedInWalletonce the batch status is final, the bank payment didn't go through, and the money is in the company's Xtrm wallet. Record it as final and don't resubmit it: the money has left your wallet, and the fee isn't refunded. Treat it like a wallet payment: the company can transfer it out itself in the Xtrm web app, or you can request the transfer for it withBeneficiaryCompanyWithdrawFundand its one-time password. That transfer is made only when a response hasPaymentStatusCompletedand aPaymentTransactionId: the first response, withSuccess: true, only sends the code. See When a payment stays RetainedInWallet. - The bank you named is ignored. If a bank item also sends a
WalletIdwhoseAllowWalletLinkedBankOverrideisfalse, Xtrm pays the wallet's linked bank instead of theBeneficiaryBankIDyou name, without an error, and fails the item withDEFAULT_BANK_NOT_FOUNDif the wallet has none. LeaveWalletIdout of bank items unless you want the wallet's bank. See Bank transfer.
#Next steps
Pay many companies and people in one request, with every send method.
How batch payments workThe batch lifecycle, wallet-first processing and how your IDs are used.
Batch and payment statusesWhat each batch and payment status means.
WebhooksGet notified as payments complete or fail, alongside the status calls.
Complete the advanced profileSubmit the KYC/KYB application a company completes to pay recipients.
Track & reconcile paymentsMatch Xtrm's records to the IDs you stored with each payment.
Bank accounts & transfersLink bank accounts, and transfer money from Xtrm wallets to them.
Retries & idempotencyResubmit failed payments and timed-out requests without paying twice.
For every field, see the reference page for batch payments, business recipients or wallets.