Exchange currency
To make a batch payment in another currency, exchange funds into a company wallet in that currency, then pay the batch from that wallet. Currency exchange (FX: converting money from one currency into another) is part of managing your wallets: you check the rate with GetExchangeRate and book the exchange with BookExchange. Payments and currency exchange are executed by regulated financial partners.
Every item in a batch is paid in one currency: the currency of the batch's source wallet (SourceWalletId). A bank item can still go to a bank account in another currency: the amount is converted when it's transferred to the bank. To pay wallets, gift cards or prepaid cards in another currency, though, you exchange the funds into a wallet in that currency first, then pay the batch from that wallet. Checks and Rapid Transfer items pay only from a USD batch. See Currency for the full rules.
In this guide you prepare a batch that pays Jane Doe (PAT9999888) AUD 500.00, from US dollars your company holds in its wallet 122181. You list your wallets, create an AUD wallet, check the real-time exchange rate, exchange enough US dollars to cover the batch, confirm the AUD balance, and submit the batch with that wallet as its source.
#Before you begin
- Sandbox credentials. In your sandbox company account, go to Settings > Integrations > Get Credentials for your client ID and secret. See Sandbox & environments.
- An access token in the
XTRM_ACCESS_TOKENenvironment variable. See Authentication. - Your company's account number (
SPN), which you send asIssuerAccountNumber. The samples useSPN1111222. - A funded wallet in the currency you convert from. In the sandbox, Xtrm credits test funds to your wallets after approving your IP addresses; see Test funds. To add more, see Fund your wallet.
- The batch payment you're preparing: its currency and the total of its items'
Amountvalues. Currencies are three-letter ISO 4217 codes, such asUSDandAUD. Create a batch payment shows how to build the items.
Each sample below runs on its own, so values from one step's response (such as wallet IDs) are typed in literally in the next. Replace them with the values your own responses return.
#Exchange funds into the batch's source wallet
- Find your wallets
Call
GetCompanyWalletsto list your company's wallets. You're looking for two of them:- The wallet you convert from, here in
USD, with aWalletBalancethat covers the amount you plan to exchange. - The wallet in the batch's currency, here
AUD. It's the wallet you name asSourceWalletId, and the batch is paid from that wallet alone.
Companies can hold more than one wallet per currency, so choose each wallet by its
WalletID, not by its currency alone.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyWallets: { request: { IssuerAccountNumber: 'SPN1111222', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetCompanyWallets": { "request": { "IssuerAccountNumber": "SPN1111222" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyWallets' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response (excerpt){ "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 } } } }Keep for the next steps: the
USDwallet'sWalletID(122181) and itsWalletBalance(57715.15), so you can compare the balance after the exchange. If you already have a wallet in the batch's currency, keep itsWalletIDandWalletBalancetoo. Responses returnWalletIDas a number. The exchange request sends wallet IDs as strings ("122181"), butSourceWalletIdin the batch is an integer (122182). Every wallet field takes the numeric ID, never the wallet's name.This company has no
AUDwallet yet, so the next step creates one. If you already have a wallet in the batch's currency, skip to step 3. - The wallet you convert from, here in
- Create a wallet in the batch's currency (if needed)
Create the wallet your batch will pay from with
CreateCompanyWallet, withWalletCurrencyset to the batch's currency andWalletTypeset toStandard. A wallet's currency can't change after you create it. Fund your wallet explains every field of this call.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "Australian Dollars Wallet", "WalletCurrency": "AUD", "WalletType": "Standard" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ CreateCompanyWallet: { request: { IssuerAccountNumber: 'SPN1111222', WalletName: 'Australian Dollars Wallet', WalletCurrency: 'AUD', WalletType: 'Standard', }, }, }), }); 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/CreateCompanyWallet", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "Australian Dollars Wallet", "WalletCurrency": "AUD", "WalletType": "Standard", }, }, }, ) 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 = """ { "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "Australian Dollars Wallet", "WalletCurrency": "AUD", "WalletType": "Standard" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet", 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 = """ { "CreateCompanyWallet": { "request": { "IssuerAccountNumber": "SPN1111222", "WalletName": "Australian Dollars Wallet", "WalletCurrency": "AUD", "WalletType": "Standard" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet")) .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/CreateCompanyWallet'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'CreateCompanyWallet' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'WalletName' => 'Australian Dollars Wallet', 'WalletCurrency' => 'AUD', 'WalletType' => 'Standard', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response (excerpt){ "CreateCompanyWalletResponse": { "CreateCompanyWalletResult": { "WalletID": 122182, "OperationStatus": { "Success": true, "Errors": null } } } }Keep for the next steps: the new
AUDwallet'sWalletID(122182). You book the exchange into it in step 4, and it's theSourceWalletIdof your batch in step 6. A new wallet starts with a balance of0, so after the exchange itsWalletBalanceis exactly what the exchange credited. - Check the exchange rate
Call
GetExchangeRatewith the currency you convert from (FromCurrency) and the batch's currency (ToCurrency). It returns the current real-time rate, quoted for 1 unit ofFromCurrency(anAmountof1).BookExchangetakes itsAmountinFromCurrency, while your batch total is inToCurrency, so you use the rate to size the exchange, as shown below the response.The exchange endpoints wrap their fields in
Request, andBatchTransferhas no wrapper. We recommend copying each body as shown (see Requests & responses).curl -X POST "https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetExchangeRate": { "Request": { "IssuerAccountNumber": "SPN1111222", "FromCurrency": "USD", "ToCurrency": "AUD" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetExchangeRate: { Request: { IssuerAccountNumber: 'SPN1111222', FromCurrency: 'USD', ToCurrency: 'AUD', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetExchangeRate": { "Request": { "IssuerAccountNumber": "SPN1111222", "FromCurrency": "USD", "ToCurrency": "AUD", }, }, }, ) 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 = """ { "GetExchangeRate": { "Request": { "IssuerAccountNumber": "SPN1111222", "FromCurrency": "USD", "ToCurrency": "AUD" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate", 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 = """ { "GetExchangeRate": { "Request": { "IssuerAccountNumber": "SPN1111222", "FromCurrency": "USD", "ToCurrency": "AUD" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetExchangeRate' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'FromCurrency' => 'USD', 'ToCurrency' => 'AUD', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetExchangeRateMethodsResponse": { "ExchangeRateMethodResult": { "ExchangeRateMethods": { "ExchangeRateMethodsDetail": [ { "IssuerAccountNumber": "SPN1111222", "FromCurrency": "USD", "ToCurrency": "AUD", "Amount": 1, "ExchangeRate": 1.4005406 } ] }, "OperationStatus": { "Success": true, "Errors": null } } } }Keep for your records:
ExchangeRate, the real-time rate between the two currencies. It's the number of units ofToCurrencythat 1 unit ofFromCurrencybuys, so multiply an amount inFromCurrencyby the rate to get its value inToCurrency. Here, USD 1.00 buys AUD 1.4005406, so USD 100.00 converts to AUD 140.05. To estimate how much to exchange, divide the amount you need inToCurrencyby the rate: at this rate, the batch's AUD 500.00 takes about USD 357.01. This guide exchanges USD 365.00, about AUD 511.20 at this rate, which leaves headroom for the item's fee and for the rate moving before you book. Check the amount credited in step 5 before you submit the batch.ExchangeRateMethodsDetailis an array with one entry, for the currency pair you asked for.The rate isn't part of the booking
BookExchangehas no field for a rate or a quote reference, so nothing from this response goes into the next request. Xtrm books the exchange at the real-time rate at the moment of booking, which can differ slightly from the rate this call returned. - Book the exchange into the source wallet
Call
BookExchange. Xtrm debitsAmount, inFromCurrency, from the wallet inFromWalletID, exchanges it at the real-time rate, and credits the result inToCurrencyto the wallet inToWalletID.IssuerAccountNumberis your company'sSPN.AccountNumberis the account that executes the exchange. Both wallets need to belong to it. You're exchanging between your own company's wallets, so it's the sameSPN. Any other account must be connected to your company.FromWalletIDis the wallet you convert from (122181, step 1).ToWalletIDis your batch's source wallet (122182, step 2). It's optional: if you leave it out, Xtrm credits one of the account's wallets inToCurrency, or creates one if there's none, and that isn't necessarily the wallet your batch pays from. We recommend always sending it, as the numeric ID: a value that isn't a number, such as the wallet's name, counts as left out.Amountis a decimal string inFromCurrency: here,"365.00"US dollars, sized in step 3 to cover the AUD 500.00 batch. The wallet inFromWalletIDmust hold at least this amount, or Xtrm refuses the exchange (see When you exchange).
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "BookExchange": { "Request": { "IssuerAccountNumber": "SPN1111222", "AccountNumber": "SPN1111222", "FromWalletID": "122181", "FromCurrency": "USD", "ToCurrency": "AUD", "Amount": "365.00", "ToWalletID": "122182" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ BookExchange: { Request: { IssuerAccountNumber: 'SPN1111222', AccountNumber: 'SPN1111222', FromWalletID: '122181', FromCurrency: 'USD', ToCurrency: 'AUD', Amount: '365.00', ToWalletID: '122182', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "BookExchange": { "Request": { "IssuerAccountNumber": "SPN1111222", "AccountNumber": "SPN1111222", "FromWalletID": "122181", "FromCurrency": "USD", "ToCurrency": "AUD", "Amount": "365.00", "ToWalletID": "122182", }, }, }, ) 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 = """ { "BookExchange": { "Request": { "IssuerAccountNumber": "SPN1111222", "AccountNumber": "SPN1111222", "FromWalletID": "122181", "FromCurrency": "USD", "ToCurrency": "AUD", "Amount": "365.00", "ToWalletID": "122182" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange", 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 = """ { "BookExchange": { "Request": { "IssuerAccountNumber": "SPN1111222", "AccountNumber": "SPN1111222", "FromWalletID": "122181", "FromCurrency": "USD", "ToCurrency": "AUD", "Amount": "365.00", "ToWalletID": "122182" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'BookExchange' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'AccountNumber' => 'SPN1111222', 'FromWalletID' => '122181', 'FromCurrency' => 'USD', 'ToCurrency' => 'AUD', 'Amount' => '365.00', 'ToWalletID' => '122182', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "BookExchangeMethodsResponse": { "BookExchangeMethodResult": { "BookExchangeMethods": { "BookExchangeMethodsDetail": { "DebitTransactionID": 888111, "CreditTransactionID": 888222, "PaymentDate": "2026-06-04T00:00:00-04:00", "PaymentStatus": "Completed" } }, "OperationStatus": { "Success": true, "Errors": null } } } }Keep for your records:
DebitTransactionID(the debit from the wallet you converted from) andCreditTransactionID(the credit to your batch's source wallet), withPaymentDateandPaymentStatus. We recommend storing both transaction IDs next to your own record of the batch they pay for.PaymentStatusis alwaysCompletedon success: Xtrm posts the debit and the credit before it responds, so the converted funds can pay a batch right away.The response doesn't include the rate that was applied or the amount credited. The next step shows what arrived.
- Confirm the source wallet's balance
Call
GetCompanyWalletsagain, with the same request as in step 1, and compare each wallet'sWalletBalancewith the values you kept. The wallet you converted from is debited, and your batch's source wallet is credited.Response (excerpt){ "GetCompanyWalletResponse": { "CompanyWalletResult": { "CompanyWallets": { "CompanyWalletDetails": [ { "WalletID": 122181, "WalletName": "USD Wallet for Main Company", "WalletCurrency": "USD", "WalletBalance": 57350.15, "WalletType": "Standard", "IsBankLinked": false, "AllowWalletLinkedBankOverride": false, "EntityID": 12345 }, { "WalletID": 122182, "WalletName": "Australian Dollars Wallet", "WalletCurrency": "AUD", "WalletBalance": 511.13, "WalletType": "Standard", "IsBankLinked": false, "AllowWalletLinkedBankOverride": false, "EntityID": 12345 } ] }, "OperationStatus": { "Success": true, "Errors": null } } } }The
USDwallet is down by the USD 365.00 you exchanged, and the newAUDwallet holds AUD 511.13. That's slightly less than the AUD 511.20 estimated in step 3, because the booking used the rate at that moment, so always take the amount received from the balance, not from the rate.Before you submit the batch, check that the source wallet's balance covers the total of your items'
Amountvalues plus their fees. Here, AUD 511.13 covers the AUD 500.00 item and leaves AUD 11.13 for its fee. A202 Acceptedresponse to a batch says nothing about the balance: Xtrm debits each item when it processes it, for the item'sAmountplus its fee, and an item the source wallet can't cover fails withINSUFFICIENT_BALANCE.The wallets also record the exchange as two
Currency Exchangetransactions, the debit and the credit. To list them, callGetCompanyWalletTransactionsfor the wallet, withFilters.TransactionTypeset toCurrency Exchange. See Track & reconcile payments.Keep for the next step: the source wallet's
WalletID(122182), which you send asSourceWalletId. - Submit the batch payment from that wallet
Submit your batch with
BatchTransferand name the wallet you just exchanged into asSourceWalletId. The batch takes its currency from that wallet, so every item'sAmountis in Australian dollars.This example pays Jane Doe (
PAT9999888) AUD 500.00 into her Xtrm wallet (XTR94502).Amountis a number. ItsDestinationis empty, so Xtrm credits her oldest activeStandardwallet inAUD, or creates one namedWallet - AUDbecause she has no wallet in that currency yet. A wallet item with an emptyDestinationneeds no connection to the recipient. For how Xtrm processes a batch, see How batch payments work. For every send method and option, see Create a batch payment.The batch uses this guide's own IDs,
BATCH-FX-0001andTXN-FX-0001.CustomerBatchIdvalues are shared across all Xtrm accounts, so replace them with your own unique values before you run this in the sandbox, and give every new batch new IDs. See Batch and payment identifiers.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": 122182, "CustomerBatchId": "BATCH-FX-0001", "Items": [ { "CustomerTransactionId": "TXN-FX-0001", "RecipientId": "PAT9999888", "Amount": 500, "SendMethodId": "XTR94502", "Destination": {} } ] }'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: 122182, CustomerBatchId: 'BATCH-FX-0001', Items: [ { CustomerTransactionId: 'TXN-FX-0001', RecipientId: 'PAT9999888', Amount: 500, SendMethodId: 'XTR94502', Destination: {}, }, ], }), }); 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": 122182, "CustomerBatchId": "BATCH-FX-0001", "Items": [ { "CustomerTransactionId": "TXN-FX-0001", "RecipientId": "PAT9999888", "Amount": 500, "SendMethodId": "XTR94502", "Destination": {}, }, ], }, ) 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": 122182, "CustomerBatchId": "BATCH-FX-0001", "Items": [ { "CustomerTransactionId": "TXN-FX-0001", "RecipientId": "PAT9999888", "Amount": 500, "SendMethodId": "XTR94502", "Destination": {} } ] } """; 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": 122182, "CustomerBatchId": "BATCH-FX-0001", "Items": [ { "CustomerTransactionId": "TXN-FX-0001", "RecipientId": "PAT9999888", "Amount": 500, "SendMethodId": "XTR94502", "Destination": {} } ] } """; 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' => 122182, 'CustomerBatchId' => 'BATCH-FX-0001', 'Items' => [ [ 'CustomerTransactionId' => 'TXN-FX-0001', 'RecipientId' => 'PAT9999888', 'Amount' => 500, 'SendMethodId' => 'XTR94502', 'Destination' => new stdClass(), ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Xtrm responds with
202 Acceptedand pays the item in the background. Create a batch payment explains the whole response. In this one, check that:ItemsCount.Acceptedis1and theRejectedarray is empty.- The entry in
AcceptedshowsAmount500andCurrencyAUD, the currency of your source wallet.
The item ends
Successonce Jane Doe'sAUDwallet is credited. Follow it with the payment status endpoint, usingBATCH-FX-0001andTXN-FX-0001; it reportsCurrencyAUD. See Batch and payment statuses. If the submit call times out, resend it unchanged, with the same IDs (see A safe retry pattern).
#What can go wrong
A wallet or exchange call in this guide that fails returns HTTP 400 with OperationStatus.Success set to false and the reasons in OperationStatus.Errors. Decide with Success: on success, Errors is null or [], depending on the endpoint. GetExchangeRate and BookExchange also return 503, with Currency exchange service temporarily unavailable. Please try again later., when Xtrm can't get a rate or complete the exchange. Before you resend a BookExchange, check the wallet you convert from (see below). For the other statuses, see HTTP status codes. For a batch item that's rejected or fails, see Errors and Error codes on attempts.
Check before you resend an exchange
BookExchange takes no idempotency key, so resending it can book the exchange twice. If a BookExchange call times out, you don't get a response, or it returns an error, check the balance of the wallet you convert from and its Currency Exchange transactions before you send the request again. See Errors.
#When you exchange
- The rate moved. The exchange happens at the real-time rate when you call
BookExchange, which can differ slightly from whatGetExchangeRatereturned a moment earlier. If the source wallet ends up short of your batch total, exchange the difference before you submit. - The funds went to a different wallet. Without
ToWalletID, or with a value that isn't a number such as a wallet name, Xtrm credits one of the account's wallets inToCurrency, which isn't necessarily the wallet you name inSourceWalletId. SendToWalletIDset to your batch's source wallet. - A wallet belongs to another account.
FromWalletIDandToWalletIDboth need to belong to the account inAccountNumber, inFromCurrencyandToCurrency. Otherwise Xtrm refuses the exchange with<FromWalletID> - Invalid from wallet idor<ToWalletID> - Invalid to wallet id. An exchange never moves money from one account to another. - The wallet you convert from is short. If the wallet in
FromWalletIDholds less thanAmount, Xtrm rejects the exchange with HTTP400before it books anything, so no money is exchanged and nothing leaves the wallet.OperationStatus.Successisfalse, andErrorscontains<FromWalletID> - Insufficient balance in the wallet. AnAmountequal to the wallet balance is accepted. Fund the wallet or exchange a smaller amount, then book again. - Wallet creation fails.
CreateCompanyWalletrefuses aWalletCurrencythat Xtrm doesn't hold wallets in withInvalid Wallet Currency(HTTP500), and aWalletTypeit doesn't recognize with<WalletType> - Invalid wallet type. Send a three-letter ISO 4217 code andStandard. - Your code waits for an
OTP.BookExchangeno longer takes a one-time password: release 4.91.2 removed it, so the exchange books in a single request, and Xtrm ignores anOTPfield if you still send one.
#When the batch payment is processed
- Items fail with
INSUFFICIENT_BALANCE. The source wallet held less than the item'sAmountplus its fee when Xtrm processed it, so nothing was debited for that item. Exchange more into the same wallet, then resubmit only the failed items under their original IDs, with every field as before. See Resubmit failed payments. - Card items in another currency. Gift card and prepaid card SKUs vary by currency, so look them up in the batch's currency with
GetDigitalGiftCardsorGetPrepaidCards. A gift card item (XTR94505) whoseSKUis in a different currency from the batch fails during processing withCURRENCY_MISMATCH. A prepaid card item (XTR94503) fails withSKU_NOT_FOUNDwhen itsSKUisn't one of the prepaid products for the batch's currency, or withCURRENCY_INVALIDwhen there's no prepaid product in that currency. - You pay in more than one currency. A batch has a single currency, shared by all its items. We recommend one batch per currency, each from a wallet in that currency. Exchange funds into each wallet with the steps in this guide.
#Next steps
Build a batch with any send method, then track every payment to completion.
How batch payments workThe batch lifecycle, wallet-first delivery, currency rules and limits.
Currency exchange referenceEvery field of GetExchangeRate and BookExchange.
Match wallet transactions and payments to your own records.