Core concepts

Requests & responses

You pay recipients with batch payments, and the three batch payment endpoints use plain JSON. You POST a batch as a flat JSON object, Xtrm answers 202 Accepted, and you GET the status of the batch and of each item in it. The rest of the API, which you use to look up wallets, manage recipients, fund your wallets and read reference data, wraps most requests and responses in an operation envelope and reports the outcome in an OperationStatus object.

This page covers both styles and the conventions they share: headers, data types, formats and pagination. It ends with a reusable helper for the envelope endpoints.

#At a glance

Batch payment endpointsEvery other endpoint
Paths/Fund/BatchTransfer, /Fund/BatchTransfer/{CustomerBatchId} and /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}/<Resource>/<Operation>, for example /Wallet/GetCompanyWallets
MethodPOST to submit a batch, GET to check its statusPOST, lookups included
Request bodyFlat JSON: the fields sit at the root. The GET endpoints take no body.JSON wrapped as {"<Operation>": {"request": { … }}}
Response bodyPlain JSON: {"BatchTransferResponse": { … }} when you submit, the status object itself when you checkJSON wrapped as {"<Name>Response": {"<Name>Result": { … }}}
OutcomeThe HTTP status (202 Accepted on submit), the Accepted and Rejected items, then each item's StatusThe HTTP status and OperationStatus.Success inside the result
PaginationrecordsToSkip and recordsToTake query parameters, Pagination in the responseA Pagination object in the body, PaginationTotal in the response
AuthenticationAuthorization: Bearer <access_token>Authorization: Bearer <access_token>, except on the token request

#URLs, methods and content types

An endpoint URL is a base URL followed by a path:

EnvironmentBase URL
Sandboxhttps://xapisandbox.xtrm.com/API/v4
Productionhttps://xapi.xtrm.com/API/v4

The batch payment paths all start with /Fund/BatchTransfer. Every other path is a resource segment followed by the operation name, for example /Wallet/GetCompanyWallets. The resource segments are Fund, Wallet, Bank, Card, Beneficiary, Register, Payment, Programs, GiftCard, OTP, General and Report.

The token endpoint is the only one outside /API/v4. It sits at the host root: https://xapisandbox.xtrm.com/oAuth/token. See Authentication. Paths match in any case, so /API/V4 reaches the same endpoints; this site writes /API/v4. See Sandbox & environments.

RequestMethodContent-TypeBody
Submit a batch paymentPOSTapplication/jsonThe batch as a flat JSON object, UTF-8 encoded
Batch status and item statusGETNoneNo body. Path parameters and query parameters
Token request (/oAuth/token)POSTapplication/x-www-form-urlencodedForm fields grant_type, client_id, client_secret, plus refresh_token when you renew a session
Every other endpointPOSTapplication/jsonJSON in the operation envelope

Submit a batch payment as JSON with Content-Type: application/json. Xtrm refuses a request whose Content-Type is missing or not supported with 415 (invalid_media_type), before it checks the token, and a body that isn't valid JSON with 400 (BAD_REQUEST).

Lookups use POST too. List endpoints that need no input, such as GetCountry, take an empty JSON object {} as the body. Apart from the two batch status calls, every endpoint accepts only POST. A GET to one of the POST endpoints under /API/v4, such as GetAdvancedContactCountry, returns HTTP 404 with {"StatusCode": 404, "Message": "The requested resource is not found"} and no OperationStatus.

#Headers

HeaderValueSend it on
AuthorizationBearer <access_token>Every request except the token request
Content-Typeapplication/jsonEvery POST except the token request, which sends application/x-www-form-urlencoded. The batch status GET requests have no body and need no Content-Type.
Acceptapplication/jsonOptional: every response is JSON whatever you send, except the CSV from GetConnectedCompanyFundRequest. The samples on this site leave it out for brevity; the helper sends it.

The access token comes from the token request. See Authentication for how to get and renew it. For the batch payment endpoints, the token is scoped to your company's account.

Xtrm also sends requests to you: batch payment webhooks, signed with HMAC-SHA256 in an X-Signature header. See Webhooks.

#Batch payment requests

#Submit a batch payment

POST /API/v4/Fund/BatchTransfer takes the batch as a flat JSON object. There is no operation wrapper and no request object: the batch fields sit at the root of the body, and each payment is an object in the Items array.

LevelFields
BatchIssuerAccountNumber (required), SourceWalletId (required), CustomerBatchId (required), EmailNotification, Items (required)
Each item in ItemsCustomerTransactionId (required), RecipientId (required), Amount (required), SendMethodId (required), Description, Destination (required)
DestinationThe fields that apply to the item's SendMethodId, such as BeneficiaryBankID for a bank transfer or Email and SKU for a prepaid virtual debit card. Send Destination on every item, even as {}. See Payment methods & destinations.

This batch pays a business recipient by bank transfer and an individual recipient with a prepaid virtual debit card. Both recipients already exist, and the bank account is linked to the business recipient; see Accounts, wallets & IDs and Bank accounts & transfers. CustomerBatchId values are shared across all Xtrm accounts. Replace the sample IDs with your own unique values, for example ones that include your account number or a UUID, before you run this in the sandbox.

curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -w "\nHTTP %{http_code}\n" \
  -d '{
  "IssuerAccountNumber": "SPN1111222",
  "SourceWalletId": 122181,
  "CustomerBatchId": "BATCH-REQUESTS-0001",
  "EmailNotification": true,
  "Items": [
    {
      "CustomerTransactionId": "TXN-REQUESTS-0001",
      "RecipientId": "SPN8888777",
      "Amount": 100,
      "Destination": {
        "BeneficiaryBankID": "41953ec32f3e4765a35a902c82bdd995",
        "BeneficiaryBankPaymentMethod": "ACH"
      },
      "SendMethodId": "XTR94500",
      "Description": "TXN-REQUESTS-0001 Q3 Executive Sales Performance Incentive"
    },
    {
      "CustomerTransactionId": "TXN-REQUESTS-0002",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      },
      "SendMethodId": "XTR94503",
      "Description": "TXN-REQUESTS-0002 Q3 Top Performer Contractor Reward"
    }
  ]
}'

Xtrm accepts different batches in parallel. Never have two requests for the same CustomerBatchId in flight at once: wait for the response, or follow A safe retry pattern when you don't get one.

#The 202 Accepted response

Xtrm validates the batch and each item before it responds. When at least one item passes, it answers 202 Accepted and processes the accepted items in the background; when every item is rejected, it answers 422, or 409 if any of them already exists in the batch. The response is plain JSON under a single BatchTransferResponse key. It has no OperationStatus.

Response: 202 Accepted
{
  "BatchTransferResponse": {
    "CustomerBatchId": "BATCH-REQUESTS-0001",
    "Status": "Accepted",
    "ItemsCount": {
      "Total": 2,
      "Accepted": 2,
      "Rejected": 0
    },
    "Accepted": [
      {
        "CustomerTransactionId": "TXN-REQUESTS-0002",
        "Amount": 50.0,
        "Currency": "USD",
        "SendMethodId": "XTR94503",
        "RecipientId": "PAT9999888"
      },
      {
        "CustomerTransactionId": "TXN-REQUESTS-0001",
        "Amount": 100.0,
        "Currency": "USD",
        "SendMethodId": "XTR94500",
        "RecipientId": "SPN8888777"
      }
    ],
    "Rejected": []
  }
}
FieldWhat it holds
CustomerBatchIdYour batch ID, echoed back.
StatusThe outcome of the submission: Accepted (no item rejected), CompletedWithFailures (some items rejected) or Failed (no item accepted). It describes validation and storage only, not payment.
ItemsCountAn object with the Total, Accepted and Rejected item counts. Total is the number of items you sent.
AcceptedThe items taken for processing, in no particular order, each with CustomerTransactionId, Amount, Currency, SendMethodId and RecipientId. Amount is a JSON number with the decimals you sent: 100.00 comes back as 100.00, "51.5" as 51.5, and the 100 in this request as 100.0.
RejectedThe items Xtrm didn't take, each with CustomerTransactionId, Key (a category such as INVALID_FIELD), ErrorCode (an HTTP-style code such as 422), Field and Message.
Key, ErrorCode, MessageReturned when Xtrm refuses the request at the batch level (for example CONFLICT_PROCESSING, FORBIDDEN or LIMIT_EXCEEDED) or can't store the accepted items: the error category, an HTTP-style code and a description. Left out otherwise, so they don't appear in the example. When every item is rejected, they're left out too, and Rejected says why each item was refused. A wrong Content-Type (415) or a token problem (401) returns {"error", "error_message"} instead.

Field is usually Items[i].<field>, with a zero-based index, for example Items[0].Destination.SKU. The index can differ from the item's position in your request, Field can name a related field or be empty, and one item can appear more than once, so match each rejection to your item by its CustomerTransactionId.

A 202 Accepted means Xtrm received the batch and took the items in Accepted for processing. It doesn't mean they were paid, and it isn't proof that each one was stored. Follow each item with the status endpoints. Webhooks can tell you sooner, and the status endpoints confirm each item's final status.

#Check a batch or an item

The two status endpoints are GET requests with no body. You name the batch, and the item, in the path with your CustomerBatchId and CustomerTransactionId. Options go in the query string:

Query parameterEndpointsMeaning
recordsToSkipBatch statusThe number of items to skip. See Pagination.
recordsToTakeBatch statusThe maximum number of items to return.
historyBothtrue fills each item's Attempts with its full attempt history; false or no value leaves it []. Any other value fails with 400.

Query parameter names match in any case. This site writes them in camelCase.

curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-REQUESTS-0001?recordsToSkip=0&recordsToTake=50&history=true" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -w "\nHTTP %{http_code}\n"

The response is the status object itself, with no wrapper and no OperationStatus:

Batch status response, history=true
{
  "CustomerBatchId": "BATCH-REQUESTS-0001",
  "Status": "Completed",
  "Currency": "USD",
  "ItemsCount": 2,
  "Items": [
    {
      "CustomerTransactionId": "TXN-REQUESTS-0001",
      "Status": "Success",
      "RecipientId": "SPN8888777",
      "SendMethodId": "XTR94500",
      "Amount": "100.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-REQUESTS-0002",
      "Status": "Success",
      "RecipientId": "PAT9999888",
      "SendMethodId": "XTR94503",
      "Amount": "50.00",
      "LastUpdatedAt": "2026-06-05T20:49:47.1834547Z",
      "Attempts": [
        {
          "AttemptNo": 1,
          "Result": "Success",
          "ErrorCode": "SUCCESS",
          "CreatedAt": "2026-06-05T20:49:47.1834547Z",
          "CompletedAt": "2026-06-05T20:49:47.1834547Z"
        }
      ]
    }
  ],
  "Pagination": {
    "HasMore": false,
    "NextRecordsToSkip": 0
  }
}

The item status endpoint returns a single item the same way, at the root, and adds its Currency and DeliveryType. A status request that the endpoint refuses returns {"StatusCode": …, "Message": …}, with an ErrorKey for 400, 413 and 422 errors; neither endpoint returns an Errors field. A token or IP problem returns 401 with {"error": …, "error_message": …}, as on every endpoint. A 404 doesn't prove that a batch or payment is missing: when Xtrm can't read it, both endpoints return the same 404 as for an unknown ID, and right after a submit call times out, the item endpoint can return 404 while the original request is still being stored. Repeat the check a few times, at least a minute apart, before you conclude that a payment wasn't stored; see A safe retry pattern. Batch & item statuses explains every Status value.

#How batch payment responses differ

If you also call the envelope endpoints, keep these differences in mind:

  • No envelope, no OperationStatus. There is no Success flag to read. The HTTP status and the body's Status tell you whether Xtrm took the batch, Accepted and Rejected tell you which items it took, and each item's Status tells you how it ended.
  • Your IDs come back. Xtrm echoes CustomerBatchId and CustomerTransactionId, as it stored them, in the submit response, the status responses and the item webhook events (Batch.Item.…), so you can match results to your own records. The batch-level webhook events carry only CustomerBatchId, and a response that refuses the request before Xtrm reads the batch, such as a token error, carries neither.
  • ItemsCount changes shape. It's an object (Total, Accepted, Rejected) in the submit response and a number, the count of items in the batch, in the status response.
  • Amount changes type. You send it as a JSON number, and the submit response echoes it as a number with the decimals you sent (100.00 comes back as 100.00, and 100 as 100.0). The status endpoints return it as a string with 2 decimals: the batch status endpoint with a thousands separator ("1,234.56"), the item endpoint without one ("1234.56"). The item webhook events send it as a JSON number with 2 decimals (1234.56).
  • There are two kinds of ErrorCode. In Rejected, ErrorCode is an HTTP-style code such as 422, with the category in Key. In an item's Attempts, ErrorCode is a named code such as BANKID_INVALID, or SUCCESS for an attempt that worked. Errors lists the codes in Rejected; Error codes on attempts lists the attempt codes.

#The operation envelope

Apart from the batch payment endpoints and the token request, the API uses the operation envelope, with the few exceptions listed below. You use these endpoints to prepare and fund payments. For example, GetCompanyWallets gives you the wallet ID to send as a batch's SourceWalletId, and GetPaymentMethods lists the send methods.

#Request envelope

The body wraps its fields in two objects: a root key named after the operation, and an inner request object.

GetCompanyWallets request body
{
  "GetCompanyWallets": {
    "request": {
      "IssuerAccountNumber": "SPN1111222"
    }
  }
}

Nearly every request includes IssuerAccountNumber, the account number of your company, which starts with SPN. A batch payment carries it at the root of the body; an envelope body carries it inside request. The requests without it are the token request, the eight {} lookups, GetAdvancedContactCompanyType (takes CountryISO2), GetAdvancedContactState (takes CountryCode) and the two batch status endpoints.

Some bodies nest further. FundCompanyWalletUsingCreditCard splits its fields into PaymentDetails, PayerInformation, PayerBillingAddress and CreditCardDetails, and LinkBankBeneficiary uses Beneficiary › BeneficiaryDetails › BeneficiaryInformation and Beneficiary › BankDetails › BeneficiaryBankInformation.

#Names that break the pattern

The wrapper names don't always follow the pattern. Xtrm matches JSON property names regardless of case, but it silently ignores a name it doesn't recognize, so a misspelled wrapper or field is dropped as if you hadn't sent it. Copy each spelling exactly as the endpoint's request example in the API reference shows it, including odd spellings such as IsPublicallyTraded in the advanced profile. Casing doesn't change the match, but this site's samples keep the casing shown in the tables below for consistency.

Inner key Request (capital R). These 25 operations spell the inner key Request instead of request in their samples:

AreaOperations
Bank accountsSearchBankByBIC, SearchBankByNationalID
Bank debitReleaseACHDebitMicrodeposit, VerifyACHDebitMicrodeposit
Business recipientsCreateBeneficiary, UpdateBeneficiary
Currency exchangeGetExchangeRate, BookExchange
FundingFundWalletUsingBankTransfer, FundWalletUsingACHDebit, FundCompanyWalletUsingCreditCard
Gift cards & prepaid cardsGetGiftCardDetails, GetPrepaidCards, GetPrepaidCardDetails
OTP & connectionsGetConnectedStatus
Fees & reportsGetCompanyFees, TransferTaxInformation
Wallet transactionsGetCompanyWalletTransactions, GetCompanyWalletTransactionDetails, GetUserWalletTransactions, GetUserWalletTransactionDetails, GetUserWalletTransactionsByRemitter
WalletsGetUserWallets, UpdateUserWallet, UpdateBeneficiaryCompanyWallet

Root key that differs from the operation name.

OperationRoot key in the request body
CompanyAdvancedProfileAdvancedProfile
CompanyAdvancedProfileStatusAdvancedProfileStatus
GetCompanyAdvancedProfileDetailsAdvancedProfileDetails
GetAdvancedContactCompanyTypeCompanyType
GetAdvancedContactStateAdvancedContactState
GetLinkedCardsGetLinkedCardAccounts
GetDigitalGiftCardsGetGiftCards
GetGiftCardDetailsGetGiftCards
GetPrepaidCardDetailsGetPrepaidCards
ProgramCategoryGetProgramCategory
ProgramTypeGetProgramType
FundCompanyWalletUsingCreditCardFundCompanyWalletUsingCreditCardRequest
FundWalletUsingACHDebitFundWalletUsingACHDebitRequest
GetCompanyWalletTransactionDetailsGetCompanyTransactionDetails
GetUserWalletTransactionDetailsGetUserTransactionDetails
GetConnectedCompanyFundRequestGetConnectedFundRequestDetails

Similar fields, different names. Field names aren't consistent across endpoints either. A wallet ID is SourceWalletId or Destination.WalletId in a batch, but WalletID in envelope requests such as UpdateCompanyWallet and in the GetCompanyWallets response. An individual recipient's account number is RecipientId in a batch item, RecipientUserId in GetLinkedBankAccounts, UserID in GetUserWallets and UserId in GetUserWalletBalance.

#Bodies without an envelope

RequestBody
GetCountry, GetAdvancedContactCountry, GetAdvancedContactJobTitles, GetIdentificationType, GetNAICS, GetPaymentMethods, GetUserPaymentMethods, GetBeneficiaryCompanyPaymentMethodsAn empty JSON object: {}
Token requestForm-encoded fields, not JSON
The batch payment endpointsA flat JSON body, or no body for the status requests. See Batch payment requests.

#Response envelope

A successful response wraps the payload in a …Response object and a …Result object. The result holds the data and an OperationStatus object:

GetCompanyWallets response
{
  "GetCompanyWalletResponse": {
    "CompanyWalletResult": {
      "CompanyWallets": {
        "CompanyWalletDetails": [
          {
            "WalletID": 122181,
            "WalletName": "USD Wallet for Main Company",
            "WalletCurrency": "USD",
            "WalletBalance": 57715.15,
            "WalletType": "Standard",
            "IsBankLinked": false,
            "AllowWalletLinkedBankOverride": false,
            "EntityID": 12345
          }
        ]
      },
      "OperationStatus": {
        "Success": true,
        "Errors": null
      }
    }
  }
}

WalletID comes back as a number. Send it as the same JSON number when you use it as a batch's SourceWalletId, as the batch above does with 122181, and the wallet's currency becomes the currency of the batch.

OperationStatus fieldTypeMeaning
SuccessbooleanWhether the operation succeeded (true) or failed (false).
Errorsarray or nullError messages when the call fails, as strings, or as objects when a bank link needs more fields. On success it's null, [] or [""], depending on the endpoint (see below).

On success, Errors is null, an empty array [] or [""], depending on the endpoint, so decide on OperationStatus.Success and use Errors only to explain a failure. See Errors on a successful call.

Two calls need more than Success: UserWithdrawFund and BeneficiaryCompanyWithdrawFund, which transfer money out of a recipient's wallet with the recipient's one-time password. Their first request, which sends the code, also returns Success: true, with One Time Password sent to user. Please resubmit with One Time Password. in Errors, and moves no money. The transfer is made only when the response has PaymentStatus Completed and a PaymentTransactionId.

#Response wrapper names vary

Many response wrappers don't match the operation name, so take them from each endpoint's response example, or find OperationStatus without hard-coding them, as the helper below does. Some notable cases:

OperationResponse wrappers
GetCompanyWalletsGetCompanyWalletResponse › CompanyWalletResult
GetBeneficiariesGetBeneficiariesResponse › BeneficiaryResult
GetUserWalletBalanceUserWalletBalnceResponse › UserWalletBalanceResult
SearchBankByBICSearchBankbyBICResponse › SearchBankbyBICResult
BookExchangeBookExchangeMethodsResponse › BookExchangeMethodResult
GetExchangeRateGetExchangeRateMethodsResponse › ExchangeRateMethodResult
CreateProgramCreateProgramsResponse › CreateProgramsResult
DeleteBankBeneficiaryDeleteBankBeneficiary › DeleteBankBeneficiaryResult (no Response suffix)
DeleteCardDeleteCard › DeleteCardResult (no Response suffix)

#Responses without the envelope

EndpointWhat comes back
The batch payment endpointsPlain JSON with no OperationStatus. See Batch payment requests.
Token requestA flat token object (access_token, token_type, expires_in, refresh_token, …). No OperationStatus.
GetConnectedCompanyFundRequestPlain text, not JSON: CSV rows, starting with the header row Account Number,Name,Credits,Debits,Currency.

#HTTP status codes

The batch payment endpoints use the HTTP status: submitting a batch returns 202 Accepted when at least one item passes validation, the status endpoints return 200, and Xtrm answers with a 4xx status when it refuses the whole request or rejects every item, and 500 on an internal error. The envelope endpoints answer 200 when the call succeeds, and a 4xx or 500 status with OperationStatus.Success set to false when it fails. A few one-time password steps break that pattern, so check both the HTTP status and OperationStatus.Success; HTTP status codes lists every status and its exceptions.

See Errors when you submit a batch payment for the codes a refused request or a reused CustomerTransactionId gets, and Other endpoints for how the envelope endpoints report failures.

#Data types

#Numbers and booleans as strings

Request values are strings in most envelope bodies, even when they hold numbers or booleans, for example "RecordsToSkip": "1" and "WalletID": "122181". A few envelope fields are sent as real JSON numbers or booleans too:

FieldEndpointsJSON value in the example
EntityIDLinkBankBeneficiary, LinkACHDebitBankBeneficiary, LinkCard, CreateCompanyWallet, CreateBeneficiaryCompanyWallet27044, 27045
EmailNotificationUserWithdrawFund, BeneficiaryCompanyWithdrawFundtrue
AmountFundCompanyWalletUsingCreditCard50

IsClaim (CreateProgram, UpdateProgram) and InvoiceRequired (FundWalletUsingBankTransfer) read like booleans but are strings: send "true" or "false", lowercase and in quotes. Xtrm reads a JSON true in a text field as "True", and only the exact string "true" makes a claim program or asks Xtrm for an invoice. A JSON true passes Xtrm's checks but does neither: the program is saved as not a claim, and no invoice is requested.

A batch payment is different: it sends Amount as a JSON number (100.00), SourceWalletId and Destination.WalletId as integers (122181, 122311) and EmailNotification as a boolean (true). The batch endpoint also accepts these values as strings ("100.00", "122181", "true") and converts them. A value it can't convert doesn't fail the request by itself: Xtrm reads it as empty (0, or false for EmailNotification) and checks that value as usual, so an empty Amount rejects its item and an empty SourceWalletId fails the whole request. Each field in the reference says what happens. We recommend sending the JSON types shown.

The batch's text fields work the other way round. CustomerBatchId, CustomerTransactionId, RecipientId, SendMethodId, Description and the Destination text fields accept a JSON number and store it as text (1001 becomes "1001"), so send IDs as strings to keep them exactly as you store them.

The batch status query parameters are plain integers and booleans in the query string, for example recordsToSkip=0, recordsToTake=50 and history=false.

#Types in responses

Responses mix strings and numbers:

ValueType in responsesExample
Accepted[].Amount in the batch submit responsenumber, with the decimals you sent100.00 (sent as 100.00), 100.0 (sent as 100)
Amount in the batch and item status responsesstring"100.00"; "1,234.56" on the batch endpoint, "1234.56" on the item endpoint
Amount in item webhook eventsnumber, with 2 decimals100.00, 1234.56
ItemsCount in batch payment responsesobject on submit, number on status{"Total": 2, "Accepted": 2, "Rejected": 0}, 2
AttemptNo in item attemptsnumber1
Amount, Fee, TotalAmount on recipient transfers and card fundingstring"4.50", "0.50", "5.00". Card funding and bank transfers return all three with 2 decimals and a thousands separator, as in "1,250.00", so strip separators before you parse them.
Amounts and balances in wallet transaction lists and wallet listsnumber51.5, 57715.15
Balance from GetUserWalletBalancenumber1250.43
Fees from GetCompanyFeesnumber2.50
WalletIDnumber (a string in envelope requests, a number in a batch's SourceWalletId)122181
TransactionID in wallet transaction listsnumber (pass it as a string to the details endpoints)888601

We recommend that your client accept both strings and numbers for amounts and parse them into a decimal type rather than binary floating point.

#Formats

ValueFormatExampleNotes
CurrencyThree-letter ISO 4217 codeUSDA batch payment takes the currency of its source wallet, and the batch responses report it as Currency.
CountryTwo-letter ISO 3166-1 alpha-2 codeUSFields such as BeneficiaryCheckCountryCodeISO2 in a check item, and CountryISO2, Country_Code2 and CountryCode2 elsewhere. See the CountryCode note below. The Country that CheckUserExist and GetPersonalBeneficiaries return is the full country name instead, for example United States of America.
Amount in a batchJSON number100.00An item's Amount must be greater than 0 and at most 9999999999999999.99. A numeric string such as "100.00" is accepted too. Send at most 2 decimal places: Xtrm stores and pays amounts with 2.
Batch and item IDsStrings of 1 to 128 letters, digits and . _ - : @"BATCH-REQUESTS-0001", "TXN-REQUESTS-0001"Required: Xtrm never generates them. Retries & idempotency has the full rules, including reserved prefixes and how case is treated.
Timestamp in a status responseISO 8601, with up to seven fractional digits"2026-06-05T20:49:01.1150192Z", "2026-06-05T20:50:36.2431Z"LastUpdatedAt, CreatedAt and CompletedAt. The values are in UTC. Parse them with or without a trailing Z, and read a value without a time zone as UTC. On the batch status endpoint, LastUpdatedAt is null until processing first updates the item; the item endpoint falls back to the submission time.
ReceivedAt and CompletedAt in a webhook eventM/d/yyyy h:mm:ss tt, whole seconds, no time zone"10/28/2025 3:11:35 AM"The time is UTC, and the value isn't ISO 8601. The webhook's other timestamps are described in Webhooks.
Timestamp in other responsesVaries"2024-08-28T15:03:33.847", "2026-06-05T16:33:26.385963Z", "2026-06-04T00:00:00-04:00"Some have no time zone designator.
Date in a requestMM/DD/YYYY, month first"12/31/2020"Strict for FromDate and ToDate in GetConnectedCompanyFundRequest. RequiredDepositDate and RequiredPaymentDate in FundWalletUsingBankTransfer are US dates in the same format: "06/05/2026" is 5 June 2026. The wallet transaction filters StartUTC and EndUTC take dates in this format too ("01/01/2024"), and both are inclusive: EndUTC covers its whole day.
Date of birthSeparate Day (1–31), Month (1–12) and Year (four digits) strings"08"CreateUser and UpdateUser. The advanced profile takes dates of birth as mm/dd/yyyy.
Card expiryMonth as a numeric string from 1 to 12, year as four digitsLinkCard, FundCompanyWalletUsingCreditCard

Timestamps don't share one format across endpoints, so we recommend an ISO 8601 parser that accepts any number of fractional digits and handles a missing time zone explicitly. Name/value detail arrays, such as PayDirectTransactionDetails, contain display strings like "6/5/2026 1:01:59 PM"; we recommend showing them as they are rather than parsing them.

CountryCode means different things

In GetCountry, CountryCode is the three-letter code (USA) and the two-letter code is in CountryISO2. In GetAdvancedContactCountry and GetAdvancedContactState, CountryCode is the two-letter code (US).

#Pagination

The API pages results in two ways:

Batch statusList endpoints
Where you send itQuery stringA Pagination object in the request body
Parameter namesrecordsToSkip, recordsToTake (camelCase)RecordsToSkip, RecordsToTake
Parameter typeIntegersStrings
What comes backPagination: HasMore, NextRecordsToSkipPaginationTotal: RecordsTotal, RecordsToSkip, RecordsToTake
How to get the next pageSend NextRecordsToSkip as recordsToSkipAdd 1 to RecordsToSkip, a page number

#Items in a batch

Get the status of a batch payment pages through the batch's items:

  • Start at 0. Send recordsToSkip=0 for the first page, as the example request does.
  • Page size. recordsToTake sets the number of items per page, up to your account's maximum. Without it, you get up to that maximum; a larger value fails with 422 LIMIT_EXCEEDED, and the message states the maximum. A page that would exceed the response-size limit fails with 413 LIMIT_EXCEEDED; ask for fewer items or leave out history.
  • Next page. While Pagination.HasMore is true, call again with Pagination.NextRecordsToSkip as recordsToSkip and the same recordsToTake. On the last page, NextRecordsToSkip is 0. ItemsCount gives the number of items stored in the batch.
  • History. Add history=true to include every attempt for each item; without it, Attempts is an empty array.

The item status endpoint returns a single item, so it takes only history. Create a batch payment walks through the whole flow.

#List endpoints

These envelope endpoints take a Pagination object inside the request: SearchBankByBIC, SearchBankByNationalID, CheckBeneficiaryExist, GetBeneficiaries, GetEntities, GetPersonalBeneficiaries, GetPrograms, ProgramCategory, ProgramType, GetCompanyWalletTransactions, GetUserWalletTransactions, GetUserWalletTransactionsByRemitter and GetConnectedCompanyFundRequest.

FieldInTypeMeaning
Pagination.RecordsToSkipRequeststringThe page number, starting at "1". For page 2, send "2" with the same RecordsToTake. "0" fails with 400.
Pagination.RecordsToTakeRequeststringMaximum number of records per page, for example "25".
PaginationTotal.RecordsTotalResponsenumberTotal number of records available.
PaginationTotal.RecordsToSkipResponsenumberThe page number of this page.
PaginationTotal.RecordsToTakeResponsenumberPage size requested.

PaginationTotal sits next to OperationStatus in the result:

GetBeneficiaries response (trimmed to one record)
{
  "GetBeneficiariesResponse": {
    "BeneficiaryResult": {
      "Beneficiaries": {
        "BeneficiaryDetail": [
          {
            "BeneficiaryCompanyName": "Acme Corporation",
            "BeneficiaryContact": "Marcus Chen",
            "PartnerAccountManager": "Sam Rivera",
            "BeneficiaryID": "SPN9999888",
            "BeneficiarySalesforceId": "0018000000abcde",
            "OtherPartnerID": "Gold",
            "Region": "CA",
            "BeneficiaryEmail": "[email protected]",
            "BeneficiaryAccountIdentityLevel": "Basic"
          }
        ]
      },
      "OperationStatus": {
        "Success": true,
        "Errors": [""]
      },
      "PaginationTotal": {
        "RecordsToSkip": 1,
        "RecordsToTake": 25,
        "RecordsTotal": 2
      }
    }
  }
}

Things to know:

  • Start at "1". RecordsToSkip is a page number, not a record offset: "1" is the first page, and "0" fails with 400. The bank searches SearchBankByNationalID and SearchBankByBIC work the same way: send "1" for the first page, "2" for the second, and so on.
  • Strings in, numbers out. The request sends RecordsToSkip and RecordsToTake as strings; PaginationTotal returns numbers.
  • To read every page, add 1 to RecordsToSkip on each call, with the same RecordsToTake, until you have PaginationTotal.RecordsTotal records.
  • Pages aren't a snapshot. Each list has its own sort order, and records added or changed while you page can shift later pages, so a record can repeat or be skipped. De-duplicate on the record's ID.
  • Not every list returns totals. CheckBeneficiaryExist makes Pagination optional (send both fields if you send it) and returns no PaginationTotal; without Pagination, it returns the first 30 matches. Read pages until one has fewer records than RecordsToTake. GetConnectedCompanyFundRequest returns CSV, so it has no PaginationTotal either.
  • Page size. GetBeneficiaries, CheckBeneficiaryExist, GetPersonalBeneficiaries and ProgramCategory take a RecordsToTake of at most "100". The wallet transaction lists have no maximum.

#A reusable request helper

This helper wraps the envelope conventions above. It sends a JSON POST with the recommended headers, fails on a non-2xx status, finds OperationStatus wherever the wrappers put it, and fails unless Success is true. On success it returns the parsed response. The example call lists your company's wallets with GetCompanyWallets, which is where a batch's SourceWalletId comes from.

Use it for the envelope endpoints only. The token request and GetConnectedCompanyFundRequest return different shapes, and the batch payment endpoints are covered in the note after the code. For UserWithdrawFund and BeneficiaryCompanyWithdrawFund, also check the result's PaymentStatus: the helper returns their first request, which only sends the one-time password, as a success. The cURL version does a quick text match on the response; for anything more, parse the JSON with a tool such as jq. The Java version is a complete class: save it as XtrmClient.java and add jackson-databind 2.10 or later, since the JDK has no JSON parser.

XTRM_API="https://xapisandbox.xtrm.com/API/v4"

# Sends a JSON request and prints the response. Fails when the HTTP status
# is not 2xx or OperationStatus.Success is not true.
call_xtrm() {
  local endpoint="$1" body="$2" response status
  # -w appends the HTTP status code on its own line after the body.
  response=$(curl -sS -w '\n%{http_code}' -X POST "$XTRM_API$endpoint" \
    -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "$body") || { echo "$endpoint: request failed" >&2; return 1; }
  status=${response##*$'\n'}
  response=${response%$'\n'*}
  if [[ $status != 2?? ]]; then
    echo "$endpoint: HTTP $status: $response" >&2
    return 1
  fi
  if ! grep -Eq '"Success"[[:space:]]*:[[:space:]]*true' <<<"$response"; then
    echo "$endpoint: operation failed: $response" >&2
    return 1
  fi
  echo "$response"
}

call_xtrm "/Wallet/GetCompanyWallets" '{"GetCompanyWallets": {"request": {"IssuerAccountNumber": "SPN1111222"}}}'

Batch payment responses need their own checks

Don't submit a batch payment through this helper: the response has no OperationStatus, so the helper would report a failure even though Xtrm accepted the batch. For a batch you submit, check for a 2xx status (202 Accepted), then read the body's Status, ItemsCount and the Rejected list. For the status endpoints, which are GET requests, read the batch's Status and each item's Status, and page with Pagination. Create a batch payment walks through both.

#Next steps