Skip to main content
WEBHOOK
card.transaction.approved
{
  "event": "card.transaction.approved",
  "version": "3.0",
  "eventId": "c9d0e1f2-a3b4-5678-2345-6789abcdef01",
  "sign": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "data": {
    "cardId": "a4e8f2b6c9d1e3f7a2b5c8d0e4f1a3b6c9d2e5f8a1b4c7d0e3",
    "cardholderId": "8f4e2a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d",
    "reference": "hos_tx_a4e8f2b6_20260510143200",
    "originalReference": null,
    "type": "DEBIT",
    "amount": 49.99,
    "currency": "USD",
    "merchant": {
      "name": "AMAZON MARKETPLACE",
      "country": "US",
      "mcc": "5999"
    },
    "category": "Card Charge",
    "network": "VISA",
    "authorizationCode": "AUTH123",
    "status": "PENDING",
    "appId": "A1B2C3D4E5F6G7H8",
    "timestamp": "2026-05-10T14:32:00Z"
  }
}

{}

{
  "event": "card.transaction.approved",
  "version": "3.0",
  "eventId": "c9d0e1f2-a3b4-5678-2345-6789abcdef01",
  "sign": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "data": {
    "cardId": "a4e8f2b6c9d1e3f7a2b5c8d0e4f1a3b6c9d2e5f8a1b4c7d0e3",
    "cardholderId": "8f4e2a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d",
    "reference": "hos_tx_a4e8f2b6_20260510143200",
    "originalReference": null,
    "type": "DEBIT",
    "amount": 49.99,
    "currency": "USD",
    "merchant": {
      "name": "AMAZON MARKETPLACE",
      "country": "US",
      "mcc": "5999"
    },
    "category": "Card Charge",
    "network": "VISA",
    "authorizationCode": "AUTH123",
    "status": "PENDING",
    "appId": "A1B2C3D4E5F6G7H8",
    "timestamp": "2026-05-10T14:32:00Z"
  }
}

{}

​
Event Flow

Card charge events follow a two-phase pattern:
  1. PENDING — sent immediately when the authorization is captured (before settlement). status is "PENDING".
  2. APPROVED — sent again when the charge settles. status is "APPROVED".
If the original authorization is reversed at settlement, the second event has status: "REVERSED" (see card.transaction.reversed for a standalone reversal). Fee events (Cross-border Fee, Decline Fee (Domestic), Decline Fee (International)) are always sent with status: "APPROVED" and include originalReference pointing to the charge that triggered the fee.

​
Payload Fields

FieldTypeDescription
cardIdstringYour card identifier
cardholderIdstringCardholder identifier
referencestring | nullUnique transaction reference
originalReferencestring | nullReference of the parent charge (fee events only)
typestringAlways "DEBIT"
amountnumberTransaction amount
currencystringCurrency code (e.g., "USD")
merchant.namestringMerchant name
merchant.countrystring | nullMerchant country code
merchant.mccstring | nullMerchant category code
categorystringOne of: "Card Charge", "Cross-border Fee", "Decline Fee (Domestic)", "Decline Fee (International)"
networkstring | nullCard network (e.g., "VISA", "MASTERCARD")
authorizationCodestring | nullAuthorization code from the network
statusstring"PENDING", "APPROVED", or "REVERSED"

Body

application/json
​
event
string

The event type identifier (e.g. card.funded).

​
version
string

Webhook payload version.

​
sign
string

HMAC-SHA256 signature of the data object using your webhook secret. Always verify this before processing.

​
data
object

Response

200

Acknowledge receipt of the event