Requests & responses
You pay recipients with batch payments, and the three batch payment endpoints use plain JSON. You POST a batch as a flat JSON object, Xtrm answers 202 Accepted, and you GET the status of the batch and of each item in it. The rest of the API, which you use to look up wallets, manage recipients, fund your wallets and read reference data, wraps most requests and responses in an operation envelope and reports the outcome in an OperationStatus object.
This page covers both styles and the conventions they share: headers, data types, formats and pagination. It ends with a reusable helper for the envelope endpoints.
#At a glance
| Batch payment endpoints | Every other endpoint | |
|---|---|---|
| Paths | /Fund/BatchTransfer, /Fund/BatchTransfer/{CustomerBatchId} and /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId} | /<Resource>/<Operation>, for example /Wallet/GetCompanyWallets |
| Method | POST to submit a batch, GET to check its status | POST, lookups included |
| Request body | Flat JSON: the fields sit at the root. The GET endpoints take no body. | JSON wrapped as {"<Operation>": {"request": { … }}} |
| Response body | Plain JSON: {"BatchTransferResponse": { … }} when you submit, the status object itself when you check | JSON wrapped as {"<Name>Response": {"<Name>Result": { … }}} |
| Outcome | The HTTP status (202 Accepted on submit), the Accepted and Rejected items, then each item's Status | The HTTP status and OperationStatus.Success inside the result |
| Pagination | recordsToSkip and recordsToTake query parameters, Pagination in the response | A Pagination object in the body, PaginationTotal in the response |
| Authentication | Authorization: Bearer <access_token> | Authorization: Bearer <access_token>, except on the token request |
#URLs, methods and content types
An endpoint URL is a base URL followed by a path:
| Environment | Base URL |
|---|---|
| Sandbox | https://xapisandbox.xtrm.com/API/v4 |
| Production | https://xapi.xtrm.com/API/v4 |
The batch payment paths all start with /Fund/BatchTransfer. Every other path is a resource segment followed by the operation name, for example /Wallet/GetCompanyWallets. The resource segments are Fund, Wallet, Bank, Card, Beneficiary, Register, Payment, Programs, GiftCard, OTP, General and Report.
The token endpoint is the only one outside /API/v4. It sits at the host root: https://xapisandbox.xtrm.com/oAuth/token. See Authentication. Paths match in any case, so /API/V4 reaches the same endpoints; this site writes /API/v4. See Sandbox & environments.
| Request | Method | Content-Type | Body |
|---|---|---|---|
| Submit a batch payment | POST | application/json | The batch as a flat JSON object, UTF-8 encoded |
| Batch status and item status | GET | None | No body. Path parameters and query parameters |
Token request (/oAuth/token) | POST | application/x-www-form-urlencoded | Form fields grant_type, client_id, client_secret, plus refresh_token when you renew a session |
| Every other endpoint | POST | application/json | JSON in the operation envelope |
Submit a batch payment as JSON with Content-Type: application/json. Xtrm refuses a request whose Content-Type is missing or not supported with 415 (invalid_media_type), before it checks the token, and a body that isn't valid JSON with 400 (BAD_REQUEST).
Lookups use POST too. List endpoints that need no input, such as GetCountry, take an empty JSON object {} as the body. Apart from the two batch status calls, every endpoint accepts only POST. A GET to one of the POST endpoints under /API/v4, such as GetAdvancedContactCountry, returns HTTP 404 with {"StatusCode": 404, "Message": "The requested resource is not found"} and no OperationStatus.
#Headers
| Header | Value | Send it on |
|---|---|---|
Authorization | Bearer <access_token> | Every request except the token request |
Content-Type | application/json | Every POST except the token request, which sends application/x-www-form-urlencoded. The batch status GET requests have no body and need no Content-Type. |
Accept | application/json | Optional: every response is JSON whatever you send, except the CSV from GetConnectedCompanyFundRequest. The samples on this site leave it out for brevity; the helper sends it. |
The access token comes from the token request. See Authentication for how to get and renew it. For the batch payment endpoints, the token is scoped to your company's account.
Xtrm also sends requests to you: batch payment webhooks, signed with HMAC-SHA256 in an X-Signature header. See Webhooks.
#Batch payment requests
#Submit a batch payment
POST /API/v4/Fund/BatchTransfer takes the batch as a flat JSON object. There is no operation wrapper and no request object: the batch fields sit at the root of the body, and each payment is an object in the Items array.
| Level | Fields |
|---|---|
| Batch | IssuerAccountNumber (required), SourceWalletId (required), CustomerBatchId (required), EmailNotification, Items (required) |
Each item in Items | CustomerTransactionId (required), RecipientId (required), Amount (required), SendMethodId (required), Description, Destination (required) |
Destination | The fields that apply to the item's SendMethodId, such as BeneficiaryBankID for a bank transfer or Email and SKU for a prepaid virtual debit card. Send Destination on every item, even as {}. See Payment methods & destinations. |
This batch pays a business recipient by bank transfer and an individual recipient with a prepaid virtual debit card. Both recipients already exist, and the bank account is linked to the business recipient; see Accounts, wallets & IDs and Bank accounts & transfers. CustomerBatchId values 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.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-w "\nHTTP %{http_code}\n" \
-d '{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-REQUESTS-0001",
"EmailNotification": true,
"Items": [
{
"CustomerTransactionId": "TXN-REQUESTS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
},
"SendMethodId": "XTR94500",
"Description": "TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive"
},
{
"CustomerTransactionId": "TXN-REQUESTS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
},
"SendMethodId": "XTR94503",
"Description": "TXN-REQUESTS-0002 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-REQUESTS-0001',
EmailNotification: true,
Items: [
{
CustomerTransactionId: 'TXN-REQUESTS-0001',
RecipientId: 'SPN8888777',
Amount: 100,
Destination: {
BeneficiaryBankID: '41953ec32f3e4765a35a902c82bdd995',
BeneficiaryBankPaymentMethod: 'ACH',
},
SendMethodId: 'XTR94500',
Description: 'TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive',
},
{
CustomerTransactionId: 'TXN-REQUESTS-0002',
RecipientId: 'PAT9999888',
Amount: 50,
Destination: {
Email: '[email protected]',
SKU: 'PREP9001',
},
SendMethodId: 'XTR94503',
Description: 'TXN-REQUESTS-0002 Q3 Top Performer Contractor Reward',
},
],
}),
});
console.log(response.status, await response.text());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-REQUESTS-0001",
"EmailNotification": True,
"Items": [
{
"CustomerTransactionId": "TXN-REQUESTS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH",
},
"SendMethodId": "XTR94500",
"Description": "TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive",
},
{
"CustomerTransactionId": "TXN-REQUESTS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001",
},
"SendMethodId": "XTR94503",
"Description": "TXN-REQUESTS-0002 Q3 Top Performer Contractor Reward",
},
],
},
)
print(response.status_code, response.text)
response.raise_for_status()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-REQUESTS-0001",
"EmailNotification": true,
"Items": [
{
"CustomerTransactionId": "TXN-REQUESTS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
},
"SendMethodId": "XTR94500",
"Description": "TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive"
},
{
"CustomerTransactionId": "TXN-REQUESTS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
},
"SendMethodId": "XTR94503",
"Description": "TXN-REQUESTS-0002 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"));
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
response.EnsureSuccessStatusCode();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-REQUESTS-0001",
"EmailNotification": true,
"Items": [
{
"CustomerTransactionId": "TXN-REQUESTS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
},
"SendMethodId": "XTR94500",
"Description": "TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive"
},
{
"CustomerTransactionId": "TXN-REQUESTS-0002",
"RecipientId": "PAT9999888",
"Amount": 50,
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
},
"SendMethodId": "XTR94503",
"Description": "TXN-REQUESTS-0002 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.statusCode() + " " + 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-REQUESTS-0001',
'EmailNotification' => true,
'Items' => [
[
'CustomerTransactionId' => 'TXN-REQUESTS-0001',
'RecipientId' => 'SPN8888777',
'Amount' => 100,
'Destination' => [
'BeneficiaryBankID' => '41953ec32f3e4765a35a902c82bdd995',
'BeneficiaryBankPaymentMethod' => 'ACH',
],
'SendMethodId' => 'XTR94500',
'Description' => 'TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive',
],
[
'CustomerTransactionId' => 'TXN-REQUESTS-0002',
'RecipientId' => 'PAT9999888',
'Amount' => 50,
'Destination' => [
'Email' => '[email protected]',
'SKU' => 'PREP9001',
],
'SendMethodId' => 'XTR94503',
'Description' => 'TXN-REQUESTS-0002 Q3 Top Performer Contractor Reward',
],
],
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE) . ' ' . $response . PHP_EOL;Xtrm accepts different batches in parallel. Never have two requests for the same CustomerBatchId in flight at once: wait for the response, or follow A safe retry pattern when you don't get one.
#The 202 Accepted response
Xtrm validates the batch and each item before it responds. When at least one item passes, it answers 202 Accepted and processes the accepted items in the background; when every item is rejected, it answers 422, or 409 if any of them already exists in the batch. The response is plain JSON under a single BatchTransferResponse key. It has no OperationStatus.
{
"BatchTransferResponse": {
"CustomerBatchId": "BATCH-REQUESTS-0001",
"Status": "Accepted",
"ItemsCount": {
"Total": 2,
"Accepted": 2,
"Rejected": 0
},
"Accepted": [
{
"CustomerTransactionId": "TXN-REQUESTS-0002",
"Amount": 50.0,
"Currency": "USD",
"SendMethodId": "XTR94503",
"RecipientId": "PAT9999888"
},
{
"CustomerTransactionId": "TXN-REQUESTS-0001",
"Amount": 100.0,
"Currency": "USD",
"SendMethodId": "XTR94500",
"RecipientId": "SPN8888777"
}
],
"Rejected": []
}
}| Field | What it holds |
|---|---|
CustomerBatchId | Your batch ID, echoed back. |
Status | The outcome of the submission: Accepted (no item rejected), CompletedWithFailures (some items rejected) or Failed (no item accepted). It describes validation and storage only, not payment. |
ItemsCount | An object with the Total, Accepted and Rejected item counts. Total is the number of items you sent. |
Accepted | The items taken for processing, in no particular order, each with CustomerTransactionId, Amount, Currency, SendMethodId and RecipientId. Amount is a JSON number with the decimals you sent: 100.00 comes back as 100.00, "51.5" as 51.5, and the 100 in this request as 100.0. |
Rejected | The items Xtrm didn't take, each with CustomerTransactionId, Key (a category such as INVALID_FIELD), ErrorCode (an HTTP-style code such as 422), Field and Message. |
Key, ErrorCode, Message | Returned when Xtrm refuses the request at the batch level (for example CONFLICT_PROCESSING, FORBIDDEN or LIMIT_EXCEEDED) or can't store the accepted items: the error category, an HTTP-style code and a description. Left out otherwise, so they don't appear in the example. When every item is rejected, they're left out too, and Rejected says why each item was refused. A wrong Content-Type (415) or a token problem (401) returns {"error", "error_message"} instead. |
Field is usually Items[i].<field>, with a zero-based index, for example Items[0].Destination.SKU. The index can differ from the item's position in your request, Field can name a related field or be empty, and one item can appear more than once, so match each rejection to your item by its CustomerTransactionId.
A 202 Accepted means Xtrm received the batch and took the items in Accepted for processing. It doesn't mean they were paid, and it isn't proof that each one was stored. Follow each item with the status endpoints. Webhooks can tell you sooner, and the status endpoints confirm each item's final status.
#Check a batch or an item
The two status endpoints are GET requests with no body. You name the batch, and the item, in the path with your CustomerBatchId and CustomerTransactionId. Options go in the query string:
| Query parameter | Endpoints | Meaning |
|---|---|---|
recordsToSkip | Batch status | The number of items to skip. See Pagination. |
recordsToTake | Batch status | The maximum number of items to return. |
history | Both | true fills each item's Attempts with its full attempt history; false or no value leaves it []. Any other value fails with 400. |
Query parameter names match in any case. This site writes them in camelCase.
curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REQUESTS-0001?recordsToSkip=0&recordsToTake=50&history=true" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
-w "\nHTTP %{http_code}\n"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REQUESTS-0001?recordsToSkip=0&recordsToTake=50&history=true', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
},
});
console.log(response.status, await response.text());import os
import requests
response = requests.get(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REQUESTS-0001?recordsToSkip=0&recordsToTake=50&history=true",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
)
print(response.status_code, response.text)
response.raise_for_status()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-REQUESTS-0001?recordsToSkip=0&recordsToTake=50&history=true");
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");
response.EnsureSuccessStatusCode();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-REQUESTS-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.statusCode() + " " + response.body());<?php
$ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REQUESTS-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);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE) . ' ' . $response . PHP_EOL;The response is the status object itself, with no wrapper and no OperationStatus:
{
"CustomerBatchId": "BATCH-REQUESTS-0001",
"Status": "Completed",
"Currency": "USD",
"ItemsCount": 2,
"Items": [
{
"CustomerTransactionId": "TXN-REQUESTS-0001",
"Status": "Success",
"RecipientId": "SPN8888777",
"SendMethodId": "XTR94500",
"Amount": "100.00",
"LastUpdatedAt": "2026-06-05T20:49:44.0208205Z",
"Attempts": [
{
"AttemptNo": 1,
"Result": "Success",
"ErrorCode": "SUCCESS",
"CreatedAt": "2026-06-05T20:49:44.0159177Z",
"CompletedAt": "2026-06-05T20:49:44.0208205Z"
}
]
},
{
"CustomerTransactionId": "TXN-REQUESTS-0002",
"Status": "Success",
"RecipientId": "PAT9999888",
"SendMethodId": "XTR94503",
"Amount": "50.00",
"LastUpdatedAt": "2026-06-05T20:49:47.1834547Z",
"Attempts": [
{
"AttemptNo": 1,
"Result": "Success",
"ErrorCode": "SUCCESS",
"CreatedAt": "2026-06-05T20:49:47.1834547Z",
"CompletedAt": "2026-06-05T20:49:47.1834547Z"
}
]
}
],
"Pagination": {
"HasMore": false,
"NextRecordsToSkip": 0
}
}The item status endpoint returns a single item the same way, at the root, and adds its Currency and DeliveryType. A status request that the endpoint refuses returns {"StatusCode": …, "Message": …}, with an ErrorKey for 400, 413 and 422 errors; neither endpoint returns an Errors field. A token or IP problem returns 401 with {"error": …, "error_message": …}, as on every endpoint. A 404 doesn't prove that a batch or payment is missing: when Xtrm can't read it, both endpoints return the same 404 as for an unknown ID, and right after a submit call times out, the item endpoint can return 404 while the original request is still being stored. Repeat the check a few times, at least a minute apart, before you conclude that a payment wasn't stored; see A safe retry pattern. Batch & item statuses explains every Status value.
#How batch payment responses differ
If you also call the envelope endpoints, keep these differences in mind:
- No envelope, no
OperationStatus. There is noSuccessflag to read. The HTTP status and the body'sStatustell you whether Xtrm took the batch,AcceptedandRejectedtell you which items it took, and each item'sStatustells you how it ended. - Your IDs come back. Xtrm echoes
CustomerBatchIdandCustomerTransactionId, as it stored them, in the submit response, the status responses and the item webhook events (Batch.Item.…), so you can match results to your own records. The batch-level webhook events carry onlyCustomerBatchId, and a response that refuses the request before Xtrm reads the batch, such as a token error, carries neither. ItemsCountchanges shape. It's an object (Total,Accepted,Rejected) in the submit response and a number, the count of items in the batch, in the status response.Amountchanges type. You send it as a JSON number, and the submit response echoes it as a number with the decimals you sent (100.00comes back as100.00, and100as100.0). The status endpoints return it as a string with 2 decimals: the batch status endpoint with a thousands separator ("1,234.56"), the item endpoint without one ("1234.56"). The item webhook events send it as a JSON number with 2 decimals (1234.56).- There are two kinds of
ErrorCode. InRejected,ErrorCodeis an HTTP-style code such as422, with the category inKey. In an item'sAttempts,ErrorCodeis a named code such asBANKID_INVALID, orSUCCESSfor an attempt that worked. Errors lists the codes inRejected; Error codes on attempts lists the attempt codes.
#The operation envelope
Apart from the batch payment endpoints and the token request, the API uses the operation envelope, with the few exceptions listed below. You use these endpoints to prepare and fund payments. For example, GetCompanyWallets gives you the wallet ID to send as a batch's SourceWalletId, and GetPaymentMethods lists the send methods.
#Request envelope
The body wraps its fields in two objects: a root key named after the operation, and an inner request object.
{
"GetCompanyWallets": {
"request": {
"IssuerAccountNumber": "SPN1111222"
}
}
}Nearly every request includes IssuerAccountNumber, the account number of your company, which starts with SPN. A batch payment carries it at the root of the body; an envelope body carries it inside request. The requests without it are the token request, the eight {} lookups, GetAdvancedContactCompanyType (takes CountryISO2), GetAdvancedContactState (takes CountryCode) and the two batch status endpoints.
Some bodies nest further. FundCompanyWalletUsingCreditCard splits its fields into PaymentDetails, PayerInformation, PayerBillingAddress and CreditCardDetails, and LinkBankBeneficiary uses Beneficiary › BeneficiaryDetails › BeneficiaryInformation and Beneficiary › BankDetails › BeneficiaryBankInformation.
#Names that break the pattern
The wrapper names don't always follow the pattern. Xtrm matches JSON property names regardless of case, but it silently ignores a name it doesn't recognize, so a misspelled wrapper or field is dropped as if you hadn't sent it. Copy each spelling exactly as the endpoint's request example in the API reference shows it, including odd spellings such as IsPublicallyTraded in the advanced profile. Casing doesn't change the match, but this site's samples keep the casing shown in the tables below for consistency.
Inner key Request (capital R). These 25 operations spell the inner key Request instead of request in their samples:
| Area | Operations |
|---|---|
| Bank accounts | SearchBankByBIC, SearchBankByNationalID |
| Bank debit | ReleaseACHDebitMicrodeposit, VerifyACHDebitMicrodeposit |
| Business recipients | CreateBeneficiary, UpdateBeneficiary |
| Currency exchange | GetExchangeRate, BookExchange |
| Funding | FundWalletUsingBankTransfer, FundWalletUsingACHDebit, FundCompanyWalletUsingCreditCard |
| Gift cards & prepaid cards | GetGiftCardDetails, GetPrepaidCards, GetPrepaidCardDetails |
| OTP & connections | GetConnectedStatus |
| Fees & reports | GetCompanyFees, TransferTaxInformation |
| Wallet transactions | GetCompanyWalletTransactions, GetCompanyWalletTransactionDetails, GetUserWalletTransactions, GetUserWalletTransactionDetails, GetUserWalletTransactionsByRemitter |
| Wallets | GetUserWallets, UpdateUserWallet, UpdateBeneficiaryCompanyWallet |
Root key that differs from the operation name.
| Operation | Root key in the request body |
|---|---|
CompanyAdvancedProfile | AdvancedProfile |
CompanyAdvancedProfileStatus | AdvancedProfileStatus |
GetCompanyAdvancedProfileDetails | AdvancedProfileDetails |
GetAdvancedContactCompanyType | CompanyType |
GetAdvancedContactState | AdvancedContactState |
GetLinkedCards | GetLinkedCardAccounts |
GetDigitalGiftCards | GetGiftCards |
GetGiftCardDetails | GetGiftCards |
GetPrepaidCardDetails | GetPrepaidCards |
ProgramCategory | GetProgramCategory |
ProgramType | GetProgramType |
FundCompanyWalletUsingCreditCard | FundCompanyWalletUsingCreditCardRequest |
FundWalletUsingACHDebit | FundWalletUsingACHDebitRequest |
GetCompanyWalletTransactionDetails | GetCompanyTransactionDetails |
GetUserWalletTransactionDetails | GetUserTransactionDetails |
GetConnectedCompanyFundRequest | GetConnectedFundRequestDetails |
Similar fields, different names. Field names aren't consistent across endpoints either. A wallet ID is SourceWalletId or Destination.WalletId in a batch, but WalletID in envelope requests such as UpdateCompanyWallet and in the GetCompanyWallets response. An individual recipient's account number is RecipientId in a batch item, RecipientUserId in GetLinkedBankAccounts, UserID in GetUserWallets and UserId in GetUserWalletBalance.
#Bodies without an envelope
| Request | Body |
|---|---|
GetCountry, GetAdvancedContactCountry, GetAdvancedContactJobTitles, GetIdentificationType, GetNAICS, GetPaymentMethods, GetUserPaymentMethods, GetBeneficiaryCompanyPaymentMethods | An empty JSON object: {} |
| Token request | Form-encoded fields, not JSON |
| The batch payment endpoints | A flat JSON body, or no body for the status requests. See Batch payment requests. |
#Response envelope
A successful response wraps the payload in a …Response object and a …Result object. The result holds the data and an OperationStatus object:
{
"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
}
}
}
}WalletID comes back as a number. Send it as the same JSON number when you use it as a batch's SourceWalletId, as the batch above does with 122181, and the wallet's currency becomes the currency of the batch.
OperationStatus field | Type | Meaning |
|---|---|---|
Success | boolean | Whether the operation succeeded (true) or failed (false). |
Errors | array or null | Error messages when the call fails, as strings, or as objects when a bank link needs more fields. On success it's null, [] or [""], depending on the endpoint (see below). |
On success, Errors is null, an empty array [] or [""], depending on the endpoint, so decide on OperationStatus.Success and use Errors only to explain a failure. See Errors on a successful call.
Two calls need more than Success: UserWithdrawFund and BeneficiaryCompanyWithdrawFund, which transfer money out of a recipient's wallet with the recipient's one-time password. Their first request, which sends the code, also returns Success: true, with One Time Password sent to user. Please resubmit with One Time Password. in Errors, and moves no money. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId.
#Response wrapper names vary
Many response wrappers don't match the operation name, so take them from each endpoint's response example, or find OperationStatus without hard-coding them, as the helper below does. Some notable cases:
| Operation | Response wrappers |
|---|---|
GetCompanyWallets | GetCompanyWalletResponse › CompanyWalletResult |
GetBeneficiaries | GetBeneficiariesResponse › BeneficiaryResult |
GetUserWalletBalance | UserWalletBalnceResponse › UserWalletBalanceResult |
SearchBankByBIC | SearchBankbyBICResponse › SearchBankbyBICResult |
BookExchange | BookExchangeMethodsResponse › BookExchangeMethodResult |
GetExchangeRate | GetExchangeRateMethodsResponse › ExchangeRateMethodResult |
CreateProgram | CreateProgramsResponse › CreateProgramsResult |
DeleteBankBeneficiary | DeleteBankBeneficiary › DeleteBankBeneficiaryResult (no Response suffix) |
DeleteCard | DeleteCard › DeleteCardResult (no Response suffix) |
#Responses without the envelope
| Endpoint | What comes back |
|---|---|
| The batch payment endpoints | Plain JSON with no OperationStatus. See Batch payment requests. |
| Token request | A flat token object (access_token, token_type, expires_in, refresh_token, …). No OperationStatus. |
GetConnectedCompanyFundRequest | Plain text, not JSON: CSV rows, starting with the header row Account Number,Name,Credits,Debits,Currency. |
#HTTP status codes
The batch payment endpoints use the HTTP status: submitting a batch returns 202 Accepted when at least one item passes validation, the status endpoints return 200, and Xtrm answers with a 4xx status when it refuses the whole request or rejects every item, and 500 on an internal error. The envelope endpoints answer 200 when the call succeeds, and a 4xx or 500 status with OperationStatus.Success set to false when it fails. A few one-time password steps break that pattern, so check both the HTTP status and OperationStatus.Success; HTTP status codes lists every status and its exceptions.
See Errors when you submit a batch payment for the codes a refused request or a reused CustomerTransactionId gets, and Other endpoints for how the envelope endpoints report failures.
#Data types
#Numbers and booleans as strings
Request values are strings in most envelope bodies, even when they hold numbers or booleans, for example "RecordsToSkip": "1" and "WalletID": "122181". A few envelope fields are sent as real JSON numbers or booleans too:
| Field | Endpoints | JSON value in the example |
|---|---|---|
EntityID | LinkBankBeneficiary, LinkACHDebitBankBeneficiary, LinkCard, CreateCompanyWallet, CreateBeneficiaryCompanyWallet | 27044, 27045 |
EmailNotification | UserWithdrawFund, BeneficiaryCompanyWithdrawFund | true |
Amount | FundCompanyWalletUsingCreditCard | 50 |
IsClaim (CreateProgram, UpdateProgram) and InvoiceRequired (FundWalletUsingBankTransfer) read like booleans but are strings: send "true" or "false", lowercase and in quotes. Xtrm reads a JSON true in a text field as "True", and only the exact string "true" makes a claim program or asks Xtrm for an invoice. A JSON true passes Xtrm's checks but does neither: the program is saved as not a claim, and no invoice is requested.
A batch payment is different: it sends Amount as a JSON number (100.00), SourceWalletId and Destination.WalletId as integers (122181, 122311) and EmailNotification as a boolean (true). The batch endpoint also accepts these values as strings ("100.00", "122181", "true") and converts them. A value it can't convert doesn't fail the request by itself: Xtrm reads it as empty (0, or false for EmailNotification) and checks that value as usual, so an empty Amount rejects its item and an empty SourceWalletId fails the whole request. Each field in the reference says what happens. We recommend sending the JSON types shown.
The batch's text fields work the other way round. CustomerBatchId, CustomerTransactionId, RecipientId, SendMethodId, Description and the Destination text fields accept a JSON number and store it as text (1001 becomes "1001"), so send IDs as strings to keep them exactly as you store them.
The same field can change type between endpoints
A wallet ID is an integer in a batch (SourceWalletId, Destination.WalletId) but a numeric string in envelope requests (WalletID, for example "122181"). Always send the ID, never the wallet's name. In BeneficiaryCompanyWithdrawFund, EmailNotification must be a real boolean while SendTransferCodeToEmail and SendTransferCodeToMobile must be the strings "true" or "false". Send each value with the JSON type the endpoint's request example uses.
The batch status query parameters are plain integers and booleans in the query string, for example recordsToSkip=0, recordsToTake=50 and history=false.
#Types in responses
Responses mix strings and numbers:
| Value | Type in responses | Example |
|---|---|---|
Accepted[].Amount in the batch submit response | number, with the decimals you sent | 100.00 (sent as 100.00), 100.0 (sent as 100) |
Amount in the batch and item status responses | string | "100.00"; "1,234.56" on the batch endpoint, "1234.56" on the item endpoint |
Amount in item webhook events | number, with 2 decimals | 100.00, 1234.56 |
ItemsCount in batch payment responses | object on submit, number on status | {"Total": 2, "Accepted": 2, "Rejected": 0}, 2 |
AttemptNo in item attempts | number | 1 |
Amount, Fee, TotalAmount on recipient transfers and card funding | string | "4.50", "0.50", "5.00". Card funding and bank transfers return all three with 2 decimals and a thousands separator, as in "1,250.00", so strip separators before you parse them. |
| Amounts and balances in wallet transaction lists and wallet lists | number | 51.5, 57715.15 |
Balance from GetUserWalletBalance | number | 1250.43 |
Fees from GetCompanyFees | number | 2.50 |
WalletID | number (a string in envelope requests, a number in a batch's SourceWalletId) | 122181 |
TransactionID in wallet transaction lists | number (pass it as a string to the details endpoints) | 888601 |
We recommend that your client accept both strings and numbers for amounts and parse them into a decimal type rather than binary floating point.
#Formats
| Value | Format | Example | Notes |
|---|---|---|---|
| Currency | Three-letter ISO 4217 code | USD | A batch payment takes the currency of its source wallet, and the batch responses report it as Currency. |
| Country | Two-letter ISO 3166-1 alpha-2 code | US | Fields such as BeneficiaryCheckCountryCodeISO2 in a check item, and CountryISO2, Country_Code2 and CountryCode2 elsewhere. See the CountryCode note below. The Country that CheckUserExist and GetPersonalBeneficiaries return is the full country name instead, for example United States of America. |
| Amount in a batch | JSON number | 100.00 | An item's Amount must be greater than 0 and at most 9999999999999999.99. A numeric string such as "100.00" is accepted too. Send at most 2 decimal places: Xtrm stores and pays amounts with 2. |
| Batch and item IDs | Strings of 1 to 128 letters, digits and . _ - : @ | "BATCH-REQUESTS-0001", "TXN-REQUESTS-0001" | Required: Xtrm never generates them. Retries & idempotency has the full rules, including reserved prefixes and how case is treated. |
| Timestamp in a status response | ISO 8601, with up to seven fractional digits | "2026-06-05T20:49:01.1150192Z", "2026-06-05T20:50:36.2431Z" | LastUpdatedAt, CreatedAt and CompletedAt. The values are in UTC. Parse them with or without a trailing Z, and read a value without a time zone as UTC. On the batch status endpoint, LastUpdatedAt is null until processing first updates the item; the item endpoint falls back to the submission time. |
ReceivedAt and CompletedAt in a webhook event | M/d/yyyy h:mm:ss tt, whole seconds, no time zone | "10/28/2025 3:11:35 AM" | The time is UTC, and the value isn't ISO 8601. The webhook's other timestamps are described in Webhooks. |
| Timestamp in other responses | Varies | "2024-08-28T15:03:33.847", "2026-06-05T16:33:26.385963Z", "2026-06-04T00:00:00-04:00" | Some have no time zone designator. |
| Date in a request | MM/DD/YYYY, month first | "12/31/2020" | Strict for FromDate and ToDate in GetConnectedCompanyFundRequest. RequiredDepositDate and RequiredPaymentDate in FundWalletUsingBankTransfer are US dates in the same format: "06/05/2026" is 5 June 2026. The wallet transaction filters StartUTC and EndUTC take dates in this format too ("01/01/2024"), and both are inclusive: EndUTC covers its whole day. |
| Date of birth | Separate Day (1–31), Month (1–12) and Year (four digits) strings | "08" | CreateUser and UpdateUser. The advanced profile takes dates of birth as mm/dd/yyyy. |
| Card expiry | Month as a numeric string from 1 to 12, year as four digits | LinkCard, FundCompanyWalletUsingCreditCard |
Timestamps don't share one format across endpoints, so we recommend an ISO 8601 parser that accepts any number of fractional digits and handles a missing time zone explicitly. Name/value detail arrays, such as PayDirectTransactionDetails, contain display strings like "6/5/2026 1:01:59 PM"; we recommend showing them as they are rather than parsing them.
CountryCode means different things
In GetCountry, CountryCode is the three-letter code (USA) and the two-letter code is in CountryISO2. In GetAdvancedContactCountry and GetAdvancedContactState, CountryCode is the two-letter code (US).
#Pagination
The API pages results in two ways:
| Batch status | List endpoints | |
|---|---|---|
| Where you send it | Query string | A Pagination object in the request body |
| Parameter names | recordsToSkip, recordsToTake (camelCase) | RecordsToSkip, RecordsToTake |
| Parameter type | Integers | Strings |
| What comes back | Pagination: HasMore, NextRecordsToSkip | PaginationTotal: RecordsTotal, RecordsToSkip, RecordsToTake |
| How to get the next page | Send NextRecordsToSkip as recordsToSkip | Add 1 to RecordsToSkip, a page number |
#Items in a batch
Get the status of a batch payment pages through the batch's items:
- Start at
0. SendrecordsToSkip=0for the first page, as the example request does. - Page size.
recordsToTakesets the number of items per page, up to your account's maximum. Without it, you get up to that maximum; a larger value fails with422LIMIT_EXCEEDED, and the message states the maximum. A page that would exceed the response-size limit fails with413LIMIT_EXCEEDED; ask for fewer items or leave outhistory. - Next page. While
Pagination.HasMoreistrue, call again withPagination.NextRecordsToSkipasrecordsToSkipand the samerecordsToTake. On the last page,NextRecordsToSkipis0.ItemsCountgives the number of items stored in the batch. - History. Add
history=trueto include every attempt for each item; without it,Attemptsis an empty array.
The item status endpoint returns a single item, so it takes only history. Create a batch payment walks through the whole flow.
#List endpoints
These envelope endpoints take a Pagination object inside the request: SearchBankByBIC, SearchBankByNationalID, CheckBeneficiaryExist, GetBeneficiaries, GetEntities, GetPersonalBeneficiaries, GetPrograms, ProgramCategory, ProgramType, GetCompanyWalletTransactions, GetUserWalletTransactions, GetUserWalletTransactionsByRemitter and GetConnectedCompanyFundRequest.
| Field | In | Type | Meaning |
|---|---|---|---|
Pagination.RecordsToSkip | Request | string | The page number, starting at "1". For page 2, send "2" with the same RecordsToTake. "0" fails with 400. |
Pagination.RecordsToTake | Request | string | Maximum number of records per page, for example "25". |
PaginationTotal.RecordsTotal | Response | number | Total number of records available. |
PaginationTotal.RecordsToSkip | Response | number | The page number of this page. |
PaginationTotal.RecordsToTake | Response | number | Page size requested. |
PaginationTotal sits next to OperationStatus in the result:
{
"GetBeneficiariesResponse": {
"BeneficiaryResult": {
"Beneficiaries": {
"BeneficiaryDetail": [
{
"BeneficiaryCompanyName": "Acme Corporation",
"BeneficiaryContact": "Marcus Chen",
"PartnerAccountManager": "Sam Rivera",
"BeneficiaryID": "SPN9999888",
"BeneficiarySalesforceId": "0018000000abcde",
"OtherPartnerID": "Gold",
"Region": "CA",
"BeneficiaryEmail": "[email protected]",
"BeneficiaryAccountIdentityLevel": "Basic"
}
]
},
"OperationStatus": {
"Success": true,
"Errors": [""]
},
"PaginationTotal": {
"RecordsToSkip": 1,
"RecordsToTake": 25,
"RecordsTotal": 2
}
}
}
}Things to know:
- Start at
"1".RecordsToSkipis a page number, not a record offset:"1"is the first page, and"0"fails with400. The bank searchesSearchBankByNationalIDandSearchBankByBICwork the same way: send"1"for the first page,"2"for the second, and so on. - Strings in, numbers out. The request sends
RecordsToSkipandRecordsToTakeas strings;PaginationTotalreturns numbers. - To read every page, add 1 to
RecordsToSkipon each call, with the sameRecordsToTake, until you havePaginationTotal.RecordsTotalrecords. - Pages aren't a snapshot. Each list has its own sort order, and records added or changed while you page can shift later pages, so a record can repeat or be skipped. De-duplicate on the record's ID.
- Not every list returns totals.
CheckBeneficiaryExistmakesPaginationoptional (send both fields if you send it) and returns noPaginationTotal; withoutPagination, it returns the first 30 matches. Read pages until one has fewer records thanRecordsToTake.GetConnectedCompanyFundRequestreturns CSV, so it has noPaginationTotaleither. - Page size.
GetBeneficiaries,CheckBeneficiaryExist,GetPersonalBeneficiariesandProgramCategorytake aRecordsToTakeof at most"100". The wallet transaction lists have no maximum.
#A reusable request helper
This helper wraps the envelope conventions above. It sends a JSON POST with the recommended headers, fails on a non-2xx status, finds OperationStatus wherever the wrappers put it, and fails unless Success is true. On success it returns the parsed response. The example call lists your company's wallets with GetCompanyWallets, which is where a batch's SourceWalletId comes from.
Use it for the envelope endpoints only. The token request and GetConnectedCompanyFundRequest return different shapes, and the batch payment endpoints are covered in the note after the code. For UserWithdrawFund and BeneficiaryCompanyWithdrawFund, also check the result's PaymentStatus: the helper returns their first request, which only sends the one-time password, as a success. The cURL version does a quick text match on the response; for anything more, parse the JSON with a tool such as jq. The Java version is a complete class: save it as XtrmClient.java and add jackson-databind 2.10 or later, since the JDK has no JSON parser.
XTRM_API="https://xapisandbox.xtrm.com/API/v4"
# Sends a JSON request and prints the response. Fails when the HTTP status
# is not 2xx or OperationStatus.Success is not true.
call_xtrm() {
local endpoint="$1" body="$2" response status
# -w appends the HTTP status code on its own line after the body.
response=$(curl -sS -w '\n%{http_code}' -X POST "$XTRM_API$endpoint" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "$body") || { echo "$endpoint: request failed" >&2; return 1; }
status=${response##*$'\n'}
response=${response%$'\n'*}
if [[ $status != 2?? ]]; then
echo "$endpoint: HTTP $status: $response" >&2
return 1
fi
if ! grep -Eq '"Success"[[:space:]]*:[[:space:]]*true' <<<"$response"; then
echo "$endpoint: operation failed: $response" >&2
return 1
fi
echo "$response"
}
call_xtrm "/Wallet/GetCompanyWallets" '{"GetCompanyWallets": {"request": {"IssuerAccountNumber": "SPN1111222"}}}'const XTRM_API = 'https://xapisandbox.xtrm.com/API/v4';
// Finds the OperationStatus object, whatever the wrapper names are.
function findOperationStatus(node) {
if (!node || typeof node !== 'object') return undefined;
if (node.OperationStatus) return node.OperationStatus;
for (const child of Object.values(node)) {
const status = findOperationStatus(child);
if (status) return status;
}
return undefined;
}
// Sends a JSON request and returns the parsed response. Throws when the
// HTTP status is not 2xx or OperationStatus.Success is not true.
async function callXtrm(endpoint, body) {
const response = await fetch(`${XTRM_API}${endpoint}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
Accept: 'application/json',
},
body: JSON.stringify(body),
});
const text = await response.text();
if (!response.ok) throw new Error(`${endpoint}: HTTP ${response.status}: ${text}`);
const data = JSON.parse(text);
const status = findOperationStatus(data);
if (status?.Success !== true) {
throw new Error(`${endpoint}: operation failed: ${JSON.stringify(status?.Errors ?? data)}`);
}
return data;
}
const data = await callXtrm('/Wallet/GetCompanyWallets', {
GetCompanyWallets: {
request: {
IssuerAccountNumber: 'SPN1111222',
},
},
});
console.log(JSON.stringify(data, null, 2));import os
import requests
XTRM_API = "https://xapisandbox.xtrm.com/API/v4"
def find_operation_status(node):
"""Returns the OperationStatus object, whatever the wrapper names are."""
if isinstance(node, dict):
if isinstance(node.get("OperationStatus"), dict):
return node["OperationStatus"]
children = node.values()
elif isinstance(node, list):
children = node
else:
return None
for child in children:
status = find_operation_status(child)
if status is not None:
return status
return None
def call_xtrm(endpoint, body):
"""Sends a JSON request and returns the parsed response. Raises when the
HTTP status is not 2xx or OperationStatus.Success is not true."""
response = requests.post(
XTRM_API + endpoint,
headers={
"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}",
"Accept": "application/json",
},
json=body,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"{endpoint}: HTTP {response.status_code}: {response.text}")
data = response.json()
status = find_operation_status(data)
if status is None or status.get("Success") is not True:
details = status.get("Errors") if status else data
raise RuntimeError(f"{endpoint}: operation failed: {details}")
return data
data = call_xtrm(
"/Wallet/GetCompanyWallets",
{
"GetCompanyWallets": {
"request": {
"IssuerAccountNumber": "SPN1111222",
}
}
},
)
print(data)using System.Net.Http.Headers;
using System.Text;
using System.Text.Json.Nodes;
const string XtrmApi = "https://xapisandbox.xtrm.com/API/v4";
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN"));
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var json = """
{
"GetCompanyWallets": {
"request": {
"IssuerAccountNumber": "SPN1111222"
}
}
}
""";
var data = await CallXtrm("/Wallet/GetCompanyWallets", json);
Console.WriteLine(data);
// Sends a JSON request and returns the parsed response. Throws when the
// HTTP status is not 2xx or OperationStatus.Success is not true.
async Task<JsonNode> CallXtrm(string endpoint, string body)
{
var response = await client.PostAsync(
XtrmApi + endpoint,
new StringContent(body, Encoding.UTF8, "application/json"));
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
throw new HttpRequestException($"{endpoint}: HTTP {(int)response.StatusCode}: {text}");
var parsed = JsonNode.Parse(text)!;
var status = FindOperationStatus(parsed);
if (status?["Success"]?.GetValue<bool>() != true)
throw new InvalidOperationException($"{endpoint}: operation failed: {status?["Errors"]?.ToJsonString() ?? text}");
return parsed;
}
// Finds the OperationStatus object, whatever the wrapper names are.
static JsonNode? FindOperationStatus(JsonNode? node)
{
if (node is JsonObject obj)
{
if (obj["OperationStatus"] is JsonObject status) return status;
foreach (var (_, child) in obj)
if (FindOperationStatus(child) is JsonNode found) return found;
}
else if (node is JsonArray array)
{
foreach (var child in array)
if (FindOperationStatus(child) is JsonNode found) return found;
}
return null;
}import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class XtrmClient {
static final String XTRM_API = "https://xapisandbox.xtrm.com/API/v4";
static final HttpClient HTTP = HttpClient.newHttpClient();
static final ObjectMapper MAPPER = new ObjectMapper();
// Sends a JSON request and returns the parsed response. Throws when the
// HTTP status is not 2xx or OperationStatus.Success is not true.
static JsonNode callXtrm(String endpoint, String body) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(XTRM_API + endpoint))
.header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HTTP.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() / 100 != 2) {
throw new RuntimeException(endpoint + ": HTTP " + response.statusCode() + ": " + response.body());
}
JsonNode data = MAPPER.readTree(response.body());
// findValue searches the whole tree, so the wrapper names don't matter.
JsonNode status = data.findValue("OperationStatus");
if (status == null || !status.path("Success").booleanValue()) {
throw new RuntimeException(endpoint + ": operation failed: " + (status == null ? data : status.path("Errors")));
}
return data;
}
public static void main(String[] args) throws Exception {
String json = """
{
"GetCompanyWallets": {
"request": {
"IssuerAccountNumber": "SPN1111222"
}
}
}
""";
System.out.println(callXtrm("/Wallet/GetCompanyWallets", json).toPrettyString());
}
}<?php
const XTRM_API = 'https://xapisandbox.xtrm.com/API/v4';
// Finds the OperationStatus object, whatever the wrapper names are.
function find_operation_status($node): ?array
{
if (!is_array($node)) {
return null;
}
if (isset($node['OperationStatus']) && is_array($node['OperationStatus'])) {
return $node['OperationStatus'];
}
foreach ($node as $child) {
$status = find_operation_status($child);
if ($status !== null) {
return $status;
}
}
return null;
}
// Sends a JSON request and returns the parsed response. Throws when the
// HTTP status is not 2xx or OperationStatus.Success is not true.
function call_xtrm(string $endpoint, string $json): array
{
$ch = curl_init(XTRM_API . $endpoint);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $json,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
'Accept: application/json',
],
]);
$text = curl_exec($ch);
if ($text === false) {
throw new RuntimeException("$endpoint: " . curl_error($ch));
}
$httpStatus = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($httpStatus < 200 || $httpStatus >= 300) {
throw new RuntimeException("$endpoint: HTTP $httpStatus: $text");
}
$data = json_decode($text, true, 512, JSON_THROW_ON_ERROR);
$status = find_operation_status($data);
if (($status['Success'] ?? null) !== true) {
throw new RuntimeException("$endpoint: operation failed: " . json_encode($status['Errors'] ?? $data));
}
return $data;
}
$data = call_xtrm('/Wallet/GetCompanyWallets', json_encode([
'GetCompanyWallets' => [
'request' => [
'IssuerAccountNumber' => 'SPN1111222',
],
],
]));
print_r($data);Batch payment responses need their own checks
Don't submit a batch payment through this helper: the response has no OperationStatus, so the helper would report a failure even though Xtrm accepted the batch. For a batch you submit, check for a 2xx status (202 Accepted), then read the body's Status, ItemsCount and the Rejected list. For the status endpoints, which are GET requests, read the batch's Status and each item's Status, and page with Pagination. Create a batch payment walks through both.
#Next steps
The batch lifecycle, wallet-first delivery, send methods, currency rules and limits.
Create a batch paymentBuild a batch, submit it and track every payment to its outcome.
ErrorsRejected items, attempt error codes and what the envelope endpoints return when a call fails.
API referenceEvery endpoint with its exact wrapper names, fields and example responses.