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

{
  "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).

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.

Example: TRANSACTION_PROCESSED webhook

{
  "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):

GET /transactions?limit=20&offset=0&cardId=crd_01HXYZ...&type=AUTHORIZATION

A single transaction:

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:

// 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);

Use CLEARING transactions (not AUTHORIZATION) for financial reconciliation. Authorizations represent intent; clearings represent actual settled spend.

Endpoints

GET /transactions — List transactions
GET /transactions/{id} — Get transaction

Getting Started

Concepts

Transactions

Transactions

Transaction Types

Transaction Statuses

The Authorization → Clearing Lifecycle

What “available balance” means

Declined Authorizations

Reversals

Amount Fields

Merchant Data

Transaction Webhook Events

Example: TRANSACTION_PROCESSED webhook

Querying Transactions

Reconciliation Pattern

Endpoints

​Transactions

​Transaction Types

​Transaction Statuses

​The Authorization → Clearing Lifecycle

​What “available balance” means

​Declined Authorizations

​Reversals

​Amount Fields

​Merchant Data

​Transaction Webhook Events

​Example: TRANSACTION_PROCESSED webhook

​Querying Transactions

​Reconciliation Pattern

​Endpoints

Transactions

Transaction Types

Transaction Statuses

The Authorization → Clearing Lifecycle

What “available balance” means

Declined Authorizations

Reversals

Amount Fields

Merchant Data

Transaction Webhook Events

Example: TRANSACTION_PROCESSED webhook

Querying Transactions

Reconciliation Pattern

Endpoints