> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Card Transaction Approved
> Sent when a card charge is approved at the point of sale or online, and also when fee charges (cross-border, decline fees) are applied to a business card.
```json Webhook Payload (Card Charge — Pending) theme={null}
{
"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"
}
}
```
```json Webhook Payload (Card Charge — Approved) theme={null}
{
"event": "card.transaction.approved",
"version": "3.0",
"eventId": "d1e2f3a4-b5c6-7890-3456-789abcdef012",
"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": "APPROVED",
"appId": "A1B2C3D4E5F6G7H8",
"timestamp": "2026-05-10T14:35:00Z"
}
}
```
```json Webhook Payload (Cross-border Fee) theme={null}
{
"event": "card.transaction.approved",
"version": "3.0",
"eventId": "e2f3a4b5-c6d7-8901-4567-89abcdef0123",
"sign": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
"data": {
"cardId": "a4e8f2b6c9d1e3f7a2b5c8d0e4f1a3b6c9d2e5f8a1b4c7d0e3",
"cardholderId": "8f4e2a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d",
"reference": "hos_fee_a4e8f2b6_20260510143300",
"originalReference": "hos_tx_a4e8f2b6_20260510143200",
"type": "DEBIT",
"amount": 1.50,
"currency": "USD",
"merchant": {
"name": "AMAZON MARKETPLACE",
"country": "US",
"mcc": "5999"
},
"category": "Cross-border Fee",
"network": null,
"authorizationCode": null,
"status": "APPROVED",
"appId": "A1B2C3D4E5F6G7H8",
"timestamp": "2026-05-10T14:35:01Z"
}
}
```
```json 200 theme={null}
{}
```
## 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
| Field | Type | Description |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `cardId` | string | Your card identifier |
| `cardholderId` | string | Cardholder identifier |
| `reference` | string \| null | Unique transaction reference |
| `originalReference` | string \| null | Reference of the parent charge (fee events only) |
| `type` | string | Always `"DEBIT"` |
| `amount` | number | Transaction amount |
| `currency` | string | Currency code (e.g., `"USD"`) |
| `merchant.name` | string | Merchant name |
| `merchant.country` | string \| null | Merchant country code |
| `merchant.mcc` | string \| null | Merchant category code |
| `category` | string | One of: `"Card Charge"`, `"Cross-border Fee"`, `"Decline Fee (Domestic)"`, `"Decline Fee (International)"` |
| `network` | string \| null | Card network (e.g., `"VISA"`, `"MASTERCARD"`) |
| `authorizationCode` | string \| null | Authorization code from the network |
| `status` | string | `"PENDING"`, `"APPROVED"`, or `"REVERSED"` |
## OpenAPI
````yaml v3/openapi.json webhook card.transaction.approved
openapi: 3.1.0
info:
title: FYATU API v3
description: >-
FYATU API v3 with JWT authentication for Collections, Payouts, and Card
Issuing.
version: 3.0.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3
description: Production
security: []
tags:
- name: Authentication
description: JWT token management endpoints
- name: Account
description: Business account, wallet, and address management
- name: Collections
description: Accept payments from customers via checkout sessions
- name: Refunds
description: Issue refunds for completed collections
- name: Payouts
description: Send money to Fyatu account holders
- name: Cardholders
description: Cardholder management for card issuing programs
- name: Cards
description: Issue, fund, freeze, and manage virtual cards
- name: Webhooks
description: Webhook configuration and management
paths: {}
````