Transaction

Overview of the Transaction Event Type

The transaction webhook is triggered when a specific event occurs in the transaction lifecycle. A transaction can go through multiple stages, such as Authorization, Clearing, Reversal, and Refund, each of which triggers a corresponding webhook event.

Transaction Lifecycle Events

Transaction Lifecycle Event	Transaction Webhook `eventName`	Description
Authorization	`authorization`	Triggered when a transaction is authorized.
Clearing	`authorization.clearing`	Triggered when an authorized transaction amount is cleared.
Transaction Decline	`authorization.advice`	Triggered when a transaction is declined.
Reversal	`authorization.reversal`	Triggered when an authorized transaction is reversed.
Refund	`refund`	Triggered when a transaction is refunded.

What You Can Do With This Webhook

Instant Notifications – Receive real-time updates on transactions, flag fraud, and monitor activity.
Enhanced Cardholder Experience – Notify users of successful transactions, declines, or required actions.
Automated Workflows – Integrate transaction data into your system and trigger actions based on event types.
Targeted Monitoring – Focus on specific transaction types or statuses to maintain security and compliance.

Sample Webhook Payload

{
  "eventName": "authorization", 
  "eventType": "transaction", 
  "data": {
    "id": "tid_5sgKF4HjD1"
  },
  "fees": {
    "fx_fees": "0.00",
    "atm_fees": "0.00"
  },
  "status": "PENDING",
  "wallet": null,
  "card_id": "85d5407f-5388-4c3d-97d1-bcaef3a5f68f",
  "channel": "ECOMMERCE",
  "cleared_at": null, 
  "created_at": "2025-02-04T07:28:04.362Z",
  "bill_amount": 500,
  "bill_currency": "840",
  "merchant_data": {
    "mcc_code": "5732",
    "merchant_id": "311178830000",
    "mcc_category": "Electronics Stores",
    "merchant_city": "www.merchant.com",
    "merchant_name": "Merchant",
    "merchant_country": "HKG"
  },
  "transaction_amount": 500,
  "transaction_currency": "840"
}

Webhook Event Fields

Field	Description	Possible Values
`eventName`	Name of the webhook event.	`authorization` \| `authorization.advice` \| `authorization.reversal` \| `authorization.clearing` \| `refund`
`eventType`	Type of webhook event.	`transaction`
`data.id`	Unique identifier for the transaction lifecycle.	`String` (e.g., `tid_5sgKF4HjD1`)
`fees.fx_fees`	Foreign exchange (FX) fees incurred.	`String` (e.g., `0.00`)
`fees.atm_fees`	ATM withdrawal fees incurred.	`String` (e.g., `0.00`)
`status`	The current status of the transaction event.	`PENDING` \| `CLEARED` \| `DECLINED` \| `VOID`
`wallet`	Mobile wallet used for this transaction.	`android` \| `apple` \| `null`
`card_id`	Unique identifier of the card used in this transaction.	`String`
`channel`	Payment channel used.	`ATM` \| `POS` \| `ECOMMERCE` \| `VISA_DIRECT`
`created_at`	Timestamp when the transaction was created.	`ISO 8601 format`
`cleared_at`	Timestamp when the transaction was cleared (if applicable).	`ISO 8601 format` \| `null`
`bill_currency`	Currency of the cardholder’s account.	`ISO 4217 currency code` (e.g., `840` for USD)
`bill_amount`	Amount billed in the cardholder’s currency.	`Float`
`merchant_data.mcc_code`	Merchant Category Code (MCC).	`String` (e.g., `5732`)
`merchant_data.merchant_id`	Unique identifier of the merchant.	`String` (e.g., `311178830000`)
`merchant_data.mcc_category`	Business category of the merchant.	`String` (e.g., `Electronics Stores`)
`merchant_data.merchant_city`	Registered city of the merchant.	`String` (e.g., `Manchester`)
`merchant_data.merchant_name`	Registered name of the merchant.	`String` (e.g., `ABC Company`)
`merchant_data.merchant_country`	Merchant's country.	`ISO 3166-1 Alpha-2`
`transaction_amount`	Amount charged in the merchant's currency.	`Float`
`transaction_currency`	Currency used by the merchant.	`ISO 4217 currency code` (e.g., `840` for USD)

Transaction Status & Event Mapping

`eventName`	Status
`authorization`	`PENDING`, `VOID`
`authorization.clearing`	`CLEARED`
`authorization.reversal`	`PENDING`, `VOID`
`authorization.advice`	`DECLINED`
`refund`	`CLEARED`