Batch payments

Webhooks

Webhooks tell your system how a batch payment is going. Xtrm notifies your endpoint as it picks up and validates payments, as each payment succeeds or fails, and when a batch reaches a final status. Item events echo your CustomerBatchId and CustomerTransactionId, so you can match them to your own records.

Xtrm processes batch payments asynchronously (see How batch payments work). When you submit a batch, Xtrm validates it and, when at least one item is accepted, responds with 202 Accepted, then processes the accepted items in the background.

You can also poll the status endpoints. We recommend using both: webhooks to react quickly, and the status endpoints as the record you book and reconcile against.

#Where webhooks fit in a batch

StepWhat happensEvents
1. SubmitYou submit the batch to POST /Fund/BatchTransfer. Xtrm checks the request (authentication, required fields and formats, the source wallet, duplicate IDs) and stores the accepted items.None. When at least one item is accepted, you get 202, normally listing the accepted and the rejected items; otherwise Xtrm refuses the request with an error status (see Errors).
2. ValidateEvery 2 seconds, Xtrm picks up stored items in groups, one group per source wallet, and checks each item's recipient, wallet, destination and method.Batch.Started for each group, Batch.Item.Processing for each item, Batch.Item.Failed for each item that fails, and Batch.Failed when every item in a group fails.
3. Credit the walletXtrm debits your source wallet for each item's amount plus fee and credits the recipient's wallet.Batch.Item.Failed for each item that fails. Batch.Item.Completed for wallet payments (XTR94502, XTR94504), which are done at this point. No event for the other items, which now show RetainedInWallet while Xtrm delivers them.
4. DeliverFor bank transfer, push-to-card, check, prepaid card and gift card items, Xtrm delivers the payment from the recipient's wallet to the destination.Batch.Item.Completed, whether the delivery went through or not (see Events for a delivery).
5. FinishAfter a wallet-credit or delivery pass, Xtrm finds the batch in a final status.Batch.Completed

Items rejected at submission (listed in Rejected in the response) are never stored and send no events, so expect events only for accepted items. The exception is a CONFLICT_DUPLICATE_ITEM entry: it refers to an item that an earlier request stored, and that item's events come from the earlier submission. Confirm final statuses with the status endpoints: some outcomes, such as a delivery that Xtrm is holding, send no event until they're resolved (see Events for a delivery).

#Enable webhooks

If you're a managing platform

Webhooks are set up per company account, so request an endpoint for each client company in the same way as for your own. Give each client company its own URL, for example with its SPN in the path, so you know which company every event belongs to. See Pseudo credentials.

Xtrm support sets up webhooks with you. To set one up, send your endpoint URL to [email protected] or to your Account Manager or Customer Success Manager. Xtrm support then configures the webhook for your company account and sets up its signing secret with you.

  • One endpoint per company account. Your company account has one active subscription, and it receives every event type.
  • Events need an active subscription. Xtrm records an event only if your company account has an active subscription when the event happens. This applies to every event, including those from a manual review. Before your company's first endpoint is set up, Xtrm records no events for it, so none from that time are sent later. When a subscription is switched off, Xtrm stops recording your company's events, so don't count on events for anything that happens after the switch-off. Because Xtrm checks each event as it happens, a batch that's being processed around the time the subscription is switched on or off can be missing some of its events. We recommend having Xtrm set up your endpoint before you submit the batches you want events for, ideally while none of your batches is being processed. Get your endpoint live and verifying signatures before the subscription is switched on: Xtrm retries an event only until 24 hours after it was created (see Retries and duplicates). Follow batches submitted before then, and any batch whose events you're missing, with the status endpoints.
  • Register an HTTPS URL, so events aren't sent in clear text.
  • Use a dedicated path, for example https://payments.example.com/webhooks/xtrm, so you can apply the checks on this page to Xtrm traffic only.
  • Set up each environment. Your sandbox and live company accounts are separate, so if you integrate in both, request an endpoint for each. Each one has its own signing secret.

Each subscription has one signing secret. You need it to verify signatures. Store it like your API credentials: in a secrets manager or an environment variable (the samples on this page read XTRM_WEBHOOK_SECRET), never in source control.

To rotate the secret, contact Xtrm support and agree a switch-over time. Xtrm replaces the secret in one step: from then on, every delivery attempt, including retries of older events, is signed with the new secret, and a delivery always carries exactly one signature. So during the switch-over, accept a delivery that verifies with either the old or the new secret.

#Event types

There are six event types, and the names are exact.

EventWhen Xtrm sends itKey fields
Batch.StartedEach time Xtrm picks up a group of stored items for one source wallet to validate them. A group can include items from more than one batch that use the same source wallet; the event then carries the first item's CustomerBatchId and the combined count. It's sent again after you resubmit failed items.CustomerBatchId, BatchStatus, ItemsCount, Currency
Batch.Item.ProcessingEach time an item is validated, including after a resubmission.CustomerTransactionId, Status, AttemptNo
Batch.Item.FailedAn item failed validation, or failed when Xtrm tried to credit the recipient's wallet. The payload includes the ErrorCode of the failure. The item can be resubmitted, so this isn't necessarily its final outcome.CustomerTransactionId, Status, ErrorCode
Batch.Item.CompletedA wallet payment (XTR94502, XTR94504) was credited; a delivery to the destination finished, whether it went through or not; or Xtrm staff completed a manual review of the item. Read Status and DeliveryType together (see Events for a delivery).CustomerTransactionId, Status, DeliveryType
Batch.CompletedAfter a processing pass finds the batch in a final status: Completed, CompletedWithFailures or Failed. It can be sent more than once, for example again after a resubmission. Xtrm doesn't send it after a manual review, so resolving a delivery that Xtrm held doesn't send one.CustomerBatchId, BatchStatus, Succeeded, Failed
Batch.FailedEvery item in one validation group failed validation.CustomerBatchId, BatchStatus, Failed

Build your receiver to accept event types it doesn't recognize: respond with a 2xx status and ignore them, so a new event type never turns into failed deliveries.

#Events for a delivery to the destination

A bank transfer, push-to-card, check, prepaid card or gift card payment shows RetainedInWallet while Xtrm delivers it from the recipient's wallet, but no event reports RetainedInWallet, and none is sent when the money reaches the recipient's wallet on its way to the destination. For such a payment, you receive:

What happensWhat you receive
Xtrm validates the payment.Batch.Item.Processing, with Status Processing.
Xtrm credits the recipient's wallet, and the payment shows RetainedInWallet while the delivery is under way.Nothing.
The delivery goes through, and the payment moves on to Success.Batch.Item.Completed, with Status Success and the rail in DeliveryType: Bank, Bank Check, Rapid Transfer, Digital Gift Cards or Prepaid Virtual Debit Card.
The delivery doesn't go through, and the payment stays RetainedInWallet.Batch.Item.Completed, with Status Success and DeliveryType Wallet. No Batch.Item.Failed is sent.
Xtrm holds the delivery, for example for a compliance review or because the provider couldn't take it.Nothing while it's held. When Xtrm staff resolve it, a Batch.Item.Completed with Status Success or Failed and the delivery's DeliveryType (see Events from a manual review).
Every payment of the batch is final.Batch.Completed, which counts a payment that stayed RetainedInWallet under Failed. It isn't sent for a batch while a delivery is held, or when Xtrm staff resolve one.

So read DeliveryType, not Status, to tell a delivery that went through from one that didn't, and while Xtrm holds a delivery, follow the batch with the status endpoints. When a payment stays RetainedInWallet explains how the status endpoints show each case.

#The webhook request

Xtrm sends each event as a POST to your endpoint URL. The body is the event's JSON, encoded in UTF-8 and sent byte for byte as Xtrm stored it. It's the event object itself, with no envelope: the event type and ID are only in the headers.

HeaderValue
Content-Typeapplication/json; charset=utf-8
X-Event-IdThe event's ID, a GUID. It stays the same when Xtrm retries the delivery.
X-Event-TypeOne of the six event types, for example Batch.Item.Completed.
X-Event-TimestampWhen Xtrm sent this delivery attempt, in UTC ISO 8601 with fractional seconds, for example 2025-10-29T13:02:24.3517420Z. It's new on every attempt, and it isn't when the event happened.
X-Retry-Count1 on the first delivery; it goes up by one with each attempt, and it can grow large (see Retries and duplicates).
X-SignatureThe HMAC-SHA256 signature of the request, in the form t=<timestamp>, v1=<signature>. See Verify the signature.

The examples on this page follow one batch of two payments, BATCH-WEBHOOK-0001. This delivery is the Batch.Item.Completed event for its first item, TXN-WEBHOOK-0001, a bank payment that the provider accepted on the item's second attempt:

Example delivery
POST /webhooks/xtrm HTTP/1.1
Host: payments.example.com
Content-Type: application/json; charset=utf-8
X-Event-Id: 7d2f4c1e-9a3b-4e6f-8c51-2b0a9e7d3f14
X-Event-Type: Batch.Item.Completed
X-Event-Timestamp: 2025-10-29T13:02:24.3517420Z
X-Retry-Count: 1
X-Signature: t=1761742944, v1=721c4c1b3c7d84bf8858128810a78bc9e6e0f4ab50891107e55e7203a233bb9d

{"CustomerBatchId":"BATCH-WEBHOOK-0001","CustomerTransactionId":"TXN-WEBHOOK-0001","Status":"Success","Amount":100.00,"Currency":"USD","SendMethodId":"XTR94500","RecipientId":"100245","DeliveryType":"Bank","AttemptNo":2,"LastUpdatedAt":"2025-10-29T13:02:23Z"}

The signature in this example is computed with the test secret example-webhook-secret, so you can use the request as a test case.

#Event payloads

Each payload is a flat JSON object with PascalCase field names, in the order the tables below list them. Xtrm sends it without whitespace, as in the example delivery; the examples below are formatted for reading. Every payload includes the CustomerBatchId, and item events also include the CustomerTransactionId: the IDs from your request. The examples follow BATCH-WEBHOOK-0001: the batch starting, its first item succeeding and its second item, TXN-WEBHOOK-0002, failing.

#Batch.Started

FieldDescription
CustomerBatchIdThe CustomerBatchId of the first item in the group. A group can also include items of other batches that use the same source wallet.
BatchStatusAlways Processing.
ItemsCountThe number of items in the group, as an integer. It isn't necessarily the number of items in the batch; to count a batch's stored items, read ItemsCount from Get the status of a batch payment.
CurrencyThe currency of the batch, which the source wallet sets.
ReceivedAtWhen the group's first item was stored or last resubmitted, as a plain date and time with whole seconds and no time zone, for example 10/28/2025 3:11:35 AM. The time is UTC. It isn't ISO 8601, so parse it with the pattern M/d/yyyy h:mm:ss tt.
Batch.Started
{
  "CustomerBatchId": "BATCH-WEBHOOK-0001",
  "BatchStatus": "Processing",
  "ItemsCount": 2,
  "Currency": "USD",
  "ReceivedAt": "10/28/2025 3:11:35 AM"
}

#Item events

Batch.Item.Processing, Batch.Item.Completed and Batch.Item.Failed share most of their fields.

FieldSent inDescription
CustomerBatchIdAll threeThe ID of the batch that contains the item.
CustomerTransactionIdAll threeThe ID of the item.
StatusAll threeProcessing in Batch.Item.Processing and Failed in Batch.Item.Failed. In Batch.Item.Completed, Success, also when the delivery didn't go through and the item stays RetainedInWallet; an event from a manual review can also say Failed. No event carries RetainedInWallet. Confirm final statuses with the status endpoints.
AmountAll threeThe item amount as a JSON number with 2 decimals and no thousands separator, for example 100.00 or 1234.56. The extra events described in Events from a manual review can differ.
CurrencyAll threeThe currency of the item, for example USD.
SendMethodIdAll threeThe payment method of the item, for example XTR94500.
RecipientIdAll threeThe RecipientId you sent, for example PAT9999888. In a Batch.Item.Completed sent after a delivery to the destination (bank, check, card and push-to-card items), it's Xtrm's internal numeric ID for the recipient, as a string, for example "100245". Match events to your records on CustomerBatchId and CustomerTransactionId.
DeliveryTypeBatch.Item.CompletedWallet when the recipient's wallet was credited and nothing more was sent: for wallet payments, and for any other method whose delivery didn't go through, so the item stays RetainedInWallet. Otherwise the rail of the delivery, for example Bank.
ErrorCodeBatch.Item.FailedThe error code of the failure, for example RECIPIENT_NOT_FOUND. See Error codes on attempts.
AttemptNoAll threeThe item's attempt number, always present: 1 for the first submission, plus one for each accepted resubmission. Events from a manual review always say 1.
LastUpdatedAtBatch.Item.Completed, Batch.Item.FailedA time in the form yyyy-MM-ddTHH:mm:ssZ (whole seconds), or an empty string. The moment it records depends on the stage that sent the event, so don't treat it as the time of the outcome.
Batch.Item.Completed
{
  "CustomerBatchId": "BATCH-WEBHOOK-0001",
  "CustomerTransactionId": "TXN-WEBHOOK-0001",
  "Status": "Success",
  "Amount": 100.00,
  "Currency": "USD",
  "SendMethodId": "XTR94500",
  "RecipientId": "100245",
  "DeliveryType": "Bank",
  "AttemptNo": 2,
  "LastUpdatedAt": "2025-10-29T13:02:23Z"
}
Batch.Item.Failed
{
  "CustomerBatchId": "BATCH-WEBHOOK-0001",
  "CustomerTransactionId": "TXN-WEBHOOK-0002",
  "Status": "Failed",
  "Amount": 50.00,
  "Currency": "USD",
  "SendMethodId": "XTR94502",
  "RecipientId": "PAT0000001",
  "ErrorCode": "RECIPIENT_NOT_FOUND",
  "AttemptNo": 1,
  "LastUpdatedAt": "2025-10-28T03:11:37Z"
}

In this example, PAT0000001 isn't an Xtrm account, so the item failed validation with RECIPIENT_NOT_FOUND. Use ErrorCode to react to failures in code. A Batch.Item.Failed carries only codes from validation and from the wallet credit, for example RECIPIENT_NOT_FOUND, BANKID_INVALID, SKU_NOT_FOUND and INSUFFICIENT_BALANCE. For every code and what to do, see Error codes on attempts. We recommend treating a code you don't recognize as a generic failure. If the code is TEMPORARY_ERROR, check with Xtrm support before you resubmit the item: the payment may already have gone through.

#Batch.Completed and Batch.Failed

Both events have the same fields. Use them as a prompt to read the batch status, not as the final word: a final batch status can still change (see Reconcile with the status endpoints).

FieldDescription
CustomerBatchIdThe ID of the batch. In Batch.Failed, the batch of the first item in the group.
BatchStatusIn Batch.Completed, the batch's final status: Completed, CompletedWithFailures or Failed. In Batch.Failed, Failed.
ItemsCountIn Batch.Completed, the number of stored items in the batch. In Batch.Failed, the number of items in the group.
SucceededIn Batch.Completed, the items whose status is Success. In Batch.Failed, always 0.
FailedIn Batch.Completed, the items that failed, including items whose delivery didn't go through, which stay RetainedInWallet, and stored items that haven't been validated yet. So an early Batch.Completed can count items that are still in progress as failed. In Batch.Failed, the items in the group that failed.
CurrencyThe currency of the batch.
CompletedAtA date string in the same format as ReceivedAt, with no time zone. The time is UTC: the batch's latest item update in Batch.Completed, and when the event was created in Batch.Failed.

#Events from a manual review

Xtrm staff can review an item by hand, for example to resolve a delivery that Xtrm held for a sanctions review or because the provider couldn't take it. Xtrm then sends a Batch.Item.Completed for the item if your company has an active subscription when the item is resolved, which can be well after you submitted the batch (as with every event, see Enable webhooks). The event has the same field names as the other item events, with these differences:

  • Status is Success or Failed, with no ErrorCode.
  • RecipientId is the one you sent, and AttemptNo is always 1.
  • LastUpdatedAt is in the server's local time, followed by a Z.
  • Amount is usually a number with 8 decimals, for example 125.00000000, and can also arrive as a string or be left out.
  • DeliveryType can differ from the method's usual value, for example Digital Gift Cards for a prepaid card, or a value cut to 10 characters such as Rapid Tran.

Book the status you fetch from the status endpoints, not the event's. No Batch.Completed follows a manual review.

Separately, after every successful gift card or prepaid card payment to an individual recipient, Xtrm sends a second Batch.Item.Completed for the same item next to the usual one, with a different X-Event-Id, AttemptNo 1, DeliveryType Digital Gift Cards, an Amount with 8 decimals (100.00000000) and the RecipientId you sent instead of Xtrm's internal ID. De-duplicate so you don't process the same outcome twice.

#Verify the signature

Xtrm signs every webhook with HMAC-SHA256 and sends the result in the X-Signature header:

X-Signature format
X-Signature: t=<Unix time in seconds>, v1=<lowercase hex HMAC-SHA256 of t + "." + raw body>

The HMAC key is your subscription's signing secret, as UTF-8 bytes, and the signed message is the value of t, a period, and the request body exactly as sent, in UTF-8. The header always carries exactly one v1 value of 64 hex characters, and t is the time of the delivery attempt, so it's new on every retry. To verify an event:

  1. Read the raw request body as bytes, before any JSON parsing.
  2. Split X-Signature on commas and read the t and v1 values.
  3. Compute the HMAC-SHA256 of t, . and the raw body with your secret, and hex-encode it.
  4. Compare the result with v1 using a constant-time comparison. The event is authentic if they match. During an agreed secret switch-over, also try the old secret when the new one doesn't match.
  5. Check that t is recent. We recommend a tolerance of 300 seconds, which limits replays of captured requests. Because every attempt is signed with a new t, the window doesn't reject retries for their age; only a large difference between your clock and Xtrm's matters. De-duplicating on X-Event-Id also stops a captured delivery from being processed twice.

If verification fails, don't process the event. We recommend responding with 401 so the failure shows up in your logs. Xtrm retries a delivery that doesn't get a 2xx response until about 24 hours after the event was created (see Retries and duplicates), so fix a misconfigured secret quickly.

Each sample below defines a verification function that takes the raw body, the X-Signature header, your secret, the current time and an optional tolerance in seconds. It checks the HMAC first and the timestamp second, and it skips the timestamp check when you leave out the tolerance. Each sample then tests the function with the example delivery above: a valid signature, a tampered body, the wrong secret, a stale timestamp with a 300-second window, and the same timestamp with no window. Use it as a test vector for your own implementation. The cURL tab is for checking test vectors only, not live traffic: its string comparison isn't constant-time, and it passes the secret to openssl on the command line, where anyone else signed in to the machine can see it.

# Checks an X-Signature header against a raw request body with openssl.
# For test vectors only: the comparison isn't constant-time and the secret is visible in the process list.
# Usage: verify_signature RAW_BODY SIGNATURE_HEADER SECRET [NOW] [TOLERANCE_SECONDS]
# Without TOLERANCE_SECONDS, the timestamp window isn't checked.
verify_signature() {
  local raw_body="$1" header="$2" secret="$3" now="${4:-$(date +%s)}" tolerance="${5:-}"
  local t="" t_num part sig expected matched=1
  local -a parts signatures=()
  IFS=',' read -ra parts <<< "$header"
  for part in "${parts[@]}"; do
    part="${part//[[:space:]]/}"
    case "$part" in
      t=*) t="${part#t=}" ;;
      v1=*) signatures+=("${part#v1=}") ;;
    esac
  done
  [[ "$t" =~ ^[0-9]{1,12}$ ]] || return 1
  (( ${#signatures[@]} > 0 )) || return 1

  # Sign t exactly as it appears in the header.
  expected=$(printf '%s.%s' "$t" "$raw_body" | openssl dgst -sha256 -hmac "$secret" | sed 's/^.*= //')
  for sig in "${signatures[@]}"; do
    [[ "$(printf '%s' "$sig" | tr '[:upper:]' '[:lower:]')" == "$expected" ]] && matched=0
  done
  (( matched == 0 )) || return 1

  if [[ -n "$tolerance" ]]; then
    t_num=$((10#$t))
    (( now - t_num <= tolerance && t_num - now <= tolerance )) || return 1
  fi
  return 0
}

# Test with the example delivery.
SECRET='example-webhook-secret'
RAW_BODY='{"CustomerBatchId":"BATCH-WEBHOOK-0001","CustomerTransactionId":"TXN-WEBHOOK-0001","Status":"Success","Amount":100.00,"Currency":"USD","SendMethodId":"XTR94500","RecipientId":"100245","DeliveryType":"Bank","AttemptNo":2,"LastUpdatedAt":"2025-10-29T13:02:23Z"}'
HEADER='t=1761742944, v1=721c4c1b3c7d84bf8858128810a78bc9e6e0f4ab50891107e55e7203a233bb9d'
T=1761742944

fail() { echo "Check failed: $1" >&2; exit 1; }
verify_signature "$RAW_BODY" "$HEADER" "$SECRET" $((T + 10)) 300 || fail "valid signature"
if verify_signature "${RAW_BODY/100.00/900.00}" "$HEADER" "$SECRET" $((T + 10)) 300; then fail "tampered body"; fi
if verify_signature "$RAW_BODY" "$HEADER" "wrong-secret" $((T + 10)) 300; then fail "wrong secret"; fi
if verify_signature "$RAW_BODY" "$HEADER" "$SECRET" $((T + 600)) 300; then fail "stale timestamp, 300-second window"; fi
verify_signature "$RAW_BODY" "$HEADER" "$SECRET" $((T + 600)) || fail "stale timestamp, no window"
echo "All signature checks passed"

#Retries and duplicates

Xtrm waits 10 seconds for your response, and any 2xx status counts as delivered. Respond with a 2xx after only lightweight checks, and do the real work afterwards. Keep the response body short, under about 2,000 characters, and don't answer with a redirect (see below). If Xtrm gets no response in time or a non-2xx status, it retries the delivery:

  • Retry pace. Xtrm retries on each pass of its retry worker, about once a second when your endpoint fails fast, taking up to 200 waiting events for your endpoint per pass. While your endpoint is failing, expect bursts of retries and large X-Retry-Count values.
  • Same event, same ID. A retried delivery has the same X-Event-Id and the same body. X-Retry-Count goes up by one, and X-Event-Timestamp and the signature's t are new.
  • 24 hours. Xtrm retries until 24 hours after the event was created. The first failed retry after that marks the event as failed, and it isn't sent again. Use the status endpoints to catch anything you missed.
  • Short responses. If Xtrm can't record the outcome of a delivery, the event isn't retried. A response body longer than about 2,000 characters causes this, so keep yours short.
  • No redirects. Xtrm's client follows redirects, and after a 301 or 302 the request can arrive as a GET without a body and still count as delivered. Register the final URL.

Because a delivery can arrive more than once, de-duplicate on X-Event-Id. The same outcome can also arrive as separate events with different IDs: Batch.Started and Batch.Completed again after a resubmission, or a second Batch.Item.Completed for a gift card or prepaid card (see Events from a manual review). We recommend this approach:

  • Record each event ID you process, for example in a database table with a unique key on the ID, written in the same transaction as the changes the event causes.
  • When an event ID is already recorded, respond with 2xx and do nothing else, so Xtrm stops retrying it.
  • Also make your own updates idempotent: key them on a business key such as the event type, CustomerBatchId, CustomerTransactionId and Status, so that two events about the same outcome can't, for example, mark a payment as paid twice. Leave AttemptNo out of the key: events from a manual review always say 1, and two attempts can share a number.

#Event order

Deliveries can arrive out of order. Xtrm picks up waiting events oldest first, but sends each group of them in no defined order, and an event that keeps failing is retried while later events get through. An item event can arrive before Batch.Started, and a retried delivery can arrive after a newer event for the same item.

Neither the headers nor the payload order events reliably: X-Event-Timestamp is the time of the delivery attempt, LastUpdatedAt records a different moment at each stage, and AttemptNo is always 1 in events from a manual review. We recommend:

  • Don't decide which event is newer from the order of arrival, X-Event-Timestamp or LastUpdatedAt.
  • Treat each event as a signal to check the item, not as its final state. A failed item can be resubmitted, which creates a new attempt and keeps the history of the earlier ones, so a Batch.Item.Failed for attempt 1 can arrive after a Batch.Item.Completed for attempt 2.
  • When the order matters, for example before you resubmit a failed item, fetch the item's status with history=true instead of relying on the events you received.

#Reconcile with the status endpoints

Webhooks tell you that something changed; the status endpoints give you the current state. We recommend checking them in three situations:

  • Before you act on an outcome. After a Batch.Item.Failed, or a Batch.Item.Completed that doesn't report a completed delivery to the destination (see Events for a delivery), fetch the item and book the Status it returns. For a failed item, set history=true to see every attempt, its Result and its ErrorCode. The same call follows an item you resubmitted: its attempts list every submission's outcome. Before you resubmit anything, see Retries & idempotency: under its original IDs an item that already succeeded isn't paid again, but under new IDs it is.
  • When a batch goes quiet. Schedule a job that checks batches with items whose outcome you haven't recorded yet. It catches events that were never delivered.
  • To know when a batch is finished. Poll Get the status of a batch payment, increasing the interval between calls, until its Status is no longer Processing. The other values are Completed, CompletedWithFailures and Failed, and even these can change (see How the batch status is derived). So when the status leaves Processing, read it again after a short pause, and check that none of the batch's items is Accepted, Processing or Verified, before you treat the batch as finished. An item's final statuses are Success, Failed, and RetainedInWallet once the batch is final: while the batch is Processing, a RetainedInWallet item is still on its way to its destination. See Payment statuses and When a payment stays RetainedInWallet. Page through the batch's items with recordsToSkip and recordsToTake.

This request fetches TXN-WEBHOOK-0001, the item from the Batch.Item.Completed example, with its full attempt history, using Get the status of a payment. Replace BATCH-WEBHOOK-0001 and TXN-WEBHOOK-0001 with the IDs of one of your own items. CustomerBatchId values are shared across all Xtrm accounts, so the sample IDs return 404, or 401 if another account used them.

curl -X GET "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer/BATCH-WEBHOOK-0001/Items/TXN-WEBHOOK-0001?history=true" \
  -H "Authorization: Bearer $XTRM_ACCESS_TOKEN"
Response
{
  "CustomerBatchId": "BATCH-WEBHOOK-0001",
  "CustomerTransactionId": "TXN-WEBHOOK-0001",
  "Status": "Success",
  "RecipientId": "PAT9999888",
  "SendMethodId": "XTR94500",
  "Amount": "100.00",
  "Currency": "USD",
  "DeliveryType": "Bank",
  "LastUpdatedAt": "2025-10-29T13:02:23.259Z",
  "Attempts": [
    {
      "AttemptNo": 1,
      "Result": "Failed",
      "ErrorCode": "INSUFFICIENT_BALANCE",
      "CreatedAt": "2025-10-29T13:01:35.0055683Z",
      "CompletedAt": "2025-10-29T13:02:23.259Z"
    },
    {
      "AttemptNo": 2,
      "Result": "Success",
      "ErrorCode": "SUCCESS",
      "CreatedAt": "2025-10-29T13:01:35.0055683Z",
      "CompletedAt": "2025-10-29T13:02:23.259Z"
    }
  ]
}

The item's first attempt failed with INSUFFICIENT_BALANCE, so nothing was debited; it was resubmitted under the same IDs after the source wallet was funded, and the second attempt went through. The payment status endpoint gives every attempt the item's own CreatedAt and CompletedAt, so they don't tell you when each attempt happened. Don't rely on the order of Attempts; sort them by AttemptNo. Unlike the event sent after a delivery to the destination, the payment status endpoint returns the recipient's account number in RecipientId. For the meaning of each status, see Batch and payment statuses.

If you need Xtrm to look into an item, give Xtrm support its CustomerBatchId and CustomerTransactionId.

#Build a receiver

We recommend this sequence for every delivery:

  1. Read the raw body

    Read the request body as bytes and keep them. Don't let your framework parse the JSON first.

  2. Verify the signature

    Check X-Signature against the raw body and your secret, as in Verify the signature. If it fails, respond with 401 and stop.

  3. De-duplicate

    If you've already recorded the X-Event-Id, respond with 200 and stop.

  4. Store the event and acknowledge it

    Save the event durably, then respond with 200 and a short or empty body within a few seconds, well inside the 10 seconds Xtrm waits. Leave anything slow, such as calls to other systems, for later.

  5. Process and reconcile

    Process the stored event in a background job: update your records, and check the status endpoints whenever you need the current state of an item. An event can name a batch or payment you have no record of, for example one that was already being processed when your subscription was switched on, or one submitted by another system that uses your company account. Don't treat it as an error: look it up with the status endpoints if you need it.

The samples below are minimal receivers that follow these steps on http://localhost:8080/webhooks/xtrm. They listen on your machine only, reject a request body larger than 1 MiB as a precaution, keep the event IDs they've seen in memory or in temporary files, and log each event; in production, store events and their IDs in a database. Their handlers read a Batch.Item.Completed by its Status, and flag one with DeliveryType Wallet for a method other than XTR94502 or XTR94504: its delivery to the destination didn't go through, so the payment stays RetainedInWallet. The Java handler reads fields with a small regular expression so that it needs no dependencies; use a JSON library in production. Put the receiver behind HTTPS before you register its URL.

Set XTRM_WEBHOOK_SECRET to your endpoint's signing secret before you start one. The receivers check the timestamp window only when you also set XTRM_WEBHOOK_TOLERANCE_SECONDS; we recommend 300. Because Xtrm signs every attempt with a new t, the window doesn't reject retries. When the window rejects a delivery whose signature is valid, the receivers log it, so you can tell a stale delivery from a forged one.

cURL can't receive webhooks, so the cURL tab does the opposite: it signs a test Batch.Item.Completed event with XTRM_WEBHOOK_SECRET and sends it to a receiver running on your machine. Send it twice to see the duplicate handling.

# Sends a signed test Batch.Item.Completed event to a receiver on your machine.
# Start a receiver from another tab first, with the same XTRM_WEBHOOK_SECRET.
: "${XTRM_WEBHOOK_SECRET:?Set XTRM_WEBHOOK_SECRET to the signing secret of the receiver}"
RAW_BODY='{"CustomerBatchId":"BATCH-WEBHOOK-0001","CustomerTransactionId":"TXN-WEBHOOK-0001","Status":"Success","Amount":100.00,"Currency":"USD","SendMethodId":"XTR94500","RecipientId":"100245","DeliveryType":"Bank","AttemptNo":2,"LastUpdatedAt":"2025-10-29T13:02:23Z"}'
T=$(date +%s)
SIGNATURE=$(printf '%s.%s' "$T" "$RAW_BODY" | openssl dgst -sha256 -hmac "$XTRM_WEBHOOK_SECRET" | sed 's/^.*= //')

curl -sS -i -X POST "http://localhost:8080/webhooks/xtrm" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Event-Id: 7d2f4c1e-9a3b-4e6f-8c51-2b0a9e7d3f14" \
  -H "X-Event-Type: Batch.Item.Completed" \
  -H "X-Event-Timestamp: $(date -u +%Y-%m-%dT%H:%M:%S.0000000Z)" \
  -H "X-Retry-Count: 1" \
  -H "X-Signature: t=$T, v1=$SIGNATURE" \
  --data-binary "$RAW_BODY"

#Next steps