Transaction Events

Transaction events fire in real time as card activity occurs on the Visa/Mastercard network. Subscribe to these events to build live transaction feeds, send push notifications, and enforce spending controls. All transaction events share the same outer envelope:

{
  "event":       "TRANSACTION_AUTHORIZED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T10:00:00Z",
  "data": { ... }
}

TRANSACTION_AUTHORIZED

When it fires

Fires when a cardholder makes a purchase and the authorization is approved. The funds are reserved on the card but not yet permanently settled — a subsequent TRANSACTION_CLEARED event confirms final settlement. This is the earliest signal that a transaction has occurred. Use it to show pending activity in real time.

Payload

{
  "event":       "TRANSACTION_AUTHORIZED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T10:00:00Z",
  "data": {
    "transactionId":        "txn_01HXYZ8888ABCDEF9999",
    "cardId":               "crd_01HXYZ5555ABCDEF1111",
    "programId":            "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":         "chl_01HXYZ1234ABCDEF5678",
    "externalId":           "my-user-id-789",
    "type":                 "AUTHORIZATION",
    "status":               "PENDING",
    "amountCents":          2999,
    "currency":             "USD",
    "billingAmountCents":   2999,
    "billingCurrency":      "USD",
    "exchangeRate":         null,
    "relatedTransactionId": null,
    "merchant": {
      "name":           "Amazon",
      "id":             "AMZN_MERCHANT_001",
      "city":           "Seattle",
      "country":        "US",
      "mcc":            "5999",
      "mccDescription": "Miscellaneous General Merchandise"
    }
  }
}

Payload fields

Field	Type	Description
`transactionId`	string	Unique transaction identifier
`cardId`	string	The card used
`programId`	string	The card’s program
`cardholderId`	string	The cardholder (best-effort — may be absent if not resolvable)
`externalId`	string or null	Your internal user ID from the cardholder profile
`type`	string	Always `AUTHORIZATION` for this event
`status`	string	Always `PENDING` for this event
`amountCents`	integer	Transaction amount in cents
`currency`	string	Transaction currency (ISO 4217)
`billingAmountCents`	integer	Amount in the card’s billing currency (in cents)
`billingCurrency`	string	Card billing currency (may differ for cross-border transactions)
`exchangeRate`	number or null	FX rate applied — null for same-currency
`relatedTransactionId`	string or null	Always null for authorizations
`merchant`	object	Merchant details — may be absent for non-purchase transactions
`merchant.name`	string	Merchant name
`merchant.id`	string	Merchant identifier from the network
`merchant.city`	string	Merchant city
`merchant.country`	string	Merchant country (ISO 3166-1 alpha-2)
`merchant.mcc`	string	ISO 18245 Merchant Category Code
`merchant.mccDescription`	string	Human-readable MCC description

Common use cases

Show a “Pending” transaction in the cardholder’s transaction history
Send a real-time push notification: “$29.99 at Amazon — pending”
Implement MCC-based spending controls (alert or block certain categories)

TRANSACTION_CLEARED

When it fires

Fires when a pending authorization is settled by the merchant. This is the final, permanent state — funds are now permanently debited from the card. The relatedTransactionId links back to the original TRANSACTION_AUTHORIZED event.

Payload

{
  "event":       "TRANSACTION_CLEARED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T12:00:00Z",
  "data": {
    "transactionId":        "txn_01HXYZ7777ABCDEF9999",
    "cardId":               "crd_01HXYZ5555ABCDEF1111",
    "programId":            "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":         "chl_01HXYZ1234ABCDEF5678",
    "externalId":           "my-user-id-789",
    "type":                 "CLEARING",
    "status":               "SETTLED",
    "amountCents":          2999,
    "currency":             "USD",
    "billingAmountCents":   2999,
    "billingCurrency":      "USD",
    "exchangeRate":         null,
    "relatedTransactionId": "txn_01HXYZ8888ABCDEF9999",
    "merchant": {
      "name":           "Amazon",
      "id":             "AMZN_MERCHANT_001",
      "city":           "Seattle",
      "country":        "US",
      "mcc":            "5999",
      "mccDescription": "Miscellaneous General Merchandise"
    }
  }
}

Payload fields

Field	Type	Description
`transactionId`	string	Unique transaction identifier for this clearing event
`relatedTransactionId`	string	The original `TRANSACTION_AUTHORIZED` transaction ID
`type`	string	Always `CLEARING` for this event
`status`	string	Always `SETTLED` for this event
All other fields	—	Same as `TRANSACTION_AUTHORIZED`

Common use cases

Move the transaction from “Pending” to “Settled” in your UI
Update your ledger or reporting systems with the final settled amount
Note: the settled amount may differ slightly from the authorized amount (tip adjustments, etc.)

TRANSACTION_REVERSED

When it fires

Fires when a previously cleared (or authorized) transaction is reversed. This typically occurs when a merchant issues a refund or when the authorization expires without a clearing.

Payload

{
  "event":       "TRANSACTION_REVERSED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T14:00:00Z",
  "data": {
    "transactionId":        "txn_01HXYZ6666ABCDEF9999",
    "cardId":               "crd_01HXYZ5555ABCDEF1111",
    "programId":            "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":         "chl_01HXYZ1234ABCDEF5678",
    "externalId":           "my-user-id-789",
    "type":                 "REVERSAL",
    "status":               "REVERSED",
    "amountCents":          2999,
    "currency":             "USD",
    "billingAmountCents":   2999,
    "billingCurrency":      "USD",
    "exchangeRate":         null,
    "relatedTransactionId": "txn_01HXYZ7777ABCDEF9999",
    "merchant": {
      "name":           "Amazon",
      "id":             "AMZN_MERCHANT_001",
      "city":           "Seattle",
      "country":        "US",
      "mcc":            "5999",
      "mccDescription": "Miscellaneous General Merchandise"
    }
  }
}

Payload fields

Field	Type	Description
`transactionId`	string	Unique transaction identifier for this reversal event
`relatedTransactionId`	string	The original transaction that was reversed
`type`	string	Always `REVERSAL` for this event
`status`	string	Always `REVERSED` for this event
`amountCents`	integer	Amount reversed (returned to the card) in cents
All other fields	—	Same as `TRANSACTION_AUTHORIZED`

Common use cases

Mark the original transaction as refunded in your cardholder’s history
Notify the cardholder: “Your $29.99 refund from Amazon has been processed”
Update running balance displays

TRANSACTION_DECLINED

When it fires

Fires when a card authorization is declined. The decline may originate from FYATU (insufficient balance, frozen card) or from the card network (merchant restrictions, limits).

No funds are moved on a decline. The card balance is unchanged.

Payload

{
  "event":       "TRANSACTION_DECLINED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T10:00:00Z",
  "data": {
    "transactionId":  "txn_01HXYZ5555ABCDEF9999",
    "cardId":         "crd_01HXYZ5555ABCDEF1111",
    "programId":      "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":   "chl_01HXYZ1234ABCDEF5678",
    "externalId":     "my-user-id-789",
    "type":           "DECLINE",
    "status":         "DECLINED",
    "amountCents":    2999,
    "currency":       "USD",
    "declineReason":  "INSUFFICIENT_BALANCE",
    "merchant": {
      "name":           "Netflix",
      "id":             "NFLX_MERCHANT_001",
      "city":           "Los Gatos",
      "country":        "US",
      "mcc":            "7812",
      "mccDescription": "Motion Picture Theaters"
    }
  }
}

Payload fields

Field	Type	Description
`transactionId`	string	Unique transaction identifier for this decline event
`type`	string	Always `DECLINE` for this event
`status`	string	Always `DECLINED` for this event
`amountCents`	integer	Amount that was attempted in cents
`declineReason`	string	Machine-readable decline reason — see values below
All other fields	—	Same as `TRANSACTION_AUTHORIZED`

Decline reason values:

Value	Meaning
`INSUFFICIENT_BALANCE`	Card balance too low for the purchase
`CARD_FROZEN`	Card is frozen — no new transactions permitted
`CARD_TERMINATED`	Card has been terminated
`CARDHOLDER_SUSPENDED`	Cardholder account is suspended
`MERCHANT_BLOCKED`	Merchant is on a block list for this program
`MCC_BLOCKED`	Merchant Category Code is blocked for this program
`VELOCITY_EXCEEDED`	Transaction velocity limit exceeded
`NETWORK_DECLINED`	Declined by the card network (reason opaque)
`FRAUD_SUSPECTED`	Suspected fraud — automatic decline
`EXPIRED_CARD`	Card has passed its expiry date

Common use cases

Notify the cardholder in real time: “Your $29.99 payment at Netflix was declined — insufficient balance”
Prompt the cardholder to top up their card
Log decline patterns to detect fraud or program configuration issues

TRANSACTION_FEE

When it fires

Fires when a fee is posted against the card. This includes cross-border transaction fees, decline fees, and any other card-level fee configured for the program.

Payload

{
  "event":       "TRANSACTION_FEE",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T10:00:00Z",
  "data": {
    "transactionId":        "txn_01HXYZ4444ABCDEF9999",
    "cardId":               "crd_01HXYZ5555ABCDEF1111",
    "programId":            "prg_01HXYZ9876ABCDEF0000",
    "cardholderId":         "chl_01HXYZ1234ABCDEF5678",
    "externalId":           "my-user-id-789",
    "type":                 "FEE",
    "status":               "SETTLED",
    "amountCents":          150,
    "currency":             "USD",
    "feeType":              "CROSS_BORDER",
    "relatedTransactionId": "txn_01HXYZ7777ABCDEF9999"
  }
}

Payload fields

Field	Type	Description
`transactionId`	string	Unique transaction identifier for this fee event
`type`	string	Always `FEE` for this event
`status`	string	Always `SETTLED` for this event
`amountCents`	integer	Fee amount in cents
`feeType`	string	Type of fee — see values below
`relatedTransactionId`	string or null	The transaction that triggered the fee, if applicable
All other fields	—	Same as `TRANSACTION_AUTHORIZED`

Fee type values:

Value	Meaning
`CROSS_BORDER`	International transaction fee
`DECLINE`	Fee charged for declined authorization
`MAINTENANCE`	Periodic card maintenance fee
`REPLACEMENT`	Fee for card replacement
`ATM_WITHDRAWAL`	ATM cash withdrawal fee
`OTHER`	Other fee type — see your program agreement

Common use cases

Show fees as separate line items in the cardholder’s transaction history
Sum fees for billing transparency and reconciliation

Documentation Index

​Transaction Events

​TRANSACTION_AUTHORIZED

​When it fires

​Payload

​Payload fields

​Common use cases

​TRANSACTION_CLEARED

​When it fires

​Payload

​Payload fields

​Common use cases

​TRANSACTION_REVERSED

​When it fires

​Payload

​Payload fields

​Common use cases

​TRANSACTION_DECLINED

​When it fires

​Payload

​Payload fields

​Common use cases

​TRANSACTION_FEE

​When it fires

​Payload

​Payload fields

​Common use cases

Transaction Events

TRANSACTION_AUTHORIZED

When it fires

Payload

Payload fields

Common use cases

TRANSACTION_CLEARED

When it fires

Payload

Payload fields

Common use cases

TRANSACTION_REVERSED

When it fires

Payload

Payload fields

Common use cases

TRANSACTION_DECLINED

When it fires

Payload

Payload fields

Common use cases

TRANSACTION_FEE

When it fires

Payload

Payload fields

Common use cases