Track & reconcile payments
This guide keeps your books in step with every batch payment. You follow each payment by the CustomerBatchId and CustomerTransactionId you gave it, confirm where it stands from its status, and tie it to the money that left your wallet and reached the recipient, fee included. One habit makes that last part easy: start each payment's Description with its CustomerTransactionId, and your ID travels with the money, onto the debit from your wallet and the credit to the recipient's. A suggested reconciliation loop then puts it all on a schedule.
How you reconcile is up to you: the matching rules and the loop in this guide are our recommendations, built on what each call returns.
#Before you begin
- Sandbox credentials and an access token in the
XTRM_ACCESS_TOKENenvironment variable. See Sandbox & environments and Authentication. - Your company's account number (
SPN), sent asIssuerAccountNumber. The samples useSPN1111222, the account of your company, Fabrikam Inc. - A batch payment you've submitted and its
CustomerBatchId, ideally with each payment'sCustomerTransactionIdat the start of itsDescription(see Your join keys). To submit a batch, see Create a batch payment. - Your own payment records, one row per payment, keyed by
CustomerBatchIdandCustomerTransactionId(see the next section). - A connection to the recipients you look into in steps 5 and 8. Recipients you create with
CreateUserorCreateBeneficiaryare connected to your company. See Connections and manager services.
The samples follow one batch from start to finish: BATCH-2026-Q3-01, paid on 5 June 2026 from your USD source wallet 122181. It holds six payments. The one the steps follow most closely is TXN-2026-9912A, a USD 100.00 bank payment to Jane Doe (PAT9999888). Its first attempt failed with INSUFFICIENT_BALANCE because the wallet was short, and it went through when you funded the wallet and resubmitted it under the same IDs. Three more payments from the batch appear along the way: TXN-2026-9902A, USD 50.00 to the wallet of business recipient SPN8888776; TXN-2026-9903A, a USD 50.00 prepaid card for Jane Doe; and TXN-2026-9905A, USD 50.00 pushed to the card of Acme Corporation (SPN9999888). Every payment's Description starts with its CustomerTransactionId, such as TXN-2026-9912A Q3 Contractor Bonus. Each sample runs on its own, so values from one step's response are typed in literally in the next. Replace them with your own.
#How the pieces fit
| Piece | Its job in reconciliation |
|---|---|
CustomerBatchId and CustomerTransactionId | The keys that match your records to Xtrm's. |
Each payment's Description | Carries your CustomerTransactionId onto the wallet transactions, so you can find each payment's money (steps 3 to 6). |
| Batch and payment status | Each payment's state, with the history of every attempt (steps 1 and 2). |
| Webhooks | A signal that something changed and it's time to check the status. |
| Wallet transactions, fees and totals | The money movements you book (steps 3 to 8). |
In the API, each payment in a batch is an item (Items[]), so the status calls and error codes below say "item".
#Your join keys
You set both IDs yourself: every batch needs a CustomerBatchId and every payment a CustomerTransactionId, and Xtrm never generates them. Xtrm echoes the IDs in batch payment responses and webhooks, and both status calls are addressed by them. We recommend creating the record for each payment, with both IDs, before you submit the batch, so a lost response never leaves you without the key. The format rules, and what happens when an ID is reused, are in Batch and payment identifiers and Duplicate IDs.
Wallet transactions have IDs of their own (TransactionID) and don't return yours, but they do carry each payment's Description. So we recommend starting every Description with the payment's CustomerTransactionId, followed by a space and the text you want the recipient to see. Your ID then links each payment's status to the money it moved. So that each ID points to one payment, keep every CustomerTransactionId unique across all your batches, not only within one, as the samples do. This payment from the example batch does it:
{
"CustomerTransactionId": "TXN-2026-9912A",
"RecipientId": "PAT9999888",
"Amount": 100,
"SendMethodId": "XTR94500",
"Destination": {
"BeneficiaryBankID": "907599f594b044d08cf81a2afb0a7967",
"BeneficiaryBankPaymentMethod": "ACH"
},
"Description": "TXN-2026-9912A Q3 Contractor Bonus"
}Description is optional and holds up to 1,024 characters. The recipient sees it on the credit in their wallet, so use text you're happy to share. Every item field is described in BatchTransfer.
#Status is the source of truth
Book a payment by its status. A 202 Accepted response to BatchTransfer only tells you which payments passed Xtrm's checks: each payment is processed afterwards, in the background, and Accepted isn't proof that a payment was stored. A payment ends Success or Failed, or stays RetainedInWallet, and only a Failed payment can be resubmitted. RetainedInWallet is a pass-through status for bank, push-to-card, check, prepaid card and gift card payments, so 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 (details). Batch and payment statuses explains every status and what to do about each one.
#Webhooks are triggers
Webhooks tell you when to look, not what to book. We recommend treating each event as a prompt to fetch the payment's status (step 2), and booking the status from that response. Your scheduled status sweep (see Build a reconciliation loop) finds any change that no event reported. See Webhooks.
#Money movements
Each payment moves money out of your source wallet and into the recipient's. When Xtrm processes a payment (not when it accepts the batch), it debits your source wallet once for the payment's Amount plus its fee, and credits the recipient's wallet with the full Amount. Fees are charged per payment, never per batch. The status calls give each payment's Amount before fees, and the details of each wallet debit give its fee (step 4).
Both transactions carry the payment's Description, as Xtrm stored it. Your source wallet's debit shows it in GetCompanyWalletTransactions and in the debit's details, and the recipient's credit shows it in their wallet's transaction list. With the CustomerTransactionId at the start of each Description, you match a payment to its debit by that ID, and check that the debit's Amount is the payment's Amount plus its fee. A payment whose Description carries no ID can only be matched by amount plus fee, currency, date and recipient, which can't tell two equal payments to one recipient apart. Status timestamps are UTC, while wallet TransactionDate values are in Xtrm's server time with no time zone, so allow a day of tolerance when you compare dates.
#Returned bank payments
A bank payment can show Success and be returned by the recipient's bank days later. Xtrm then credits the money back to your wallet by hand. The batch doesn't change: the payment stays Success, and no webhook is sent. In GetCompanyWalletTransactions, the money appears as a separate record with Type Credit and, as its Description, the note Xtrm entered. Nothing in the record links it to the original payment, and the Received filter doesn't return it: use All or Funded. Xtrm emails you the reason and the original transaction ID. Watch your wallets for credits you don't expect, and match each one to its email before you book it.
#Reconcile step by step
- Get the batch status with attempt history
Call
GET /Fund/BatchTransfer/{CustomerBatchId}. It returns the batchStatus, itsCurrency,ItemsCount, and one page ofItems, each with itsStatus,RecipientId,SendMethodId,AmountandLastUpdatedAt.- Page through the payments with the query parameters
recordsToSkip(an item offset,0for the first page) andrecordsToTake. They're camelCase, unlike thePaginationobjects in the wallet calls below, whereRecordsToSkipis a page number. - Set
history=trueto include each payment'sAttempts: the history of its processing attempts, with each one'sAttemptNo,Result(SuccessorFailed),ErrorCodeand timestamps. Without it,Attemptsis[]. For what each field and code means, see Attempts and history and Error codes on attempts.
curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true', { method: 'GET', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, }, }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.get( "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var response = await client.GetAsync("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true"); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .GET() .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01?recordsToSkip=0&recordsToTake=50&history=true'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The excerpt shows three of the batch's six payments. All six are
Success, so the batch readsCompleted.Response (excerpt){ "CustomerBatchId": "BATCH-2026-Q3-01", "Status": "Completed", "Currency": "USD", "ItemsCount": 6, "Items": [ { "CustomerTransactionId": "TXN-2026-9902A", "Status": "Success", "RecipientId": "SPN8888776", "SendMethodId": "XTR94504", "Amount": "50.00", "LastUpdatedAt": "2026-06-05T20:49:44.0208205Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-06-05T20:49:44.0159177Z", "CompletedAt": "2026-06-05T20:49:44.0208205Z" } ] }, { "CustomerTransactionId": "TXN-2026-9905A", "Status": "Success", "RecipientId": "SPN9999888", "SendMethodId": "XTR94508", "Amount": "50.00", "LastUpdatedAt": "2026-06-05T20:49:48.6328481Z", "Attempts": [ { "AttemptNo": 1, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-06-05T20:49:48.6328481Z", "CompletedAt": "2026-06-05T20:49:48.6328481Z" } ] }, { "CustomerTransactionId": "TXN-2026-9912A", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94500", "Amount": "100.00", "LastUpdatedAt": "2026-06-05T21:15:09.4470000Z", "Attempts": [ { "AttemptNo": 2, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-06-05T21:15:09.4402213Z", "CompletedAt": "2026-06-05T21:15:09.447Z" }, { "AttemptNo": 1, "Result": "Failed", "ErrorCode": "INSUFFICIENT_BALANCE", "CreatedAt": "2026-06-05T20:49:44.6127730Z", "CompletedAt": "2026-06-05T21:15:09.447Z" } ] } ], "Pagination": { "HasMore": false, "NextRecordsToSkip": 0 } }Keep for your records: for each payment, matched on
CustomerTransactionId, itsStatus,Amount,LastUpdatedAt, and theErrorCodeof any failed attempt; for the batch, itsStatusandCurrency. On this endpointAmountis a string with a thousands separator, such as"1,234.56", so strip separators before you parse it. WhenPagination.HasMoreistrue, call again withPagination.NextRecordsToSkipasrecordsToSkip.We recommend booking a payment by its
Status, not by a single attempt'sResult:TXN-2026-9912AisSuccessalthough its first attempt failed. This endpoint listsAttemptsnewest first and the payment status endpoint (step 2) oldest first, so sort byAttemptNo. - Page through the payments with the query parameters
- Check one payment when something changes
When a webhook arrives, or when you need to look into one payment, call
GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}. It returns the same fields as step 1, plus the payment'sCurrencyandDeliveryType.Once the payment is
Success,DeliveryTypenames the rail that delivered it, such asBankorWallet. It'sWalletfor everyRetainedInWalletpayment. It's an empty string while the payment isAcceptedorProcessing, and when it isFailed. This endpoint returnsAmountwithout a thousands separator ("1234.56"), and it reads only committed data, so confirm a payment here before you act on it. Sethistory=trueto includeAttempts.curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?history=true" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-2026-Q3-01/Items/TXN-2026-9912A?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-2026-Q3-01/Items/TXN-2026-9912A?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-2026-Q3-01/Items/TXN-2026-9912A?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-2026-Q3-01/Items/TXN-2026-9912A?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-2026-Q3-01/Items/TXN-2026-9912A?history=true'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "CustomerBatchId": "BATCH-2026-Q3-01", "CustomerTransactionId": "TXN-2026-9912A", "Status": "Success", "RecipientId": "PAT9999888", "SendMethodId": "XTR94500", "Amount": "100.00", "Currency": "USD", "DeliveryType": "Bank", "LastUpdatedAt": "2026-06-05T21:15:09.447Z", "Attempts": [ { "AttemptNo": 1, "Result": "Failed", "ErrorCode": "INSUFFICIENT_BALANCE", "CreatedAt": "2026-06-05T21:15:02.1180436Z", "CompletedAt": "2026-06-05T21:15:09.447Z" }, { "AttemptNo": 2, "Result": "Success", "ErrorCode": "SUCCESS", "CreatedAt": "2026-06-05T21:15:02.1180436Z", "CompletedAt": "2026-06-05T21:15:09.447Z" } ] }Keep for your records:
Status,DeliveryType,CurrencyandLastUpdatedAt. Here the payment isSuccesswithDeliveryTypeBank: its first attempt failed withINSUFFICIENT_BALANCE, which debits nothing, and its second attempt, after you funded the wallet, went through. On this endpoint every attempt repeats the payment's latest submission time asCreatedAtand its last update asCompletedAt. - List your source wallet's transactions
A batch is funded from its source wallet (
SourceWalletId), so that's the wallet whose transactions you reconcile. CallGetCompanyWalletTransactionswith the source wallet's ID asWalletID. Each record has the date, currency, program, description,Type(CreditorDebit),Amount, the wallet'sBalanceafter the transaction, and aPaymentType.Paginationis required.RecordsToSkipis the page number, not a record offset: send"1"for the first page."0"is rejected with400.RecordsToTakeis the page size.Filtersis optional: aDateRange(StartUTC,EndUTC), a search term inSearchParam, and aTransactionType, one ofAll,Received,Sent,Transfer,Currency Exchange,PendingorFunded. Any other value, such asCreditsorDebits, is refused with400. If you sendFilters,DateRangeandTransactionTypeare required. WithoutFilters, you get only the last 90 days.
Each payment whose recipient's wallet was credited appears here as one
DebitwhoseAmountis the payment'sAmountplus its fee, and whoseDescriptionis the payment'sDescription: in the format we recommend, it starts with the payment'sCustomerTransactionId. These debits have the transaction typeSent, so"TransactionType": "Sent"selects them, together with every otherSenttransaction from the wallet.SearchParamfinds text in a record's description or amount, which is how you look up one payment's debit (see the end of this step).This request lists the first page of 25 transactions in wallet
122181for June 2026.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026" }, "TransactionType": "All" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyWalletTransactions: { Request: { IssuerAccountNumber: 'SPN1111222', WalletID: '122181', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, Filters: { DateRange: { StartUTC: '06/01/2026', EndUTC: '06/30/2026', }, TransactionType: 'All', }, }, }, }), }); 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/GetCompanyWalletTransactions", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026", }, "TransactionType": "All", }, }, }, }, ) 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 = """ { "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026" }, "TransactionType": "All" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions", 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 = """ { "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026" }, "TransactionType": "All" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions")) .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/GetCompanyWalletTransactions'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyWalletTransactions' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'WalletID' => '122181', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], 'Filters' => [ 'DateRange' => [ 'StartUTC' => '06/01/2026', 'EndUTC' => '06/30/2026', ], 'TransactionType' => 'All', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));The excerpt shows the three newest of the wallet's seven records for June. Records come newest first.
Response (excerpt){ "GetCompanyWalletTransactionsResponse": { "GetCompanyWalletTransactionsResult": { "Transactions": [ { "TransactionID": 888607, "TransactionDate": "2026-06-05T16:15:06.283", "Currency": "USD", "ProgramName": "Q3 Partner Rewards", "Description": "TXN-2026-9912A Q3 Contractor Bonus", "Type": "Debit", "Amount": 102, "Balance": 57715.15, "PaymentType": "Personal (1 individuals)" }, { "TransactionID": 888606, "TransactionDate": "2026-06-05T16:10:21.530", "Currency": "USD", "ProgramName": "Q3 Partner Rewards", "Description": "ACH Wallet Funding", "Type": "Credit", "Amount": 57750, "Balance": 57817.15, "PaymentType": "" }, { "TransactionID": 888605, "TransactionDate": "2026-06-05T15:49:44.017", "Currency": "USD", "ProgramName": "Q3 Partner Rewards", "Description": "TXN-2026-9902A Q3 Channel Partner Marketing Bonus", "Type": "Debit", "Amount": 52.5, "Balance": 67.15, "PaymentType": "Company (1 companies)" } ], "OperationStatus": { "Success": true, "Errors": null }, "PaginationTotal": { "RecordsToSkip": 1, "RecordsToTake": 25, "RecordsTotal": 7 } } } }Read from the bottom up, the excerpt tells the story of the retry, and each debit's
Descriptionnames its payment.888605is the debit forTXN-2026-9902A: USD 50.00 plus a USD 2.50 fee, which left USD 67.15 in the wallet, too little forTXN-2026-9912A's first attempt.888606is the funding that followed, and888607is the debit forTXN-2026-9912Aafter you resubmitted it: USD 100.00 plus a USD 2.00 fee. The four older records are the debits for the batch's other payments.Keep for the next steps: each
TransactionID(step 4 takes it as a string, such as"888607"), with itsType,Amount,CurrencyandTransactionDate, and theCustomerTransactionIdat the start of itsDescription; andPaginationTotal.RecordsTotal. For the next page, add 1 toRecordsToSkip("2","3", …) until you've readRecordsTotalrecords.PaginationTotal.RecordsToSkipechoes the page number you sent.Match each debit to its payment by the first word of its
Description, theCustomerTransactionId. The rest of the text can come back changed, for example with an&as&, so compare only the ID.AmountandBalanceare numbers here, while the batch status calls return amounts as strings, before fees. We recommend converting every amount to a decimal type, then checking that the debit'sAmountequals the payment's statusAmountplus its fee (step 4).Find one payment's debit. To look into a single payment, search for its ID. Send
Filterswith"TransactionType": "Sent", the payment'sCustomerTransactionIdinSearchParam, and aDateRangefrom the day before the payment was processed to the day after, sinceTransactionDateis in Xtrm's server time. This request finds the debit forTXN-2026-9912A, which reachedSuccesson 5 June 2026.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/04/2026", "EndUTC": "06/06/2026" }, "SearchParam": "TXN-2026-9912A", "TransactionType": "Sent" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyWalletTransactions: { Request: { IssuerAccountNumber: 'SPN1111222', WalletID: '122181', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, Filters: { DateRange: { StartUTC: '06/04/2026', EndUTC: '06/06/2026', }, SearchParam: 'TXN-2026-9912A', TransactionType: 'Sent', }, }, }, }), }); 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/GetCompanyWalletTransactions", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, "Filters": { "DateRange": { "StartUTC": "06/04/2026", "EndUTC": "06/06/2026", }, "SearchParam": "TXN-2026-9912A", "TransactionType": "Sent", }, }, }, }, ) 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 = """ { "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/04/2026", "EndUTC": "06/06/2026" }, "SearchParam": "TXN-2026-9912A", "TransactionType": "Sent" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions", 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 = """ { "GetCompanyWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "WalletID": "122181", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/04/2026", "EndUTC": "06/06/2026" }, "SearchParam": "TXN-2026-9912A", "TransactionType": "Sent" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactions")) .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/GetCompanyWalletTransactions'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyWalletTransactions' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'WalletID' => '122181', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], 'Filters' => [ 'DateRange' => [ 'StartUTC' => '06/04/2026', 'EndUTC' => '06/06/2026', ], 'SearchParam' => 'TXN-2026-9912A', 'TransactionType' => 'Sent', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetCompanyWalletTransactionsResponse": { "GetCompanyWalletTransactionsResult": { "Transactions": [ { "TransactionID": 888607, "TransactionDate": "2026-06-05T16:15:06.283", "Currency": "USD", "ProgramName": "Q3 Partner Rewards", "Description": "TXN-2026-9912A Q3 Contractor Bonus", "Type": "Debit", "Amount": 102, "Balance": 57715.15, "PaymentType": "Personal (1 individuals)" } ], "OperationStatus": { "Success": true, "Errors": null }, "PaginationTotal": { "RecordsToSkip": 1, "RecordsToTake": 25, "RecordsTotal": 1 } } } }SearchParammatches any part of a record's description or amount, so a search forTXN-2026-991would also returnTXN-2026-9912A. Before you book a match, check that the first word ofDescriptionis exactly the ID.SearchParamuses up to 100 characters, and an_in it matches any single character, so IDs made of letters, digits and hyphens give the cleanest matches. - Get the details of one company transaction
This call shows the fee charged on a payment and who received it. Call
GetCompanyWalletTransactionDetailswith aTransactionIDthat step 3 returns, as a string: here"888607", the debit forTXN-2026-9912A. The request wrapper isGetCompanyTransactionDetails, withoutWallet.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactionDetails" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetCompanyTransactionDetails": { "Request": { "IssuerAccountNumber": "SPN1111222", "TransactionID": "888607" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactionDetails', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyTransactionDetails: { Request: { IssuerAccountNumber: 'SPN1111222', TransactionID: '888607', }, }, }), }); 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/GetCompanyWalletTransactionDetails", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyTransactionDetails": { "Request": { "IssuerAccountNumber": "SPN1111222", "TransactionID": "888607", }, }, }, ) 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 = """ { "GetCompanyTransactionDetails": { "Request": { "IssuerAccountNumber": "SPN1111222", "TransactionID": "888607" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactionDetails", 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 = """ { "GetCompanyTransactionDetails": { "Request": { "IssuerAccountNumber": "SPN1111222", "TransactionID": "888607" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWalletTransactionDetails")) .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/GetCompanyWalletTransactionDetails'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyTransactionDetails' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'TransactionID' => '888607', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response (excerpt){ "GetCompanyTransactionDetailsResponse": { "GetCompanyTransactionDetailsResult": { "Field": [ [ { "Name": "Beneficiary Transaction Id", "Value": "888707" }, { "Name": "Sub Transaction Id", "Value": "99988817" }, { "Name": "Method", "Value": "Wallet" }, { "Name": "Type", "Value": "Debit" }, { "Name": "Status", "Value": "Transaction Complete (Jun 05, 2026)" }, { "Name": "Transferred to", "Value": "Jane Doe ([email protected])" }, { "Name": "Program", "Value": "Q3 Partner Rewards" }, { "Name": "Description", "Value": "TXN-2026-9912A Q3 Contractor Bonus" }, { "Name": "Comment", "Value": "TXN-2026-9912A Q3 Contractor Bonus" }, { "Name": "Amount", "Value": "100.00" }, { "Name": "Fees", "Value": "2.00" }, { "Name": "Total Payment", "Value": "102.00" }, { "Name": "Currency", "Value": "USD" } ] ], "PayDirectTransactionDetails": [], "OperationStatus": { "Success": true, "Errors": null } } } }Keep for your records: the details are
Name/Valuepairs inField[0]. We recommend looking them up byName, not by position. BookAmount,Fees,Total PaymentandCurrency(strings such as"100.00"), and compareStatus,MethodandTransferred towith the payment you matched.DescriptionandCommentboth hold the payment'sDescription, so they start with itsCustomerTransactionId. HereAmountis the USD 100.00 ofTXN-2026-9912A,Total Paymentis the USD 102.00 debit from step 3, andTransferred tois Jane Doe.MethodisWalletbecause every payment is first credited to the recipient's wallet; the delivery to Jane's bank account happens from there. On a debit for a payment,Beneficiary Transaction Idis theTransactionIDof the matching credit in the recipient's wallet: here888707, the credit to Jane's wallet that step 5 lists. The full response also has entries such asSale DateandBudget Code, andPayDirectTransactionDetailsfor Pay Direct transactions. - List an individual recipient's wallet transactions
To see a payment from the receiving side, call
GetUserWalletTransactions. A batch payment credits the recipient's wallet first, and creates one in the batch currency if the recipient has none. So look for the credit of the payment's fullAmountin the individual recipient's wallet for the batchCurrency, with the payment'sDescription. When a bank, check, card or Rapid Transfer payment reachesSuccess, the wallet also shows the debit for its delivery, with a description of its own rather than the payment's.This call needs a connection to the recipient. Jane Doe is connected to your company because you created her with
CreateUser. With the connection, the call returns every transaction in her wallet, from any company, not only your payments.An individual recipient has at most one wallet per currency, so you address it with
UserIDandWalletCurrency.PaginationandFilterswork as in step 3, with two differences: withoutFilters, this call returns the wallet's whole transaction history, newest first, not only the last 90 days; andSearchParamdoesn't search descriptions here, so filter byDateRangeand compareDescriptionyourself. This request lists only the credits to Jane's USD wallet in June 2026.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactions" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetUserWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026" }, "TransactionType": "Received" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetUserWalletTransactions: { Request: { IssuerAccountNumber: 'SPN1111222', UserID: 'PAT9999888', WalletCurrency: 'USD', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, Filters: { DateRange: { StartUTC: '06/01/2026', EndUTC: '06/30/2026', }, TransactionType: 'Received', }, }, }, }), }); 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/GetUserWalletTransactions", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetUserWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026", }, "TransactionType": "Received", }, }, }, }, ) 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 = """ { "GetUserWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026" }, "TransactionType": "Received" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactions", 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 = """ { "GetUserWalletTransactions": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" }, "Filters": { "DateRange": { "StartUTC": "06/01/2026", "EndUTC": "06/30/2026" }, "TransactionType": "Received" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactions")) .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/GetUserWalletTransactions'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetUserWalletTransactions' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT9999888', 'WalletCurrency' => 'USD', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], 'Filters' => [ 'DateRange' => [ 'StartUTC' => '06/01/2026', 'EndUTC' => '06/30/2026', ], 'TransactionType' => 'Received', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetUserWalletTransactionsResponse": { "GetUserWalletTransactionsResult": { "Transactions": [ { "TransactionID": 888707, "CompanyName": "Fabrikam Inc", "ProgramName": "Q3 Partner Rewards", "TransactionDate": "2026-06-05T16:15:06.283", "Description": "TXN-2026-9912A Q3 Contractor Bonus", "Amount": 100, "Type": "Credit", "PaymentMethod": "AnyPay" }, { "TransactionID": 888702, "CompanyName": "Fabrikam Inc", "ProgramName": "Q3 Partner Rewards", "TransactionDate": "2026-06-05T15:49:41.870", "Description": "TXN-2026-9903A Q3 Top Performer Contractor Reward", "Amount": 50, "Type": "Credit", "PaymentMethod": "AnyPay" } ], "OperationStatus": { "Success": true, "Errors": null }, "PaginationTotal": { "RecordsToSkip": 1, "RecordsToTake": 25, "RecordsTotal": 2 } } } }Each credit's
Descriptionnames its payment. The first credit isTXN-2026-9912A: the full USD 100.00. Your company paid the USD 2.00 fee on top, so it doesn't appear here. The second isTXN-2026-9903A, the USD 50.00 prepaid card payment to Jane in the same batch. Jane sees both descriptions in her wallet. Both amounts then left the wallet again, on their way to Jane's bank account and to her prepaid card. Those debits show when you listAlltransactions.Keep for your records: each record's
TransactionID,TransactionDate,Amount,CompanyNameandPaymentMethod, and theCustomerTransactionIdat the start of itsDescription. The filter value for credits isReceived; the recordTypeisCredit. For one record's full breakdown, pass itsTransactionID(as a string) and the recipient'sUserIDtoGetUserWalletTransactionDetails. ItsDescriptionreadsWalletfor a payment's credit, so take the payment's ID from this list. - List only what your company paid the recipient
An individual recipient's wallet can also hold payments from other companies.
GetUserWalletTransactionsByRemitterlists only the transactions from one paying company, given inRemitterAccountNo. Set it to your ownSPN: for your own payments, this call doesn't need a connection to the recipient. There are noFilters, so page through withPagination. Each record adds itsCurrency.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactionsByRemitter" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetUserWalletTransactionsByRemitter": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "RemitterAccountNo": "SPN1111222", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactionsByRemitter', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetUserWalletTransactionsByRemitter: { Request: { IssuerAccountNumber: 'SPN1111222', UserID: 'PAT9999888', RemitterAccountNo: 'SPN1111222', WalletCurrency: 'USD', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, }, }, }), }); 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/GetUserWalletTransactionsByRemitter", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetUserWalletTransactionsByRemitter": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "RemitterAccountNo": "SPN1111222", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, }, }, }, ) 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 = """ { "GetUserWalletTransactionsByRemitter": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "RemitterAccountNo": "SPN1111222", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactionsByRemitter", 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 = """ { "GetUserWalletTransactionsByRemitter": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT9999888", "RemitterAccountNo": "SPN1111222", "WalletCurrency": "USD", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletTransactionsByRemitter")) .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/GetUserWalletTransactionsByRemitter'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetUserWalletTransactionsByRemitter' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT9999888', 'RemitterAccountNo' => 'SPN1111222', 'WalletCurrency' => 'USD', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetUserWalletTransactionsByRemitterResponse": { "GetUserWalletTransactionsByRemitterResult": { "Transactions": [ { "TransactionID": 888607, "CompanyName": "Fabrikam Inc", "ProgramName": "Q3 Partner Rewards", "TransactionDate": "2026-06-05T16:15:06.283", "Description": "TXN-2026-9912A Q3 Contractor Bonus", "Amount": 100, "Currency": "USD", "Type": "Credit", "PaymentMethod": "AnyPay" }, { "TransactionID": 888602, "CompanyName": "Fabrikam Inc", "ProgramName": "Q3 Partner Rewards", "TransactionDate": "2026-06-05T15:49:41.870", "Description": "TXN-2026-9903A Q3 Top Performer Contractor Reward", "Amount": 50, "Currency": "USD", "Type": "Credit", "PaymentMethod": "AnyPay" } ], "OperationStatus": { "Success": true, "Errors": null }, "PaginationTotal": { "RecordsToSkip": 1, "RecordsToTake": 25, "RecordsTotal": 2 } } } }Your company has paid Jane twice, both in this batch, so the list holds the same two credits as step 5. Here, though, each record's
TransactionIDis the ID of your debit for the payment, as step 3 lists it:888607forTXN-2026-9912A, not888707, the credit's ID in step 5.Keep for your records: each record's
TransactionID,TransactionDate,AmountandCurrency. Match each record to your payment by theCustomerTransactionIdat the start of itsDescription, and check it against that payment's debit from step 3, which has the sameTransactionID. - Check your wallet fees
GetCompanyFeesreturns the wallet fees from the fee schedule of the account inBeneficiaryAccountNumber: aFlatFee,PercentageFeeandCapFeefor paying into a company wallet (SendtoCompany, the fee type ofXTR94504payments) and into an individual's wallet (sendtoIndividual, lowercases, the fee type ofXTR94502payments). Pass your ownSPNto see your own schedule, as this request does. OnlyUSDis accepted asCurrencyCode. For bank, check, card and Rapid Transfer payments, book the fee charged on each payment (Feesin step 4).curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/GetCompanyFees" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetCompanyFees": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "CurrencyCode": "USD" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/GetCompanyFees', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetCompanyFees: { Request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryAccountNumber: 'SPN1111222', CurrencyCode: 'USD', }, }, }), }); 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/GetCompanyFees", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetCompanyFees": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "CurrencyCode": "USD", }, }, }, ) 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 = """ { "GetCompanyFees": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "CurrencyCode": "USD" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/GetCompanyFees", 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 = """ { "GetCompanyFees": { "Request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN1111222", "CurrencyCode": "USD" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/GetCompanyFees")) .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/GetCompanyFees'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetCompanyFees' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryAccountNumber' => 'SPN1111222', 'CurrencyCode' => 'USD', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetCompanyFeesResponse": { "GetCompanyFeesResult": { "CompanyFees": { "SendFees": { "SendtoCompany": { "FlatFee": 2.50, "PercentageFee": 0.00, "CapFee": 0.00 }, "sendtoIndividual": { "FlatFee": 0.00, "PercentageFee": 3.20, "CapFee": 0.00 } } }, "OperationStatus": { "Success": true, "Errors": null } } } }Keep for your records: the schedule and the date you fetched it. A batch payment fee is a percentage of the payment's
Amountplus a flat fee, and some fee types also have a cap.PercentageFee3.20means 3.2%. Xtrm picks the fee type from each payment'sSendMethodIdand, for bank payments, the rail. In this schedule,SendtoCompanyis a flat USD 2.50: the fee onTXN-2026-9902A, whose debit in step 3 is USD 52.50 for a USD 50.00 payment. Use the schedule to check your wallet payments and to spot changes in your wallet fees. - Get credit and debit totals for a connected company
GetConnectedCompanyFundRequestreturns total credits and debits, per currency, for a connected business recipient over a date range. You can use it as a period-end cross-check for the business recipients you pay. The totals cover every credit and debit in the company's wallets in each currency, not only payments from your company, so treat a difference from your own sums as something to look into, not as an error. This request reads June 2026 for Acme Corporation (SPN9999888), which is connected to your company because you created it withCreateBeneficiary.FromDateandToDateare strictlyMM/DD/YYYY.Pagination.RecordsToSkipis a page number here too:"1"for the first page.PaymentTypeselects the totals:Creditsreturns only credits (Debitsreads0.00),Debitsonly debits, andAllboth.- The wrapper is
GetConnectedFundRequestDetails, with a lowercaserequestinside.
The response is CSV text, not JSON, so these samples read the body as text.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/GetConnectedCompanyFundRequest" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetConnectedFundRequestDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888", "PaymentType": "All", "FromDate": "06/01/2026", "ToDate": "06/30/2026", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Fund/GetConnectedCompanyFundRequest', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetConnectedFundRequestDetails: { request: { IssuerAccountNumber: 'SPN1111222', BeneficiaryAccountNumber: 'SPN9999888', PaymentType: 'All', FromDate: '06/01/2026', ToDate: '06/30/2026', Pagination: { RecordsToSkip: '1', RecordsToTake: '25', }, }, }, }), }); const csv = await response.text(); console.log(csv);import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Fund/GetConnectedCompanyFundRequest", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetConnectedFundRequestDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888", "PaymentType": "All", "FromDate": "06/01/2026", "ToDate": "06/30/2026", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25", }, }, }, }, ) response.raise_for_status() print(response.text)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 = """ { "GetConnectedFundRequestDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888", "PaymentType": "All", "FromDate": "06/01/2026", "ToDate": "06/30/2026", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Fund/GetConnectedCompanyFundRequest", 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 = """ { "GetConnectedFundRequestDetails": { "request": { "IssuerAccountNumber": "SPN1111222", "BeneficiaryAccountNumber": "SPN9999888", "PaymentType": "All", "FromDate": "06/01/2026", "ToDate": "06/30/2026", "Pagination": { "RecordsToSkip": "1", "RecordsToTake": "25" } } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Fund/GetConnectedCompanyFundRequest")) .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/GetConnectedCompanyFundRequest'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetConnectedFundRequestDetails' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'BeneficiaryAccountNumber' => 'SPN9999888', 'PaymentType' => 'All', 'FromDate' => '06/01/2026', 'ToDate' => '06/30/2026', 'Pagination' => [ 'RecordsToSkip' => '1', 'RecordsToTake' => '25', ], ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); echo $response, PHP_EOL;ResponseAccount Number,Name,Credits,Debits,Currency SPN9999888,Acme Corporation,50.00,50.00,USDThe USD credit is
TXN-2026-9905A, your USD 50.00 payment, and the debit is its delivery to Acme's card. In this example Acme had no other activity in June. Acme's own wallet lists that credit with your payment'sDescription, which starts withTXN-2026-9905A, inGetCompanyWalletTransactionsand in the transaction's details, so Acme sees which of your payments it was.Keep for your records: the CSV starts with the header row,
Account Number,Name,Credits,Debits,Currency, with no line before it, followed by one row per currency.CreditsandDebitsare totals for the date range. We recommend comparing them with your own per-currency sums for that company and looking into any difference.
#Build a reconciliation loop
Here's the routine we recommend. Adapt it to your own books:
- Record before you pay. Create a record for each payment, keyed by
CustomerBatchIdandCustomerTransactionId, before you submit the batch, and start the payment'sDescriptionwith itsCustomerTransactionId. From the202 Acceptedresponse, mark the payments inRejectedas not paid, except aCONFLICT_DUPLICATE_ITEMentry, which an earlier request already stored (Items rejected at submission explains each code). Confirm the payments inAcceptedwith the status endpoints, becauseAcceptedalone doesn't prove a payment was stored. If a submit call times out, follow A safe retry pattern instead of building a new batch. - React to webhooks. Verify and de-duplicate each webhook as described in Verify the signature and Retries and duplicates, then fetch the payment's status (step 2) and update its record. An event for a payment you have no record of isn't an error: see Build a receiver.
- Sweep open batches. On a schedule, call the batch status (step 1) with
history=truefor every batch you haven't closed, and page untilHasMoreisfalse. This catches any change a webhook didn't tell you about. - Settle each payment. Book
Successas paid: the provider accepted the payment, though settlement can follow later. Leave aRetainedInWalletpayment open while its batch isProcessing: Xtrm is still delivering it, and it normally moves on toSuccess. Book it as final only once the batch status is final: it has then stuck, itsAmountplus fee has left your source wallet, the fee isn't refunded, and the money is in the recipient's Xtrm wallet, from where it reaches their bank or card as described in When a payment stays RetainedInWallet. ForFailed, fix the cause and resubmit it under its original IDs, or close it, as described in What to do for each status. - Tie it to the money. Daily, for example, pull your source wallet's transactions (step 3) for a
DateRangethat ends in the past, so results don't change while you page. Both bounds are inclusive,EndUTCcovers its whole day, and records come newest first, so start each window the day after the previous one ends, and de-duplicate byTransactionIDas a safeguard. Match eachSentdebit to its payment by theCustomerTransactionIdthat starts itsDescription. Check that the payment reachedSuccessorRetainedInWalletand that the debit'sAmountis the payment'sAmountplus its fee, then open the details (step 4) to book the fee. Fall back to amount plus fee, currency and date, with a day of tolerance, only for a debit whoseDescriptioncarries no ID. - Flag both directions. Report wallet transactions you can't match to a payment, and settled payments you can't find in the wallet. To look for a settled payment's debit, search for its
CustomerTransactionId(step 3). Look into each one rather than paying it again as a new payment. A credit you didn't expect can be a returned bank payment: match it to Xtrm's email before you book it. - Close the period. Compare each connected company's totals (step 8) with your per-currency sums and look into any difference, keeping in mind that those totals include every transaction in the company's wallets, not only your payments. Refresh your copy of the fee schedule (step 7).
At year end, you can also email a connected individual recipient their tax forms with TransferTaxInformation. The email goes to the recipient as soon as you call, so we recommend logging every request and not retrying it automatically.
#What can go wrong
The wallet and fee calls report failures in OperationStatus: a failed call returns HTTP 400 with Success set to false and an Errors array with one message per problem. We recommend checking OperationStatus.Success in every JSON response, not only the HTTP status, and logging OperationStatus.Errors when it's false. The batch status calls have no OperationStatus, so log the full response body of every failed status request. See Errors.
- A status call can't find the batch or payment. Use the IDs exactly as Xtrm stored them. A
404doesn't prove that the batch or payment is missing: a failed database read returns the same404, and so can a check made while a timed-out submit call is still storing the batch. Repeat the check a few times, at least a minute apart; see When a status request fails. A401for aCustomerBatchIdmeans another Xtrm account used it. See Errors when you check status. Attemptsis empty. Sendhistory=true. Without it,Attemptsis[]on both status endpoints.- A batch status call returns
413LIMIT_EXCEEDED. The response would exceed your account's response-size limit, which is easier to reach withhistory=true. Request fewer payments withrecordsToTake, or leave outhistoryand fetch history per payment (step 2). - A status value you don't expect. Keep the payment open and alert, rather than booking it as paid or failed. Payment statuses lists every value.
- A webhook doesn't match the status you fetch. Book the status you fetch (step 2), not the event. For how Xtrm orders and retries events, see Event order and Retries and duplicates.
- A wallet list returns
400or skips records. In the wallet calls,RecordsToSkipis a page number, not a record offset: send"1"for the first page and add 1 for each next page."0"is rejected, and a record count such as"25"jumps to page 25. - Types differ between calls. Status amounts are strings, with a thousands separator on the batch status endpoint (
"1,234.56") and without one on the payment status endpoint ("1234.56"). Wallet lists returnTransactionIDand amounts as numbers. The details calls take the ID as a string and return amounts as strings, with the currency code for an individual recipient's wallet ("100.00 USD"). Pagination values are strings in wallet requests and numbers inPaginationTotal. - A filter is refused or matches less than you expect.
TransactionTypeaccepts onlyAll,Received,Sent,Transfer,Currency Exchange,PendingandFunded, soCreditsandDebitsget400. The filter for credits isReceived, while the recordTypeisCredit. In a company wallet, a credit that Xtrm makes by hand, such as a returned bank payment, comes underFundedandAllinstead ofReceived. If you sendFilters, includeDateRangeandTransactionType. WithoutFilters,GetCompanyWalletTransactionsreturns only the last 90 days, whileGetUserWalletTransactionsreturns the wallet's whole history. SendStartUTCandEndUTCasMM/DD/YYYYdates. Xtrm compares them with each record'sTransactionDate, which is in Xtrm's server time, and includes both days. - A search for one payment returns other debits too.
SearchParammatches any part of a description or amount, and an_in it matches any single character, so a search forTXN-2026-991also returnsTXN-2026-9912A. Book a match only when the first word ofDescriptionis exactly the ID. In an individual recipient's wallet,SearchParamdoesn't search descriptions, so compareDescriptionyourself. - Your parser expects JSON.
GetConnectedCompanyFundRequestreturns CSV text and noPaginationTotal. Its first line is the header row (step 8). - You can't see a recipient's full wallet history. A recipient's whole wallet activity (
GetUserWalletTransactions) and a company's credit and debit totals (GetConnectedCompanyFundRequest) need a connection to the recipient's account. Check it withGetConnectedStatus: onlyConnectedgives access, and aPendingrequest gives none until it's approved. See Check a connection and Connect existing accounts. For your own payments to an individual recipient,GetUserWalletTransactionsByRemitter(step 6) needs no connection. - Sandbox results differ from what you expect. The sandbox runs the same batch payment processing as production. See Sandbox & environments for test values and for the inputs that make a payment fail on purpose.
#Next steps
The batch lifecycle and wallet-first delivery behind each status.
Create a batch paymentSet CustomerBatchId and CustomerTransactionId on every batch you reconcile, and start each Description with the payment's ID.
What each batch and payment status means.
WebhooksGet notified when payments complete or fail.
Retries & idempotencyRetry failed payments safely with the same batch and payment IDs.
Batch paymentsAPI reference: every field of the batch and status endpoints.
ReportsAPI reference: fee schedules, connected-company totals and year-end tax forms.