Accounts, wallets & IDs
Every batch payment moves money from one of your company's wallets to the people and businesses you pay. A BatchTransfer request names your company and the wallet that funds the batch. Each item in it names a recipient, a send method and a destination, and carries your own ID so you can follow it. This page explains the objects behind those fields and lists the identifiers you work with: what each looks like, which call returns it and where you use it.
#The object model
Xtrm has two kinds of account, told apart by the prefix of the account number: company accounts start with SPN and personal accounts start with PAT. A batch payment involves three roles:
| Role | Account | What it is | Field in a batch | How you get one |
|---|---|---|---|---|
| Your company | SPN | The company account that owns your API credentials and the wallets you pay from. | IssuerAccountNumber | You sign up for it. See Sandbox & environments. |
| Individual recipient | PAT | A person you pay. | RecipientId | CreateUser |
| Business recipient | SPN | A business you pay. | RecipientId | CreateBeneficiary |
We call anyone you pay a recipient. Older operation and field names in the API use other words: User means an individual recipient, and Beneficiary means a business recipient or, in some names, any recipient. So CreateUser creates an individual recipient, CreateBeneficiary creates a business recipient, and LinkBankBeneficiary links a bank account to either. Your company appears as Issuer or Remitter, as in IssuerAccountNumber and GetUserWalletTransactionsByRemitter.
Every account has Xtrm wallets, and each wallet holds one currency. Your company pays from its wallets, and each payment lands in a wallet of the recipient first. Xtrm is a payment platform, not a bank.
Individual and business recipients can also have linked bank accounts and cards. Each item in a batch delivers its payment to one of the recipient's wallets, bank accounts or cards, or as a digital gift card, a prepaid virtual debit card or a mailed check; the item's send method decides which. Recipients are Xtrm accounts in their own right: the tree shows what a batch refers to, not who owns what.
Your company (SPN…, sent as IssuerAccountNumber)
├── Wallets (WalletID; the one that funds a batch is its SourceWalletId)
└── Batch payments (CustomerBatchId)
└── Items: one per payment (CustomerTransactionId)
├── RecipientId the account you pay: PAT… or SPN…
├── SendMethodId how the payment is delivered (XTR945xx)
└── Destination where it is delivered, depending on SendMethodId
├── WalletId a wallet of the recipient
├── BeneficiaryBankID a bank account linked to the recipient
├── CardToken a card linked to the recipient
├── SKU and Email a gift card or prepaid card product
└── BeneficiaryCheck… the recipient name and address for a mailed check
Recipient: individual (PAT…) or business (SPN…)
├── Wallets (WalletID; one per currency for PAT, more than one allowed for SPN)
├── Linked bank accounts (BeneficiaryId; up to 3 for PAT, more for SPN)
└── Linked cards (CardToken)Batch payments are wallet-first: Xtrm credits each payment to a wallet of the recipient before it delivers the money on to an external destination such as a bank account or card. If the recipient has no wallet in the batch currency, Xtrm creates one named Wallet - <currency code>. While Xtrm delivers a bank, card, check, gift card or prepaid payment on from that wallet, the item shows RetainedInWallet, usually only briefly, and it moves on to Success once the delivery goes through. Don't act on that status while the batch is still Processing. An item that is still RetainedInWallet once the batch status is final didn't reach its destination, and the money stays in the recipient's Xtrm wallet. Treat it like a wallet payment. You can't retry it as a batch payment, and the fee isn't refunded. When a payment stays RetainedInWallet explains how the money moves on from there. See How batch payments work.
The prefix tells you the account type, not the role
Your company and the business recipients you pay both have SPN account numbers. The field tells you the role: IssuerAccountNumber is always your company (or, if you use pseudo credentials, the client company you call on behalf of), while RecipientId names the account an item in a batch pays. Other calls name the account they act on with fields such as UserID or BeneficiaryAccountNumber.
#Identifiers in a batch
These are the IDs a batch carries or returns, in the order you meet them.
| Identifier | Format and example | Which call returns it | Where you use it |
|---|---|---|---|
| Your company account number | Starts with SPN, e.g. SPN1111222 | None: it's your company's SPN, tied to the API credentials you get under Settings → Integrations → Get Credentials (see Sandbox & environments) | IssuerAccountNumber in BatchTransfer, and on nearly every other request |
| Source wallet ID | Number, e.g. 122181 | GetCompanyWallets and CreateCompanyWallet (WalletID) | SourceWalletId in BatchTransfer, as an integer (a numeric string such as "122181" works too). The wallet's currency is the batch currency. |
| Batch ID | Your own string, e.g. BATCH-IDS-0001. Required: Xtrm never generates one. | You set it in BatchTransfer. Xtrm echoes it in the 202 response (BatchTransferResponse.CustomerBatchId), in the status calls and in webhooks. | CustomerBatchId in BatchTransfer, and in the path of both status calls |
| Item ID | Your own string, e.g. TXN-IDS-0001. Required: Xtrm never generates one. | You set it on each item in BatchTransfer. Xtrm echoes it in Accepted or Rejected in the 202 response, in each item of the status calls and in item webhooks. | Items[].CustomerTransactionId in BatchTransfer, and in the path of the item status call |
| Recipient account number | PAT for an individual recipient (PAT9999888), SPN for a business recipient (SPN8888777) | Individual recipients: CreateUser (UserID), CheckUserExist and GetPersonalBeneficiaries (AccountNo). Business recipients: CreateBeneficiary and GetBeneficiaries (BeneficiaryID), CheckBeneficiaryExist (AccountNumber) | Items[].RecipientId |
| Send method ID | XTR945xx, e.g. XTR94500 | GetPaymentMethods (PaymentMethodId) | Items[].SendMethodId |
| Destination wallet ID | Number, e.g. 67812 (an individual recipient's wallet) or 122311 (a business recipient's) | GetUserWallets (WalletID) for an individual recipient, GetBeneficiaryWallets (ID) for a business recipient | Destination.WalletId on any item, as an integer (a numeric string such as "67812" works too). Optional: without it, Xtrm credits the recipient's oldest active Standard wallet in the batch currency, or creates one. See Recipient wallets. |
| Linked bank ID | 32-character hex string, e.g. 41953ec32f3e4765a35a902c82bdd995 | LinkBankBeneficiary and GetLinkedBankAccounts (BeneficiaryId) | Destination.BeneficiaryBankID on bank transfer items (XTR94500). Required for an individual recipient. A business recipient sent with a WalletId can be paid to the bank linked to that wallet instead; see Linked bank accounts. |
| Card token | A 15-character string of digits and capital letters A to F, e.g. EC1B22028C5B488, a transfer card in the GetLinkedCards example. Store it as a string, exactly as returned. | LinkCard and GetLinkedCards (CardToken) | Destination.CardToken on Rapid Transfer items (XTR94508). Required, and it must be a transfer card linked to the recipient. |
| Card product SKU | String, e.g. U935268 (a digital gift card) or PREP9001 (a prepaid card) | GetPrepaidCards and GetDigitalGiftCards (sku in items) | Destination.SKU, together with Destination.Email, on prepaid virtual debit card (XTR94503) and digital gift card (XTR94505) items, which pay individual recipients only. Required. |
| Attempt number | Integer: 1 for the first submission, one higher for each accepted resubmission | Both status calls with history=true, in each item's Attempts (AttemptNo) | Your records. When you resubmit a failed item, its next attempt gets the next AttemptNo, and the earlier attempts are kept. |
Copy field names exactly
The same kind of ID goes by different field names from call to call, sometimes differing only in case. A wallet ID is WalletID in GetCompanyWallets, ID in GetBeneficiaryWallets, and SourceWalletId or Destination.WalletId in a batch. Copy each field name from the endpoint's reference entry.
#A batch payment, field by field
This batch pays four items from wallet 122181, each with a different send method, so it shows every kind of destination ID. The recipients already exist, and each destination belongs to its recipient; the table after the code says where each ID comes from. Looking up a recipient's bank and card IDs needs a connection to the recipient, which your company has with every recipient it creates. 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" \
-d '{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-IDS-0001",
"Items": [
{
"CustomerTransactionId": "TXN-IDS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
}
},
{
"CustomerTransactionId": "TXN-IDS-0002",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311
}
},
{
"CustomerTransactionId": "TXN-IDS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
}
},
{
"CustomerTransactionId": "TXN-IDS-0004",
"RecipientId": "SPN9999888",
"Amount": 50,
"SendMethodId": "XTR94508",
"Destination": {
"CardToken": "EC1B22028C5B488"
}
}
]
}'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-IDS-0001',
Items: [
{
CustomerTransactionId: 'TXN-IDS-0001',
RecipientId: 'SPN8888777',
Amount: 100,
SendMethodId: 'XTR94500',
Destination: {
BeneficiaryBankID: '41953ec32f3e4765a35a902c82bdd995',
BeneficiaryBankPaymentMethod: 'ACH',
},
},
{
CustomerTransactionId: 'TXN-IDS-0002',
RecipientId: 'SPN8888776',
Amount: 50,
SendMethodId: 'XTR94504',
Destination: {
WalletId: 122311,
},
},
{
CustomerTransactionId: 'TXN-IDS-0003',
RecipientId: 'PAT9999888',
Amount: 50,
SendMethodId: 'XTR94503',
Destination: {
Email: '[email protected]',
SKU: 'PREP9001',
},
},
{
CustomerTransactionId: 'TXN-IDS-0004',
RecipientId: 'SPN9999888',
Amount: 50,
SendMethodId: 'XTR94508',
Destination: {
CardToken: 'EC1B22028C5B488',
},
},
],
}),
});
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-IDS-0001",
"Items": [
{
"CustomerTransactionId": "TXN-IDS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH",
},
},
{
"CustomerTransactionId": "TXN-IDS-0002",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311,
},
},
{
"CustomerTransactionId": "TXN-IDS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001",
},
},
{
"CustomerTransactionId": "TXN-IDS-0004",
"RecipientId": "SPN9999888",
"Amount": 50,
"SendMethodId": "XTR94508",
"Destination": {
"CardToken": "EC1B22028C5B488",
},
},
],
},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN"));
var json = """
{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-IDS-0001",
"Items": [
{
"CustomerTransactionId": "TXN-IDS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
}
},
{
"CustomerTransactionId": "TXN-IDS-0002",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311
}
},
{
"CustomerTransactionId": "TXN-IDS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
}
},
{
"CustomerTransactionId": "TXN-IDS-0004",
"RecipientId": "SPN9999888",
"Amount": 50,
"SendMethodId": "XTR94508",
"Destination": {
"CardToken": "EC1B22028C5B488"
}
}
]
}
""";
var response = await client.PostAsync(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer",
new StringContent(json, Encoding.UTF8, "application/json"));
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
String json = """
{
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-IDS-0001",
"Items": [
{
"CustomerTransactionId": "TXN-IDS-0001",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
}
},
{
"CustomerTransactionId": "TXN-IDS-0002",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311
}
},
{
"CustomerTransactionId": "TXN-IDS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
}
},
{
"CustomerTransactionId": "TXN-IDS-0004",
"RecipientId": "SPN9999888",
"Amount": 50,
"SendMethodId": "XTR94508",
"Destination": {
"CardToken": "EC1B22028C5B488"
}
}
]
}
""";
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-IDS-0001',
'Items' => [
[
'CustomerTransactionId' => 'TXN-IDS-0001',
'RecipientId' => 'SPN8888777',
'Amount' => 100,
'SendMethodId' => 'XTR94500',
'Destination' => [
'BeneficiaryBankID' => '41953ec32f3e4765a35a902c82bdd995',
'BeneficiaryBankPaymentMethod' => 'ACH',
],
],
[
'CustomerTransactionId' => 'TXN-IDS-0002',
'RecipientId' => 'SPN8888776',
'Amount' => 50,
'SendMethodId' => 'XTR94504',
'Destination' => [
'WalletId' => 122311,
],
],
[
'CustomerTransactionId' => 'TXN-IDS-0003',
'RecipientId' => 'PAT9999888',
'Amount' => 50,
'SendMethodId' => 'XTR94503',
'Destination' => [
'Email' => '[email protected]',
'SKU' => 'PREP9001',
],
],
[
'CustomerTransactionId' => 'TXN-IDS-0004',
'RecipientId' => 'SPN9999888',
'Amount' => 50,
'SendMethodId' => 'XTR94508',
'Destination' => [
'CardToken' => 'EC1B22028C5B488',
],
],
],
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));| Item | RecipientId | SendMethodId | Destination ID | Where you get it |
|---|---|---|---|---|
TXN-IDS-0001 | SPN8888777, a business recipient | XTR94500, bank transfer | BeneficiaryBankID | BeneficiaryId from GetLinkedBankAccounts |
TXN-IDS-0002 | SPN8888776, a business recipient | XTR94504, company wallet | WalletId | ID from GetBeneficiaryWallets |
TXN-IDS-0003 | PAT9999888, an individual recipient | XTR94503, prepaid virtual debit card | SKU, plus the Email that receives the card | sku from GetPrepaidCards |
TXN-IDS-0004 | SPN9999888, a business recipient | XTR94508, Rapid Transfer | CardToken of a transfer card | CardToken from GetLinkedCards |
XTR94504 (AnyPay Company) pays a business recipient's wallet; to pay an individual recipient's wallet, use XTR94502 (AnyPay Individual). IssuerAccountNumber is your company and SourceWalletId is one of its wallets. For what every send method needs, see Payment methods & destinations.
Xtrm checks the fields of each item when you submit the batch and answers 202 Accepted when at least one item passes. The response echoes your CustomerBatchId and lists each accepted item by its CustomerTransactionId, with its recipient, send method, amount and currency, and each rejected item in Rejected, also by CustomerTransactionId. The amount comes back as a number with the decimals you sent, so 100 comes back as 100.0. Errors covers the rejections. This excerpt shows the first item accepted:
{
"BatchTransferResponse": {
"CustomerBatchId": "BATCH-IDS-0001",
"Status": "Accepted",
"Accepted": [
{
"CustomerTransactionId": "TXN-IDS-0001",
"Amount": 100.0,
"Currency": "USD",
"SendMethodId": "XTR94500",
"RecipientId": "SPN8888777"
}
],
"Rejected": []
}
}202 Accepted doesn't mean the payments went through. Xtrm checks that each recipient, recipient wallet, bank account, card token and SKU exists, and that your balance covers the item, while it processes the item. Follow each item by its IDs with the status calls; see Batch and item IDs and How batch payments work.
#Your company and its wallets
Your company is the SPN account tied to the API credentials you get from Settings → Integrations → Get Credentials in the Xtrm dashboard. Nearly every request carries its account number as IssuerAccountNumber; in a batch, it is the account that owns the source funds. If you're a managing platform using a client company's pseudo credentials, which require manager services, IssuerAccountNumber is instead that client company's SPN, and "your company" on these pages means the client company. See How managing platforms work.
A few requests don't take IssuerAccountNumber, among them the token request, the lists that take an empty {} body and the two batch status calls; see Requests & responses. The status calls identify the batch by your IDs in the path, and your access token is scoped to your company account. You can look up only the batches that belong to a company your token can act for; any other batch returns 401.
#Choose the source wallet
A batch pays from one of your company's wallets. List them, with their IDs, currencies and balances, with GetCompanyWallets:
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));{
"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
}
}
}
}Send the WalletID of the wallet you pay from as SourceWalletId, as the same JSON number: 122181 in the batch above. It must be an active wallet of your company itself: a wallet that another company shares with you fails the whole request with 403. The wallet determines the currency of the batch: every item pays in that currency, and the status calls report it in Currency. A company can hold more than one wallet in the same currency, so pick the wallet by its WalletID. To add a wallet, see CreateCompanyWallet.
We recommend checking that WalletBalance covers the batch and its fees before you submit it. The balance is checked as each item is processed, for the item's Amount plus its fee, and an item the wallet can't cover fails with INSUFFICIENT_BALANCE.
In the sandbox, Xtrm credits test funds to your sandbox wallets after approving your IP addresses. See Test funds.
#Batch and item IDs
CustomerBatchId identifies a batch payment and CustomerTransactionId identifies one payment in it. They are your tracking IDs: you choose them, and you use them to look up status and to reconcile with your own records. Xtrm echoes both, as it stored them, in the submit responses, the status responses and the item webhook events (Batch.Item.…); the batch-level webhook events carry only CustomerBatchId.
Both are required, and Xtrm never generates either one. Each is a string of 1 to 128 letters, digits and . _ - : @. CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID. A CustomerTransactionId only has to be unique within its batch. Retries & idempotency has every rule for these IDs, what Xtrm does when you send one again, and how to retry safely.
The batch payment endpoints return no transaction ID of Xtrm's own, so store both IDs with your payment records. Create them before the first send: if a response never reaches you, you can then resend the identical request. See A safe retry pattern.
#Look up a payment by its IDs
Pass your IDs in the path of the status calls. GET /Fund/BatchTransfer/{CustomerBatchId} returns the batch and a page of its items; GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId} returns one item. Set history to true to include every attempt:
curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true" \
-H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`,
},
});
const data = await response.json();
console.log(JSON.stringify(data, null, 2));import os
import requests
response = requests.get(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN"));
var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true"))
.header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN"))
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());<?php
$ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-IDS-0001/Items/TXN-IDS-0001?history=true');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));The response identifies the item by its CustomerBatchId and CustomerTransactionId, repeats its RecipientId, SendMethodId, Amount and Currency, and lists each attempt in Attempts with its AttemptNo, Result and ErrorCode. Batch and payment statuses explains each status, the DeliveryType and the error codes on attempts. If you use webhooks, the events carry the same IDs; see Webhooks.
#Recipients
Each item's RecipientId is the account number of the person or business you pay: an individual recipient (PAT) or a business recipient (SPN). It must be an existing Xtrm account: a batch never creates an account or a connection. Xtrm checks the account while it processes the item, not when it accepts the batch, and a RecipientId that doesn't match an account in status active (A), email not verified (NC) or pending approval (EV) fails the item with RECIPIENT_NOT_FOUND.
Create recipients before the batch
Look up or create each recipient before you add it to a batch: create a person with CreateUser or a company with CreateBeneficiary, then send the account number it returns as RecipientId. You can pay the new account right away.
In the Xtrm web app, you can create a person's account as you pay them, which also connects it to your company, but a company needs more details, so you create it first.
Once Xtrm credits a payment to a recipient's wallet, the recipient appears in your recipient list, which GetPersonalBeneficiaries and GetBeneficiaries page through. The list also holds every recipient you create or connect to.
#Individual recipients
An individual recipient is a person's Xtrm account. Its account number starts with PAT, for example PAT9999888. The recipient can use the account to make and receive payments, and has Xtrm wallets, one per currency.
CheckUserExistlooks up one person byEmailand returns the account number asAccountNo. We recommend calling it before you create an account.GetPersonalBeneficiariespages through the individual recipients in your recipient list, each with itsAccountNo.CreateUsercreates the account with a full profile and returns the account number asUserID. It also creates a wallet in the currency of the country inAddress.CountryISO2.
Here is an example CreateUser response:
{
"CreateUserResponse": {
"CreateUserResult": {
"UserID": "PAT9999888",
"AccountIdentityLevel": "Standard",
"OperationStatus": {
"Success": true,
"Errors": null
}
}
}
}Store the UserID. It is the value you send as RecipientId in a batch item, and as UserID in the personal wallet calls such as GetUserWallets. For the full request, see Pay individual recipients.
AccountIdentityLevel is the compliance verification level of the account's identity, on one scale for people and companies. It rises as the profile is completed:
| Level | What the profile holds |
|---|---|
Draft | The lowest level: the account exists with only the bare minimum of details. |
Basic | First and last name and email address, plus the company name for a company. |
Standard | Everything in Basic plus the full address: street, city, state, country and postal code. A person's profile also needs a tax ID and date of birth. |
Advanced | A complete profile: everything in Standard, the tax ID for a company, and the identity documents uploaded in the Xtrm web app. For a company, that's a government-issued photo ID of its administrator and, for a private company, a company tax document that shows its tax ID (a W-9 for a US company); a public company needs only the photo ID. No API call uploads documents. |
Xtrm approves accounts you create through the API straight away, at whatever level their profile has reached. You can read any account's level, connected or not, with CheckUserExist or CheckBeneficiaryExist. A company needs a 100% complete profile, which the API reports as Advanced, and an approved advanced profile before Xtrm unlocks funding for its account; see Complete the advanced profile. Getting a company there isn't API-only, because no API call uploads documents. The company uploads its documents in the Xtrm web app, under Identity > Identity Documents. For a client company, your platform can upload them for it instead, as a manager service: choose Identity Documents in the company's Connected Manager Services menu. Then the company, or your platform for it, submits the advanced profile (the Advanced Services application), in the web app or with CompanyAdvancedProfile.
Real data only in production
Xtrm reviews new personal accounts with identity checks (KYC), so the information you submit must be real and accurate. Don't create test recipients or test email addresses in production.
#Business recipients
A business recipient is the Xtrm account of a business you pay. Like your company, its account number starts with SPN, for example SPN9999888.
CheckBeneficiaryExistsearches every company account on Xtrm and returns each match's account number asAccountNumber. When you know the company's email domain, search withCompanyEmailDomainon its own: send the domain (acmecorp.com) or any address at it ([email protected]). A company's own domain usually returns just that company, and a shared domain can return several. ACompanyNamesearch returns every company whose name contains the text, and if you send both, you get the companies that match either one. CheckEmailandNamebefore you use anAccountNumber. Companies often already have an Xtrm account, so search before you create one.GetBeneficiariespages through the business recipients in your recipient list, each with itsBeneficiaryID.CreateBeneficiarycreates the company and its master administrator, and returns the account number asBeneficiaryID.
Here is an example CreateBeneficiary response, with placeholder values for the credentials:
{
"CreateBeneficiaryResponse": {
"CreateBeneficiaryResult": {
"BeneficiaryID": "SPN9999888",
"AccountIdentityLevel": "Basic",
"ClientID": "YOUR_CLIENT_ID",
"SecretKey": "YOUR_CLIENT_SECRET",
"OperationStatus": {
"Success": true,
"Errors": []
}
}
}
}BeneficiaryID is the account number you send as RecipientId in a batch item, and as BeneficiaryAccountNumber in calls such as GetBeneficiaryWallets. ClientID and SecretKey are your pseudo credentials for the new company, not the company's own credentials: with them, your company requests an access token that acts as the new company, with its SPN as IssuerAccountNumber. If you call CreateBeneficiary with a client company's pseudo credentials, the pair is issued to that client company. Pseudo credentials require manager services, which Xtrm turns on for your company. Keep them on your server, as you keep your own, and out of logs. See Pseudo credentials. For the full request, see Pay business recipients.
Real data only in production
Every business recipient you create goes through identity checks (KYC). Don't create test companies or test email addresses in production.
#Connections
You don't need a connection to pay an account in a batch, and paying it doesn't connect it. A connection is what lets your company manage more about a recipient: for example, link a bank account with LinkBankBeneficiary, see an individual recipient's balance with GetUserWalletBalance or update a profile with UpdateUser.
Your company is connected to every recipient it creates with CreateUser or CreateBeneficiary. In the API, you connect an account that already exists with a one-time password: its holder gives you the code that GetOTPAuthorizedVendor sends them, and you confirm it with ValidateOTPAuthorizeVendor. See Connect existing accounts. Connections and manager services lists what your company can do with and without a connection.
#Destinations
An item's SendMethodId picks how the payment is delivered, and its Destination object says where. Wallet, bank and card IDs refer to the item's recipient, so look them up with the same account number you send as RecipientId.
Looking up or linking a recipient's bank accounts and cards needs a connection to the recipient, which you have with every recipient you create. Listing an individual recipient's wallets with GetUserWallets doesn't, and neither does a wallet item that leaves Destination empty.
| Send method | SendMethodId | Destination ID | Where you get it |
|---|---|---|---|
| Bank transfer | XTR94500 | BeneficiaryBankID (required for an individual recipient; see Linked bank accounts) | BeneficiaryId from GetLinkedBankAccounts |
| Wallet of an individual recipient | XTR94502 | WalletId (optional) | WalletID from GetUserWallets |
| Wallet of a business recipient | XTR94504 | WalletId (optional) | ID from GetBeneficiaryWallets |
| Prepaid virtual debit card (individual recipients only) | XTR94503 | SKU, with Email (both required) | sku from GetPrepaidCards |
| Digital gift card (individual recipients only) | XTR94505 | SKU, with Email (both required) | sku from GetDigitalGiftCards |
| Rapid Transfer (push to card) | XTR94508 | CardToken of a transfer card (required) | CardToken from GetLinkedCards |
| Check (US only) | XTR94507 | None: the recipient's name and mailing address go in the BeneficiaryCheck… fields | Not needed |
Every send method also accepts Destination.WalletId, which picks the recipient's wallet that Xtrm credits first; see Recipient wallets. GetPaymentMethods lists the send method IDs with their names, for example XTR94500 (Bank). Payment methods & destinations has every field each method takes and the checks Xtrm runs on it.
#Recipient wallets
On any item, Destination.WalletId picks the recipient's wallet that Xtrm credits. Send the ID as a JSON number: WalletID from GetUserWallets for an individual recipient, or ID from GetBeneficiaryWallets for a business recipient. Leave it out and Xtrm credits the recipient's wallet in the batch currency, creating one if the recipient doesn't have one. Wallets: XTR94502 and XTR94504 says which wallet Xtrm picks and when a wallet ID fails the item.
#Linked bank accounts
LinkBankBeneficiary links a bank account that receives payments to a recipient's account (UserID, SPN or PAT), and GetLinkedBankAccounts lists a recipient's linked bank accounts (RecipientUserId). To link a bank for a recipient, the recipient must be connected to your company; see Connections. Both calls identify each linked bank profile with a BeneficiaryId, such as 907599f594b044d08cf81a2afb0a7967. A personal account can have up to 3 linked banks, and a company account more, up to a limit Xtrm sets. A link over the limit fails with 400 and the message You can link maximum N banks.
To pay a linked bank account, send its BeneficiaryId as Destination.BeneficiaryBankID on a bank transfer (XTR94500) item. The bank must be linked to the recipient you pay. A business recipient's wallet can also have a bank of its own, which a bank transfer item that names that wallet in WalletId may pay instead: Bank transfer: XTR94500 explains which bank Xtrm pays and when you can leave BeneficiaryBankID out.
To delete a linked bank account, send its BeneficiaryId as BeneficiaryBankID in DeleteBankBeneficiary. Banks linked for bank debit with LinkACHDebitBankBeneficiary are for funding your company wallets; see Fund your wallet.
BeneficiaryId is not an account number
In the bank calls, BeneficiaryId identifies a linked bank profile, such as 907599f594b044d08cf81a2afb0a7967. Don't confuse it with BeneficiaryID in CreateBeneficiary, GetBeneficiaries and UpdateBeneficiary, which is a business recipient's SPN account number.
#Linked cards
LinkCard links a card to a recipient's account (UserID) and returns a CardToken; GetLinkedCards lists a recipient's cards with their tokens (userid). Both need a connection to the recipient. To pay a linked card, send its token as Destination.CardToken on a Rapid Transfer (XTR94508) item, the push-to-card method; Push to card: XTR94508 lists what the item needs. DeleteCard and UserWithdrawFund take the token as CardToken too.
LinkCard takes a LinkCardType: identity or transfer. transfer cards are prepaid debit cards that receive funds, and only they can receive a Rapid Transfer item. Only US cards can be linked, and a transfer card must be able to receive push payments. In the GetLinkedCards example, EC1B22028C5B488 is a transfer card and A3F9C27E1B8D054 is an identity card.
#Gift card and prepaid card SKUs
Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505) items name a product by its SKU and send the card's digital credentials to the address in Email. GetPrepaidCards and GetDigitalGiftCards take a Currency and list the products, each with its sku; the catalogs vary by currency, so pick the SKU from the catalog for your batch currency. In the examples on these pages, U935268 is a digital gift card and PREP9001 is a prepaid card. Payment methods & destinations lists what each card item needs, and Rewards with gift & prepaid cards walks through paying with them.
#Wallets
A wallet is one account's balance in one currency. Xtrm generates its WalletID. After you create a wallet you can change only its name: the WalletID and currency are fixed.
| Account | Wallets per currency | Create | List | Rename |
|---|---|---|---|---|
| Your company | More than one allowed | CreateCompanyWallet | GetCompanyWallets | UpdateCompanyWallet |
| Business recipient | More than one allowed | CreateBeneficiaryCompanyWallet | GetBeneficiaryWallets | UpdateBeneficiaryCompanyWallet |
| Individual recipient | One | CreateUserWallet (CreateUser also creates one with the account) | GetUserWallets; GetUserWalletBalance for a balance | UpdateUserWallet |
- Batch payments create wallets. If a recipient has no wallet in the batch currency, Xtrm creates one, so you don't have to create recipient wallets before you pay.
- Personal wallets are one per currency, so some calls identify a personal wallet by account and currency instead of
WalletID:GetUserWalletBalance(UserIdandCurrency),GetUserWalletTransactions(UserIDandWalletCurrency) andUserWithdrawFund(UserIDandCurrency). - Create
Standardwallets. When you create a wallet for your company or a business recipient, setWalletTypetoStandard. The field is required, andStandardis the only type to use when you create a wallet through the API. - Some calls need a connection. Creating a recipient's wallets, renaming an individual recipient's wallet and reading its balance work only for a recipient connected to your company. Listing an individual recipient's wallets with
GetUserWalletsdoesn't need a connection, and you can rename a business recipient's wallet once the business is in your recipient list. Connections and manager services lists every call. - Send the ID, not the name. Where a funding, exchange or recipient transfer request names a wallet, send its numeric
WalletID, for example"122181". A funding or recipient transfer request with a wallet name in place of the ID is rejected, and no money moves.
#Three wallet lists, three shapes
The three list calls describe the same things with different field names:
GetCompanyWallets | GetBeneficiaryWallets | GetUserWallets | |
|---|---|---|---|
| Whose wallets | Your company (IssuerAccountNumber) | A recipient (BeneficiaryAccountNumber) | An individual recipient (UserID) |
| Wallet ID | WalletID | ID | WalletID |
| Name | WalletName | Name | WalletName |
| Currency | WalletCurrency | Currency | WalletCurrency |
| Balance | WalletBalance | Balance | Not returned; use GetUserWalletBalance |
| Type | WalletType | Type | Not returned |
| Bank link flags | IsBankLinked, AllowWalletLinkedBankOverride | IsBankLinked, AllowWalletLinkedBankOverride | Not returned |
| Entity ID | EntityID | EntityID | Not returned |
#Other identifiers
| Identifier | Format and example | Which call returns it | Where you use it |
|---|---|---|---|
| Wallet transaction ID | Number in lists (888601), string in requests ("888601") | GetCompanyWalletTransactions and GetUserWalletTransactions (TransactionID) | TransactionID in GetCompanyWalletTransactionDetails and GetUserWalletTransactionDetails |
| Program ID | String from CreateProgram ("1026"), number from GetPrograms (1026) | CreateProgram (ProgramID), GetPrograms (ProgramId) | ProgramID in FundWalletUsingBankTransfer and UpdateProgram |
| Program category and type IDs | Numbers in responses (2, 4), strings in requests ("2") | ProgramCategory (CategoryID), ProgramType (SubCategoryID) | CategoryID in ProgramType; TransactionCategoryID and TransactionSubCategoryID in CreateProgram and UpdateProgram |
| Entity ID | Number, e.g. 27044 | GetEntities (EntityId) | EntityID in wallet creation (CreateCompanyWallet, CreateBeneficiaryCompanyWallet) and in bank and card linking; see Entity IDs |
#Wallet transaction IDs
Your batch payments are tracked by your own CustomerBatchId and CustomerTransactionId. Wallet history uses IDs that Xtrm generates: GetCompanyWalletTransactions, GetUserWalletTransactions and GetUserWalletTransactionsByRemitter return a TransactionID (a number) for each credit and debit in a wallet. To see the full breakdown of a wallet transaction, pass its TransactionID as a string to GetCompanyWalletTransactionDetails or GetUserWalletTransactionDetails; GetUserWalletTransactionDetails also needs the UserID.
Each item in a batch is debited from your source wallet on its own, for its Amount plus its fee, when Xtrm processes it. Wallet transactions carry Xtrm's IDs rather than yours: no wallet call returns or searches your CustomerBatchId or CustomerTransactionId, so keep both of your IDs with every payment record.
What a wallet transaction does carry is the item's Description. Xtrm copies it to the debit in your source wallet and to the credit in the recipient's wallet, so it's the key that ties a payment to its money. We recommend starting every item's Description with its CustomerTransactionId, for example "TXN-2026-9912A Q3 Contractor Bonus". You can then find the payment's debit with GetCompanyWalletTransactions: send Filters with the ID in SearchParam, "TransactionType": "Sent" and a DateRange from the day before the payment was processed to the day after. The debit's TransactionID opens its details. The recipient sees the Description too, so use text you're happy to share. Track & reconcile payments shows how to match wallet transactions to your payments.
#Programs
Programs are your company's payment programs or projects, such as remittance, payment or budget programs. CreateProgram returns the new program's ID as a string in ProgramID ("1026"), and GetPrograms lists programs with the ID as a number in ProgramId (1026). To associate a funding transaction with a program, send the ID as ProgramID in FundWalletUsingBankTransfer. UpdateProgram requires ProgramID to identify the program you update. A batch payment request has no program field.
CreateProgram and UpdateProgram also take a category and a type. ProgramCategory lists the categories, each with a CategoryID, and ProgramType lists the types (subcategories) in a category, each with a SubCategoryID. Send them as TransactionCategoryID and TransactionSubCategoryID.
#Entity IDs
A company account can be divided into entities, for example a headquarters, a subsidiary and a regional branch. One of them is the company's prime entity, its default. GetEntities lists the active entities of the account in UserID, prime entity first, each with its EntityId and an IsPrimeEntity flag. It works for your own company and for a company connected to yours.
EntityID is always one of these Xtrm entity IDs, never a value from your own systems, and it's optional in every request that takes it:
- Wallet creation.
CreateCompanyWalletcreates the wallet in that entity of your company, andCreateBeneficiaryCompanyWalletin that entity of the business recipient. LeaveEntityIDout, or send0, and the wallet goes into the company's prime entity. An ID that isn't one of that company's active entities fails with400and<id> - Invalid Entity ID.CreateUserWallettakes noEntityID. - Bank and card linking. In
LinkBankBeneficiary,LinkACHDebitBankBeneficiaryandLinkCard,EntityIDmaps the bank or card profile to one of the entities of the company inUserID.LinkBankBeneficiaryandLinkCardignore it for a personal account. TheLinkCardexample links a card forSPN9999888withEntityID27044, that company's prime entity in theGetEntitiesexample.
Send a whole number, or leave the field out. An empty string (""), a negative number or any other value that isn't a whole number fails with 400 and EntityID must be an integer.
The wallet lists return the entity each wallet belongs to as EntityID: GetCompanyWallets for your company's wallets and GetBeneficiaryWallets for a recipient's, where 0 means the wallet has no entity.
#Next steps
The batch lifecycle, wallet-first delivery and how your IDs are used.
GuideCreate a batch paymentPut these IDs together into a batch payment and follow it to completion.
Batch paymentsPayment methods & destinationsEvery send method and the Destination fields it takes.
Resubmit a batch payment safely with the same CustomerBatchId and CustomerTransactionId.