Batch payments

Retries & idempotency

Your CustomerBatchId and CustomerTransactionId values make a resubmission safe. They tie every submission to the same payments, and Xtrm stores each pair at most once, so a resend can never store a payment twice.

Xtrm processes batch payments asynchronously (see How batch payments work). When you submit a batch to POST /Fund/BatchTransfer, Xtrm validates it, responds with 202 Accepted, and processes the payments in the background. Two things can leave you unsure what happened:

  • The call fails. After a timeout or a dropped connection, you can't tell whether Xtrm received the batch.
  • A payment fails during processing. The batch was accepted, but one or more payments didn't go through.

In both cases you resubmit with the same identifiers. The exception is a payment that stays RetainedInWallet. Bank, card, check, gift card and prepaid payments pass through that status briefly while Xtrm delivers them, so don't act on it while the batch is still Processing. A payment still RetainedInWallet once the batch status is final didn't reach its destination: the money is in the recipient's Xtrm wallet, and you can't retry or resubmit the payment. When a payment stays RetainedInWallet explains how to tell and how that money reaches the recipient.

An item stored as Failed gets a new attempt with the values you send, any other stored item comes back as CONFLICT_DUPLICATE_ITEM and nothing changes, and if no item of the batch is Failed, Xtrm refuses the whole request with 409 CONFLICT_PROCESSING. What you resend differs: after a timeout, resend the identical request; after a payment fails, we recommend resubmitting only the failed payments, with every field.

#Batch and payment identifiers

A batch payment uses two identifiers of your own. Both are required: Xtrm never generates either one.

FieldWhere it goesIf you omit it
CustomerBatchIdThe root of the request body, one per batchThe whole request fails with 422 INVALID_FIELD (Customer batch id is required.) and nothing is stored.
CustomerTransactionIdEach entry in Items, one per paymentThe item is rejected with 422 INVALID_FIELD (Customer transaction id is required.); the other items go ahead.

Xtrm echoes both IDs, as it stored them, in its responses and webhooks, so you can match each batch and payment to your own records. They are also how you look a payment up later:

Both IDs follow these rules:

RuleDetail
Length1 to 128 characters.
CharactersA–Z, a–z, 0–9, and . _ - : @.
Reserved prefixesA CustomerBatchId can't start with cb_, and a CustomerTransactionId can't start with ct_.
SanitizingBefore it checks and stores an ID, Xtrm trims spaces at either end and removes --, @@ and some SQL keywords (such as sysobjects), so don't use those sequences. Use each ID exactly as the create response echoes it.
CaseXtrm treats IDs that differ only in case as the same ID: BATCH-1 and batch-1 are the same batch. Don't use two IDs that differ only in case.

A CustomerBatchId that breaks the length, character or prefix rules fails the whole request with 422 INVALID_FIELD, and a CustomerTransactionId that breaks them rejects its item.

The sample on this page uses BATCH-RETRY-0001, with items TXN-RETRY-0001 and TXN-RETRY-0002.

If you're a managing platform

Batch IDs must be unique across all your client companies too. Include the client company's SPN or a UUID in every CustomerBatchId.

#The logical key

Xtrm identifies each payment by two values together:

  • CustomerBatchId
  • CustomerTransactionId

Your IssuerAccountNumber isn't part of the key. Requests that carry the same pair refer to the same payment, and Xtrm stores at most one item per pair, even when requests overlap, with no expiry. That is what makes a resubmission a retry rather than a new payment. Once an item is stored, its IDs never change: a retry replaces the item's other fields but keeps its IDs.

The two IDs have different scopes:

  • CustomerBatchId is global. Xtrm looks a batch up by its CustomerBatchId alone, across all Xtrm accounts.
  • CustomerTransactionId is unique only within its batch. The same CustomerTransactionId under a different CustomerBatchId is a new, separate payment, and Xtrm pays it.

#Duplicate IDs

What you sendWhat happens
The same CustomerTransactionId twice in one request (the same Items array)Xtrm rejects every copy with DUPLICATE_ITEM_IN_REQUEST and processes none of them.
The same CustomerBatchId and CustomerTransactionId in a later requestIf the stored item 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 item of the batch is Failed, Xtrm refuses the whole request with 409 CONFLICT_PROCESSING. See Retry a batch payment.
A CustomerTransactionId already used in a different batchXtrm accepts it as a new payment and pays it. Never reuse an ID for a different payment.
A new CustomerTransactionId under an existing CustomerBatchIdAdded only while the batch has a Failed item; otherwise the whole request gets 409 CONFLICT_PROCESSING. Put new payments in a new batch.

#Retry a batch payment

To retry, submit POST /Fund/BatchTransfer again under the original CustomerBatchId, with each item's original CustomerTransactionId. Xtrm accepts the request only while the batch has at least one Failed item; otherwise it refuses the whole request with 409 CONFLICT_PROCESSING and stores nothing. We recommend resubmitting only the failed items, with every field.

Any other already-stored item you include comes back in Rejected as CONFLICT_DUPLICATE_ITEM, which is harmless: that entry is part of a 202 with Status CompletedWithFailures, and the HTTP status is 409 only when no item is accepted. Don't include new CustomerTransactionId values: Xtrm adds them to the batch and pays them as new payments. What happens to each item depends on its stored status:

Item's statusWhat the resubmission does
FailedXtrm accepts the item and queues it again in the same record: its status goes back to Accepted, the values you send replace the stored ones, and its next attempt gets the next AttemptNo. The earlier attempts stay in its history. There's no time limit and no limit on the number of retries. Before you retry an item whose latest attempt is TEMPORARY_ERROR, check with Xtrm support: the money may already have moved.
Accepted, Processing or VerifiedThe item comes back as CONFLICT_DUPLICATE_ITEM and keeps processing. Wait until its status changes.
SuccessThe item comes back as CONFLICT_DUPLICATE_ITEM and isn't paid again.
RetainedInWalletThe item comes back as CONFLICT_DUPLICATE_ITEM, and nothing changes. While the batch is Processing, Xtrm is still delivering the payment: wait. If it's still RetainedInWallet once the batch status is final, the delivery didn't go through and the money is in the recipient's Xtrm wallet, so treat it like a wallet payment, not a retry: under new IDs it would be paid a second time. The fee you paid for it isn't refunded. See When a payment stays RetainedInWallet.
Rejected at submission (listed in Rejected)The item was never stored. Fix it, then resubmit it under the same CustomerBatchId only if nothing of that batch was stored or the batch has a Failed item; otherwise submit it in a new batch with a new CustomerBatchId. Either way, it can keep its CustomerTransactionId. Its first accepted submission is attempt 1.

Never send two requests for the same CustomerBatchId at the same time; see Don't overlap requests for one batch. For what each status means, see Batch and payment statuses.

#Attempt history

To follow an item after you resubmit it, read its history: request it with history=true on either status endpoint. The attempts of a resubmission carry the next AttemptNo, and the earlier attempts stay in the item's Attempts. The attempts don't include the field values an earlier attempt used: a retry replaces them, and no endpoint returns the old ones. We recommend keeping your own record of what you sent on each attempt.

For example, Get one payment shows TXN-2026-9912A, whose first attempt failed with INSUFFICIENT_BALANCE and whose second attempt, resubmitted under the same IDs after the source wallet was funded, succeeded. Attempts and history explains each attempt field and how the two status endpoints order attempts.

#What you can change on a retry

A retry replaces the whole stored item with the values you send, not only the fields you changed: IssuerAccountNumber, SourceWalletId, EmailNotification, RecipientId, SendMethodId, Amount, Description and every Destination field. A Destination field you leave out becomes empty. Xtrm doesn't block a change to any of these fields and returns no error for one, and the status endpoints then show only the new values. New values apply only to an item whose stored status is Failed.

So send every field again. We recommend correcting only what caused the failure and keeping the fields that define the payment:

Correct if neededKeep the same
Amount, Description and EmailNotificationRecipientId and SendMethodId
Destination and its fields, such as BeneficiaryBankID, CardToken, WalletId, Email, SKU and the check address fieldsIssuerAccountNumber, SourceWalletId, and the item's CustomerBatchId and CustomerTransactionId

To pay a different recipient or use a different payment method, create a new payment with a new CustomerTransactionId, in a new batch: new items join an existing batch only while it has a Failed item.

A corrected destination doesn't always take effect. Once an item has passed validation, Xtrm keeps the destination it resolved then, such as the bank account, its rail or the card, for every later retry, even if a later retry fails validation. That is the case for an item that failed while Xtrm was debiting your wallet, for example with SEND_LIMIT_EXCEEDED, INSUFFICIENT_BALANCE, WALLET_AUTO_CREATE_FAILED, SEND_FAILED or TEMPORARY_ERROR. A corrected BeneficiaryBankID or CardToken therefore takes effect only if the item has never passed validation, that is, when every earlier attempt failed at the validation stage. SENDMETHODID_NOT_FOUND can come from either stage.

A retry after a timeout is different: you don't know whether the first request arrived, so resend exactly the same body, with nothing changed. See A safe retry pattern.

#Don't overlap requests for one batch

Xtrm still stores each item at most once, but the later of two overlapping requests can't tell you what the first one stored. Depending on timing, it can get 409 CONFLICT_PROCESSING, because it saw the first request's items, or a 202 with TEMPORARY_ERROR, because its own insert collided with them: either as the Key of a Failed response, or as entries in Rejected of a CompletedWithFailures response.

You can submit different batches at the same time, and Xtrm processes the items of one source wallet one at a time, across batches. To pay more people, we recommend adding items to one batch, up to your account's limit (the MaxAllowed value in a LIMIT_EXCEEDED error message), rather than submitting many small batches.

#A safe retry pattern

The steps below are our recommendation for submitting a batch so that you can always retry it safely. In short:

When you get no usable response (a timeout, a dropped connection or an HTTP 5xx), wait, then resend exactly the same body, with the same CustomerBatchId and the same CustomerTransactionId on every item. Xtrm stores each item at most once, so the resend can't create a duplicate. If an item of the batch failed in the meantime, though, the resend retries it; see the steps below. Don't build a new batch or generate new IDs: Xtrm doesn't compare a new batch with earlier ones, so new IDs pay again. Never have two requests for the same CustomerBatchId in flight at once. Read the response: on a resend, 409 CONFLICT_PROCESSING, or CONFLICT_DUPLICATE_ITEM entries in Rejected, mean the first request stored payments of the batch, though not necessarily all of them. On the very first send of a batch, 409 CONFLICT_PROCESSING means the CustomerBatchId is already in use, possibly by another account. Then check every payment you sent with the status endpoints. A 404 can be temporary, so repeat the check a few times, at least a minute apart. Submit the payments that still return 404, and only those, in a new batch with a new CustomerBatchId.

  1. Generate the IDs once

    Create the CustomerBatchId and each item's CustomerTransactionId when you create the payments in your own system, not when you build the HTTP request. Every attempt then carries the same values. Make the CustomerBatchId unique across all of Xtrm, for example by including your account number or a UUID.

  2. Store them before the first call

    Save the IDs with your payment records before you call Xtrm. If your process crashes or restarts mid-request, it picks up the stored IDs and retries with them instead of generating new ones.

  3. Send one request per batch at a time

    Never send two requests with the same CustomerBatchId at the same time, and that includes a resend while the original request may still be running. See Don't overlap requests for one batch.

  4. Wait, then resend the identical request

    When you get no usable response (a timeout, a dropped connection, an HTTP 5xx status, or a 400 whose Message is Sequence contains no elements), wait before you resend: Xtrm keeps working on a request after your client gives up. Then resend exactly the same body, with the same CustomerBatchId and the same CustomerTransactionId on every item. A resend can never store an item twice. It can retry one, though: if an item of the batch failed while you waited, the resend queues it again with the same values, and it appears in Accepted.

    When you confirm the batch afterwards, check any item with a TEMPORARY_ERROR attempt with Xtrm support: that code can be recorded after the money moved. Don't build a new batch or generate new IDs: Xtrm doesn't compare a new batch with earlier ones, so the same payments under a new CustomerBatchId are paid again. Wait longer between resends and cap their number. If your access token expired in the meantime, get a new one and resend the same body.

  5. Read the response

    The response to a resend tells you what this call stored:

    • 202 with Status Accepted or CompletedWithFailures: this call accepted the items in Accepted; confirm that they were stored in the next step. Accepted can include items of the batch that had failed and that this call queued again. Entries in Rejected with CONFLICT_DUPLICATE_ITEM were already stored by the earlier request; they aren't errors. A TEMPORARY_ERROR entry in Rejected means that item's insert was rolled back, possibly because it collided with the original request: confirm it with the status endpoints before you resend it.
    • 409 with Key CONFLICT_PROCESSING: the batch has stored payments, and this call stored nothing. It doesn't prove that every payment was stored, so confirm each one in the next step.
    • 202 with Status Failed and Key TEMPORARY_ERROR: this call stored nothing. It may have collided with the original request, still running: wait, then go to the next step.
    • 409 with Status Failed and only CONFLICT_DUPLICATE_ITEM entries in Rejected: the earlier request already stored every item. Follow the batch.
    • 422 with Status Failed, or a 409 with other codes in Rejected: this call stored nothing new. Fix the items listed and resubmit them as described in Retry a batch payment.
    • 401: Xtrm refused the request before storing anything. If your token expired (invalid_token), get a new one and resend the same body. A Key of Unauthorized means the token can't act for IssuerAccountNumber.

    If the very first request for a batch gets 409 CONFLICT_PROCESSING, the CustomerBatchId is already in use, possibly by another account: submit the payments under a new CustomerBatchId. A 401 from the batch status endpoint for that ID means another account owns it. In a 202, ItemsCount counts this request, and each rejected item has a Key, the Field that failed and a Message.

  6. Confirm what was stored

    Neither a 202 nor a 409 proves that every payment was stored. A 202 can list a payment in Accepted that Xtrm didn't store, and a 409 CONFLICT_PROCESSING on a resend means the batch has stored payments, not that it has all of them. That 409 also hides any item that the first request rejected at submission, because Xtrm checks the CustomerBatchId before it checks the items. Xtrm stores a batch of more than 500 payments in groups of 500, each group on its own, and a group that fails doesn't undo the groups before it. A batch of 500 payments or fewer is stored all at once or not at all. If a group fails to store, the 202 lists its payments in Rejected with TEMPORARY_ERROR. If storing a group breaks off inside Xtrm, for example on a database timeout, the 202 can still list the group's payments in Accepted.

    So after a 202 or a 409, check every payment you sent; this matters most for a batch of more than 500 payments. Get the batch with GET /Fund/BatchTransfer/{CustomerBatchId} and compare its items with what you sent. Then check each payment that's missing from it with GET /Fund/BatchTransfer/{CustomerBatchId}/Items/{CustomerTransactionId}, which answers 404 with CustomerTransactionId not found within the specified batch. for a payment that isn't stored. The batch status endpoint can show changes that are still in progress, while the payment status endpoint reads only committed data.

    A 404 from either status endpoint doesn't prove that a batch or a payment is missing: a failed database read behind the check returns the same 404 as an unknown ID, and right after a submit call times out, the payment endpoint can return 404 while the original request is still storing the batch. When a status request fails explains both cases. A payment that still returns 404 after you've repeated the check a few times, at least a minute apart, wasn't stored. A 500 from a status check is temporary too: repeat the check.

  7. Submit missing payments in a new batch

    Submit the payments that weren't stored, and only those, in a new batch with a new CustomerBatchId. They keep their CustomerTransactionId values: Xtrm checks an ID only against its own batch. Don't resend them under the original CustomerBatchId: Xtrm refuses that with 409 CONFLICT_PROCESSING unless the batch has a Failed payment. Never put a stored payment in the new batch: Xtrm doesn't compare batches, so it would be paid twice.

  8. Resubmit failed items under the same IDs

    Follow processing with webhooks or the status endpoints. To retry an item whose Status is Failed, resubmit it under its original CustomerBatchId and CustomerTransactionId. Send only the failed items, with every field, because a retry replaces the whole item; see What you can change on a retry. Other already-stored items you include come back as CONFLICT_DUPLICATE_ITEM, which is harmless. Don't include new CustomerTransactionId values: Xtrm would add them and pay them as new payments.

  9. Never reuse an ID for a different payment

    A new payment, or a payment to a different recipient or by a different payment method, gets a new CustomerTransactionId. A new batch gets a new CustomerBatchId. Reusing a CustomerBatchId for new payments gets 409 CONFLICT_PROCESSING, or adds them to the old batch if it has a Failed item. Reusing a CustomerTransactionId in the same batch gets CONFLICT_DUPLICATE_ITEM (or 409 CONFLICT_PROCESSING for the whole request when no item of the batch is Failed), or replaces the old item with the new payment if that item is Failed.

#What not to do

  • Don't generate new IDs, or a new CustomerBatchId, for a payment until you've confirmed that it's missing. Xtrm never compares a new batch with earlier ones, so the same payment under a new CustomerBatchId is paid again.
  • Don't treat a 404 from either status endpoint as proof that a payment is missing until you've repeated the check a few times, at least a minute apart. The original request may still be running, and both endpoints also answer 404 when their database read fails. Until then, resend only under the original CustomerBatchId and CustomerTransactionId values: Xtrm's duplicate check works only within one CustomerBatchId, so it protects a resend under the original IDs and never one under new IDs.
  • Don't treat the Accepted list of a 202, or a 409 CONFLICT_PROCESSING on a resend, as proof that every payment was stored.
  • Don't resubmit a RetainedInWallet payment. While the batch is Processing, it's still on its way to the destination; once the batch status is final, it has stuck and the money is in the recipient's Xtrm wallet. Under the same IDs it comes back as CONFLICT_DUPLICATE_ITEM, and under new IDs it's paid a second time.
  • Don't change RecipientId, SendMethodId, SourceWalletId or IssuerAccountNumber when you retry a Failed item. Xtrm would apply the change without an error. A different recipient or method is a new payment with a new CustomerTransactionId.
  • Don't retry a Failed item whose latest attempt is TEMPORARY_ERROR without first checking with Xtrm support. That code can be recorded after the money moved, so a retry could pay twice.
  • Don't use two IDs that differ only in case: Xtrm treats them as the same ID.

#Example: resend a batch with the same IDs

This sample submits a batch of two payments with fixed IDs. When there's no usable response (a timeout, a dropped connection, a 5xx, or a 400 with Sequence contains no elements), it waits and sends the identical request again, up to three times in all (the cURL tab resends on fewer of these cases; see below). It then reads the response as in Read the response.

A 409 with only CONFLICT_DUPLICATE_ITEM entries in Rejected means an earlier request already stored the items, so the sample reports them as stored. A 409 with CONFLICT_PROCESSING means a batch with this CustomerBatchId already exists: most likely from the earlier attempt if the sample had to resend, but possibly another account's, especially if this is your first submission of these payments. So the sample doesn't report your items as stored. It tells you to check the batch with the batch status endpoint: a 401 there means another account owns the ID, so submit the payments under a new CustomerBatchId; otherwise compare its items with what you sent, and confirm each missing payment as in Confirm what was stored. In every other case it reports how many items this call accepted and why any were rejected. In production, read the IDs from your payment records instead of hard-coding them, and then confirm what was stored with the status endpoints.

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.

In the cURL tab, --retry 2 resends the identical request after a timeout or an HTTP 500, 502, 503 or 504 response, --retry-all-errors (curl 7.71 or later) adds dropped connections and other transfer errors, and --retry-delay waits 30 seconds before each resend. curl doesn't resend after other 5xx codes or the 400 with Sequence contains no elements: for those, wait, then run the same command again. -o writes the final response to batch-response.json, and -w prints its HTTP status, or HTTP 000 when no response arrived.

# Every attempt sends the same CustomerBatchId and CustomerTransactionId values.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
  --retry 2 --retry-all-errors --retry-delay 30 --max-time 60 \
  -o batch-response.json -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "IssuerAccountNumber": "SPN1111222",
  "SourceWalletId": 122181,
  "CustomerBatchId": "BATCH-RETRY-0001",
  "Items": [
    {
      "CustomerTransactionId": "TXN-RETRY-0001",
      "RecipientId": "SPN8888776",
      "Amount": 50,
      "SendMethodId": "XTR94504",
      "Destination": {
        "WalletId": 122311
      }
    },
    {
      "CustomerTransactionId": "TXN-RETRY-0002",
      "RecipientId": "PAT9999888",
      "Amount": 50,
      "SendMethodId": "XTR94503",
      "Destination": {
        "Email": "[email protected]",
        "SKU": "PREP9001"
      }
    }
  ]
}'
# HTTP 000 (no response after the last attempt), any 5xx, or 400 with "Sequence contains no elements":
# the outcome is unknown. Wait, then run the same command again.
# HTTP 202: Xtrm accepted the items in Accepted (confirm with the batch status endpoint). Accepted can
# include items of this batch that had failed and that this call queued again. Rejected entries with
# CONFLICT_DUPLICATE_ITEM were stored by an earlier request; TEMPORARY_ERROR entries weren't stored by
# this call. Status Failed with TEMPORARY_ERROR means this call stored nothing.
# HTTP 409 with only CONFLICT_DUPLICATE_ITEM entries in Rejected: an earlier request stored the items.
# HTTP 409 with CONFLICT_PROCESSING: a batch with this CustomerBatchId already exists, from your earlier
# request or, if this is your first send of these payments, from another account. Check it with the
# batch status endpoint: a 401 there means another account owns the ID, so use a new CustomerBatchId.
# HTTP 422, or 409 with other codes: this call stored nothing new. Fix the items listed.
# Then confirm what was stored with the batch status endpoint.

#Duplicate webhook deliveries

The same webhook event can be delivered more than once; see Retries and duplicates.