API reference

Batch payments

A batch payment pays many recipients in one request, by wallet, bank, card, gift card or check. Each batch is one request to POST /Fund/BatchTransfer, and each payment in it is an item in Items.

Each item has its own recipient, amount and payment method, so one batch can pay individual recipients (PAT…) and business recipients (SPN…) through different methods at once. Every recipient must already have an Xtrm account: create new ones with CreateUser or CreateBeneficiary before you submit the batch. Every item is paid from the same wallet of your company (SourceWalletId), in that wallet's currency.

How a batch is processed. Processing is asynchronous:

  1. Submit. You send the batch with Create a batch payment. Xtrm checks the request and the fields of each item, stores the items that pass and answers 202, listing the accepted and the rejected items. If no item passes, nothing is stored and the answer is a 422 (or a 409 for items that already exist). Xtrm doesn't check your balance or move any money at this point.
  2. Validation. In the background, Xtrm checks each stored payment against the accounts involved: the recipient, the wallet, the bank account, card token or SKU, and whether the method fits the recipient. A payment that fails here ends Failed, and nothing is debited.
  3. Wallet credit. Xtrm debits your source wallet for the payment's Amount plus its fee and credits the recipient's Xtrm wallet with the full Amount. Payments from one source wallet are processed one at a time. Wallet payments (XTR94502, XTR94504) end Success here.
  4. Delivery. For bank, prepaid card, gift card, check and Rapid Transfer payments, Xtrm then delivers the money from the recipient's wallet to the destination. The payment ends Success when the provider accepts it.

Follow a batch with the batch and payment status endpoints, or with webhooks.

Wallet first. Every payment is credited to the recipient's Xtrm wallet before it's delivered. Success means the provider accepted the payment, not that the funds have settled. Bank, card, check, gift card and prepaid payments pass through RetainedInWallet briefly while Xtrm delivers them, and move on to Success when the delivery goes through, so don't act on that status while the batch is still Processing. If a payment is still RetainedInWallet once the batch status is final, the delivery didn't go through: the money stays in the recipient's Xtrm wallet, so treat it like a wallet payment: the recipient transfers it out, or, if they're connected to your company, you request the transfer for them with their one-time password. You can't retry or resubmit it, and the fee isn't refunded. See Wallet-first delivery and When a payment stays RetainedInWallet.

Recipient wallets and banks. Without Destination.WalletId, Xtrm credits the recipient's oldest active Standard wallet in the batch's currency, and creates a wallet named Wallet - <currency code> when the recipient has no wallet in that currency. A bank payment to an individual recipient always needs BeneficiaryBankID. For a business recipient sent with a WalletId, the bank linked to that wallet can be used instead; see BeneficiaryBankID.

Your own IDs. Every batch needs a CustomerBatchId and every payment a CustomerTransactionId; Xtrm never generates them, and echoes them in every response and webhook. The wallet transaction calls don't return them, so start each item's Description with its CustomerTransactionId to match the payment to its wallet transactions. CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID. A CustomerTransactionId repeated within one request is rejected with DUPLICATE_ITEM_IN_REQUEST. Resending it under its original CustomerBatchId either retries it (if it failed) or returns CONFLICT_DUPLICATE_ITEM. Under a different CustomerBatchId it is a new payment, so never reuse IDs across batches. Xtrm treats IDs that differ only in case as the same ID (BATCH-1 and batch-1 are the same batch), so don't use two IDs that differ only in case.

Limits and access. Each account has a maximum number of items per batch, and Xtrm has one maximum request size for every account. A batch with too many items fails with 422 LIMIT_EXCEEDED, and the error message gives your limit as MaxAllowed. A body over the size limit fails with 413 PAYLOAD_TOO_LARGE. Every request needs a bearer token that is allowed to act for IssuerAccountNumber.

Track results. Xtrm can also notify your server with webhooks as payments are processed. The status endpoints below return the same information on demand, including each payment's attempt history.

To learn more, read How batch payments work, Batch and payment statuses, Webhooks and Retries & idempotency, or follow Create a batch payment step by step.

#Create a batch payment

POST/API/v4/Fund/BatchTransfer

Submits a batch payment: one request that pays every item in Items from your company's wallet SourceWalletId. Processing is asynchronous, so the response tells you which items Xtrm accepted for processing, not whether they were paid. Each item pays an existing Xtrm account, so create new recipients with CreateUser or CreateBeneficiary before you submit the batch.

What Xtrm checks before it responds. The body must be JSON with a supported Content-Type (send application/json), and the token must be allowed to act for IssuerAccountNumber. Xtrm then checks the batch (IssuerAccountNumber, CustomerBatchId, the number of items, and that SourceWalletId is an active wallet of IssuerAccountNumber) and the fields of each item, including the Destination fields its SendMethodId needs. It doesn't check the recipient account, the recipient wallet, bank account, card token or SKU, or your balance at this point: those checks run during processing.

Responses.

  • 202 with Status Accepted: every item was accepted and is listed in Accepted.
  • 202 with Status CompletedWithFailures: some items were accepted and are listed in Accepted. The others are listed in Rejected, each with a Key, Field and Message, and weren't stored. Here CompletedWithFailures only means that some items were rejected.
  • 422 with Status Failed, or 409 when any rejection is CONFLICT_DUPLICATE_ITEM: every item was rejected, nothing was stored, and Rejected lists the items.
  • 400, 401, 403, 409, 413 or 422 for a problem with the whole request, such as an invalid IssuerAccountNumber, CustomerBatchId or SourceWalletId, a CustomerBatchId that is already in use, or too many items. The body has Status Failed and a top-level Key and Message, and nothing is stored. Token errors (401) and a missing or wrong Content-Type (415) return an error and error_message body instead. See the error table below.
  • 202 with Status Failed and Key TEMPORARY_ERROR: the items passed validation but couldn't be stored, so this call stored nothing. A 500 with TEMPORARY_ERROR is an unexpected error. In both cases, follow A safe retry pattern.

A 202 doesn't prove that every item in Accepted was stored or that it will be paid, and a 409 CONFLICT_PROCESSING on a resend doesn't prove that every item was stored: Xtrm stores a batch of more than 500 items in groups of 500, and a group that fails doesn't undo the groups before it. Confirm storage with Get the status of a batch payment and Get the status of a payment in a batch, as described in A safe retry pattern.

Processing. In the background, Xtrm validates each stored payment against the accounts involved, debits your source wallet for the payment's Amount plus its fee, credits the recipient's wallet with the full Amount, and then delivers bank, prepaid card, gift card, check and Rapid Transfer payments to their destination. The outcome of each step shows in the payment's status, its attempts and webhooks.

Field types. Send each field with the type shown below. SourceWalletId, Amount, EmailNotification and Destination.WalletId also accept the value as a string ("122181", "100.00", "true"), and the text fields accept a JSON number and store it as text (1001 becomes "1001"), so send IDs as strings. A value Xtrm can't convert is read as empty, as each field explains. You don't send a currency: every item is paid in the currency of SourceWalletId.

Payment methods and Destination fields. Set SendMethodId on each item; one batch can mix methods. Destination is required on every item: for a wallet payment without a WalletId, send "Destination": {}. Destination.WalletId works with every method and chooses the recipient wallet that Xtrm credits first. Fields that don't belong to the item's method are discarded.

  • Bank (XTR94500): pays a bank account linked to the recipient, individual or business. Send BeneficiaryBankID, WalletId or both; an item with neither is rejected. An individual recipient always needs BeneficiaryBankID. For a business recipient sent with a WalletId, the bank linked to that wallet can apply; see BeneficiaryBankID. Optional: BeneficiaryBankPaymentMethod.
  • Individual wallet (XTR94502): credits an individual recipient's (PAT…) Xtrm wallet. Optional: WalletId.
  • Business wallet (XTR94504): credits a business recipient's (SPN…) Xtrm wallet. Optional: WalletId.
  • Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505): individual recipients only. The card's credentials are emailed to Email. Required: Email, SKU.
  • Rapid Transfer (XTR94508): pushes the money to a US card linked to the recipient as a transfer card. The batch must be in USD. Required: CardToken.
  • Physical check (XTR94507): mails a check to a US address. The source wallet must be in USD; otherwise the item is rejected with CURRENCY_MISMATCH. Required: BeneficiaryCheckName, BeneficiaryCheckAddress1, BeneficiaryCheckCity, BeneficiaryCheckState, BeneficiaryCheckPostalCode, BeneficiaryCheckCountryCodeISO2, BeneficiaryCheckMemo, BeneficiaryCheckReference. Optional: BeneficiaryCheckAddress2.

To choose a method, see Payment methods & destinations.

Duplicates and retries. A CustomerBatchId and a CustomerTransactionId together identify one payment, and Xtrm stores each pair at most once.

  • The same CustomerTransactionId twice in one request: Xtrm rejects every copy with DUPLICATE_ITEM_IN_REQUEST and processes none of them.
  • The same CustomerBatchId and CustomerTransactionId in a later request: if the stored payment is Failed, Xtrm re-queues it as a new attempt with the values you sent. Otherwise that item comes back as CONFLICT_DUPLICATE_ITEM and nothing changes. If no payment in the batch is Failed, Xtrm refuses the whole request with 409 CONFLICT_PROCESSING.
  • A CustomerTransactionId already used in a different batch: Xtrm accepts it as a new payment and pays it. Never reuse an ID for a different payment.
  • A new CustomerTransactionId under an existing CustomerBatchId: added only while the batch has a Failed payment; otherwise the whole request gets 409 CONFLICT_PROCESSING. Put new payments in a new batch.
  • Items rejected at submission were never stored. Submit them again in a new batch with a new CustomerBatchId (they can keep their CustomerTransactionId values), unless nothing of the original batch was stored or it has a Failed payment.

A retry replaces the whole stored item with the values you send, so send every field again: a Destination field you leave out becomes empty. Xtrm doesn't stop you from changing RecipientId, SendMethodId, SourceWalletId or IssuerAccountNumber on a retry, so keep them the same: a different recipient or method is a new payment with a new CustomerTransactionId. After a failure when Xtrm debits your wallet (SEND_LIMIT_EXCEEDED, INSUFFICIENT_BALANCE, SENDMETHODID_NOT_FOUND, WALLET_AUTO_CREATE_FAILED, SEND_FAILED or TEMPORARY_ERROR), a retry keeps the destination Xtrm resolved the first time, so a corrected BeneficiaryBankID or CardToken has no effect. Before you retry a Failed payment whose latest attempt is TEMPORARY_ERROR, check with Xtrm support: the money may already have moved. You can't retry or resubmit a payment that stays RetainedInWallet once the batch status is final: the money has already left your wallet and is in the recipient's Xtrm wallet, and the fee isn't refunded. See When a payment stays RetainedInWallet for how the money reaches the recipient.

To follow processing, use webhooks, Get the status of a batch payment or Get the status of a payment in a batch. For a walkthrough, see Create a batch payment.

Note

202 means Xtrm accepted the items listed in Accepted for processing, not that they were stored or paid. Confirm them with the status endpoints, then follow each payment there or with webhooks.

Note

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.

Body parameters

  • IssuerAccountNumberstringRequired

    Your company's Xtrm account number (SPN…), for example SPN1111222: the account that owns the source wallet. At most 20 characters. The token must be allowed to act for this account; otherwise the request fails with 401 (Key Unauthorized). A missing value, or one that doesn't start with SPN, fails with 422 INVALID_FIELD.

  • SourceWalletIdintegerRequired

    The ID of your company's wallet that funds the batch, as an integer, for example 122181: the WalletID that GetCompanyWallets returns. A numeric string such as "122181" works too. Every item is paid in this wallet's currency, so you don't send a currency.

    It must be an active wallet of IssuerAccountNumber itself, in an active currency; otherwise the request fails with 403 (FORBIDDEN). A wallet that another company shares with you doesn't qualify. A missing, zero or negative value, or one that isn't a whole number (such as "abc" or 122181.0), fails the whole request with 422 INVALID_FIELD and Invalid source wallet id.

    Xtrm doesn't check the balance when you submit the batch. Each payment is debited separately when it's processed, for its Amount plus its fee. A payment the wallet can't cover then fails with INSUFFICIENT_BALANCE, and later, smaller payments can still go through. Fund the wallet before you submit.

  • CustomerBatchIdstringRequired

    Your ID for the batch. Required: Xtrm never generates one. 1 to 128 characters from A-Z, a-z, 0-9, ., _, -, : and @, not starting with cb_. A missing or invalid value fails the whole request with 422 INVALID_FIELD.

    CustomerBatchId values are shared across all Xtrm accounts, so make yours unique, for example by including your account number or a UUID. An ID that is already in use, with no Failed payment, returns 409 CONFLICT_PROCESSING. Xtrm trims spaces and removes -- and @@ before it stores the ID, so don't use those sequences, and use the ID exactly as the response echoes it. Xtrm treats IDs that differ only in case as the same ID (BATCH-1 and batch-1 are the same batch), so don't use two IDs that differ only in case. To reuse an ID, see duplicates and retries.

  • EmailNotificationbooleanOptional

    true to have Xtrm email each recipient a payment-received message at their own address when their wallet is credited, for every payment method. Defaults to false. It doesn't control how card credentials are delivered: prepaid and gift card credentials always go to Destination.Email.

    The strings "true" and "false" work too, in any case. Any other string, such as "yes" or "1", is read as false without an error, so send a real boolean.

  • Itemsobject[]Required

    The payments in the batch, one object per item. Items can have different recipients and payment methods. Send at least one item and no more than your account's limit: an empty or missing Items fails with 422 INVALID_FIELD, and too many items fail with 422 LIMIT_EXCEEDED, whose Message ends with your limit (MaxAllowed: N).

    Child parameters6
    • CustomerTransactionIdstringRequired

      Your ID for this payment. Required: Xtrm never generates one. 1 to 128 characters from A-Z, a-z, 0-9, ., _, -, : and @, not starting with ct_. A missing or invalid value rejects the item with INVALID_FIELD (Customer transaction id is required. when it's missing). Like CustomerBatchId, it's stored and echoed without spaces at either end and without -- or @@.

      Use each value once per request: repeated values are all rejected with DUPLICATE_ITEM_IN_REQUEST. Resending it under its original CustomerBatchId retries the payment if it failed, or returns CONFLICT_DUPLICATE_ITEM. Under a different CustomerBatchId, the same value is a new payment and is paid again. See duplicates and retries.

    • RecipientIdstringRequired

      The recipient's Xtrm account number: an individual recipient (PAT…) or a business recipient (SPN…), for example PAT9999888 or SPN8888777. One batch can pay both. At most 20 characters, and not your own IssuerAccountNumber: such an item is rejected with INVALID_FIELD and From Account no and To Account no cannot be same. To move money between your own wallets, see Move money between your own wallets. XTR94502 needs a PAT… account and XTR94504 an SPN… account, or the item is rejected. Other methods that don't fit the account type fail during processing with SENDMETHODID_NOT_FOUND.

      During processing, the account must exist in status A (active), NC (email not verified) or EV (pending approval); otherwise the payment fails with RECIPIENT_NOT_FOUND. Create a new recipient with CreateUser or CreateBeneficiary before you submit the batch: the new account can be paid right away. Xtrm pays any eligible account number you send, so double-check it. You don't need a connection to the account, and a batch never creates an account or a connection; see Who you can pay.

    • AmountnumberRequired

      The amount to pay, as a JSON number in the batch's currency, for example 100.00. A numeric string such as "100.00" works too. Greater than 0 and at most 9999999999999999.99. A missing amount, or one that isn't a number (for example "abc", "" or null), is read as 0 and rejects the item with Amount must be greater than zero. Send at most 2 decimal places: Xtrm stores and pays amounts with 2. The recipient receives the full Amount, and the payment's fee is charged to your source wallet on top.

    • SendMethodIdstringRequired

      How the payment is delivered: XTR94500 (bank), XTR94502 (individual recipient's wallet), XTR94504 (business recipient's wallet), XTR94503 (prepaid virtual debit card), XTR94505 (digital gift card), XTR94508 (Rapid Transfer) or XTR94507 (physical check). Send the value exactly as shown, in upper case; any other value rejects the item. The method decides which Destination fields apply; see the payment methods. GetPaymentMethods lists the method IDs.

      Allowed values: XTR94500, XTR94502, XTR94503, XTR94504, XTR94505, XTR94507, XTR94508.

    • DescriptionstringOptional

      Optional, up to 1,024 characters. Xtrm removes some character sequences, such as --, and HTML-encodes the text before it checks the length, so an & counts as 5 characters.

      Xtrm copies it to the wallet transactions the payment creates: the debit in your source wallet and the credit in the recipient's wallet, where the recipient sees it. Start it with the payment's CustomerTransactionId, as the example does, so you can find the payment's debit with SearchParam in GetCompanyWalletTransactions. See Track & reconcile payments.

    • DestinationobjectRequired

      Where and how the payment is delivered. Required on every item, whatever the method: a missing or null Destination, or one that isn't an object, rejects the item with Destination is required. For a wallet payment without a WalletId, send {}. Which fields apply, and which of them are required, depends on SendMethodId; fields that don't apply to the method are discarded.

      Child parameters15
      • BeneficiaryBankIDstring

        Bank (XTR94500). The ID of a bank account linked to the recipient: the 32-character BeneficiaryId that LinkBankBeneficiary returns and GetLinkedBankAccounts lists. At most 40 characters. A bank payment needs BeneficiaryBankID, WalletId or both; with neither, the item is rejected with Beneficiary bank id or wallet id is required..

        • Individual recipient: always send it. Without it, the payment fails during processing with BENEFICIARY_BANKID_REQUIRED.
        • Business recipient without WalletId: always send it.
        • Business recipient with WalletId: the wallet's AllowWalletLinkedBankOverride flag, from GetBeneficiaryWallets, decides. When it's false, Xtrm always pays the bank linked to the wallet, and it replaces any bank you send. When it's true, Xtrm pays the bank you send, or the wallet's linked bank if you leave it out. If the wallet has no linked bank where one is needed, the payment fails with DEFAULT_BANK_NOT_FOUND.

        During processing, before any money moves, the bank must be pending or approved and linked to the recipient; otherwise the payment fails with BANKID_INVALID. This also applies when the wallet's linked bank was deleted. A bank the bank provider doesn't recognize fails with BANK_NOT_FOUND.

      • BeneficiaryBankPaymentMethodstringOptional

        Bank (XTR94500), optional. The rail: send exactly ACH, WIRE or RTP (any case); other names are rejected when you submit the batch. Without it, Xtrm uses the bank account's primary rail. A rail that doesn't fit the bank's rail or Xtrm's RTP settings fails during processing with INVALID_PAYMENTMETHOD. Some rail problems show up only after the wallet credit, as Invalid payment method, and the payment stays RetainedInWallet. A linked bank account's PaymentMethods in GetLinkedBankAccounts are a guide to its rails, not a promise that a rail works.

      • WalletIdintegerOptional

        Any method, optional. The ID of the recipient's wallet to credit, as an integer, for example 122311: the ID that GetBeneficiaryWallets returns. A numeric string such as "122311" works too, and a value that isn't a whole number is read as no WalletId. It can't be your SourceWalletId; that rejects the item. During processing, it must be an active wallet of the recipient in the batch's currency; otherwise the payment fails with INVALID_BENEFICIARY_WALLET before any money moves.

        If you leave it out, Xtrm credits the recipient's oldest active Standard wallet in the batch's currency, not the wallet marked as default. If the recipient has no wallet in that currency, Xtrm creates one named Wallet - <currency code>, for example Wallet - EUR. If its only wallets in that currency are of another type, the payment fails with WALLET_AUTO_CREATE_FAILED.

        On a bank payment to a business recipient, WalletId also brings in the bank linked to that wallet; see BeneficiaryBankID.

      • Emailstring

        Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505), required. A valid email address. The card provider emails the card's credentials to this address, whatever EmailNotification says. No API returns or resends the credentials, so check the address before you submit.

      • SKUstring

        Prepaid virtual debit card (XTR94503) and digital gift card (XTR94505), required, at most 20 characters. The catalog code of the card: from GetPrepaidCards for XTR94503, or GetDigitalGiftCards for XTR94505. List cards in the currency of SourceWalletId.

        During processing, before any money moves:

        • Gift card: the SKU must be in Xtrm's catalog (SKU_NOT_FOUND otherwise), and its currency must be the batch's currency (CURRENCY_MISMATCH otherwise).
        • Prepaid card: Xtrm must offer prepaid cards in the batch's currency (CURRENCY_INVALID otherwise), and the SKU must be one of them (SKU_NOT_FOUND otherwise).
        • Both: a fixed-value card needs an Amount equal to its face value, and a variable-value card an Amount between its minimum and maximum (INVALID_CARD_AMOUNT otherwise).

        Don't rely on the prepaid card bought being the SKU you send: the current release buys the first prepaid card available in the batch's currency.

      • CardTokenstring

        Rapid Transfer (XTR94508), required. The CardToken of a card linked to the recipient's account as a transfer card, from GetLinkedCards; only US cards can be linked as transfer cards. A CardToken is a 15-character string of digits and capital letters A to F, for example EC1B22028C5B488: send it exactly as GetLinkedCards returns it. During processing, before any money moves, the batch must be in USD (CURRENCY_MISMATCH otherwise), and the token must be an active transfer card of the recipient (TOKEN_NOT_FOUND otherwise, for example for an identity card, a deleted card or another account's card). For a business recipient, the card must be linked to the company's own account.

      • BeneficiaryCheckNamestring

        Physical check (XTR94507), required. The name printed on the check. Xtrm accepts any text here and doesn't compare it with the name on the recipient's account.

      • BeneficiaryCheckAddress1string

        Physical check (XTR94507), required. The street address the check is mailed to.

      • BeneficiaryCheckAddress2stringOptional

        Physical check (XTR94507), optional. A second address line, such as a suite or apartment.

      • BeneficiaryCheckCitystring

        Physical check (XTR94507), required. The city the check is mailed to.

      • BeneficiaryCheckStatestring

        Physical check (XTR94507), required, at most 50 characters (the error message for a longer value says 30). The state the check is mailed to, for example CA.

      • BeneficiaryCheckPostalCodestring

        Physical check (XTR94507), required, at most 30 characters. The ZIP code the check is mailed to.

      • BeneficiaryCheckCountryCodeISO2string

        Physical check (XTR94507), required, at most 2 characters. The country code of the mailing address. Checks are mailed in the US only: any value other than US passes submission but fails during processing with COUNTRY_UNSUPPORTED.

      • BeneficiaryCheckMemostring

        Physical check (XTR94507), required, at most 150 characters. The check memo.

      • BeneficiaryCheckReferencestring

        Physical check (XTR94507), required, at most 75 characters. Your reference for the check, such as an invoice number.

Response fields

  • BatchTransferResponseobject

    The result of the submission. Error responses use the same wrapper, except token errors (401) and a missing or wrong Content-Type (415).

    Child parameters8
    • CustomerBatchIdstring

      The CustomerBatchId as Xtrm stored it. Use it with the status endpoints. null when the request was refused before the batch was read, for example on a 400 or when the token can't act for IssuerAccountNumber.

    • Statusstring

      Accepted (every item accepted), CompletedWithFailures (some items rejected) or Failed (nothing accepted, or the accepted items couldn't be stored). It describes the submission only, never the payments: get those from the status endpoints or webhooks.

    • Keystring

      The error key when the whole request fails, for example INVALID_FIELD, CONFLICT_PROCESSING, FORBIDDEN or TEMPORARY_ERROR. Left out when there's no request-level error, including when every item is rejected (see Rejected).

    • ErrorCodeinteger

      The HTTP-style code that goes with Key, for example 422. Left out when there's no request-level error.

    • Messagestring

      A human-readable explanation that goes with Key. Left out when there's no request-level error. Some messages start with a space.

    • ItemsCountobject

      How many items the request had and how many were accepted and rejected. null when the request was refused before the items were read.

      Child parameters3
      • Totalinteger

        The number of items in the request.

      • Acceptedinteger

        The number of items this request accepted, that is, the items listed in Accepted. Confirm storage with the status endpoints.

      • Rejectedinteger

        Total minus Accepted.

    • Acceptedobject[]

      The items this request accepted for processing, in no particular order. A 202 doesn't prove that every listed item was stored; confirm with the status endpoints.

      Child parameters5
      • CustomerTransactionIdstring

        The item ID as Xtrm stored it.

      • Amountnumber

        The item amount, as a JSON number with the decimals you sent: 100.00 comes back as 100.00, "51.5" as 51.5, and 100 as 100.0. Compare it as a number, not as text.

      • Currencystring

        The batch's currency, which is the currency of SourceWalletId, for example USD.

      • SendMethodIdstring

        The item's payment method, for example XTR94500.

      • RecipientIdstring

        The item's recipient.

    • Rejectedobject[]

      The items that weren't stored, each with the reason. Empty when the whole request was refused. One item can appear more than once. To send rejected items again, see duplicates and retries.

      Child parameters5
      • CustomerTransactionIdstring

        The ID of the rejected item.

      • Keystring

        The error key, for example INVALID_FIELD, DUPLICATE_ITEM_IN_REQUEST, CONFLICT_DUPLICATE_ITEM, CURRENCY_MISMATCH or TEMPORARY_ERROR. See the error table below.

      • ErrorCodeinteger

        The HTTP-style code for Key: 422, 409 for CONFLICT_DUPLICATE_ITEM, or 500 for TEMPORARY_ERROR.

      • Fieldstring

        The path of the field that failed, as Items[i].<path>, for example Items[0].Destination.SKU. Match rejected items by CustomerTransactionId, not by the index: i can skip items that were removed as duplicates, some errors name a related field (a bad BeneficiaryBankPaymentMethod reports Items[i].Destination.BeneficiaryBankPaymentMethodType), and a check sent from a non-USD wallet reports "".

      • Messagestring

        A human-readable explanation of why the item was rejected.

#Errors

CodeMessageMeaning
invalid_media_type415 · Unsupported media typeThe Content-Type is missing or isn't a supported media type. Send application/json. The body is {"error": "invalid_media_type", "error_message": …}, and nothing is stored.
invalid_authorization401 · Not authorizedThe Authorization header is missing, the token is unrecognized or revoked, or the call comes from an IP address your company doesn't allow. Token errors have an error and error_message body.
invalid_authentication_type401 · Wrong schemeThe Authorization header doesn't use the Bearer scheme.
invalid_credentials401 · Missing credentialsThe bearer token is empty.
invalid_token401 · Token expiredThe token has expired. Get a new token and resend.
BAD_REQUEST400 · Bad requestThe body is empty or isn't valid JSON. Nothing is stored.
Unauthorized401 · Not authorized for the accountThe token can't act for IssuerAccountNumber. Nothing is stored.
INVALID_FIELD422 · Invalid fieldA batch field is missing or invalid (IssuerAccountNumber, CustomerBatchId, SourceWalletId or an empty Items), and nothing is stored. In Rejected, an item field failed; Field names it.
PAYLOAD_TOO_LARGE413 · Payload too largeThe request's Content-Length is over Xtrm's request-size limit, which is the same for every account. Nothing is stored. Split the items into smaller batches, each with a new CustomerBatchId.
LIMIT_EXCEEDED422 · Limit exceededMore items than your account's limit; Message ends with MaxAllowed: N. Nothing is stored. Split the payments into several batches.
CONFLICT_PROCESSING409 · CustomerBatchId in useThe CustomerBatchId is already in use, in any account, and has no Failed payment. Nothing is stored. If it's your batch, follow it with the status endpoints; put new payments in a new batch.
FORBIDDEN403 · ForbiddenSourceWalletId isn't an active wallet of IssuerAccountNumber. Nothing is stored.
DUPLICATE_ITEM_IN_REQUEST422 · In RejectedThe same CustomerTransactionId appears more than once in the request. Every copy is rejected.
CONFLICT_DUPLICATE_ITEM409 · In RejectedThe item is already stored in this batch with a status other than Failed. After a resend, this means your earlier request stored it: follow the payment.
CURRENCY_MISMATCH422 · In RejectedA check item (XTR94507) sent from a wallet that isn't in USD.
TEMPORARY_ERROR500 · Temporary errorXtrm couldn't store the item (in Rejected) or the request (202 or 500 with Status Failed). Confirm what was stored with the status endpoints before you resend; see A safe retry pattern.

Related: Get the status of a batch · Get the status of a payment in a batch · List company wallets · List a recipient's wallets · List a recipient's linked bank accounts · List a recipient's linked cards · List prepaid cards · List digital gift cards · List payment methods for paying recipients

#Get the status of a batch

GET/API/v4/Fund/BatchTransfer/{CustomerBatchId}

Returns a batch's overall status and one page of its payments, each with its current status. Use it to follow a batch you created with Create a batch payment, to reconcile results, or to find the payments that need attention.

Batch status. Xtrm computes Status each time you ask:

  • Processing: at least one payment is still in progress, including one whose delivery to the destination is still under way.
  • Completed: every payment ended Success.
  • CompletedWithFailures: nothing is in progress, and some payments didn't succeed.
  • Failed: nothing is in progress, and every payment failed.

Accepted never appears here, and items rejected at submission aren't counted. A batch status that looks final can still change: a resubmitted Failed payment reopens the batch, and while some payments are still being validated the batch can briefly read Failed or CompletedWithFailures before it returns to Processing.

Payment status.

  • Accepted: stored, not picked up yet.
  • Processing: being validated.
  • Verified: passed validation, waiting for the wallet credit. Only this endpoint shows Verified; the payment status endpoint shows Processing.
  • Success: final. The recipient's wallet was credited (wallet methods), or the provider accepted the payment. It doesn't mean the payment has settled: for example, a check has been created but not necessarily printed or mailed.
  • RetainedInWallet: Xtrm has credited the money to the recipient's Xtrm wallet and is delivering it to the bank account, card, check or gift card. Every payment by a method other than a wallet passes through this status, usually only briefly, and moves on to Success when the delivery goes through. Don't act on it while the batch is Processing. If the payment is still RetainedInWallet once the batch status is final, the delivery didn't go through: the money stays in the recipient's Xtrm wallet, you can't retry or resubmit the payment, and the fee isn't refunded. See When a payment stays RetainedInWallet.
  • Failed: the payment failed before any money moved, or when Xtrm tried to debit your wallet. The latest attempt's ErrorCode says why. You can resubmit it under the same IDs; see duplicates and retries.

The final statuses are Success, Failed, and RetainedInWallet once the batch status is final. We recommend treating Accepted, Processing, Verified and any value you don't recognize as still open, and RetainedInWallet too while the batch is Processing. See Payment statuses.

Pages. recordsToSkip is a 0-based item offset. Without recordsToTake, a page holds up to your account's maximum. Pagination is always present: while HasMore is true, call again with recordsToSkip set to NextRecordsToSkip and the same recordsToTake. Payments are listed in the order Xtrm stored them, a resubmitted payment keeps its place, and items added to the batch later come at the end. If a page would be larger than your account's response-size limit, the call fails with 413; request fewer items or leave out history.

History. Set history to true to fill each payment's Attempts; otherwise Attempts is []. On this endpoint, attempts are listed newest first. Each attempt's CreatedAt is when its outcome was recorded, and CompletedAt is the payment's last update, the same on every attempt. Sort attempts by AttemptNo. To follow a payment you resubmitted, read its history: the attempts of each resubmission carry the next AttemptNo.

Timestamps and consistency. Timestamps are in UTC. We recommend parsing them with or without a trailing Z, and treating a value without a time zone as UTC. This endpoint can briefly show changes that are still in progress, so before you act on a payment, for example to resubmit it, confirm it with Get the status of a payment in a batch.

Attempt error codes. Each attempt's ErrorCode is SUCCESS, or the code for the failure. These are values in a 200 response, not HTTP errors. The codes by stage:

  • Validation (the payment ends Failed, nothing is debited, and you can resubmit it after you fix the cause): RECIPIENT_NOT_FOUND, INVALID_BENEFICIARY_WALLET, SENDMETHODID_NOT_FOUND, BENEFICIARY_BANKID_REQUIRED, DEFAULT_BANK_NOT_FOUND, BANKID_INVALID, BANK_NOT_FOUND, INVALID_PAYMENTMETHOD, SKU_NOT_FOUND, INVALID_CARD_AMOUNT, CURRENCY_INVALID, CURRENCY_MISMATCH, COUNTRY_UNSUPPORTED, TOKEN_NOT_FOUND, INTERNAL_SERVICE_ERROR.
  • Wallet credit (the payment ends Failed): SEND_LIMIT_EXCEEDED, INSUFFICIENT_BALANCE, SENDMETHODID_NOT_FOUND, WALLET_AUTO_CREATE_FAILED, SEND_FAILED, TEMPORARY_ERROR. Contact Xtrm support before you resubmit a payment that failed with TEMPORARY_ERROR: the money may already have moved.
  • Delivery (the payment stays RetainedInWallet, and you can't retry or resubmit it): INSUFFICIENT_FUNDS_RUNTIME (the recipient's wallet, not yours, was short), RETAINED_IN_WALLET, TEMPORARY_ERROR, SKU_NOT_FOUND, INVALID_CARD_AMOUNT, Invalid payment method, PREVIOUS_TRANSFER_IN_PROGRESS.

We recommend treating a code that isn't in this list as a failure that needs review. For what each code means and what to do, see Error codes on attempts.

Note

Xtrm can also notify your server with webhooks as payments are processed. If you poll this endpoint instead, we recommend increasing the interval between calls rather than polling in a tight loop.

Tip

When Pagination.HasMore is true, pass Pagination.NextRecordsToSkip as recordsToSkip, with the same recordsToTake, to get the next page of items.

Path parameters

  • CustomerBatchIdstringRequired

    The batch's CustomerBatchId, exactly as the create response returned it. If your token can't act for the account that owns the batch, the call fails with 401.

Query parameters

  • recordsToSkipintegerOptional

    The number of items to skip, as a 0-based offset. Start at 0, then pass Pagination.NextRecordsToSkip. A negative value fails with 400 (INVALID_PAGINATION); a value past the last item returns an empty Items.

  • recordsToTakeintegerOptional

    The maximum number of items in this page. Without it, you get up to your account's maximum. 0 or a negative value fails with 400 (INVALID_PAGINATION), and a value over your account's maximum fails with 422 (LIMIT_EXCEEDED), whose message states the maximum.

  • historybooleanOptional

    true to fill each item's Attempts. Without it, or with false, Attempts is []. true and false are accepted in any case; any other value fails with 400 (INVALID_PAGINATION).

Response fields

  • CustomerBatchIdstring

    The batch's CustomerBatchId.

  • Statusstring

    The batch's status: Processing, Completed, CompletedWithFailures or Failed, computed when you ask. See batch status.

  • Currencystring

    The batch's currency, which is the currency of the source wallet, as a three-letter code.

  • ItemsCountinteger

    The number of items stored in the batch, including items added by later requests. Items rejected at submission aren't counted.

  • Itemsobject[]

    The payments in this page, in the order Xtrm stored them. Always an array.

    Child parameters7
    • CustomerTransactionIdstring

      The payment's CustomerTransactionId.

    • Statusstring

      The payment status: Accepted, Processing, Verified, Success, RetainedInWallet or Failed. See payment status.

    • RecipientIdstring

      The payment's recipient.

    • SendMethodIdstring

      The payment method, for example XTR94500.

    • Amountstring

      The payment amount before fees, as a string with 2 decimals and a thousands separator, for example "1,234.56". Remove the separators before you parse it. After a retry, it's the amount of the latest submission.

    • LastUpdatedAtstring

      When the payment was last updated, in UTC. null until Xtrm starts processing it.

    • Attemptsobject[]

      The payment's attempts, newest first, when history is true; otherwise []. An attempt appears once a stage records its outcome, so an attempt in progress has no entry yet.

      Child parameters5
      • AttemptNointeger

        The attempt number: 1 for the first submission, then one higher for each accepted resubmission. Two attempts can share a number.

      • Resultstring

        Success or Failed. A failed delivery records a Failed attempt, and the payment stays RetainedInWallet.

      • ErrorCodestring

        SUCCESS, or the code for the failure, for example INSUFFICIENT_BALANCE, BANKID_INVALID or SKU_NOT_FOUND. See attempt error codes.

      • CreatedAtstring

        When this attempt's outcome was recorded, in UTC.

      • CompletedAtstring

        The payment's last update, in UTC, the same on every attempt. It isn't the time this attempt finished.

  • Paginationobject

    Where you are in the list of items. Always present.

    Child parameters2
    • HasMoreboolean

      true when more items follow this page.

    • NextRecordsToSkipinteger

      The recordsToSkip value for the next page, or 0 when HasMore is false.

#Errors

CodeMessageMeaning
404 · Batch not foundXtrm has no batch with this CustomerBatchId. The body is {"StatusCode":404,"Message":"Unknown CustomerBatchId."}, with no error key. A failed database read while Xtrm looks up the batch returns the same 404, so repeat the check a few times, at least a minute apart, before you conclude that the batch wasn't stored. See A safe retry pattern.
401 · Not authorizedThe batch belongs to an account your token can't act for, which also means another account used this CustomerBatchId. The body is {"StatusCode":401,"Message":"Not authorized to access this resource."}.
401 · Token errorThe token is missing, empty, unrecognized, revoked or expired, uses the wrong scheme, or comes from an IP address your company doesn't allow. The body has an error and an error_message; the keys are listed under Create a batch payment.
INVALID_PAGINATION400 · Invalid paginationrecordsToSkip is negative, recordsToTake is 0 or negative, or history isn't true or false. The key is in ErrorKey.
LIMIT_EXCEEDED422 · Page too longrecordsToTake is over your account's maximum, which the message states.
LIMIT_EXCEEDED413 · Response too largeThe page would be larger than your account's response-size limit. Request fewer items or leave out history.
500 · Temporary error{"StatusCode":500,"Message":"There has been a temporary error. Please try again later."}. The error is temporary: repeat the check.

Related: Create a batch payment · Get the status of a payment in a batch

#Get the status of a payment in a batch

GET/API/v4/Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}

Returns the current status of one payment, identified by its batch's CustomerBatchId and its own CustomerTransactionId. Besides the fields the batch status endpoint returns for each payment, it includes the payment's Currency and DeliveryType.

This endpoint reads only committed data, so use it to confirm a payment before you act on it. A payment that isn't stored returns 404 with CustomerTransactionId not found within the specified batch., but so does a failed database read, and right after a submit call times out the original request may still be storing the batch. Repeat the check a few times, at least a minute apart, before you resubmit the payment in a new batch; see A safe retry pattern.

Status. The same values as on the batch status endpoint, except that a Verified payment shows as Processing. See payment status.

Delivery type. DeliveryType depends on the status:

  • Success: Wallet (XTR94502, XTR94504), Bank (XTR94500), Prepaid Virtual Debit Card (XTR94503), Digital Gift Cards (XTR94505), Bank Check (XTR94507) or Rapid Transfer (XTR94508).
  • RetainedInWallet: Wallet.
  • Accepted, Processing and Failed: an empty string.

History. Set history to true to fill Attempts; otherwise Attempts is []. On this endpoint, attempts are listed oldest first. On every attempt, CreatedAt is the payment's latest submission time and CompletedAt its last update, so neither tells you when that attempt ran; sort attempts by AttemptNo. A failed attempt followed by a successful one shows that a resubmission worked: in the example, the first attempt failed with INSUFFICIENT_BALANCE, and the payment went through when it was resubmitted after the source wallet was funded.

Payment statuses and attempt error codes are explained under Get the status of a batch payment.

Tip

To see what happened to a payment, request it with history=true and read the Result and ErrorCode of the attempt with the highest AttemptNo. Use the same request to follow a payment you resubmitted: the attempts of each resubmission carry the next AttemptNo. A payment by a method other than a wallet shows RetainedInWallet while Xtrm delivers it, so don't act on that status while the batch is Processing. If it's still RetainedInWallet once the batch status is final, its newest attempt is Failed, with an ErrorCode that says why: the money is in the recipient's Xtrm wallet, and you can't retry or resubmit the payment. See When a payment stays RetainedInWallet.

Path parameters

  • CustomerBatchIdstringRequired

    The batch's CustomerBatchId, exactly as the create response returned it.

  • CustomerTransactionIdstringRequired

    The payment's CustomerTransactionId, exactly as the create response returned it in Accepted.

Query parameters

  • historybooleanOptional

    true to fill Attempts. Without it, or with false, Attempts is []. true and false are accepted in any case; any other value fails with 400 (INVALID_PARAMETER).

Response fields

  • CustomerBatchIdstring

    The CustomerBatchId of the batch that contains the payment.

  • CustomerTransactionIdstring

    The payment's CustomerTransactionId.

  • Statusstring

    The payment status: Accepted, Processing (which includes Verified), Success, RetainedInWallet or Failed. See payment status.

  • RecipientIdstring

    The payment's recipient.

  • SendMethodIdstring

    The payment method, for example XTR94500.

  • Amountstring

    The payment amount before fees, as a plain string with 2 decimals, for example "1234.56". After a retry, it's the amount of the latest submission.

  • Currencystring

    The batch's currency, as a three-letter code.

  • DeliveryTypestring

    How the payment was delivered. On Success: Wallet, Bank, Prepaid Virtual Debit Card, Digital Gift Cards, Bank Check or Rapid Transfer, depending on SendMethodId. Wallet for a RetainedInWallet payment. An empty string for Accepted, Processing and Failed.

  • LastUpdatedAtstring

    When the payment was last updated, in UTC, or when it was submitted if it hasn't been updated yet.

  • Attemptsobject[]

    The payment's attempts, oldest first, when history is true; otherwise []. An attempt appears once a stage records its outcome, so an attempt in progress has no entry yet.

    Child parameters5
    • AttemptNointeger

      The attempt number: 1 for the first submission, then one higher for each accepted resubmission. Two attempts can share a number.

    • Resultstring

      Success or Failed. A failed delivery records a Failed attempt, and the payment stays RetainedInWallet.

    • ErrorCodestring

      SUCCESS, or the code for the failure, for example INSUFFICIENT_BALANCE. See attempt error codes.

    • CreatedAtstring

      The payment's latest submission time, in UTC, the same on every attempt.

    • CompletedAtstring

      The payment's last update, in UTC, the same on every attempt. It isn't the time this attempt finished.

#Errors

CodeMessageMeaning
404 · Batch not foundXtrm has no batch with this CustomerBatchId. The body is {"StatusCode":404,"Message":"Unknown CustomerBatchId."}, with no error key. A failed database read while Xtrm looks up the batch returns the same 404, so repeat the check a few times, at least a minute apart.
404 · Payment not foundThe batch has no stored payment with this CustomerTransactionId. The body is {"StatusCode":404,"Message":"CustomerTransactionId not found within the specified batch."}. A failed database read returns the same 404, and right after a submit call times out, the original request may still be storing the batch. Repeat the check a few times, at least a minute apart, before you treat the payment as missing.
401 · Not authorizedThe batch belongs to an account your token can't act for. The body is {"StatusCode":401,"Message":"Not authorized to access this resource."}.
401 · Token errorThe token is missing, empty, unrecognized, revoked or expired, uses the wrong scheme, or comes from an IP address your company doesn't allow. The body has an error and an error_message; the keys are listed under Create a batch payment.
INVALID_PARAMETER400 · Invalid parameterhistory isn't true or false. The key is in ErrorKey, and the message is History value is malformed..
LIMIT_EXCEEDED413 · Response too largeThe response would be larger than your account's response-size limit. The key is in ErrorKey. Request the item again without history.
500 · Temporary error{"StatusCode":500,"Message":"There has been a temporary error. Please try again later."}. The error is temporary: repeat the check.

Related: Get the status of a batch · Create a batch payment