Quickstart
Your first batch payment is a handful of calls away.
You'll get an access token, find the wallet your payments come from, create an individual recipient and pay her USD 50.00 straight into her Xtrm wallet. Then you'll check that the money arrived.
A wallet payment needs nothing but the recipient's account number, so it's the quickest way to see the whole flow work. Submit the batch and Xtrm answers right away, then pays each recipient in the background. When you're ready for bank accounts, cards, mixed payment methods and retries, carry on with Create a batch payment.
If you're a managing platform
Run this quickstart with a client company's pseudo credentials and its SPN, once the company is approved. Pseudo credentials require manager services, which Xtrm turns on for your company. See Onboard a client company.
#What you'll do
| Step | Call | What you get back |
|---|---|---|
| Get an access token | POST /oAuth/token | access_token for every other call |
| Find your source wallet | POST /Wallet/GetCompanyWallets | The WalletID you pay from |
| Create a recipient | POST /Register/CreateUser | The recipient's account number, UserID |
| Submit the batch payment | POST /Fund/BatchTransfer | 202 Accepted, with the payments accepted and rejected |
| Check the batch status | GET /Fund/BatchTransfer/{CustomerBatchId} | The status of the batch and of each payment |
Prefer Postman?
Import the whole API into Postman: choose Import, then paste https://www.xtrm.com/developers/xtrm-api-v4.postman_collection.json. Set the collection variables client_id and client_secret, then send Get or renew an access token. The token is saved and used by every other request.
#Before you begin
You need:
- A sandbox company account with API credentials (a client ID and a client secret). The first step summarizes how to get them.
- Your company's Xtrm account number. Company account numbers start with
SPN. Contact [email protected] if you don't know yours. - cURL, or one of: Node.js 18+, Python 3 with
requests, .NET 8, Java 17+, PHP 8 with the curl extension. The cURL samples use bash syntax.
The samples use these example values. Replace them with your own:
| Value | Example |
|---|---|
| Your company's account number | SPN1111222 |
| Your source wallet | 122181, a USD wallet |
| Your recipient | Jane Doe, [email protected], who gets the account number PAT9999888 |
Create test recipients in the sandbox only
Xtrm reviews every new recipient for KYC compliance: identity checks that confirm each recipient is who they say they are. Don't create test individuals, test companies or test email addresses in production.
#Pay your first batch payment
- Get sandbox credentials
- Create a sandbox company account with the signup link in Get sandbox access, and open the validation link Xtrm emails you. The Xtrm team then approves your account.
- Log in to the sandbox web app at
https://sandbox.xtrm.com, go to Settings > Integrations and click Get Credentials. Copy your client ID and client secret, and request the IP addresses you'll call the API from.
Once Xtrm approves your IP addresses, it credits test funds to your sandbox wallets. That's the money your first batch payment pays. No real money moves in the sandbox; see Sandbox & environments.
- Set your environment variables
Every sample on this site reads your credentials from environment variables, so no secret ends up in your code. Set them in the terminal you'll run the samples from:
export XTRM_CLIENT_ID="YOUR_CLIENT_ID" export XTRM_CLIENT_SECRET="YOUR_CLIENT_SECRET"$env:XTRM_CLIENT_ID = "YOUR_CLIENT_ID" $env:XTRM_CLIENT_SECRET = "YOUR_CLIENT_SECRET"We recommend storing the client secret in your secret manager or deployment environment, never in code or in a committed
.envfile. - Get an access token
Exchange your client ID and secret for an access token. The token endpoint sits at the host root, outside
/API/v4, and takes form-encoded fields withgrant_type=password.curl -X POST "https://xapisandbox.xtrm.com/oAuth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Accept: application/json" \ --data-urlencode "grant_type=password" \ --data-urlencode "client_id=$XTRM_CLIENT_ID" \ --data-urlencode "client_secret=$XTRM_CLIENT_SECRET"const response = await fetch('https://xapisandbox.xtrm.com/oAuth/token', { method: 'POST', headers: { Accept: 'application/json', }, body: new URLSearchParams({ grant_type: 'password', client_id: process.env.XTRM_CLIENT_ID, client_secret: process.env.XTRM_CLIENT_SECRET, }), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const { access_token } = await response.json(); console.log(access_token);import os import requests response = requests.post( "https://xapisandbox.xtrm.com/oAuth/token", headers={"Accept": "application/json"}, data={ "grant_type": "password", "client_id": os.environ["XTRM_CLIENT_ID"], "client_secret": os.environ["XTRM_CLIENT_SECRET"], }, ) response.raise_for_status() print(response.json()["access_token"])using System.Net.Http.Headers; using System.Net.Http.Json; using System.Text.Json; using var client = new HttpClient(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); var form = new FormUrlEncodedContent(new Dictionary<string, string> { ["grant_type"] = "password", ["client_id"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_ID")!, ["client_secret"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_SECRET")!, }); var response = await client.PostAsync("https://xapisandbox.xtrm.com/oAuth/token", form); response.EnsureSuccessStatusCode(); var token = await response.Content.ReadFromJsonAsync<JsonElement>(); Console.WriteLine(token.GetProperty("access_token").GetString());import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; String form = "grant_type=password" + "&client_id=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_ID"), StandardCharsets.UTF_8) + "&client_secret=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_SECRET"), StandardCharsets.UTF_8); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/oAuth/token")) .header("Content-Type", "application/x-www-form-urlencoded") .header("Accept", "application/json") .POST(HttpRequest.BodyPublishers.ofString(form)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/oAuth/token'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query([ 'grant_type' => 'password', 'client_id' => getenv('XTRM_CLIENT_ID'), 'client_secret' => getenv('XTRM_CLIENT_SECRET'), ]), CURLOPT_HTTPHEADER => [ 'Content-Type: application/x-www-form-urlencoded', 'Accept: application/json', ], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); $token = json_decode((string) $body, true); if ($status !== 200 || !isset($token['access_token'])) { fwrite(STDERR, "Token request failed (HTTP $status): $body" . PHP_EOL); exit(1); } echo $token['access_token'], PHP_EOL;Response{ "access_token": "YOUR_ACCESS_TOKEN", "token_type": "bearer", "expires_in": 86399, "refresh_token": "YOUR_REFRESH_TOKEN", ".issued": "Tue, 27 Oct 2026 14:58:21 GMT", ".expires": "Wed, 28 Oct 2026 14:58:21 GMT", "client_id": "YOUR_CLIENT_ID" }Save the
access_tokenfor the next steps. Every other call sends it in theAuthorization: Bearer <access_token>header. It lasts 24 hours; Authentication covers renewing it.export XTRM_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"$env:XTRM_ACCESS_TOKEN = "YOUR_ACCESS_TOKEN" - Find your source wallet
Every payment in a batch comes out of one of your company wallets, the source wallet, and its currency is the currency of the whole batch. List your wallets with
GetCompanyWallets, passing your company's account number asIssuerAccountNumber:curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyWallets: { request: { IssuerAccountNumber: 'SPN1111222', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyWallets' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetCompanyWalletResponse": { "CompanyWalletResult": { "CompanyWallets": { "CompanyWalletDetails": [ { "WalletID": 122181, "WalletName": "USD Wallet for Main Company", "WalletCurrency": "USD", "WalletBalance": 57715.15, "WalletType": "Standard", "IsBankLinked": false, "AllowWalletLinkedBankOverride": false, "EntityID": 12345 } ] }, "OperationStatus": { "Success": true, "Errors": null } } } }Pick a USD wallet whose
WalletBalancecovers the payment, USD 50.00 here, plus its fee: Xtrm charges each payment's fee to the source wallet on top of itsAmount. Note itsWalletID,122181in the example. You send it asSourceWalletId, a JSON number. - Create a recipient
A batch pays existing Xtrm accounts only, by their account numbers, so create the recipient before you pay her. Create Jane's personal Xtrm account 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. Xtrm creates a wallet for her in the currency of her country, USD here.Each email address can belong to only one personal account, and the sandbox is shared, so use an address of your own that has no Xtrm account yet. If the address already has one,
CreateUseranswers400withEmail Already Exists; to find and pay an existing account instead, see Pay individual recipients.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 } } } }UserIDis Jane's account number,PAT9999888. Personal account numbers start withPAT. It's theRecipientIdyou pay in the next step. Xtrm approves an account you create through the API straight away, so you can pay Jane now, without waiting for the KYC review. - Submit the batch payment
Pay Jane USD 50.00 into her Xtrm wallet with
POST /Fund/BatchTransfer. This batch,BATCH-QS-0001, has one payment,TXN-QS-0001. Unlike most Xtrm API calls, the fields sit at the root of the body, with no wrapper object.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-QS-0001", "Items": [ { "CustomerTransactionId": "TXN-QS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": {}, "Description": "TXN-QS-0001 Q3 Top Performer Contractor Reward" } ] }'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-QS-0001', Items: [ { CustomerTransactionId: 'TXN-QS-0001', RecipientId: 'PAT9999888', Amount: 50, SendMethodId: 'XTR94502', Destination: {}, Description: 'TXN-QS-0001 Q3 Top Performer Contractor Reward', }, ], }), }); 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-QS-0001", "Items": [ { "CustomerTransactionId": "TXN-QS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": {}, "Description": "TXN-QS-0001 Q3 Top Performer Contractor Reward", }, ], }, ) if not response.ok: raise RuntimeError(f"HTTP {response.status_code}: {response.text}") 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-QS-0001", "Items": [ { "CustomerTransactionId": "TXN-QS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": {}, "Description": "TXN-QS-0001 Q3 Top Performer Contractor Reward" } ] } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer", new StringContent(json, Encoding.UTF8, "application/json")); // Print the body first: on a 409 or 422 it explains why the batch or its items were rejected. Console.WriteLine(await response.Content.ReadAsStringAsync()); if (!response.IsSuccessStatusCode) { throw new HttpRequestException($"HTTP {(int)response.StatusCode}"); }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-QS-0001", "Items": [ { "CustomerTransactionId": "TXN-QS-0001", "RecipientId": "PAT9999888", "Amount": 50, "SendMethodId": "XTR94502", "Destination": {}, "Description": "TXN-QS-0001 Q3 Top Performer Contractor Reward" } ] } """; 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-QS-0001', 'Items' => [ [ 'CustomerTransactionId' => 'TXN-QS-0001', 'RecipientId' => 'PAT9999888', 'Amount' => 50, 'SendMethodId' => 'XTR94502', 'Destination' => new stdClass(), 'Description' => 'TXN-QS-0001 Q3 Top Performer Contractor Reward', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));What each field does:
IssuerAccountNumberis your company's account number, andSourceWalletIdis the wallet from step 4. The wallet must belong to your company, and its currency is the batch currency.CustomerBatchIdandCustomerTransactionIdare your own IDs for the batch and for each payment. Both are required, and Xtrm never generates them. You use them to check, reconcile and retry your payments.RecipientIdis Jane's account number from step 5, andAmountis a JSON number in the batch currency, with at most 2 decimal places.SendMethodIdXTR94502pays into an individual recipient's Xtrm wallet. It's one of the seven send methods thatGetPaymentMethodslists. SendDestinationon every item:{}lets Xtrm credit Jane's wallet in the batch currency, creating one if she has none.Descriptionis an optional note for the payment. Xtrm copies it to the wallet transactions the payment creates, in your wallet and in Jane's, where she sees it. The sample starts it with theCustomerTransactionId, which we recommend: that's how you find those transactions later. See Track & reconcile payments.
CustomerBatchIdvalues are shared across all Xtrm accounts, so replace the sample IDs with your own unique values before you run this, for example ones that include your account number or a UUID. Give every new batch a newCustomerBatchIdand every new payment a newCustomerTransactionId: Xtrm uses them to tell a new payment from a resubmitted one, so you never pay anyone twice. See Retries & idempotency.Xtrm checks the request and each payment's fields, and answers
202 Acceptedright away:Response{ "BatchTransferResponse": { "CustomerBatchId": "BATCH-QS-0001", "Status": "Accepted", "ItemsCount": { "Total": 1, "Accepted": 1, "Rejected": 0 }, "Accepted": [ { "CustomerTransactionId": "TXN-QS-0001", "Amount": 50.0, "Currency": "USD", "SendMethodId": "XTR94502", "RecipientId": "PAT9999888" } ], "Rejected": [] } }StatusAcceptedmeans your payment passed the checks and is queued. Jane hasn't been paid yet: Xtrm checks your balance and moves the money when it processes the payment, a moment later. A payment that fails the checks comes back inRejected, with theFieldandMessagethat explain why; see Errors. - Check the batch status
Get the status of the batch and its payments with
GET /Fund/BatchTransfer/{CustomerBatchId}.recordsToSkipandrecordsToTakepage through the payments, andhistory=trueadds each payment's attempts.curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-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-QS-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-QS-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-QS-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-QS-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-QS-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));Response{ "CustomerBatchId": "BATCH-QS-0001", "Status": "Completed", "Currency": "USD", "ItemsCount": 1, "Items": [ { "CustomerTransactionId": "TXN-QS-0001", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94502", "Amount": "50.00", "LastUpdatedAt": "2026-10-27T15:04:12.4410000Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-10-27T15:04:11.9820000Z", "CompletedAt": "2026-10-27T15:04:12.4410000Z" } ] } ], "Pagination": { "HasMore": false, "NextRecordsToSkip": 0 } }TXN-QS-0001readsSuccess: Xtrm credited Jane's wallet with USD 50.00. The batch readsCompletedbecause every payment in it succeeded. If the payment still readsAccepted,ProcessingorVerified, Xtrm hasn't finished with it yet: wait a few seconds and check again. A payment to a bank account or a card, or by check or gift card, also passes throughRetainedInWalleton its way toSuccess, so for those, wait until the batch no longer readsProcessingbefore you act on the payment. For what every status means, and what to do when a payment fails, see Batch and payment statuses.Instead of checking, you can have Xtrm notify your server when a payment completes. See Webhooks.
#Full example
This program puts steps 3, 6 and 7 together. It gets an access token, pays Jane USD 50.00 from your source wallet, then checks the status every 3 seconds, up to 10 times, until the payment is no longer in progress. Those timings are our choice for a demo, not API limits.
It reads XTRM_CLIENT_ID and XTRM_CLIENT_SECRET from the environment. Replace SPN1111222, 122181 and PAT9999888 with your own values, and the batch and payment IDs with your own unique ones. The program uses its own IDs, BATCH-QS-0002 and TXN-QS-0002, so it doesn't resend the batch from step 6; to run it again, change both.
#!/usr/bin/env bash
# Save as quickstart.sh and run: bash quickstart.sh
set -euo pipefail
# 1. Get an access token.
TOKEN_RESPONSE=$(curl -sS -X POST "https://xapisandbox.xtrm.com/oAuth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "grant_type=password" \
--data-urlencode "client_id=$XTRM_CLIENT_ID" \
--data-urlencode "client_secret=$XTRM_CLIENT_SECRET")
ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"access_token" *: *"\([^"]*\)".*/\1/p')
if [ -z "$ACCESS_TOKEN" ]; then
echo "Token request failed: $TOKEN_RESPONSE" >&2
exit 1
fi
# 2. Pay 50.00 USD into the recipient's wallet.
RESPONSE=$(curl -sS -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-w '\n%{http_code}' \
-d '{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-QS-0002",
"Items": [
{
"CustomerTransactionId": "TXN-QS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94502",
"Destination": {},
"Description": "TXN-QS-0002 Q3 Top Performer Contractor Reward"
}
]
}')
HTTP_CODE=${RESPONSE##*$'\n'}
echo "${RESPONSE%$'\n'*}"
if [ "${HTTP_CODE:0:1}" != "2" ]; then
echo "Batch not accepted (HTTP $HTTP_CODE)" >&2
exit 1
fi
# 3. Check the status until no payment is still in progress.
for CHECK in 1 2 3 4 5 6 7 8 9 10; do
STATUS=$(curl -sS -f "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true" \
-H "Authorization: Bearer $ACCESS_TOKEN")
if ! printf '%s' "$STATUS" | grep -Eq '"Status" *: *"(Accepted|Processing|Verified)"'; then
break
fi
sleep 3
done
echo "$STATUS"// Save as quickstart.mjs and run: node quickstart.mjs (Node.js 18+)
// 1. Get an access token.
const tokenResponse = await fetch('https://xapisandbox.xtrm.com/oAuth/token', {
method: 'POST',
headers: {
Accept: 'application/json',
},
body: new URLSearchParams({
grant_type: 'password',
client_id: process.env.XTRM_CLIENT_ID,
client_secret: process.env.XTRM_CLIENT_SECRET,
}),
});
if (!tokenResponse.ok) throw new Error(`Token request failed with HTTP ${tokenResponse.status}`);
const { access_token: accessToken } = await tokenResponse.json();
// 2. Pay 50.00 USD into the recipient's wallet.
const batchResponse = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
IssuerAccountNumber: 'SPN1111222',
SourceWalletId: 122181,
CustomerBatchId: 'BATCH-QS-0002',
Items: [
{
CustomerTransactionId: 'TXN-QS-0002',
RecipientId: 'PAT9999888',
Amount: 50,
SendMethodId: 'XTR94502',
Destination: {},
Description: 'TXN-QS-0002 Q3 Top Performer Contractor Reward',
},
],
}),
});
console.log(await batchResponse.text());
if (!batchResponse.ok) throw new Error(`Batch not accepted (HTTP ${batchResponse.status})`);
// 3. Check the status until no payment is still in progress.
const openStatuses = ['Accepted', 'Processing', 'Verified'];
let status;
for (let check = 1; check <= 10; check++) {
const response = await fetch(
'https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true',
{ headers: { Authorization: `Bearer ${accessToken}` } },
);
if (!response.ok) throw new Error(`Status check failed with HTTP ${response.status}`);
status = await response.json();
if (!status.Items.some((item) => openStatuses.includes(item.Status))) break;
await new Promise((resolve) => setTimeout(resolve, 3000));
}
console.log(`Batch ${status.CustomerBatchId}: ${status.Status}`);
for (const item of status.Items) console.log(` ${item.CustomerTransactionId}: ${item.Status}`);# Save as quickstart.py and run: python quickstart.py (Python 3 with requests)
import os
import time
import requests
# 1. Get an access token.
response = requests.post(
"https://xapisandbox.xtrm.com/oAuth/token",
headers={"Accept": "application/json"},
data={
"grant_type": "password",
"client_id": os.environ["XTRM_CLIENT_ID"],
"client_secret": os.environ["XTRM_CLIENT_SECRET"],
},
)
response.raise_for_status()
headers = {"Authorization": f"Bearer {response.json()['access_token']}"}
# 2. Pay 50.00 USD into the recipient's wallet.
response = requests.post(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer",
headers=headers,
json={
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-QS-0002",
"Items": [
{
"CustomerTransactionId": "TXN-QS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94502",
"Destination": {},
"Description": "TXN-QS-0002 Q3 Top Performer Contractor Reward",
},
],
},
)
print(response.text)
if not response.ok:
raise RuntimeError(f"Batch not accepted (HTTP {response.status_code})")
# 3. Check the status until no payment is still in progress.
open_statuses = ("Accepted", "Processing", "Verified")
for check in range(10):
response = requests.get(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true",
headers=headers,
)
response.raise_for_status()
status = response.json()
if not any(item["Status"] in open_statuses for item in status["Items"]):
break
time.sleep(3)
print(f"Batch {status['CustomerBatchId']}: {status['Status']}")
for item in status["Items"]:
print(f" {item['CustomerTransactionId']}: {item['Status']}")// Create a console app (dotnet new console), replace Program.cs with this file, then run: dotnet run
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
using var client = new HttpClient();
// 1. Get an access token.
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "password",
["client_id"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_ID")!,
["client_secret"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_SECRET")!,
});
var tokenResponse = await client.PostAsync("https://xapisandbox.xtrm.com/oAuth/token", form);
tokenResponse.EnsureSuccessStatusCode();
var token = await tokenResponse.Content.ReadFromJsonAsync<JsonElement>();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", token.GetProperty("access_token").GetString());
// 2. Pay 50.00 USD into the recipient's wallet.
var batchJson = """
{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-QS-0002",
"Items": [
{
"CustomerTransactionId": "TXN-QS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94502",
"Destination": {},
"Description": "TXN-QS-0002 Q3 Top Performer Contractor Reward"
}
]
}
""";
var batchResponse = await client.PostAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer",
new StringContent(batchJson, Encoding.UTF8, "application/json"));
Console.WriteLine(await batchResponse.Content.ReadAsStringAsync());
batchResponse.EnsureSuccessStatusCode();
// 3. Check the status until no payment is still in progress.
var openStatuses = new[] { "Accepted", "Processing", "Verified" };
JsonElement status = default;
for (var check = 1; check <= 10; check++)
{
status = await client.GetFromJsonAsync<JsonElement>(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true");
if (!status.GetProperty("Items").EnumerateArray()
.Any(item => openStatuses.Contains(item.GetProperty("Status").GetString()))) break;
await Task.Delay(TimeSpan.FromSeconds(3));
}
Console.WriteLine($"Batch {status.GetProperty("CustomerBatchId")}: {status.GetProperty("Status")}");
foreach (var item in status.GetProperty("Items").EnumerateArray())
{
Console.WriteLine($" {item.GetProperty("CustomerTransactionId")}: {item.GetProperty("Status")}");
}// Save as Quickstart.java and run: java Quickstart.java (Java 17+)
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public class Quickstart {
private static final HttpClient CLIENT = HttpClient.newHttpClient();
public static void main(String[] args) throws Exception {
// 1. Get an access token.
String form = "grant_type=password"
+ "&client_id=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_ID"), StandardCharsets.UTF_8)
+ "&client_secret=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_SECRET"), StandardCharsets.UTF_8);
String tokenJson = send(HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/oAuth/token"))
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build());
// Reads the token with a regular expression to stay dependency-free; use a JSON library in production.
Matcher token = Pattern.compile("\"access_token\"\\s*:\\s*\"([^\"]+)\"").matcher(tokenJson);
if (!token.find()) {
throw new IllegalStateException("No access_token in response: " + tokenJson);
}
String accessToken = token.group(1);
// 2. Pay 50.00 USD into the recipient's wallet.
String batchJson = """
{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-QS-0002",
"Items": [
{
"CustomerTransactionId": "TXN-QS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94502",
"Destination": {},
"Description": "TXN-QS-0002 Q3 Top Performer Contractor Reward"
}
]
}
""";
System.out.println(send(HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer"))
.header("Authorization", "Bearer " + accessToken)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(batchJson))
.build()));
// 3. Check the status until no payment is still in progress.
Pattern open = Pattern.compile("\"Status\"\\s*:\\s*\"(Accepted|Processing|Verified)\"");
String status = null;
for (int check = 1; check <= 10; check++) {
status = send(HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true"))
.header("Authorization", "Bearer " + accessToken)
.GET()
.build());
if (!open.matcher(status).find()) {
break;
}
Thread.sleep(3000);
}
System.out.println(status);
}
private static String send(HttpRequest request) throws Exception {
HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) {
throw new IllegalStateException(request.uri() + " failed with HTTP " + response.statusCode() + ": " + response.body());
}
return response.body();
}
}<?php
// Save as quickstart.php and run: php quickstart.php (PHP 8 with the curl extension)
// Sends a request and returns the decoded JSON response.
function xtrm_request(string $method, string $url, array $headers, ?string $body = null): array
{
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
}
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($response === false || $status >= 400) {
throw new RuntimeException("$method $url failed with HTTP $status: $response");
}
return json_decode($response, true);
}
// 1. Get an access token.
$token = xtrm_request('POST', 'https://xapisandbox.xtrm.com/oAuth/token', [
'Content-Type: application/x-www-form-urlencoded',
'Accept: application/json',
], http_build_query([
'grant_type' => 'password',
'client_id' => getenv('XTRM_CLIENT_ID'),
'client_secret' => getenv('XTRM_CLIENT_SECRET'),
]));
$auth = 'Authorization: Bearer ' . $token['access_token'];
// 2. Pay 50.00 USD into the recipient's wallet.
$created = xtrm_request('POST', 'https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer', [$auth, 'Content-Type: application/json'], json_encode([
'IssuerAccountNumber' => 'SPN1111222',
'SourceWalletId' => 122181,
'CustomerBatchId' => 'BATCH-QS-0002',
'Items' => [
[
'CustomerTransactionId' => 'TXN-QS-0002',
'RecipientId' => 'PAT9999888',
'Amount' => 50,
'SendMethodId' => 'XTR94502',
'Destination' => new stdClass(),
'Description' => 'TXN-QS-0002 Q3 Top Performer Contractor Reward',
],
],
]));
print_r($created['BatchTransferResponse']);
// 3. Check the status until no payment is still in progress.
for ($check = 1; $check <= 10; $check++) {
$status = xtrm_request('GET', 'https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-QS-0002?recordsToSkip=0&recordsToTake=50&history=true', [$auth]);
$open = array_filter($status['Items'], fn ($item) => in_array($item['Status'], ['Accepted', 'Processing', 'Verified'], true));
if (!$open) {
break;
}
sleep(3);
}
echo "Batch {$status['CustomerBatchId']}: {$status['Status']}", PHP_EOL;
foreach ($status['Items'] as $item) {
echo " {$item['CustomerTransactionId']}: {$item['Status']}", PHP_EOL;
}If a payment is still in progress after the last check, check the batch again later. A payment that ends Failed carries an ErrorCode on its latest attempt. Error codes on attempts says what each code means and what to do, and Create a batch payment shows a worked retry.
#Next steps
Pay bank accounts, wallets and cards in one batch, and retry failed payments safely.
Batch paymentsHow batch payments workThe batch lifecycle, wallet-first delivery and batch limits.
Batch paymentsBatch and payment statusesWhat every batch, payment and attempt status means.
Batch paymentsWebhooksGet batch and payment updates pushed to you instead of polling.
When you're ready to go live, see Move to production.