Transaction Reversed

transaction.reversed — delivered when a reversal's funds are back in your available USD
balance.

When it fires

When a transaction is reversed and its funds are back in your available USD balance. This covers
both cases:

The original had not posted yet — the hold placed at authorisation is released.

The original had already posted — the debited amount is credited back.

A reversal produces two events for the same transactionNo, and they mean different things:

Event	Meaning	Money moved?
`transaction.completed`	The reversal transaction has posted	Not necessarily yet
`transaction.reversed`	The funds are back in your available balance (hold released or amount credited back)	Yes

Returning the money is a separate step from recording the reversal, and it can lag behind. If it
does not succeed the first time it is retried independently, so the gap between the two events is
occasionally minutes rather than milliseconds.

Do not book both as separate movements. Use transaction.completed to learn that a reversal
exists, and this event to learn that the balance has actually changed.

Payload

Envelope

Field	Type	Description
`eventId`	string	Unique per event. Deduplicate on this value
`eventType`	string	Always `transaction.reversed`
`version`	string	Payload schema version. Additive changes do not bump it
`occurredAt`	string	When the funds were returned (hold released or amount credited back) — not when the reversal posted (ISO 8601)
`data`	object	The reversal transaction, see below

`data`

Structurally identical to the response of GET /api/v1/issuing/transaction/{transactionNo}, and
to the data of transaction.completed for the same transaction. One parser handles all paths.

Field	Type	Description
`transactionNo`	string	PIK transaction number of the reversal
`originalTransactionNo`	string	The transaction being reversed
`cardNo`	string	PIK card number
`cardholderNo`	string	PIK cardholder number
`type`	string	Always `REVERSAL` for this event
`status`	string	`COMPLETED`
`transactionAmount` / `transactionCurrency`	string	Amount and currency at the merchant
`billingAmount` / `billingCurrency`	string	Amount returned in the card's settlement currency
`fx`	object	Foreign exchange details
`fees`	array	Itemised fee breakdown
`totalFeeAmount`	string	Sum of all fee amounts
`totalDebitAmount`	string	`billingAmount` + `totalFeeAmount`
`merchant`	object	`name` / `mcc` / `city` / `country`
`transactionTime` / `postedTime`	string	Transaction and posting times
`declineReason`	string	`null` for this event

See Transaction Completed for the full field reference of fx
and fees[].

Example

{
  "eventId": "evt_01J9X8ZQ4T9P",
  "eventType": "transaction.reversed",
  "version": "1.0",
  "occurredAt": "2026-09-23T05:41:09Z",
  "data": {
    "transactionNo": "TX260923R4S6T2",
    "originalTransactionNo": "TX260811K3M5N1",
    "cardNo": "CD260811X9Y8Z7",
    "cardholderNo": "CH260811A1B2C3",
    "type": "REVERSAL",
    "status": "COMPLETED",
    "transactionAmount": "40.00",
    "transactionCurrency": "USD",
    "billingAmount": "40.00",
    "billingCurrency": "USD",
    "fx": {
      "isCrossCurrency": false,
      "rate": "1.00000000"
    },
    "fees": [],
    "totalFeeAmount": "0.00",
    "totalDebitAmount": "40.00",
    "merchant": {
      "name": "STEAM PURCHASE",
      "mcc": "5734",
      "city": "Singapore",
      "country": "SG"
    },
    "transactionTime": "2026-09-23T05:40:55Z",
    "postedTime": "2026-09-23T05:40:58Z",
    "declineReason": null
  }
}

Verifying the signature

Three headers accompany every delivery:

Header	Value
`X-Webhook-Event`	Event category, always `ISSUING` for this event
`X-Webhook-Event-Type`	The specific event type, see above
`X-Webhook-Signature`	HMAC-SHA256 signature, lowercase hex

X-Webhook-Signature = hex_lower( HMAC_SHA256( appSecret, rawBody ) )

The signed content is the raw request body only, with no timestamp and no separator. The signing
key is your appSecret — there is no separate webhook secret.

Sign the raw bytes of the request body, before any JSON parsing.

Compare in constant time.

Nothing time-based is signed, so a captured delivery stays replayable — deduplicating on
eventId is mandatory, not optional.

Delivery

Return any 2xx within 10 seconds to acknowledge.

Failed deliveries are retried on a fixed interval: 5 attempts, 5 minutes apart (about
20 minutes in total), after which the event is marked exhausted and never retried again.

This endpoint receives Issuing events only; still return 2xx for event types you do not handle.

Delivery is at least once — deduplicate on eventId.

Ordering is not guaranteed — use occurredAt to decide which version is newer. In particular,
do not assume this event arrives after the matching transaction.completed.

Treat transactionNo as the business key; a transaction generates several events.

See the Webhooks guide for verification code samples and recommended
handling.

Transaction Reversed

When it fires#

Payload#

Envelope#

data#

Example#

Verifying the signature#