Guide

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_TOKEN environment variable. See Sandbox & environments and Authentication.
  • Your company's account number (SPN), sent as IssuerAccountNumber. The samples use SPN1111222, the account of your company, Fabrikam Inc.
  • A batch payment you've submitted and its CustomerBatchId, ideally with each payment's CustomerTransactionId at the start of its Description (see Your join keys). To submit a batch, see Create a batch payment.
  • Your own payment records, one row per payment, keyed by CustomerBatchId and CustomerTransactionId (see the next section).
  • A connection to the recipients you look into in steps 5 and 8. Recipients you create with CreateUser or CreateBeneficiary are 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

PieceIts job in reconciliation
CustomerBatchId and CustomerTransactionIdThe keys that match your records to Xtrm's.
Each payment's DescriptionCarries your CustomerTransactionId onto the wallet transactions, so you can find each payment's money (steps 3 to 6).
Batch and payment statusEach payment's state, with the history of every attempt (steps 1 and 2).
WebhooksA signal that something changed and it's time to check the status.
Wallet transactions, fees and totalsThe 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:

One payment in the BatchTransfer request (excerpt)
{
  "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

  1. Get the batch status with attempt history

    Call GET /Fund/BatchTransfer/{CustomerBatchId}. It returns the batch Status, its Currency, ItemsCount, and one page of Items, each with its Status, RecipientId, SendMethodId, Amount and LastUpdatedAt.

    • Page through the payments with the query parameters recordsToSkip (an item offset, 0 for the first page) and recordsToTake. They're camelCase, unlike the Pagination objects in the wallet calls below, where RecordsToSkip is a page number.
    • Set history=true to include each payment's Attempts: the history of its processing attempts, with each one's AttemptNo, Result (Success or Failed), ErrorCode and timestamps. Without it, Attempts is []. 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"

    The excerpt shows three of the batch's six payments. All six are Success, so the batch reads Completed.

    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, its Status, Amount, LastUpdatedAt, and the ErrorCode of any failed attempt; for the batch, its Status and Currency. On this endpoint Amount is a string with a thousands separator, such as "1,234.56", so strip separators before you parse it. When Pagination.HasMore is true, call again with Pagination.NextRecordsToSkip as recordsToSkip.

    We recommend booking a payment by its Status, not by a single attempt's Result: TXN-2026-9912A is Success although its first attempt failed. This endpoint lists Attempts newest first and the payment status endpoint (step 2) oldest first, so sort by AttemptNo.

  2. 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's Currency and DeliveryType.

    Once the payment is Success, DeliveryType names the rail that delivered it, such as Bank or Wallet. It's Wallet for every RetainedInWallet payment. It's an empty string while the payment is Accepted or Processing, and when it is Failed. This endpoint returns Amount without a thousands separator ("1234.56"), and it reads only committed data, so confirm a payment here before you act on it. Set history=true to include Attempts.

    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"
    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, Currency and LastUpdatedAt. Here the payment is Success with DeliveryType Bank: its first attempt failed with INSUFFICIENT_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 as CreatedAt and its last update as CompletedAt.

  3. List your source wallet's transactions

    A batch is funded from its source wallet (SourceWalletId), so that's the wallet whose transactions you reconcile. Call GetCompanyWalletTransactions with the source wallet's ID as WalletID. Each record has the date, currency, program, description, Type (Credit or Debit), Amount, the wallet's Balance after the transaction, and a PaymentType.

    • Pagination is required. RecordsToSkip is the page number, not a record offset: send "1" for the first page. "0" is rejected with 400. RecordsToTake is the page size.
    • Filters is optional: a DateRange (StartUTC, EndUTC), a search term in SearchParam, and a TransactionType, one of All, Received, Sent, Transfer, Currency Exchange, Pending or Funded. Any other value, such as Credits or Debits, is refused with 400. If you send Filters, DateRange and TransactionType are required. Without Filters, you get only the last 90 days.

    Each payment whose recipient's wallet was credited appears here as one Debit whose Amount is the payment's Amount plus its fee, and whose Description is the payment's Description: in the format we recommend, it starts with the payment's CustomerTransactionId. These debits have the transaction type Sent, so "TransactionType": "Sent" selects them, together with every other Sent transaction from the wallet. SearchParam finds 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 122181 for 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"
          }
        }
      }
    }'

    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 Description names its payment. 888605 is the debit for TXN-2026-9902A: USD 50.00 plus a USD 2.50 fee, which left USD 67.15 in the wallet, too little for TXN-2026-9912A's first attempt. 888606 is the funding that followed, and 888607 is the debit for TXN-2026-9912A after 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 its Type, Amount, Currency and TransactionDate, and the CustomerTransactionId at the start of its Description; and PaginationTotal.RecordsTotal. For the next page, add 1 to RecordsToSkip ("2", "3", …) until you've read RecordsTotal records. PaginationTotal.RecordsToSkip echoes the page number you sent.

    Match each debit to its payment by the first word of its Description, the CustomerTransactionId. The rest of the text can come back changed, for example with an & as &, so compare only the ID. Amount and Balance are 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's Amount equals the payment's status Amount plus its fee (step 4).

    Find one payment's debit. To look into a single payment, search for its ID. Send Filters with "TransactionType": "Sent", the payment's CustomerTransactionId in SearchParam, and a DateRange from the day before the payment was processed to the day after, since TransactionDate is in Xtrm's server time. This request finds the debit for TXN-2026-9912A, which reached Success on 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"
          }
        }
      }
    }'
    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
          }
        }
      }
    }

    SearchParam matches any part of a record's description or amount, so a search for TXN-2026-991 would also return TXN-2026-9912A. Before you book a match, check that the first word of Description is exactly the ID. SearchParam uses up to 100 characters, and an _ in it matches any single character, so IDs made of letters, digits and hyphens give the cleanest matches.

  4. Get the details of one company transaction

    This call shows the fee charged on a payment and who received it. Call GetCompanyWalletTransactionDetails with a TransactionID that step 3 returns, as a string: here "888607", the debit for TXN-2026-9912A. The request wrapper is GetCompanyTransactionDetails, without Wallet.

    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"
        }
      }
    }'
    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/Value pairs in Field[0]. We recommend looking them up by Name, not by position. Book Amount, Fees, Total Payment and Currency (strings such as "100.00"), and compare Status, Method and Transferred to with the payment you matched. Description and Comment both hold the payment's Description, so they start with its CustomerTransactionId. Here Amount is the USD 100.00 of TXN-2026-9912A, Total Payment is the USD 102.00 debit from step 3, and Transferred to is Jane Doe. Method is Wallet because 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 Id is the TransactionID of the matching credit in the recipient's wallet: here 888707, the credit to Jane's wallet that step 5 lists. The full response also has entries such as Sale Date and Budget Code, and PayDirectTransactionDetails for Pay Direct transactions.

  5. 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 full Amount in the individual recipient's wallet for the batch Currency, with the payment's Description. When a bank, check, card or Rapid Transfer payment reaches Success, 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 UserID and WalletCurrency. Pagination and Filters work as in step 3, with two differences: without Filters, this call returns the wallet's whole transaction history, newest first, not only the last 90 days; and SearchParam doesn't search descriptions here, so filter by DateRange and compare Description yourself. 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"
          }
        }
      }
    }'
    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 Description names its payment. The first credit is TXN-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 is TXN-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 list All transactions.

    Keep for your records: each record's TransactionID, TransactionDate, Amount, CompanyName and PaymentMethod, and the CustomerTransactionId at the start of its Description. The filter value for credits is Received; the record Type is Credit. For one record's full breakdown, pass its TransactionID (as a string) and the recipient's UserID to GetUserWalletTransactionDetails. Its Description reads Wallet for a payment's credit, so take the payment's ID from this list.

  6. List only what your company paid the recipient

    An individual recipient's wallet can also hold payments from other companies. GetUserWalletTransactionsByRemitter lists only the transactions from one paying company, given in RemitterAccountNo. Set it to your own SPN: for your own payments, this call doesn't need a connection to the recipient. There are no Filters, so page through with Pagination. Each record adds its Currency.

    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"
          }
        }
      }
    }'
    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 TransactionID is the ID of your debit for the payment, as step 3 lists it: 888607 for TXN-2026-9912A, not 888707, the credit's ID in step 5.

    Keep for your records: each record's TransactionID, TransactionDate, Amount and Currency. Match each record to your payment by the CustomerTransactionId at the start of its Description, and check it against that payment's debit from step 3, which has the same TransactionID.

  7. Check your wallet fees

    GetCompanyFees returns the wallet fees from the fee schedule of the account in BeneficiaryAccountNumber: a FlatFee, PercentageFee and CapFee for paying into a company wallet (SendtoCompany, the fee type of XTR94504 payments) and into an individual's wallet (sendtoIndividual, lowercase s, the fee type of XTR94502 payments). Pass your own SPN to see your own schedule, as this request does. Only USD is accepted as CurrencyCode. For bank, check, card and Rapid Transfer payments, book the fee charged on each payment (Fees in 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"
        }
      }
    }'
    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 Amount plus a flat fee, and some fee types also have a cap. PercentageFee 3.20 means 3.2%. Xtrm picks the fee type from each payment's SendMethodId and, for bank payments, the rail. In this schedule, SendtoCompany is a flat USD 2.50: the fee on TXN-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.

  8. Get credit and debit totals for a connected company

    GetConnectedCompanyFundRequest returns 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 with CreateBeneficiary.

    • FromDate and ToDate are strictly MM/DD/YYYY.
    • Pagination.RecordsToSkip is a page number here too: "1" for the first page.
    • PaymentType selects the totals: Credits returns only credits (Debits reads 0.00), Debits only debits, and All both.
    • The wrapper is GetConnectedFundRequestDetails, with a lowercase request inside.

    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"
          }
        }
      }
    }'
    Response
    Account Number,Name,Credits,Debits,Currency
    SPN9999888,Acme Corporation,50.00,50.00,USD

    The 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's Description, which starts with TXN-2026-9905A, in GetCompanyWalletTransactions and 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. Credits and Debits are 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:

  1. Record before you pay. Create a record for each payment, keyed by CustomerBatchId and CustomerTransactionId, before you submit the batch, and start the payment's Description with its CustomerTransactionId. From the 202 Accepted response, mark the payments in Rejected as not paid, except a CONFLICT_DUPLICATE_ITEM entry, which an earlier request already stored (Items rejected at submission explains each code). Confirm the payments in Accepted with the status endpoints, because Accepted alone doesn't prove a payment was stored. If a submit call times out, follow A safe retry pattern instead of building a new batch.
  2. 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.
  3. Sweep open batches. On a schedule, call the batch status (step 1) with history=true for every batch you haven't closed, and page until HasMore is false. This catches any change a webhook didn't tell you about.
  4. Settle each payment. Book Success as paid: the provider accepted the payment, though settlement can follow later. Leave a RetainedInWallet payment open while its batch is Processing: Xtrm is still delivering it, and it normally moves on to Success. Book it as final only once the batch status is final: it has then stuck, its Amount plus 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. For Failed, fix the cause and resubmit it under its original IDs, or close it, as described in What to do for each status.
  5. Tie it to the money. Daily, for example, pull your source wallet's transactions (step 3) for a DateRange that ends in the past, so results don't change while you page. Both bounds are inclusive, EndUTC covers its whole day, and records come newest first, so start each window the day after the previous one ends, and de-duplicate by TransactionID as a safeguard. Match each Sent debit to its payment by the CustomerTransactionId that starts its Description. Check that the payment reached Success or RetainedInWallet and that the debit's Amount is the payment's Amount plus 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 whose Description carries no ID.
  6. 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.
  7. 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 404 doesn't prove that the batch or payment is missing: a failed database read returns the same 404, 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. A 401 for a CustomerBatchId means another Xtrm account used it. See Errors when you check status.
  • Attempts is empty. Send history=true. Without it, Attempts is [] on both status endpoints.
  • A batch status call returns 413 LIMIT_EXCEEDED. The response would exceed your account's response-size limit, which is easier to reach with history=true. Request fewer payments with recordsToTake, or leave out history and 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 400 or skips records. In the wallet calls, RecordsToSkip is 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 return TransactionID and 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 in PaginationTotal.
  • A filter is refused or matches less than you expect. TransactionType accepts only All, Received, Sent, Transfer, Currency Exchange, Pending and Funded, so Credits and Debits get 400. The filter for credits is Received, while the record Type is Credit. In a company wallet, a credit that Xtrm makes by hand, such as a returned bank payment, comes under Funded and All instead of Received. If you send Filters, include DateRange and TransactionType. Without Filters, GetCompanyWalletTransactions returns only the last 90 days, while GetUserWalletTransactions returns the wallet's whole history. Send StartUTC and EndUTC as MM/DD/YYYY dates. Xtrm compares them with each record's TransactionDate, which is in Xtrm's server time, and includes both days.
  • A search for one payment returns other debits too. SearchParam matches any part of a description or amount, and an _ in it matches any single character, so a search for TXN-2026-991 also returns TXN-2026-9912A. Book a match only when the first word of Description is exactly the ID. In an individual recipient's wallet, SearchParam doesn't search descriptions, so compare Description yourself.
  • Your parser expects JSON. GetConnectedCompanyFundRequest returns CSV text and no PaginationTotal. 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 with GetConnectedStatus: only Connected gives access, and a Pending request 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