Payment methods & destinations
Each payment in a batch can go to a bank account by ACH, wire or RTP, to a card, as a mailed check or a gift card, or straight into the recipient's Xtrm wallet. SendMethodId picks the method for each item, and the Destination object carries the fields that method needs. Each item has its own method, so one batch can pay bank accounts, wallets, cards and checks together.
Payments and currency exchange are executed by regulated financial partners.
This page lists every payment method, the Destination fields it takes and where to get each value. For the batch itself, see How batch payments work, Create a batch payment and the BatchTransfer reference.
#Methods at a glance
SendMethodId | Method | Delivers to | Required Destination fields |
|---|---|---|---|
XTR94500 | Bank transfer | The recipient's linked bank account, by ACH, wire or RTP | BeneficiaryBankID or WalletId; see Bank transfer |
XTR94502 | Individual wallet | An individual recipient's Xtrm wallet | None |
XTR94504 | Business wallet | A business recipient's Xtrm wallet | None |
XTR94508 | Push to card (Rapid Transfer in the API) | A US card linked to the recipient as a transfer card | CardToken |
XTR94503 | Prepaid virtual debit card | An individual recipient, as a prepaid card whose credentials are sent by email | Email, SKU |
XTR94505 | Digital gift card | An individual recipient, as a gift card whose credentials are sent by email | Email, SKU |
XTR94507 | Physical check | A check mailed to a US address | BeneficiaryCheckName, BeneficiaryCheckAddress1, BeneficiaryCheckCity, BeneficiaryCheckState, BeneficiaryCheckPostalCode, BeneficiaryCheckCountryCodeISO2, BeneficiaryCheckMemo, BeneficiaryCheckReference |
Destination itself is required on every item, even when all of its fields are optional for the method. For example, send "Destination": {} for a wallet item without a WalletId.
Prepaid and gift cards (XTR94503, XTR94505) can pay individual recipients only: an item for a business recipient fails during processing with SENDMETHODID_NOT_FOUND. Bank, push-to-card and check items can pay both kinds of recipient.
Every payment lands in the recipient's wallet first (see wallet-first delivery). For a bank, card or check payment, Xtrm first credits the recipient's wallet, then debits it and delivers the payment, and the item becomes Success when the bank or provider accepts it. RetainedInWallet is a pass-through status for bank, card, check, gift card and prepaid payments: wait while the batch is Processing. If the payment is still RetainedInWallet once the batch is final, the delivery didn't go through, the money stays in the recipient's Xtrm wallet, and the fee isn't refunded: treat it like a wallet payment (details). For what each status means and what to do, see Batch and payment statuses.
Match on the ID, not the name
The same method goes by different names in different places. For example, GetPaymentMethods calls XTR94502 AnyPay Individual, XTR94504 AnyPay Company, XTR94500 Bank and XTR94507 Bank Check. Always match on the XTR945xx ID.
#Destination fields by method
Copy each field name exactly as shown here. Names match in any case, but Xtrm silently drops a field it doesn't recognize, so a misspelled name such as Wallet_Id is lost without an error. Xtrm also discards fields that don't belong to the item's method, except WalletId, which every method accepts.
#Bank transfer: XTR94500
Use XTR94500 to pay a recipient's linked bank account by ACH, wire or RTP.
| Field | Required | If you omit it | Where the value comes from |
|---|---|---|---|
BeneficiaryBankID | Individual recipient: yes. Business recipient: yes, unless you send WalletId | With no WalletId either, the item is rejected with Beneficiary bank id or wallet id is required.. For an individual recipient, the item fails during processing with BENEFICIARY_BANKID_REQUIRED: Xtrm never falls back to a default bank. For a business recipient sent with WalletId, Xtrm uses the bank linked to that wallet (see below). | The linked bank's 32-character BeneficiaryId, from GetLinkedBankAccounts or the LinkBankBeneficiary response |
BeneficiaryBankPaymentMethod | No | Xtrm uses the bank account's primary rail. | The rail: exactly ACH, WIRE or RTP, in any case. Xtrm rejects other names when you submit the batch. |
WalletId | No | Xtrm credits the recipient's oldest active Standard wallet in the batch currency, as for wallet items. | For a business recipient, the wallet whose linked bank you want to pay; see the callout below |
- Link the recipient's bank account first with
LinkBankBeneficiary. Linking needs the recipient to be connected to the company inIssuerAccountNumber; an account you create withCreateUserorCreateBeneficiaryis connected from the start. The bank item itself needs no connection: Xtrm checks only that the bank is linked to the recipient. An individual recipient can have up to 3 linked banks and a business recipient up to 25;LinkBankBeneficiaryrefuses further links withYou can link maximum N banks. GetLinkedBankAccountstakes the recipient's account number inRecipientUserId. Each linked bank lists its rails inBankDetails.BeneficiaryBankInformation.PaymentMethods, for example["ACH"]. Treat that list as a guide, not a promise: during processing, Xtrm checks the rail against the bank's own rail and Xtrm's RTP settings. A rail that doesn't fit them fails during processing withINVALID_PAYMENTMETHOD. Some rail problems show up only after the wallet credit, asInvalid payment method, and the payment staysRetainedInWalletonce its batch is final.- During processing, before any money moves, the bank must be pending or approved and linked to the recipient's account (or to another profile of the same company). Otherwise the item fails with
BANKID_INVALID, for example for a mistyped or deleted bank, or another account's bank. A bank that the bank provider doesn't recognize fails withBANK_NOT_FOUND. - Don't take bank IDs from
GetACHDebitLinkedBankAccounts. That list holds the banks that fund company wallets by bank debit, not the banks you pay.
Check the wallet's bank flags first
When you pay a business recipient and send WalletId, the wallet's AllowWalletLinkedBankOverride flag decides which bank is paid. Check it, and IsBankLinked, with GetBeneficiaryWallets first.
false(the default): Xtrm always pays the bank linked to the wallet, and silently replaces anyBeneficiaryBankIDyou send. If the wallet has no linked bank, the item fails withDEFAULT_BANK_NOT_FOUND, even when you sent a bank.true: Xtrm pays theBeneficiaryBankIDyou send, or the wallet's linked bank if you leave it out. With neither, the item fails withDEFAULT_BANK_NOT_FOUND.
If the wallet's linked bank was deleted, the item fails with BANKID_INVALID. Without WalletId, or for an individual recipient, Xtrm doesn't read the flag. The linked bank and the flag are set in the Xtrm web app or by Xtrm staff, not through the API.
#Wallets: XTR94502 and XTR94504
Use XTR94502 to pay an individual recipient's Xtrm wallet and XTR94504 to pay a business recipient's wallet. The RecipientId must start with PAT for XTR94502 and with SPN for XTR94504; otherwise Xtrm rejects the item when you submit the batch. A wallet item is Success as soon as the recipient's wallet is credited.
Xtrm recommends paying into the Xtrm wallet: the recipient then decides how to transfer the money out of it.
| Field | Required | If you omit it | Where the value comes from |
|---|---|---|---|
WalletId | No | Xtrm credits the recipient's oldest active Standard wallet in the batch currency, not the wallet marked as default. If the recipient has no active wallet in that currency, Xtrm creates one named Wallet - <currency code>, for example Wallet - EUR. If its only wallets in that currency are of another type, the item fails with WALLET_AUTO_CREATE_FAILED. | The recipient's wallet ID: ID from GetBeneficiaryWallets (business and individual recipients), or WalletID from GetUserWallets (individual recipients) |
- The wallet lists return the ID as a number, for example
67812; send it inWalletIdas a number too. WalletIdworks on every payment method, not only on wallets: on a bank, card or check item it picks the recipient wallet that Xtrm credits before the delivery. It can't be yourSourceWalletId; that rejects the item. During processing, it must be an active wallet of the recipient in the batch currency; otherwise the item fails withINVALID_BENEFICIARY_WALLETbefore any money moves.- An individual recipient has one wallet per currency. A business recipient can have more than one wallet in the same currency, so set
WalletIdwhen the money must land in a specific one.
#Push to card: XTR94508
Push to card pays a card linked to the recipient. The API calls this method Rapid Transfer. It works only in USD batches: from a source wallet in another currency, the item fails during processing with CURRENCY_MISMATCH.
| Field | Required | If you omit it | Where the value comes from |
|---|---|---|---|
CardToken | Yes | The item is rejected. | The card's CardToken from GetLinkedCards, or from the LinkCard response when you link the card. It's a 15-character string of digits and capital letters A to F, for example EC1B22028C5B488; store and send it as a string, exactly as returned. |
- Link the recipient's card with
LinkCard, settingLinkCardTypetotransfer. Only US cards (CountryCode2set toUS) can be linked, and atransfercard must be enabled for push payments when you link it. - During processing, before any money moves, the token must be an active
transfercard linked to the recipient's account. Otherwise the item fails withTOKEN_NOT_FOUND, for example for anidentitycard, a deleted card or another account's card. For a business recipient, the card must be linked to the company's own account. GetLinkedCardstakes the recipient's account number in lowercaseuseridand returns each card'sCardTokenandLinkCardType.
#Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505)
Both methods deliver a card by email, to individual recipients only. They take the same fields; the SKU comes from a different catalog for each.
| Field | Required | If you omit it | Where the value comes from |
|---|---|---|---|
Email | Yes | The item is rejected. | The email address that receives the card's digital credentials, for example the recipient's own address. It must be a valid address. |
SKU | Yes | The item is rejected. | A product sku, at most 20 characters, from GetPrepaidCards for XTR94503, or from GetDigitalGiftCards for XTR94505 |
- Both catalogs take a
Currencyand vary by currency. Request them in the batch currency, which is the currency of your source wallet. - Each product has a
valueType:FIXED_VALUEorVARIABLE_VALUE. AFIXED_VALUEproduct is a set denomination: its price is infaceValue, andminValueandmaxValueare0. AVARIABLE_VALUEproduct takes any amount fromminValuetomaxValue, and itsfaceValueis0. For example, prepaid cardPREP9001isVARIABLE_VALUEfrom USD 5.00 to USD 1,000.00, and gift cardU935268isFIXED_VALUEat USD 25.00. - During processing, before any money moves, a fixed-value card needs an
Amountequal to its face value, and a variable-value card anAmountbetween its minimum and maximum. Otherwise the item fails withINVALID_CARD_AMOUNT. - In both catalogs, each product also lists
countries, the two-letter codes of the countries that use the card's currency, and astatussuch asActive. - To check one SKU before you submit it, call
GetPrepaidCardDetailsorGetGiftCardDetailswith it. These details calls don't returncountries. - A prepaid card is the prepaid card for the batch currency.
SKUis still required, and Xtrm checks it and the amount against the prepaid cards for that currency, but the current release orders the first prepaid card for the batch currency, atAmount. - The card provider always emails the credentials to
Email, and no API returns or resends them, so check the address before you submit. The batch-levelEmailNotificationfield doesn't control this. It's a boolean:truesends each recipient a separate payment-received email at their own address when their wallet is credited, for every payment method.
#Physical check: XTR94507
Xtrm mails the check to the address you give. Checks go to US addresses only, and only from a USD source wallet: from a wallet in another currency, Xtrm rejects the item when you submit the batch, with CURRENCY_MISMATCH and the message Bank check allows only USD wallet. Take the name and mailing address from your own records.
| Field | Required | Description |
|---|---|---|
BeneficiaryCheckName | Yes | The recipient's full name to print on the check. Xtrm doesn't compare it with the name on the recipient's account. |
BeneficiaryCheckAddress1 | Yes | The primary street address |
BeneficiaryCheckAddress2 | No | The secondary address line, such as a suite or apartment |
BeneficiaryCheckCity | Yes | The city |
BeneficiaryCheckState | Yes | The US state the check is mailed to, for example CA, up to 50 characters (the error message for a longer value says 30) |
BeneficiaryCheckPostalCode | Yes | The ZIP code, up to 30 characters |
BeneficiaryCheckCountryCodeISO2 | Yes | The two-letter country code of the mailing address, at most 2 characters: US. A longer value, such as USA, is rejected when you submit the batch. Any other code of up to 2 characters passes submission but fails during processing with COUNTRY_UNSUPPORTED, before any money moves. |
BeneficiaryCheckMemo | Yes | The check memo, up to 150 characters |
BeneficiaryCheckReference | Yes | Your reference for the check, such as an invoice number, up to 75 characters |
Xtrm HTML-encodes these values before it checks their length, so an & counts as 5 characters.
#Example: a wallet, a bank and a card in one batch
This batch pays from source wallet 122181 (USD) to three recipients, one per method family:
TXN-METHODS-0001pays business recipientSPN8888776into its wallet122311(XTR94504).TXN-METHODS-0002pays business recipientSPN8888777to a linked bank account by ACH (XTR94500). It sendsBeneficiaryBankIDwithoutWalletId, so Xtrm pays that bank.TXN-METHODS-0003pays individual recipientPAT9999888with a USD prepaid virtual debit card by email (XTR94503), naming the SKUPREP9001.
The batch sets EmailNotification to true, so Xtrm also emails each recipient a payment-received message when their wallet is credited. The prepaid card's credentials go to Destination.Email either way.
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-METHODS-0001",
"EmailNotification": true,
"Items": [
{
"CustomerTransactionId": "TXN-METHODS-0001",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311
},
"Description": "TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus"
},
{
"CustomerTransactionId": "TXN-METHODS-0002",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
},
"Description": "TXN-METHODS-0002 Q3 Executive Sales Performance Incentive"
},
{
"CustomerTransactionId": "TXN-METHODS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
},
"Description": "TXN-METHODS-0003 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-METHODS-0001',
EmailNotification: true,
Items: [
{
CustomerTransactionId: 'TXN-METHODS-0001',
RecipientId: 'SPN8888776',
Amount: 50,
SendMethodId: 'XTR94504',
Destination: {
WalletId: 122311,
},
Description: 'TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus',
},
{
CustomerTransactionId: 'TXN-METHODS-0002',
RecipientId: 'SPN8888777',
Amount: 100,
SendMethodId: 'XTR94500',
Destination: {
BeneficiaryBankID: '41953ec32f3e4765a35a902c82bdd995',
BeneficiaryBankPaymentMethod: 'ACH',
},
Description: 'TXN-METHODS-0002 Q3 Executive Sales Performance Incentive',
},
{
CustomerTransactionId: 'TXN-METHODS-0003',
RecipientId: 'PAT9999888',
Amount: 50,
SendMethodId: 'XTR94503',
Destination: {
Email: '[email protected]',
SKU: 'PREP9001',
},
Description: 'TXN-METHODS-0003 Q3 Top Performer Contractor Reward',
},
],
}),
});
const data = await response.json();
console.log(JSON.stringify(data, null, 2));import os
import requests
response = requests.post(
"https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer",
headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"},
json={
"IssuerAccountNumber": "SPN1111222",
"SourceWalletId": 122181,
"CustomerBatchId": "BATCH-METHODS-0001",
"EmailNotification": True,
"Items": [
{
"CustomerTransactionId": "TXN-METHODS-0001",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311,
},
"Description": "TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus",
},
{
"CustomerTransactionId": "TXN-METHODS-0002",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH",
},
"Description": "TXN-METHODS-0002 Q3 Executive Sales Performance Incentive",
},
{
"CustomerTransactionId": "TXN-METHODS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001",
},
"Description": "TXN-METHODS-0003 Q3 Top Performer Contractor Reward",
},
],
},
)
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-METHODS-0001",
"EmailNotification": true,
"Items": [
{
"CustomerTransactionId": "TXN-METHODS-0001",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311
},
"Description": "TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus"
},
{
"CustomerTransactionId": "TXN-METHODS-0002",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
},
"Description": "TXN-METHODS-0002 Q3 Executive Sales Performance Incentive"
},
{
"CustomerTransactionId": "TXN-METHODS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
},
"Description": "TXN-METHODS-0003 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"));
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-METHODS-0001",
"EmailNotification": true,
"Items": [
{
"CustomerTransactionId": "TXN-METHODS-0001",
"RecipientId": "SPN8888776",
"Amount": 50,
"SendMethodId": "XTR94504",
"Destination": {
"WalletId": 122311
},
"Description": "TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus"
},
{
"CustomerTransactionId": "TXN-METHODS-0002",
"RecipientId": "SPN8888777",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
"BeneficiaryBankPaymentMethod": "ACH"
},
"Description": "TXN-METHODS-0002 Q3 Executive Sales Performance Incentive"
},
{
"CustomerTransactionId": "TXN-METHODS-0003",
"RecipientId": "PAT9999888",
"Amount": 50,
"SendMethodId": "XTR94503",
"Destination": {
"Email": "[email protected]",
"SKU": "PREP9001"
},
"Description": "TXN-METHODS-0003 Q3 Top Performer Contractor Reward"
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer"))
.header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());<?php
$ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'IssuerAccountNumber' => 'SPN1111222',
'SourceWalletId' => 122181,
'CustomerBatchId' => 'BATCH-METHODS-0001',
'EmailNotification' => true,
'Items' => [
[
'CustomerTransactionId' => 'TXN-METHODS-0001',
'RecipientId' => 'SPN8888776',
'Amount' => 50,
'SendMethodId' => 'XTR94504',
'Destination' => [
'WalletId' => 122311,
],
'Description' => 'TXN-METHODS-0001 Q3 Channel Partner Marketing Bonus',
],
[
'CustomerTransactionId' => 'TXN-METHODS-0002',
'RecipientId' => 'SPN8888777',
'Amount' => 100,
'SendMethodId' => 'XTR94500',
'Destination' => [
'BeneficiaryBankID' => '41953ec32f3e4765a35a902c82bdd995',
'BeneficiaryBankPaymentMethod' => 'ACH',
],
'Description' => 'TXN-METHODS-0002 Q3 Executive Sales Performance Incentive',
],
[
'CustomerTransactionId' => 'TXN-METHODS-0003',
'RecipientId' => 'PAT9999888',
'Amount' => 50,
'SendMethodId' => 'XTR94503',
'Destination' => [
'Email' => '[email protected]',
'SKU' => 'PREP9001',
],
'Description' => 'TXN-METHODS-0003 Q3 Top Performer Contractor Reward',
],
],
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'),
'Content-Type: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));Xtrm accepts the batch with 202 and pays each item in the background. For the response, how to follow each payment to its final status and how to retry a failed one, see Create a batch payment.
Payments in the sandbox
The sandbox works the same as production. For cards, use the standard test numbers: Visa 4111111111111111 or Mastercard 5555555555554444, with a future expiry date and a three-digit CVV. The sandbox has no test bank accounts: link a real bank's routing number or SWIFT-BIC with a made-up account number in the right format, never a real one; see Test bank accounts. There are no sandbox-only SKUs either: use the SKUs the catalog calls return. See How payments finish in the sandbox for the failures you can trigger on purpose.
#Currency and country rules
- One currency per batch. The source wallet (
SourceWalletId) sets the currency of the whole batch, and every accepted item is credited to the recipient's wallet in it. To pay in another currency, submit a separate batch from a wallet in that currency. - Banks. A linked bank account can be in a different currency from the batch. When it is, the amount is converted when it's transferred to the bank.
- Wallets. Without
WalletId, Xtrm credits the recipient's oldest activeStandardwallet in the batch currency, and creates one only if the recipient has no active wallet in that currency (see Wallets). - Push to card. USD batches only. In another currency, the item fails during processing with
CURRENCY_MISMATCH. - Prepaid and gift cards. Xtrm checks the card against the batch currency while it processes the item, not when you submit the batch. A gift card (
XTR94505) in another currency fails withCURRENCY_MISMATCH. A prepaid card (XTR94503) fails withCURRENCY_INVALIDwhen Xtrm offers no prepaid card in the batch currency, or withSKU_NOT_FOUNDwhen the SKU isn't one of them. In the catalogs, each product'scountrieslists the countries that use its currency. - Checks. Xtrm mails checks to US addresses only, from USD source wallets only.
#When Xtrm checks a destination
Xtrm checks a destination in two stages:
- When you submit the batch, Xtrm runs a lightweight check of each item's fields and formats. An item that is missing a required
Destinationfield is rejected, and its entry inRejectednames the field, for exampleItems[0].Destination.SKU. Items that pass are still accepted. See Errors when you submit a batch payment. - While it processes the item, Xtrm first checks the recipient, the wallet, the destination and the method, before any money moves; a problem ends the item
Failed. Xtrm then debits your source wallet and credits the recipient's wallet, which can also end the itemFailed, for example withINSUFFICIENT_BALANCE. For a bank, card or check item, Xtrm then delivers the payment, and the item showsRetainedInWalletwhile it does; if the delivery fails, the item is stillRetainedInWalletwhen the batch status becomes final. Each outcome that a stage records is an attempt with anErrorCode, which you see in the item'sAttemptswhen you request it withhistory=true.
These are the processing error codes for each method:
| Method | Item ends Failed | Item stays RetainedInWallet |
|---|---|---|
| Any | RECIPIENT_NOT_FOUND, SENDMETHODID_NOT_FOUND, INVALID_BENEFICIARY_WALLET, INTERNAL_SERVICE_ERROR, SEND_LIMIT_EXCEEDED, INSUFFICIENT_BALANCE, WALLET_AUTO_CREATE_FAILED, SEND_FAILED, TEMPORARY_ERROR | INSUFFICIENT_FUNDS_RUNTIME, PREVIOUS_TRANSFER_IN_PROGRESS (every method except wallets) |
Bank transfer (XTR94500) | BENEFICIARY_BANKID_REQUIRED, DEFAULT_BANK_NOT_FOUND, BANKID_INVALID, BANK_NOT_FOUND, INVALID_PAYMENTMETHOD | RETAINED_IN_WALLET, TEMPORARY_ERROR, Invalid payment method |
Wallets (XTR94502, XTR94504) | No other codes | None: a wallet item is Success once the wallet is credited |
Push to card (XTR94508) | CURRENCY_MISMATCH, TOKEN_NOT_FOUND | TEMPORARY_ERROR |
Digital gift card (XTR94505) | SKU_NOT_FOUND, CURRENCY_MISMATCH, INVALID_CARD_AMOUNT | SKU_NOT_FOUND, INVALID_CARD_AMOUNT, TEMPORARY_ERROR |
Prepaid virtual debit card (XTR94503) | CURRENCY_INVALID, SKU_NOT_FOUND, INVALID_CARD_AMOUNT | SKU_NOT_FOUND, TEMPORARY_ERROR |
Physical check (XTR94507) | COUNTRY_UNSUPPORTED | TEMPORARY_ERROR |
For what each code means and what to do, see Error codes on attempts. To fix a Failed item, for example with a corrected BeneficiaryBankID, CardToken or SKU, see Resubmit failed payments. An item that stays RetainedInWallet once its batch is final can't be retried; for how the money then reaches the recipient's bank or card, see When a payment stays RetainedInWallet.
#Choose a payment method list
Three endpoints list payment methods. Take each batch item's SendMethodId from GetPaymentMethods: a batch accepts exactly its seven IDs, in capitals, and rejects any other value when you submit it. The other two aren't batch send methods: they list the ways an individual recipient or a business recipient can move its own money out of its Xtrm wallet.
| Endpoint | Returns | ID and name fields | Use it to |
|---|---|---|---|
GetPaymentMethods | All seven payment methods on this page | PaymentMethodId, PaymentMethodName | Choose the SendMethodId for each item. It is the only list with XTR94504 (AnyPay Company) and XTR94507 (Bank Check). |
GetUserPaymentMethods | The ways an individual recipient can move their own money: XTR94500, XTR94502, XTR94503, XTR94505 and XTR94508, plus XTR94506 (Reward Link), which a batch rejects. It leaves out XTR94504 and XTR94507. | UserPaymentMethodId, UserPaymentMethodName | See the ways an individual recipient can move their own money. Don't build a batch method picker from it. UserWithdrawFund accepts four of them in PaymentMethodID, sent in capitals: XTR94500, XTR94503, XTR94505 and XTR94508. XTR94502 is only for paying the recipient's Xtrm wallet in a batch. XTR94506 is a reward card that recipients choose in the Xtrm web app. Neither UserWithdrawFund nor BatchTransfer accepts it: a batch item with it is rejected with INVALID_FIELD when you submit the batch. |
GetBeneficiaryCompanyPaymentMethods | XTR94500 (Bank) and XTR94508 (Rapid Transfer) | BeneficiaryCompanyPaymentMethodId, BeneficiaryCompanyPaymentMethodName | See how a business recipient can transfer money out of its wallet, with BeneficiaryCompanyWithdrawFund. |
All three take an empty JSON object {} as the body, with no account identifier, and return the same list for every account. Send them as POST requests: a GET returns HTTP 404. Each response nests its list under its own wrapper names, so read the path from that endpoint's example.
#Next steps
The batch lifecycle and wallet-first delivery.
Create a batch paymentBuild a batch, submit it and track every payment to completion.
Batch and payment statusesWhat Success, RetainedInWallet and Failed mean for each payment.
Find a card SKU in the batch currency and pay a recipient with it.
Bank accounts & transfersLink a recipient's bank account and pay into it.
Retries & idempotencyResubmit a failed payment without paying anyone twice.