> ## 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.
# TRANSACTION_PROCESSED
> The card-transaction lifecycle event. The status field carries the phase — AUTHORIZED, CLEARED, REVERSED, REFUNDED, or ADJUSTED.
Fires as a cardholder's transaction moves through its lifecycle. `TRANSACTION_PROCESSED`
is the single, canonical event type for card transactions — you may receive it **more
than once for the same purchase** as it progresses.
Every payload has two fields you branch on:
* **`type`** — *what kind* of transaction it is: `PURCHASE`, `REVERSAL`, `REFUND`, or `ADJUSTMENT`.
* **`status`** — *which lifecycle phase / outcome* it represents.
They always pair together as follows:
| `type` | `status` | Meaning |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------ |
| `PURCHASE` | `AUTHORIZED` | The charge was authorized — a hold. Funds are reserved but **not yet final**. |
| `PURCHASE` | `CLEARED` | The charge **settled**. This is the final, captured amount — **mark the transaction successful here**. |
| `REVERSAL` | `REVERSED` | An authorization was voided **before** it cleared — the hold is released. |
| `REFUND` | `REFUNDED` | A merchant **refund** after the charge cleared — funds returned to the card. |
| `ADJUSTMENT` | `ADJUSTED` | An FX settlement adjustment was applied to a prior charge. |
A `PURCHASE` therefore progresses `AUTHORIZED` → `CLEARED`; the other types are terminal.
## The authorization → clearing flow
A typical purchase produces **two** `TRANSACTION_PROCESSED` events:
1. `status: AUTHORIZED` when the cardholder pays (a hold is placed).
2. `status: CLEARED` when the merchant settles — often a few days later, and sometimes
for a **slightly different amount** (currency conversion, tips). The `CLEARED` amount
is the real, final figure.
Both events carry the same **`authorizationCode`**, so you can correlate the phases and
act on the `CLEARED` one.
Some merchants settle almost immediately (you'll see `CLEARED` right away); others
authorize and settle days apart. Always key your "transaction complete" logic off
`status: CLEARED`, never `AUTHORIZED`.
## Correlation fields
| Field | Present on | Description |
| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `authorizationCode` | `AUTHORIZED`, `CLEARED`, `REVERSED` | Stable across a purchase's lifecycle — **group events by this to reconstruct one purchase**. |
| `relatedTransactionId` | `CLEARED`, `REVERSED`, `REFUNDED` | The transaction this one relates to — the authorization for a clearing, or the charge for a reversal. |
| `chargeId` | `REVERSED` | The specific charge that a reversal undoes. |
## Payload — settlement (`status: CLEARED`)
```json theme={null}
{
"event": "TRANSACTION_PROCESSED",
"eventId": "EVT2W9SK2233S4C",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-07-07T21:55:41Z",
"data": {
"transactionId": "237bc8d1-5b20-4d6b-8ade-059e8dd903ca",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "PURCHASE",
"status": "CLEARED",
"amount": 13.68,
"currency": "USD",
"billingAmount": 13.68,
"billingCurrency": "USD",
"authorizationCode": "21e2c774-66ac-4b09-9d9d-3abe0f944bda",
"relatedTransactionId": "21e2c774-66ac-4b09-9d9d-3abe0f944bda",
"merchant": {
"name": "ZYNGA - EMPIRES & PUZZ",
"id": "EUXEITE8IZPSUAW",
"country": "IE",
"mcc": "5816"
}
}
}
```
## Payload — reversal (`status: REVERSED`)
A reversal carries `chargeId` (the charge it undoes) and `relatedTransactionId`; a
`REFUNDED` payload has the same shape with `status: REFUNDED` and `type: REFUND`.
```json theme={null}
{
"event": "TRANSACTION_PROCESSED",
"eventId": "EVT7Q2X9K4M8ND3",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-07-08T19:45:06Z",
"data": {
"transactionId": "57f1ffae-e0af-41be-9e02-3517bc737661",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "REVERSAL",
"status": "REVERSED",
"amount": 0.85,
"currency": "USD",
"billingAmount": 0.85,
"billingCurrency": "USD",
"authorizationCode": "2d3d8c5a-66bf-479f-abd3-18efd32dfa65",
"chargeId": "64ddcacc-e73f-4046-9aa3-8a067cd9f67b",
"relatedTransactionId": "64ddcacc-e73f-4046-9aa3-8a067cd9f67b",
"merchant": {
"name": "XSOLLA *ONLINE GAMES",
"country": "US",
"mcc": "5816"
}
}
}
```
## Payload Fields
| Field | Type | Description |
| ---------------------- | -------------- | --------------------------------------------------------------------------------- |
| `transactionId` | string | Provider transaction identifier for this phase |
| `cardId` | string | The card used for the transaction |
| `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 | `PURCHASE`, `REVERSAL`, `REFUND`, or `ADJUSTMENT` |
| `status` | string | `AUTHORIZED`, `CLEARED`, `REVERSED`, `REFUNDED`, or `ADJUSTED` |
| `amount` | number | Transaction amount in dollars. On `CLEARED`, this is the final settled amount. |
| `currency` | string | Transaction currency (ISO 4217) |
| `billingAmount` | number | Amount in the card's billing currency, in dollars |
| `billingCurrency` | string | Billing currency — may differ for cross-border transactions |
| `authorizationCode` | string | Purchase-lifecycle correlation key (present on authorization, clearing, reversal) |
| `relatedTransactionId` | string | Related transaction — the authorization for a clearing, the charge for a reversal |
| `chargeId` | string | On a reversal, the charge being reversed |
| `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.country` | string | Merchant country (ISO 3166-1 alpha-2) |
| `merchant.mcc` | string | ISO 18245 Merchant Category Code |
## Common Use Cases
* **Mark a transaction successful on `status: CLEARED`**, using its `amount` as the final charge.
* **Correlate** an authorization with its settlement via `authorizationCode`, so a hold and its later capture aren't double-counted.
* Handle `REVERSED` (authorization voided) and `REFUNDED` (merchant refund) to restore balance in your ledger — a `REVERSED` payload's `chargeId` tells you exactly which charge it undoes.
* Send real-time notifications and implement MCC-based spending controls.
`TRANSACTION_PROCESSED` supersedes the deprecated granular events
([`TRANSACTION_AUTHORIZED`](/v3.20/webhooks/events/transaction-authorized),
[`TRANSACTION_CLEARED`](/v3.20/webhooks/events/transaction-cleared),
[`TRANSACTION_REVERSED`](/v3.20/webhooks/events/transaction-reversed), and
`TRANSACTION_REFUNDED`). They remain fully supported for existing integrations — no
migration required — but new integrations should subscribe to `TRANSACTION_PROCESSED`
and branch on `status`.
```json Webhook Payload (CLEARED) theme={null}
{
"event": "TRANSACTION_PROCESSED",
"eventId": "EVT2W9SK2233S4C",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-07-07T21:55:41Z",
"data": {
"transactionId": "237bc8d1-5b20-4d6b-8ade-059e8dd903ca",
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"externalId": "my-user-id-789",
"type": "PURCHASE",
"status": "CLEARED",
"amount": 13.68,
"currency": "USD",
"billingAmount": 13.68,
"billingCurrency": "USD",
"authorizationCode": "21e2c774-66ac-4b09-9d9d-3abe0f944bda",
"relatedTransactionId": "21e2c774-66ac-4b09-9d9d-3abe0f944bda",
"merchant": {
"name": "ZYNGA - EMPIRES & PUZZ",
"id": "EUXEITE8IZPSUAW",
"country": "IE",
"mcc": "5816"
}
}
}
```
```json 200 theme={null}
{}
```
## OpenAPI
````yaml v3.20/openapi.json webhook TRANSACTION_PROCESSED
openapi: 3.1.0
info:
title: FYATU CaaS API v3.20
description: >-
FYATU Cards-as-a-Service API — API key authentication, Cardholder
lifecycle, Card issuance, Transactions, Webhooks, and Programs.
version: 3.20.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3.20
description: >-
FYATU CaaS API — the environment (LIVE or SANDBOX) is determined by the
API key, not the URL
security:
- BearerAuth: []
tags:
- name: Meta
description: Liveness, account info, and supported event types
- name: Account
description: Account-level balance and funding status
- name: Programs
description: Read card program configuration
- name: Cardholders
description: Create and manage cardholder profiles
- name: Cards
description: Issue, fund, freeze, and terminate virtual cards
- name: Transactions
description: Read-only card transaction history
- name: Webhooks
description: Manage webhook endpoints for real-time event delivery
- name: Products
description: Read card product configurations
paths: {}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
`.
````