> ## 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.

# Transactions

> How card transactions flow from authorization to clearing. Transaction types, statuses, merchant data, and the AUTHORIZATION → CLEARING lifecycle every integration must understand.

# Transactions

A **transaction** is a card spend event recorded from the card network. Every swipe, tap, or online purchase generates one or more transaction records in the CaaS API. Transactions are **append-only** — they are never edited or deleted. A reversal creates a new record, not a modification of the original.

## Transaction Types

| Type            | Description                                                                    |
| --------------- | ------------------------------------------------------------------------------ |
| `AUTHORIZATION` | Real-time approval request from a merchant — a hold placed on the card balance |
| `CLEARING`      | Actual settlement of a prior authorization — the money leaves the card         |
| `REVERSAL`      | Cancellation of a prior transaction — balance is restored                      |
| `FEE`           | A fee charged by FYATU (e.g. cross-border fee)                                 |

## Transaction Statuses

| Status     | Description                                                                           |
| ---------- | ------------------------------------------------------------------------------------- |
| `APPROVED` | Transaction was approved and processed                                                |
| `DECLINED` | Transaction was rejected (insufficient balance, frozen card, or card network decline) |
| `REVERSED` | Transaction was reversed — the amount was returned to the card                        |

## The Authorization → Clearing Lifecycle

Understanding how authorizations and clearings relate is critical for reconciling card spend.

```
Cardholder pays at merchant
          │
          ▼
  AUTHORIZATION created                ← status: APPROVED, amount: $42.00
  Card balance HELD (not debited)        "Hold" reduces available balance

          │  (1–5 business days)
          ▼
  CLEARING created                     ← status: APPROVED, amount: $41.80*
  Card balance DEBITED                   Actual settled amount
  Original authorization REVERSED      ← The hold is released
  relatedTransactionId → authorization ID

* Settlement amount can differ slightly from authorization (e.g. currency conversion, gratuity)
```

### What "available balance" means

When an authorization is placed, the card's available balance drops immediately. The funds are not debited until clearing. Between authorization and clearing:

* Available balance = Total balance − sum of pending authorization holds
* If you call `GET /cards/{id}` the balance reflects this

### Declined Authorizations

A declined authorization has `type: AUTHORIZATION` and `status: DECLINED`. The `declineReason` field contains a brief reason code from the card network (e.g. `INSUFFICIENT_FUNDS`, `CARD_FROZEN`, `INVALID_CARD`).

A declined authorization does not affect balance — no hold is placed.

### Reversals

A reversal always has a `relatedTransactionId` pointing to the original transaction it reverses. Reversals are generated by:

* The merchant cancelling an authorization before it clears
* A post-clearing refund processed by the merchant
* FYATU reversing a fee on dispute

```json theme={null}
{
  "transactionId":       "txn_01HXYZ7777ABCDEF9999",
  "type":                "REVERSAL",
  "status":              "APPROVED",
  "relatedTransactionId": "txn_01HXYZ7777ABCDEF1234",
  "amount": {
    "value":        4200,
    "currency":     "USD",
    "displayValue": "42.00"
  }
}
```

## Amount Fields

Each transaction exposes two amount blocks:

| Field                    | Description                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `amount.value`           | Transaction amount in cents, in the **card's currency** (e.g. USD)                 |
| `amount.currency`        | Card currency code                                                                 |
| `amount.displayValue`    | Human-readable string, e.g. `"42.00"`                                              |
| `billingAmount.value`    | Amount in the **merchant's billing currency** (only for cross-border transactions) |
| `billingAmount.currency` | Merchant billing currency                                                          |
| `exchangeRate`           | Rate applied for cross-border conversion (`null` for same-currency transactions)   |

For domestic transactions, `amount` and `billingAmount` are the same currency and `exchangeRate` is `null`. For cross-border (e.g. a USD card used at a EUR merchant), `billingAmount` reflects the EUR amount and `exchangeRate` shows the conversion rate applied.

## Merchant Data

Transactions include structured merchant information when available from the card network:

| Field                     | Example                                     | Description                                |
| ------------------------- | ------------------------------------------- | ------------------------------------------ |
| `merchant.name`           | `AMAZON.COM`                                | Merchant name as reported by the network   |
| `merchant.city`           | `Seattle`                                   | Merchant city                              |
| `merchant.country`        | `US`                                        | ISO 3166-1 alpha-2 country code            |
| `merchant.mcc`            | `5999`                                      | Merchant Category Code (4-digit ISO 18245) |
| `merchant.mccDescription` | `Miscellaneous and Specialty Retail Stores` | Human-readable MCC description             |

MCC codes are useful for categorizing spend (e.g. detecting travel, entertainment, or utility payments in your dashboard).

## Transaction Webhook Events

You receive real-time webhook notifications for every significant transaction event:

| Event                   | Fired when                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `TRANSACTION_PROCESSED` | A card transaction was processed. Branch on `status`: `COMPLETED`, `REVERSED`, or `ADJUSTED`. |
| `TRANSACTION_DECLINED`  | Authorization declined by the card network                                                    |
| `TRANSACTION_FEE`       | A FYATU fee is charged to the card                                                            |

A card charge is delivered as a **single** `TRANSACTION_PROCESSED` event — there is no
separate authorization-then-settlement pair. Use the `status` field to tell apart a
completed charge (`COMPLETED`), a reversal/refund (`REVERSED`), and an FX settlement
adjustment (`ADJUSTED`).

<Note>
  `TRANSACTION_AUTHORIZED`, `TRANSACTION_CLEARED`, and `TRANSACTION_REVERSED` are
  deprecated in favor of `TRANSACTION_PROCESSED`. They remain fully supported for
  existing integrations — no migration is required. New integrations should use
  `TRANSACTION_PROCESSED`.
</Note>

### Example: TRANSACTION\_PROCESSED webhook

```json theme={null}
{
  "event":       "TRANSACTION_PROCESSED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T14:30:00Z",
  "data": {
    "transactionId": "txn_01HXYZ7777ABCDEF1234",
    "cardId":        "crd_01HXYZ5555ABCDEF1111",
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "externalId":    null,
    "type":          "PURCHASE",
    "status":        "COMPLETED",
    "amount":         42.00,
    "currency":       "USD",
    "billingAmount":  42.00,
    "billingCurrency": "USD",
    "merchant": {
      "name":    "STARBUCKS",
      "country": "US",
      "mcc":     "5812"
    }
  }
}
```

## Querying Transactions

Transactions can be queried at two levels:

**All transactions across your program (scoped by API key environment):**

```bash theme={null}
GET /transactions?limit=20&offset=0&cardId=crd_01HXYZ...&type=AUTHORIZATION
```

**A single transaction:**

```bash theme={null}
GET /transactions/{id}
```

Available query filters for `GET /transactions`:

| Filter             | Description                                                    |
| ------------------ | -------------------------------------------------------------- |
| `cardId`           | Transactions for a specific card                               |
| `cardholderId`     | Transactions for all cards belonging to a cardholder           |
| `type`             | Filter by type: `AUTHORIZATION`, `CLEARING`, `REVERSAL`, `FEE` |
| `status`           | Filter by status: `APPROVED`, `DECLINED`, `REVERSED`           |
| `from`             | ISO 8601 start date filter (inclusive)                         |
| `to`               | ISO 8601 end date filter (inclusive)                           |
| `limit` / `offset` | Pagination (default: 20, max: 100)                             |

## Reconciliation Pattern

To reconcile what your cardholders have spent:

```javascript theme={null}
// 1. Fetch all CLEARING transactions in a date range
const txns = await fyatu.get('/transactions', {
  type:   'CLEARING',
  status: 'APPROVED',
  from:   '2026-05-01T00:00:00Z',
  to:     '2026-05-31T23:59:59Z',
});

// 2. Sum the amounts
const totalSpentCents = txns.data.reduce((sum, t) => sum + t.amount.value, 0);
console.log('Total cleared spend:', totalSpentCents / 100, 'USD');

// 3. Cross-check against program stats
const program = await fyatu.get('/programs/prg_01HXYZ...');
console.log('Program total spend:', program.data.stats.totalSpend.displayValue);
```

<Tip>
  Use `CLEARING` transactions (not `AUTHORIZATION`) for financial reconciliation. Authorizations represent intent; clearings represent actual settled spend.
</Tip>

## Endpoints

* `GET /transactions` — [List transactions](/v3.20/api-reference/transactions/list)
* `GET /transactions/{id}` — [Get transaction](/v3.20/api-reference/transactions/get)