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:
- 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 a422(or a409for items that already exist). Xtrm doesn't check your balance or move any money at this point. - 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. - Wallet credit. Xtrm debits your source wallet for the payment's
Amountplus its fee and credits the recipient's Xtrm wallet with the fullAmount. Payments from one source wallet are processed one at a time. Wallet payments (XTR94502,XTR94504) endSuccesshere. - 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
Successwhen 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
/API/v4/Fund/BatchTransferSubmits 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.
202withStatusAccepted: every item was accepted and is listed inAccepted.202withStatusCompletedWithFailures: some items were accepted and are listed inAccepted. The others are listed inRejected, each with aKey,FieldandMessage, and weren't stored. HereCompletedWithFailuresonly means that some items were rejected.422withStatusFailed, or409when any rejection isCONFLICT_DUPLICATE_ITEM: every item was rejected, nothing was stored, andRejectedlists the items.400,401,403,409,413or422for a problem with the whole request, such as an invalidIssuerAccountNumber,CustomerBatchIdorSourceWalletId, aCustomerBatchIdthat is already in use, or too many items. The body hasStatusFailedand a top-levelKeyandMessage, and nothing is stored. Token errors (401) and a missing or wrongContent-Type(415) return anerroranderror_messagebody instead. See the error table below.202withStatusFailedandKeyTEMPORARY_ERROR: the items passed validation but couldn't be stored, so this call stored nothing. A500withTEMPORARY_ERRORis 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. SendBeneficiaryBankID,WalletIdor both; an item with neither is rejected. An individual recipient always needsBeneficiaryBankID. For a business recipient sent with aWalletId, the bank linked to that wallet can apply; seeBeneficiaryBankID. 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 toEmail. Required:Email,SKU. - Rapid Transfer (
XTR94508): pushes the money to a US card linked to the recipient as atransfercard. 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 withCURRENCY_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
CustomerTransactionIdtwice in one request: Xtrm rejects every copy withDUPLICATE_ITEM_IN_REQUESTand processes none of them. - The same
CustomerBatchIdandCustomerTransactionIdin a later request: if the stored payment isFailed, Xtrm re-queues it as a new attempt with the values you sent. Otherwise that item comes back asCONFLICT_DUPLICATE_ITEMand nothing changes. If no payment in the batch isFailed, Xtrm refuses the whole request with409 CONFLICT_PROCESSING. - A
CustomerTransactionIdalready 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
CustomerTransactionIdunder an existingCustomerBatchId: added only while the batch has aFailedpayment; otherwise the whole request gets409 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 theirCustomerTransactionIdvalues), unless nothing of the original batch was stored or it has aFailedpayment.
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.
Important
If a submit call times out, wait and resend the identical request with the same CustomerBatchId and CustomerTransactionId values. Xtrm never stores an item twice, and a 409 CONFLICT_PROCESSING reply to that resend means your first request stored items of the batch, though not necessarily all of them, for example in a batch of more than 500 items, so check each one. Don't resubmit the payments under new IDs: Xtrm doesn't compare a new batch with earlier ones, so they would be paid twice. Never have two requests for the same CustomerBatchId in flight at once. See A safe retry pattern.
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
IssuerAccountNumberstringRequiredYour company's Xtrm account number (
SPN…), for exampleSPN1111222: 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 with401(KeyUnauthorized). A missing value, or one that doesn't start withSPN, fails with422INVALID_FIELD.SourceWalletIdintegerRequiredThe ID of your company's wallet that funds the batch, as an integer, for example
122181: theWalletIDthatGetCompanyWalletsreturns. 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
IssuerAccountNumberitself, in an active currency; otherwise the request fails with403(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"or122181.0), fails the whole request with422INVALID_FIELDandInvalid 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
Amountplus its fee. A payment the wallet can't cover then fails withINSUFFICIENT_BALANCE, and later, smaller payments can still go through. Fund the wallet before you submit.CustomerBatchIdstringRequiredYour ID for the batch. Required: Xtrm never generates one. 1 to 128 characters from
A-Z,a-z,0-9,.,_,-,:and@, not starting withcb_. A missing or invalid value fails the whole request with422INVALID_FIELD.CustomerBatchIdvalues 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 noFailedpayment, returns409 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-1andbatch-1are the same batch), so don't use two IDs that differ only in case. To reuse an ID, see duplicates and retries.EmailNotificationbooleanOptionaltrueto have Xtrm email each recipient a payment-received message at their own address when their wallet is credited, for every payment method. Defaults tofalse. It doesn't control how card credentials are delivered: prepaid and gift card credentials always go toDestination.Email.The strings
"true"and"false"work too, in any case. Any other string, such as"yes"or"1", is read asfalsewithout an error, so send a real boolean.Itemsobject[]RequiredThe 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
Itemsfails with422INVALID_FIELD, and too many items fail with422LIMIT_EXCEEDED, whoseMessageends with your limit (MaxAllowed: N).Child parameters6
CustomerTransactionIdstringRequiredYour ID for this payment. Required: Xtrm never generates one. 1 to 128 characters from
A-Z,a-z,0-9,.,_,-,:and@, not starting withct_. A missing or invalid value rejects the item withINVALID_FIELD(Customer transaction id is required.when it's missing). LikeCustomerBatchId, 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 originalCustomerBatchIdretries the payment if it failed, or returnsCONFLICT_DUPLICATE_ITEM. Under a differentCustomerBatchId, the same value is a new payment and is paid again. See duplicates and retries.RecipientIdstringRequiredThe recipient's Xtrm account number: an individual recipient (
PAT…) or a business recipient (SPN…), for examplePAT9999888orSPN8888777. One batch can pay both. At most 20 characters, and not your ownIssuerAccountNumber: such an item is rejected withINVALID_FIELDandFrom Account no and To Account no cannot be same.To move money between your own wallets, see Move money between your own wallets.XTR94502needs aPAT…account andXTR94504anSPN…account, or the item is rejected. Other methods that don't fit the account type fail during processing withSENDMETHODID_NOT_FOUND.During processing, the account must exist in status
A(active),NC(email not verified) orEV(pending approval); otherwise the payment fails withRECIPIENT_NOT_FOUND. Create a new recipient withCreateUserorCreateBeneficiarybefore 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.AmountnumberRequiredThe 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 most9999999999999999.99. A missing amount, or one that isn't a number (for example"abc",""ornull), is read as 0 and rejects the item withAmount must be greater than zero.Send at most 2 decimal places: Xtrm stores and pays amounts with 2. The recipient receives the fullAmount, and the payment's fee is charged to your source wallet on top.SendMethodIdstringRequiredHow 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) orXTR94507(physical check). Send the value exactly as shown, in upper case; any other value rejects the item. The method decides whichDestinationfields apply; see the payment methods.GetPaymentMethodslists the method IDs.Allowed values:
XTR94500,XTR94502,XTR94503,XTR94504,XTR94505,XTR94507,XTR94508.DescriptionstringOptionalOptional, 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 withSearchParaminGetCompanyWalletTransactions. See Track & reconcile payments.DestinationobjectRequiredWhere and how the payment is delivered. Required on every item, whatever the method: a missing or
nullDestination, or one that isn't an object, rejects the item withDestination is required.For a wallet payment without aWalletId, send{}. Which fields apply, and which of them are required, depends onSendMethodId; fields that don't apply to the method are discarded.Child parameters15
BeneficiaryBankIDstringBank (
XTR94500). The ID of a bank account linked to the recipient: the 32-characterBeneficiaryIdthatLinkBankBeneficiaryreturns andGetLinkedBankAccountslists. At most 40 characters. A bank payment needsBeneficiaryBankID,WalletIdor both; with neither, the item is rejected withBeneficiary 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'sAllowWalletLinkedBankOverrideflag, fromGetBeneficiaryWallets, decides. When it'sfalse, Xtrm always pays the bank linked to the wallet, and it replaces any bank you send. When it'strue, 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 withDEFAULT_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 withBANK_NOT_FOUND.- Individual recipient: always send it. Without it, the payment fails during processing with
BeneficiaryBankPaymentMethodstringOptionalBank (
XTR94500), optional. The rail: send exactlyACH,WIREorRTP(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 withINVALID_PAYMENTMETHOD. Some rail problems show up only after the wallet credit, asInvalid payment method, and the payment staysRetainedInWallet. A linked bank account'sPaymentMethodsinGetLinkedBankAccountsare a guide to its rails, not a promise that a rail works.WalletIdintegerOptionalAny method, optional. The ID of the recipient's wallet to credit, as an integer, for example
122311: theIDthatGetBeneficiaryWalletsreturns. A numeric string such as"122311"works too, and a value that isn't a whole number is read as noWalletId. It can't be yourSourceWalletId; that rejects the item. During processing, it must be an active wallet of the recipient in the batch's currency; otherwise the payment fails withINVALID_BENEFICIARY_WALLETbefore any money moves.If you leave it out, Xtrm credits the recipient's oldest active
Standardwallet in the batch's currency, not the wallet marked as default. If the recipient has no wallet in that currency, Xtrm creates one namedWallet - <currency code>, for exampleWallet - EUR. If its only wallets in that currency are of another type, the payment fails withWALLET_AUTO_CREATE_FAILED.On a bank payment to a business recipient,
WalletIdalso brings in the bank linked to that wallet; seeBeneficiaryBankID.EmailstringPrepaid 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, whateverEmailNotificationsays. No API returns or resends the credentials, so check the address before you submit.SKUstringPrepaid virtual debit card (
XTR94503) and digital gift card (XTR94505), required, at most 20 characters. The catalog code of the card: fromGetPrepaidCardsforXTR94503, orGetDigitalGiftCardsforXTR94505. List cards in the currency ofSourceWalletId.During processing, before any money moves:
- Gift card: the SKU must be in Xtrm's catalog (
SKU_NOT_FOUNDotherwise), and its currency must be the batch's currency (CURRENCY_MISMATCHotherwise). - Prepaid card: Xtrm must offer prepaid cards in the batch's currency (
CURRENCY_INVALIDotherwise), and the SKU must be one of them (SKU_NOT_FOUNDotherwise). - Both: a fixed-value card needs an
Amountequal to its face value, and a variable-value card anAmountbetween its minimum and maximum (INVALID_CARD_AMOUNTotherwise).
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.
- Gift card: the SKU must be in Xtrm's catalog (
CardTokenstringRapid Transfer (
XTR94508), required. TheCardTokenof a card linked to the recipient's account as atransfercard, fromGetLinkedCards; only US cards can be linked astransfercards. ACardTokenis a 15-character string of digits and capital letters A to F, for exampleEC1B22028C5B488: send it exactly asGetLinkedCardsreturns it. During processing, before any money moves, the batch must be in USD (CURRENCY_MISMATCHotherwise), and the token must be an activetransfercard of the recipient (TOKEN_NOT_FOUNDotherwise, for example for anidentitycard, a deleted card or another account's card). For a business recipient, the card must be linked to the company's own account.BeneficiaryCheckNamestringPhysical 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.BeneficiaryCheckAddress1stringPhysical check (
XTR94507), required. The street address the check is mailed to.BeneficiaryCheckAddress2stringOptionalPhysical check (
XTR94507), optional. A second address line, such as a suite or apartment.BeneficiaryCheckCitystringPhysical check (
XTR94507), required. The city the check is mailed to.BeneficiaryCheckStatestringPhysical check (
XTR94507), required, at most 50 characters (the error message for a longer value says 30). The state the check is mailed to, for exampleCA.BeneficiaryCheckPostalCodestringPhysical check (
XTR94507), required, at most 30 characters. The ZIP code the check is mailed to.BeneficiaryCheckCountryCodeISO2stringPhysical check (
XTR94507), required, at most 2 characters. The country code of the mailing address. Checks are mailed in the US only: any value other thanUSpasses submission but fails during processing withCOUNTRY_UNSUPPORTED.BeneficiaryCheckMemostringPhysical check (
XTR94507), required, at most 150 characters. The check memo.BeneficiaryCheckReferencestringPhysical check (
XTR94507), required, at most 75 characters. Your reference for the check, such as an invoice number.
Response fields
BatchTransferResponseobjectThe result of the submission. Error responses use the same wrapper, except token errors (
401) and a missing or wrongContent-Type(415).Child parameters8
CustomerBatchIdstringThe
CustomerBatchIdas Xtrm stored it. Use it with the status endpoints.nullwhen the request was refused before the batch was read, for example on a400or when the token can't act forIssuerAccountNumber.StatusstringAccepted(every item accepted),CompletedWithFailures(some items rejected) orFailed(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.KeystringThe error key when the whole request fails, for example
INVALID_FIELD,CONFLICT_PROCESSING,FORBIDDENorTEMPORARY_ERROR. Left out when there's no request-level error, including when every item is rejected (seeRejected).ErrorCodeintegerThe HTTP-style code that goes with
Key, for example422. Left out when there's no request-level error.MessagestringA human-readable explanation that goes with
Key. Left out when there's no request-level error. Some messages start with a space.ItemsCountobjectHow many items the request had and how many were accepted and rejected.
nullwhen the request was refused before the items were read.Child parameters3
TotalintegerThe number of items in the request.
AcceptedintegerThe number of items this request accepted, that is, the items listed in
Accepted. Confirm storage with the status endpoints.RejectedintegerTotalminusAccepted.
Acceptedobject[]The items this request accepted for processing, in no particular order. A
202doesn't prove that every listed item was stored; confirm with the status endpoints.Child parameters5
CustomerTransactionIdstringThe item ID as Xtrm stored it.
AmountnumberThe item amount, as a JSON number with the decimals you sent:
100.00comes back as100.00,"51.5"as51.5, and100as100.0. Compare it as a number, not as text.CurrencystringThe batch's currency, which is the currency of
SourceWalletId, for exampleUSD.SendMethodIdstringThe item's payment method, for example
XTR94500.RecipientIdstringThe 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
CustomerTransactionIdstringThe ID of the rejected item.
KeystringThe error key, for example
INVALID_FIELD,DUPLICATE_ITEM_IN_REQUEST,CONFLICT_DUPLICATE_ITEM,CURRENCY_MISMATCHorTEMPORARY_ERROR. See the error table below.ErrorCodeintegerThe HTTP-style code for
Key:422,409forCONFLICT_DUPLICATE_ITEM, or500forTEMPORARY_ERROR.FieldstringThe path of the field that failed, as
Items[i].<path>, for exampleItems[0].Destination.SKU. Match rejected items byCustomerTransactionId, not by the index:ican skip items that were removed as duplicates, some errors name a related field (a badBeneficiaryBankPaymentMethodreportsItems[i].Destination.BeneficiaryBankPaymentMethodType), and a check sent from a non-USD wallet reports"".MessagestringA human-readable explanation of why the item was rejected.
#Errors
| Code | Message | Meaning |
|---|---|---|
invalid_media_type | 415 · Unsupported media type | The 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_authorization | 401 · Not authorized | The 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_type | 401 · Wrong scheme | The Authorization header doesn't use the Bearer scheme. |
invalid_credentials | 401 · Missing credentials | The bearer token is empty. |
invalid_token | 401 · Token expired | The token has expired. Get a new token and resend. |
BAD_REQUEST | 400 · Bad request | The body is empty or isn't valid JSON. Nothing is stored. |
Unauthorized | 401 · Not authorized for the account | The token can't act for IssuerAccountNumber. Nothing is stored. |
INVALID_FIELD | 422 · Invalid field | A 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_LARGE | 413 · Payload too large | The 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_EXCEEDED | 422 · Limit exceeded | More items than your account's limit; Message ends with MaxAllowed: N. Nothing is stored. Split the payments into several batches. |
CONFLICT_PROCESSING | 409 · CustomerBatchId in use | The 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. |
FORBIDDEN | 403 · Forbidden | SourceWalletId isn't an active wallet of IssuerAccountNumber. Nothing is stored. |
DUPLICATE_ITEM_IN_REQUEST | 422 · In Rejected | The same CustomerTransactionId appears more than once in the request. Every copy is rejected. |
CONFLICT_DUPLICATE_ITEM | 409 · In Rejected | The 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_MISMATCH | 422 · In Rejected | A check item (XTR94507) sent from a wallet that isn't in USD. |
TEMPORARY_ERROR | 500 · Temporary error | Xtrm 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
/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 endedSuccess.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 showsVerified; the payment status endpoint showsProcessing.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 toSuccesswhen the delivery goes through. Don't act on it while the batch isProcessing. If the payment is stillRetainedInWalletonce 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'sErrorCodesays 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 withTEMPORARY_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
CustomerBatchIdstringRequiredThe 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 with401.
Query parameters
recordsToSkipintegerOptionalThe number of items to skip, as a 0-based offset. Start at
0, then passPagination.NextRecordsToSkip. A negative value fails with400(INVALID_PAGINATION); a value past the last item returns an emptyItems.recordsToTakeintegerOptionalThe maximum number of items in this page. Without it, you get up to your account's maximum.
0or a negative value fails with400(INVALID_PAGINATION), and a value over your account's maximum fails with422(LIMIT_EXCEEDED), whose message states the maximum.historybooleanOptionaltrueto fill each item'sAttempts. Without it, or withfalse,Attemptsis[].trueandfalseare accepted in any case; any other value fails with400(INVALID_PAGINATION).
Response fields
CustomerBatchIdstringThe batch's
CustomerBatchId.StatusstringThe batch's status:
Processing,Completed,CompletedWithFailuresorFailed, computed when you ask. See batch status.CurrencystringThe batch's currency, which is the currency of the source wallet, as a three-letter code.
ItemsCountintegerThe 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
CustomerTransactionIdstringThe payment's
CustomerTransactionId.StatusstringThe payment status:
Accepted,Processing,Verified,Success,RetainedInWalletorFailed. See payment status.RecipientIdstringThe payment's recipient.
SendMethodIdstringThe payment method, for example
XTR94500.AmountstringThe 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.LastUpdatedAtstringWhen the payment was last updated, in UTC.
nulluntil Xtrm starts processing it.Attemptsobject[]The payment's attempts, newest first, when
historyistrue; otherwise[]. An attempt appears once a stage records its outcome, so an attempt in progress has no entry yet.Child parameters5
AttemptNointegerThe attempt number:
1for the first submission, then one higher for each accepted resubmission. Two attempts can share a number.ResultstringSuccessorFailed. A failed delivery records aFailedattempt, and the payment staysRetainedInWallet.ErrorCodestringSUCCESS, or the code for the failure, for exampleINSUFFICIENT_BALANCE,BANKID_INVALIDorSKU_NOT_FOUND. See attempt error codes.CreatedAtstringWhen this attempt's outcome was recorded, in UTC.
CompletedAtstringThe payment's last update, in UTC, the same on every attempt. It isn't the time this attempt finished.
PaginationobjectWhere you are in the list of items. Always present.
Child parameters2
HasMorebooleantruewhen more items follow this page.NextRecordsToSkipintegerThe
recordsToSkipvalue for the next page, or0whenHasMoreisfalse.
#Errors
| Code | Message | Meaning |
|---|---|---|
404 · Batch not found | Xtrm 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 authorized | The 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 error | The 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_PAGINATION | 400 · Invalid pagination | recordsToSkip is negative, recordsToTake is 0 or negative, or history isn't true or false. The key is in ErrorKey. |
LIMIT_EXCEEDED | 422 · Page too long | recordsToTake is over your account's maximum, which the message states. |
LIMIT_EXCEEDED | 413 · Response too large | The 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
/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) orRapid Transfer(XTR94508).RetainedInWallet:Wallet.Accepted,ProcessingandFailed: 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
CustomerBatchIdstringRequiredThe batch's
CustomerBatchId, exactly as the create response returned it.CustomerTransactionIdstringRequiredThe payment's
CustomerTransactionId, exactly as the create response returned it inAccepted.
Query parameters
historybooleanOptionaltrueto fillAttempts. Without it, or withfalse,Attemptsis[].trueandfalseare accepted in any case; any other value fails with400(INVALID_PARAMETER).
Response fields
CustomerBatchIdstringThe
CustomerBatchIdof the batch that contains the payment.CustomerTransactionIdstringThe payment's
CustomerTransactionId.StatusstringThe payment status:
Accepted,Processing(which includesVerified),Success,RetainedInWalletorFailed. See payment status.RecipientIdstringThe payment's recipient.
SendMethodIdstringThe payment method, for example
XTR94500.AmountstringThe 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.CurrencystringThe batch's currency, as a three-letter code.
DeliveryTypestringHow the payment was delivered. On
Success:Wallet,Bank,Prepaid Virtual Debit Card,Digital Gift Cards,Bank CheckorRapid Transfer, depending onSendMethodId.Walletfor aRetainedInWalletpayment. An empty string forAccepted,ProcessingandFailed.LastUpdatedAtstringWhen 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
historyistrue; otherwise[]. An attempt appears once a stage records its outcome, so an attempt in progress has no entry yet.Child parameters5
AttemptNointegerThe attempt number:
1for the first submission, then one higher for each accepted resubmission. Two attempts can share a number.ResultstringSuccessorFailed. A failed delivery records aFailedattempt, and the payment staysRetainedInWallet.ErrorCodestringSUCCESS, or the code for the failure, for exampleINSUFFICIENT_BALANCE. See attempt error codes.CreatedAtstringThe payment's latest submission time, in UTC, the same on every attempt.
CompletedAtstringThe payment's last update, in UTC, the same on every attempt. It isn't the time this attempt finished.
#Errors
| Code | Message | Meaning |
|---|---|---|
404 · Batch not found | Xtrm 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 found | The 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 authorized | The 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 error | The 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_PARAMETER | 400 · Invalid parameter | history isn't true or false. The key is in ErrorKey, and the message is History value is malformed.. |
LIMIT_EXCEEDED | 413 · Response too large | The 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