{
  "type": "transaction",
  "data": {
    "id": "txn_internal_123",
    "transactionId": "dfe5be96-ad64-47f4-8a06-bf81ae23a21c",
    "cardId": "66db881b3b34fedf7ba11198",
    "amount": 100,
    "currency": "AED",
    "usdAmount": 27.3,
    "fee": 0,
    "merchant": "Blue Shop",
    "merchantId": "A1B2C3D456789",
    "merchantCountry": "ARE",
    "mcc": "5812",
    "transactionChannel": "POS",
    "type": "AUTHORIZATION",
    "status": "APPROVED",
    "transactionDate": "2026-04-16T12:34:56.000Z",
    "declineReason": "",
    "externalCardId": "",
    "additionalData": {}
  }
}

API Reference

Transaction event

Use this webhook to keep your product in sync with card activity in near real time.

What it represents

A single payment can evolve over time (authorization → cleared, or failed, plus possible reversals/refunds). Do not treat the first event you receive as final.

Refunds and reversals are emitted as their own transaction events.

Status and type

Use these fields to build your transaction timeline:

data.status:
- APPROVED: the transaction (or authorization) was approved
- FAILED: the transaction (or authorization) failed (see data.declineReason when present)
- CLEARED: the transaction is finalized/settled
data.type:
- AUTHORIZATION: an authorization attempt
- REVERSAL: a reversal/void of a previous authorization
- REFUND: funds returned to the cardholder

Correlation (`transactionId`)

For authorization and reversal events, data.transactionId can be the same, but it is not guaranteed. Use it as a best-effort correlation key and build your timeline using the event’s own stable identifiers.

Processing guidance

Acknowledge fast and process asynchronously (enqueue a job / persist then return 200).
Make processing idempotent (the same event can be delivered more than once).
Treat lifecycle changes as updates to the user’s transaction timeline.
Retries are not guaranteed. Use API backfill/polling for correctness when needed.

WEBHOOK

transaction

{
  "type": "transaction",
  "data": {
    "id": "txn_internal_123",
    "transactionId": "dfe5be96-ad64-47f4-8a06-bf81ae23a21c",
    "cardId": "66db881b3b34fedf7ba11198",
    "amount": 100,
    "currency": "AED",
    "usdAmount": 27.3,
    "fee": 0,
    "merchant": "Blue Shop",
    "merchantId": "A1B2C3D456789",
    "merchantCountry": "ARE",
    "mcc": "5812",
    "transactionChannel": "POS",
    "type": "AUTHORIZATION",
    "status": "APPROVED",
    "transactionDate": "2026-04-16T12:34:56.000Z",
    "declineReason": "",
    "externalCardId": "",
    "additionalData": {}
  }
}

Body

application/json

type

string

required

Discriminator for transaction events.

Allowed value: "transaction"

data

object

required

Transaction event payload.

Show child attributes

Response

200

Event accepted

Customer status update

⌘I