Pay individual recipients
Paying a person through Xtrm takes a handful of calls: find or create their account, tell Xtrm where the money should go, and pay them in a batch, one request that can pay many recipients at once. This guide follows one person, Jane Doe, from first lookup to confirmed payment. You look her up by email, create her account, link her bank account, and pay her into her Xtrm wallet and her bank in the same batch. Then you confirm that each payment landed, with the status endpoints or a webhook. Each request runs on its own against the sandbox, so you can follow along one step at a time.
The same request pays one person or many, up to your account's limit of items per batch. A batch pays existing Xtrm accounts only, by their account numbers, so each person needs an account before you build the batch: you find it in step 1, or create it with CreateUser 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. Your client ID and secret from Settings → Integrations → Get Credentials in the sandbox web app, with your IP addresses approved. See Sandbox & environments.
- An access token in the
XTRM_ACCESS_TOKENenvironment variable. Every request in this guide sends it asAuthorization: Bearer <token>. See Authentication. - Your company account number. It starts with
SPNand goes inIssuerAccountNumber. The samples useSPN1111222. - A funded company wallet to pay from, and its wallet ID. The wallet you pay from sets the currency of the whole batch.
GetCompanyWalletslists your wallets with their currencies and balances. In the sandbox, Xtrm credits test funds to your wallets after it approves your IP addresses (see Test funds); to add more, see Fund your wallet. The samples use wallet122181. - The person's details: email address, legal first and last name, and country of residence.
- For the bank payment, the person's bank account: the bank's name, routing number and account number, with the account holder's phone number and address.
#The flow at a glance
| Step | Call | Keep from the response |
|---|---|---|
| 1 | CheckUserExist | AccountNo, if the person already has an account |
| 2 | CreateUser, only if needed | UserID of the new account |
| 3 | GetPaymentMethods, optional | The send method IDs: XTR94502 (wallet) and XTR94500 (bank) |
| 4 | GetUserWallets, optional | The WalletID in the batch's currency |
| 5 | LinkBankBeneficiary | BeneficiaryId of the linked bank |
| 6 | GetLinkedBankAccounts | The bank's BeneficiaryId and its rails in PaymentMethods |
| 7 | BatchTransfer | CustomerBatchId, and which items are in Accepted and Rejected |
| 8 | Batch status | The batch's Status and each item's Status |
| 9 | Payment status | The item's Status, DeliveryType and Attempts |
| 10 | GetUserWalletBalance, optional | Balance |
#Pay an individual recipient
- Check whether the person already has an account
Look the person up by email with
CheckUserExistbefore you create anything. That way you don't open a second account for an email address that already has one. To page through every individual recipient associated with your company instead, useGetPersonalBeneficiaries.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckUserExist" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "CheckUserExist": { "request": { "IssuerAccountNumber": "SPN1111222", "Email": "[email protected]" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckUserExist', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ CheckUserExist: { request: { IssuerAccountNumber: 'SPN1111222', Email: '[email protected]', }, }, }), }); 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/CheckUserExist", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "CheckUserExist": { "request": { "IssuerAccountNumber": "SPN1111222", "Email": "[email protected]", }, }, }, ) 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 = """ { "CheckUserExist": { "request": { "IssuerAccountNumber": "SPN1111222", "Email": "[email protected]" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckUserExist", 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 = """ { "CheckUserExist": { "request": { "IssuerAccountNumber": "SPN1111222", "Email": "[email protected]" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Beneficiary/CheckUserExist")) .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/CheckUserExist'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'CheckUserExist' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'Email' => '[email protected]', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Jane is new to Xtrm, so no account matches. The call returns HTTP
200withSuccesstrueandBeneficiaryset tonull:Response{ "CheckUserExistResponse": { "CheckUserExistResult": { "Beneficiary": null, "OperationStatus": { "Success": true, "Errors": null } } } }When accounts match the email address exactly,
Beneficiaryis an array of up to 30 of them, in no set order. Each entry has the account number inAccountNo(aPATnumber),Name,State,Country(the full country name),Employer,StatusandAccountIdentityLevel, the account's identity verification level:Draft,Basic,StandardorAdvanced. If you get more than one, confirm with the person which account to pay rather than picking one.Handle the outcomes separately:
OperationStatus.SuccessistrueandBeneficiaryisnullor empty. The person is new. Continue with step 2.SuccessistrueandBeneficiaryhas an entry. The person already has an account, so don't create another. Use itsAccountNoas theRecipientIdof your items, skip step 2, and read the note below.Successisfalse. LogOperationStatus.Errorsand stop. Don't callCreateUseruntil you know why the lookup failed: a failed call doesn't necessarily mean that no account exists.
If the person already has an account
You can pay an existing account straight away with a wallet item whose
Destinationis 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. Listing the person's wallets (step 4) works without a connection too. Linking and reading their bank account (steps 5 and 6) and reading their balance (step 10) need the account to be connected to your company. An account you create is connected from the start. To connect an existing one, its holder gives you a one-time password: see Connect existing accounts, and for what a connection allows, Connections and manager services. - Create the individual recipient
If no account exists, create one with
CreateUser. The required fields areIssuerAccountNumber,EmailAddress,EmailNotification,LegalFirstName,LegalLastNameand the country inAddress.CountryISO2. The sample also sends a street address and a date of birth, which takes separateDay,MonthandYearstrings. You can addMobilePhone(without the country code, which Xtrm derives from the country) andTaxId.Set
EmailNotificationto"true"to email the person that their account was created. Xtrm also creates a wallet for the new account, namedWallet - <currency code>, in the currency of the country you send inAddress.CountryISO2, plus aWallet - USDwallet when that currency isn't USD.Each email address can belong to only one personal account, and the sandbox is shared, so in the sandbox use an address of your own that has no Xtrm account yet. If the address already has one,
CreateUseranswers400withEmail Already Exists: look the account up as in step 1 and pay it instead.No test accounts in production
Xtrm reviews every new personal account with identity checks (KYC: confirming that a person is who they say they are), so submit real, accurate information. Don't create test accounts or test email addresses in production.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Register/CreateUser" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "CreateUser": { "request": { "IssuerAccountNumber": "SPN1111222", "EmailAddress": "[email protected]", "EmailNotification": "true", "LegalFirstName": "Jane", "LegalLastName": "Doe", "Address": { "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US" }, "DateOfBirth": { "Day": "15", "Month": "08", "Year": "1990" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Register/CreateUser', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ CreateUser: { request: { IssuerAccountNumber: 'SPN1111222', EmailAddress: '[email protected]', EmailNotification: 'true', LegalFirstName: 'Jane', LegalLastName: 'Doe', Address: { AddressLine1: '123 Main Street', City: 'Los Angeles', Region: 'CA', PostalCode: '90001', CountryISO2: 'US', }, DateOfBirth: { Day: '15', Month: '08', Year: '1990', }, }, }, }), }); 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/Register/CreateUser", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "CreateUser": { "request": { "IssuerAccountNumber": "SPN1111222", "EmailAddress": "[email protected]", "EmailNotification": "true", "LegalFirstName": "Jane", "LegalLastName": "Doe", "Address": { "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US", }, "DateOfBirth": { "Day": "15", "Month": "08", "Year": "1990", }, }, }, }, ) 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 = """ { "CreateUser": { "request": { "IssuerAccountNumber": "SPN1111222", "EmailAddress": "[email protected]", "EmailNotification": "true", "LegalFirstName": "Jane", "LegalLastName": "Doe", "Address": { "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US" }, "DateOfBirth": { "Day": "15", "Month": "08", "Year": "1990" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Register/CreateUser", 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 = """ { "CreateUser": { "request": { "IssuerAccountNumber": "SPN1111222", "EmailAddress": "[email protected]", "EmailNotification": "true", "LegalFirstName": "Jane", "LegalLastName": "Doe", "Address": { "AddressLine1": "123 Main Street", "City": "Los Angeles", "Region": "CA", "PostalCode": "90001", "CountryISO2": "US" }, "DateOfBirth": { "Day": "15", "Month": "08", "Year": "1990" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Register/CreateUser")) .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/Register/CreateUser'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'CreateUser' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'EmailAddress' => '[email protected]', 'EmailNotification' => 'true', 'LegalFirstName' => 'Jane', 'LegalLastName' => 'Doe', 'Address' => [ 'AddressLine1' => '123 Main Street', 'City' => 'Los Angeles', 'Region' => 'CA', 'PostalCode' => '90001', 'CountryISO2' => 'US', ], 'DateOfBirth' => [ 'Day' => '15', 'Month' => '08', 'Year' => '1990', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "CreateUserResponse": { "CreateUserResult": { "UserID": "PAT9999888", "AccountIdentityLevel": "Basic", "OperationStatus": { "Success": true, "Errors": null } } } }Keep
UserID, the new account number (PAT9999888). It's theRecipientIdof your items.AccountIdentityLevelis the account's identity verification level:Draft,Basic,StandardorAdvanced. This sample sends noTaxId, so the new account isBasic; with a tax ID as well as the address and date of birth, it would beStandard. We recommend storing thePATnumber with the person's record in your system, so later payments to them can skip steps 1 and 2.CreateUseralso connects the new account to your company, which steps 5, 6 and 10 need. Xtrm approves an account 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. - Look up the send method IDs
Each item in a batch names how the money is delivered in
SendMethodId. Take the IDs fromGetPaymentMethods: it lists exactly the seven send methods a batch accepts. The call takes an empty JSON object,{}, as the body and returns the same list for every account, so this step is optional: use it to confirm the IDs when you set up your integration.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Payment/GetPaymentMethods" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Payment/GetPaymentMethods', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({}), }); 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/Payment/GetPaymentMethods", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={}, ) 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 = """ {} """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Payment/GetPaymentMethods", 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 = """ {} """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Payment/GetPaymentMethods")) .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/Payment/GetPaymentMethods'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(new stdClass()), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetPaymentMethodsResponse": { "PaymentMethodResult": { "PaymentMethods": { "PaymentMethodDetails": [ { "PaymentMethodId": "XTR94504", "PaymentMethodName": "AnyPay Company" }, { "PaymentMethodId": "XTR94502", "PaymentMethodName": "AnyPay Individual" }, { "PaymentMethodId": "XTR94500", "PaymentMethodName": "Bank" }, { "PaymentMethodId": "XTR94507", "PaymentMethodName": "Bank Check" }, { "PaymentMethodId": "XTR94505", "PaymentMethodName": "Digital Gift Cards" }, { "PaymentMethodId": "XTR94503", "PaymentMethodName": "Prepaid Virtual Debit Card" }, { "PaymentMethodId": "XTR94508", "PaymentMethodName": "Rapid Transfer" } ] }, "OperationStatus": { "Success": true, "Errors": null } } } }This guide uses two of them:
XTR94502(AnyPay Individual) pays into the person's Xtrm wallet. Xtrm recommends paying into the wallet, because the person then chooses how to transfer the funds out of Xtrm. It pays individual recipients only: the item'sRecipientIdmust start withPAT, or the item is rejected when you submit. To pay a business recipient's wallet, useXTR94504(see Pay business recipients).XTR94500(Bank) pays through to a bank account linked to the person's account.
Send each ID exactly as listed, in capitals. You can also pay a person by prepaid card (
XTR94503), gift card (XTR94505), check (XTR94507, US only) or Rapid Transfer to a card (XTR94508); see Payment methods & destinations. Don't take send method IDs fromGetUserPaymentMethods: it lists the ways a person can move their own money, and it includesXTR94506(Reward Link), which a batch rejects. See Choose a payment method list. - Find the person's wallet
A wallet item pays into one of the person's wallets, which you name in
Destination.WalletId. That field is optional: without it, Xtrm picks the wallet for you (see step 7). To pay into a specific wallet, list the person's wallets withGetUserWallets. Send thePATnumber inUserID, and note the capitalRin this endpoint'sRequestobject. This call needs no connection to the person.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWallets" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetUserWallets": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWallets', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetUserWallets: { Request: { IssuerAccountNumber: 'SPN1111222', UserID: '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/Wallet/GetUserWallets", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetUserWallets": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "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 = """ { "GetUserWallets": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWallets", 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 = """ { "GetUserWallets": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWallets")) .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/GetUserWallets'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetUserWallets' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT9999888', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetUserWalletsResponse": { "GetUserWalletsResult": { "Wallets": [ { "WalletName": "Wallet - USD", "WalletID": 67812, "WalletCurrency": "USD" } ], "OperationStatus": { "Success": true, "Errors": null } } } }Jane's new account has one wallet, the USD wallet that
CreateUserset up for her. An individual recipient has one wallet per currency. Keep theWalletIDof the wallet in the batch's currency:67812here. You send it as a number inDestination.WalletIdtoo. The response doesn't include balances. Step 10 shows how to get one. - Link the person's bank account
A bank item pays a bank account linked to the person's account, which you name by its ID. Jane's account is new, so link her bank account with
LinkBankBeneficiary, sending herPATnumber inUserID. Linking needs her account to be connected to your company, and an account you created withCreateUseris. The body has two parts:BeneficiaryInformation, the account holder and their address, andBeneficiaryBankInformation, the bank account.WithdrawTypesets how the money moves to the bank,ACHhere. 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": "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 (907599f594b044d08cf81a2afb0a7967). It's theBeneficiaryBankIDof your bank item.AccountIdentityLevelis the person's identity verification level. A person can have up to 3 linked 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 bank accounts linked to the person inRecipientUserId, each with its ID and the rails it supports. Use it to confirm the bank you linked, and to find the bank again for later payments without linking it twice. Like linking, it needs the account to be connected to your company.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 the bank's
BeneficiaryIdand thePaymentMethodsarray insideBankDetails, not thePaymentMethodsobject on the entry. The response has no field namedBeneficiaryBankID:BeneficiaryIdis the value you send asDestination.BeneficiaryBankID. You can name one of the bank's rails 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. - Pay the person in a batch
Submit the payments with
BatchTransfer(POST /API/v4/Fund/BatchTransfer). Unlike the other calls in this guide, the body has no wrapper object: the batch's fields sit at the root.Field Sample value What it is IssuerAccountNumberSPN1111222Your company account number. Required. SourceWalletId122181The company wallet that funds the batch, as an integer. It sets the batch's currency. Required. CustomerBatchIdBATCH-USERS-0001Your ID for the batch. Required: Xtrm never generates one, and you need it to check the status. Items[].CustomerTransactionIdTXN-USERS-0001Your ID for the item. Required: Xtrm never generates one. You use it to look the item up and match it to your records. Items[].RecipientIdPAT9999888The person's account number from step 1 or 2. Required. Items[].Amount50The amount, as a JSON number greater than 0. Send at most 2 decimal places. Required. Items[].SendMethodIdXTR94502How the money is delivered (step 3). Required. Items[].Destination{"WalletId": 67812}Delivery details for the send method. Required on every item: for a wallet item without a WalletId, send{}.Items[].DescriptionTXN-USERS-0001 Q3 sales bonusA note for the payment, up to 1,024 characters. Optional. Xtrm copies it to the wallet transactions the payment creates: the debit in your source wallet and the credit in the person's wallet, where the person sees it. Start it with the item's CustomerTransactionId, as the samples do, so you can find those transactions later; see Track & reconcile payments.The sample batch makes two payments to Jane:
- A wallet item (
XTR94502) pays USD 50.00 into her USD wallet67812, from step 4. To let Xtrm choose the wallet instead, send an emptyDestination,{}: Xtrm then credits her oldest active Standard wallet in the batch's currency, and creates one namedWallet - <currency code>if she has none. AWalletIdyou send must be an active wallet of hers in the batch's currency, or the item fails withINVALID_BENEFICIARY_WALLETbefore any money moves. - A bank item (
XTR94500) pays USD 100.00 by ACH to her bank account907599f594b044d08cf81a2afb0a7967, from steps 5 and 6. For an individual recipient,BeneficiaryBankIDis required: Xtrm never falls back to a default bank for a person.
To pay more people, add one item per payment. Every item can use its own send method. Give every payment its own
CustomerTransactionId, and never reuse one for a different payment, even in another batch. For the ID rules, see Batch and payment identifiers.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-USERS-0001", "Items": [ { "CustomerTransactionId": "TXN-USERS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": { "WalletId": 67812 }, "Description": "TXN-USERS-0001 Q3 sales bonus" }, { "CustomerTransactionId": "TXN-USERS-0002", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH" }, "Description": "TXN-USERS-0002 Q3 sales bonus" } ] }'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-USERS-0001', Items: [ { CustomerTransactionId: 'TXN-USERS-0001', RecipientId: 'PAT9999888', Amount: 50, SendMethodId: 'XTR94502', Destination: { WalletId: 67812, }, Description: 'TXN-USERS-0001 Q3 sales bonus', }, { CustomerTransactionId: 'TXN-USERS-0002', RecipientId: 'PAT9999888', Amount: 100, SendMethodId: 'XTR94500', Destination: { BeneficiaryBankID: '907599f594b044d08cf81a2afb0a7967', BeneficiaryBankPaymentMethod: 'ACH', }, Description: 'TXN-USERS-0002 Q3 sales bonus', }, ], }), }); 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-USERS-0001", "Items": [ { "CustomerTransactionId": "TXN-USERS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": { "WalletId": 67812, }, "Description": "TXN-USERS-0001 Q3 sales bonus", }, { "CustomerTransactionId": "TXN-USERS-0002", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH", }, "Description": "TXN-USERS-0002 Q3 sales bonus", }, ], }, ) 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-USERS-0001", "Items": [ { "CustomerTransactionId": "TXN-USERS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": { "WalletId": 67812 }, "Description": "TXN-USERS-0001 Q3 sales bonus" }, { "CustomerTransactionId": "TXN-USERS-0002", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH" }, "Description": "TXN-USERS-0002 Q3 sales bonus" } ] } """; 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-USERS-0001", "Items": [ { "CustomerTransactionId": "TXN-USERS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": { "WalletId": 67812 }, "Description": "TXN-USERS-0001 Q3 sales bonus" }, { "CustomerTransactionId": "TXN-USERS-0002", "RecipientId": "PAT9999888", "Amount": 100, "SendMethodId": "XTR94500", "Destination": { "BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967", "BeneficiaryBankPaymentMethod": "ACH" }, "Description": "TXN-USERS-0002 Q3 sales bonus" } ] } """; 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-USERS-0001', 'Items' => [ [ 'CustomerTransactionId' => 'TXN-USERS-0001', 'RecipientId' => 'PAT9999888', 'Amount' => 50, 'SendMethodId' => 'XTR94502', 'Destination' => [ 'WalletId' => 67812, ], 'Description' => 'TXN-USERS-0001 Q3 sales bonus', ], [ 'CustomerTransactionId' => 'TXN-USERS-0002', 'RecipientId' => 'PAT9999888', 'Amount' => 100, 'SendMethodId' => 'XTR94500', 'Destination' => [ 'BeneficiaryBankID' => '907599f594b044d08cf81a2afb0a7967', 'BeneficiaryBankPaymentMethod' => 'ACH', ], 'Description' => 'TXN-USERS-0002 Q3 sales bonus', ], ], ]), 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. If at least one item passes, it queues the items that passed and responds
202. If none passes, it stores nothing and responds422, or409when an item already exists in this batch; see What can go wrong. When both items pass, the response lists them inAccepted, with theCurrencyof your source wallet and eachAmountas a JSON number with the decimals you sent, so the50and100here come back as50.0and100.0:Response (excerpt){ "BatchTransferResponse": { "CustomerBatchId": "BATCH-USERS-0001", "Status": "Accepted", "Accepted": [ { "CustomerTransactionId": "TXN-USERS-0001", "Amount": 50.0, "Currency": "USD", "SendMethodId": "XTR94502", "RecipientId": "PAT9999888" }, { "CustomerTransactionId": "TXN-USERS-0002", "Amount": 100.0, "Currency": "USD", "SendMethodId": "XTR94500", "RecipientId": "PAT9999888" } ], "Rejected": [] } }Keep
CustomerBatchIdand eachCustomerTransactionIdwith your payment records. A202means Xtrm received the batch, not that anyone has been paid: Xtrm checks your balance and moves the money while it processes the items in the background. Confirm the outcome with the status calls in the next steps. An item inRejectedwasn't stored; its entry names theFieldthat failed and aMessage. To fix and resend such items, see Items rejected at submission.Both items credit Jane's Xtrm wallet first. For the bank item, Xtrm then pays the money on to her bank. While it does, the bank item shows
RetainedInWallet, usually only briefly, and then moves on toSuccess, so don't act onRetainedInWalletwhile the batch is stillProcessing. If the item is stillRetainedInWalletonce the batch status is final, the bank payment didn't go through: the money has left your wallet and stays in Jane's Xtrm wallet, the fee isn't refunded, and you can't retry or resubmit the item. Treat it like a wallet payment: Jane can transfer it out herself in the Xtrm web app, or you can request the transfer for her with her one-time password; see When a payment stays RetainedInWallet. - A wallet item (
- Check the batch status
Poll the batch status endpoint,
GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}, with your ownCustomerBatchId. If you've turned on webhooks, use this call to confirm final statuses. It returns a summary of the batch and a page of its items. Page through the items withrecordsToSkipandrecordsToTake, and sethistorytotrueto include each item's processing attempts. The request has no body.curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-USERS-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-USERS-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-USERS-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-USERS-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-USERS-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-USERS-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-USERS-0001", "Status": "Completed", "Currency": "USD", "ItemsCount": 2, "Items": [ { "CustomerTransactionId": "TXN-USERS-0001", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94502", "Amount": "50.00", "LastUpdatedAt": "2026-10-27T15:04:12.4410275Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-10-27T15:04:12.4362214Z", "CompletedAt": "2026-10-27T15:04:12.4410275Z" } ] }, { "CustomerTransactionId": "TXN-USERS-0002", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94500", "Amount": "100.00", "LastUpdatedAt": "2026-10-27T15:04:19.8820431Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-10-27T15:04:19.8761390Z", "CompletedAt": "2026-10-27T15:04:19.8820431Z" } ] } ], "Pagination": { "HasMore": false, "NextRecordsToSkip": 0 } }How to read it:
- Batch
StatusisProcessingwhile items are still being processed, including while a bank item's payment to the bank is under way. It'sCompletedhere because every item isSuccess; otherwise it endsCompletedWithFailuresorFailed. - Item
Statusmoves fromAcceptedtoProcessing(this endpoint can also showVerified). A bank item then passes throughRetainedInWalletwhile Xtrm pays her bank. Each item endsSuccessorFailed, except a bank item whose bank payment didn't go through: it is stillRetainedInWalletonce the batch status is final. For a bank item,Successmeans the bank provider accepted the payment, not that the funds have settled. For what each status means and what to do next, see Batch and payment statuses. Attempts[].ErrorCodeisSUCCESSon a successful attempt, and says why an attempt failed otherwise. See Error codes on attempts.Pagination.HasMoreistruewhen more items remain. PassPagination.NextRecordsToSkipasrecordsToSkipon your next call.
Keep each item's
Status. To look at one payment on its own, use the next step. - Batch
- Check one payment's attempts
To see what happened to a single payment, call the payment status endpoint,
GET /API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}, withhistory=true. The sample checks the bank item,TXN-USERS-0002.curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-USERS-0001/Items/TXN-USERS-0002?history=true" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-USERS-0001/Items/TXN-USERS-0002?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-USERS-0001/Items/TXN-USERS-0002?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-USERS-0001/Items/TXN-USERS-0002?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-USERS-0001/Items/TXN-USERS-0002?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-USERS-0001/Items/TXN-USERS-0002?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));Here is the
history=trueresponse for the bank item:Response{ "CustomerBatchId": "BATCH-USERS-0001", "CustomerTransactionId": "TXN-USERS-0002", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94500", "Amount": "100.00", "Currency": "USD", "DeliveryType": "Bank", "LastUpdatedAt": "2026-10-27T15:04:19.882Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-10-27T15:03:58.1027734Z", "CompletedAt": "2026-10-27T15:04:19.882Z" } ] }Statusis the item's current status: here,Success.DeliveryTypeshows where the money went once the item isSuccess:Bankfor this bank item,Walletfor a wallet item. ARetainedInWalletitem showsWallet, both while the bank payment is under way and after it has stuck, and anAccepted,ProcessingorFaileditem an empty string.Attemptsis the item's attempt history, oldest first. This item succeeded on its first attempt. If you resubmit a failed item, each try is a new attempt with the nextAttemptNo. This endpoint repeats the item's own times in every attempt'sCreatedAtandCompletedAt, so identify and order attempts byAttemptNo. To retry a failed item, see Retrying an item.
Keep
Status,DeliveryTypeandLastUpdatedAtwith your payment record. - Check the wallet balance
This step is optional. Money from a wallet item is in the person's wallet.
GetUserWalletBalancereturns the balance of the person's wallet in one currency. Send thePATnumber inUserId(lowercasedon this endpoint) and the batch's currency. Like linking a bank, it needs the person's account to be connected to your company.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT9999888", "Currency": "USD" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetUserWalletBalance: { request: { IssuerAccountNumber: 'SPN1111222', UserId: 'PAT9999888', Currency: 'USD', }, }, }), }); 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/GetUserWalletBalance", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT9999888", "Currency": "USD", }, }, }, ) 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 = """ { "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT9999888", "Currency": "USD" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance", 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 = """ { "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT9999888", "Currency": "USD" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance")) .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/GetUserWalletBalance'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetUserWalletBalance' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserId' => 'PAT9999888', 'Currency' => 'USD', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "UserWalletBalnceResponse": { "UserWalletBalanceResult": { "Balance": 50.00, "Currency": "USD", "OperationStatus": { "Success": true, "Errors": null } } } }Balanceis the wallet's current available balance, as a JSON number. Here it's50.00: Jane's new wallet holds the wallet item, while the bank item passed through it on its way to her bank. The response wrapper is spelledUserWalletBalnceResponse, so read it exactly as returned.The balance covers everything in the wallet, not only your payments, so confirm a specific payment with its payment status (step 9). To find individual payments in wallet transaction lists, see Track & reconcile payments.
#Get updates by webhook
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 for the events, payloads and signature verification. No event reports RetainedInWallet. A bank item's Batch.Item.Completed has Status Success whether or not the bank payment went through, so read its DeliveryType: Bank means it did, and Wallet means it didn't and the item stays RetainedInWallet. Confirm each final status with the payment status endpoint (step 9).
#What can go wrong
#Items are rejected when you submit the batch
Items that fail the first checks come back in Rejected with the Field and a Message, and the other items of the batch are still accepted. For this guide's items, common causes are an XTR94502 item whose RecipientId doesn't start with PAT, a bank item with neither BeneficiaryBankID nor WalletId, a SendMethodId that isn't exactly one of the seven IDs from step 3, a missing Destination, or a CustomerTransactionId used twice in one request. To fix and resend them, see Items rejected at submission.
#The whole request fails
When the batch itself is invalid, or no item passes, Xtrm stores nothing. Common causes are a missing or invalid IssuerAccountNumber, CustomerBatchId or SourceWalletId (422), a source wallet that isn't yours (403), a CustomerBatchId that's already in use (409 CONFLICT_PROCESSING) and more items than your account's limit (422 LIMIT_EXCEEDED). See The whole batch is refused. If a submit call times out, wait and resend the identical request with the same IDs; see A safe retry pattern.
#Linking the bank fails
Not authorized to access this resource. Make One Time Password API Call to access this resource(HTTP400): the person's account isn't connected to your company. Connect it first with Connect existing accounts.Errorsnames one or more fields (HTTP400,Successfalse): the bank needs more information. Add the fields and send the whole request again; see Bank accounts & transfers.
#An item fails during processing
An accepted item can still end Failed, because some checks, such as the bank checks, run only while Xtrm processes the item. Its attempt's ErrorCode says why; for every code, see Error codes on attempts. The ones this guide's items can hit:
RECIPIENT_NOT_FOUND: theRecipientIddoesn't exist, or its status isn't Active, Email not verified or Account pending approval. Pay the correct account as a new item with a newCustomerTransactionId.BENEFICIARY_BANKID_REQUIREDorBANKID_INVALID: the bank item sent aWalletIdbut noBeneficiaryBankID, or named a bank that isn't linked to the person's account or was deleted. Both happen before any money moves. Check the ID withGetLinkedBankAccounts(step 6), then resubmit the item.INSUFFICIENT_BALANCE: your source wallet held less than the item'sAmountplus its fee when Xtrm paid it. Nothing was debited for that item. Fund the wallet, then resubmit the item. Xtrm doesn't check your balance when you submit, so we recommend checkingWalletBalancefromGetCompanyWalletsfirst.- The bank item 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 person'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 person can transfer it out in the Xtrm web app, or you can request the transfer for them withUserWithdrawFund. That transfer is made only when a response hasPaymentStatusCompletedand aPaymentTransactionId: the first response, withSuccess: true, only sends the person a one-time password. See When a payment stays RetainedInWallet.
#Retrying an item
To retry a Failed item, submit it again under its original CustomerBatchId and CustomerTransactionId, with every field: a retry replaces the stored item, and Xtrm records a new attempt with the next AttemptNo. Send only the failed items. If the latest attempt failed with TEMPORARY_ERROR, contact Xtrm support before you retry. For the full rules, see Resubmit failed payments and Retries & idempotency.
#Other things to watch
- No account matches the email address, or the lookup fails. Treat the person as new only when
SuccessistrueandBeneficiaryisnullor empty; whenSuccessisfalse, logOperationStatus.Errorsand find out why before you callCreateUser. See step 1. - Check
OperationStatuson every response. ForCheckUserExist,CreateUser,GetPaymentMethods,GetUserWallets,LinkBankBeneficiary,GetLinkedBankAccountsandGetUserWalletBalance, we recommend checkingOperationStatus.Successas well as the HTTP status, and loggingOperationStatus.Errorswhen it'sfalse. On a successful call,Errorsisnullor an empty array[], depending on the endpoint, so decide withSuccess. The batch payment endpoints have noOperationStatus: check the HTTP status andRejected. See Errors. - The balance shows a different currency.
CreateUsercreates a wallet in the currency of the person's country, but a batch pays in the currency of your source wallet. AskGetUserWalletBalancefor the batch's currency. - Field names and types that differ between calls. Send and read names exactly as shown:
Request(capitalR) andUserIDinGetUserWallets,UserIDinLinkBankBeneficiarybutRecipientUserIdinGetLinkedBankAccounts,requestandUserIdinGetUserWalletBalance, and theUserWalletBalnceResponsewrapper. The samples write the query parametersrecordsToSkip,recordsToTakeandhistoryin lowercase; Xtrm accepts any case.Amountis a JSON number in the batch request and the202response, which echoes the decimals you sent. The status responses return it as a string with 2 decimals: with a thousands separator on the batch status endpoint ("1,234.56") and without one on the payment status endpoint ("1234.56"), so strip separators before you parse it.WalletIDinGetUserWalletsandWalletIdinDestinationare both numbers.ItemsCountis an object in the202response but a number in the batch status.
#Next steps
Pay many recipients in one request, with every send method, and track each payment.
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, and which ones are final.
WebhooksReceive batch and payment events and verify their signatures.