TRANSACTION_PROCESSED - FYATU API Docs

{
  "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"
    }
  }
}

{}

WEBHOOK

TRANSACTION_PROCESSED

{
  "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"
    }
  }
}

{}

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:

status: AUTHORIZED when the cardholder pays (a hold is placed).
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`)

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

{
  "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, TRANSACTION_CLEARED, 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.

{
  "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"
    }
  }
}

{}

Authorizations

Authorization

string

header

required

API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

Body

application/json

event

string

Example:

"TRANSACTION_PROCESSED"

eventId

string

businessId

string

environment

enum<string>

Available options:

LIVE,

SANDBOX

timestamp

string<date-time>

data

object

Show child attributes

Response

200

Acknowledge the event.

CARD_TOKENIZATION_OTP TRANSACTION_DECLINED

​The authorization → clearing flow

​Correlation fields

​Payload — settlement (status: CLEARED)

​Payload — reversal (status: REVERSED)

​Payload Fields

​Common Use Cases

Authorizations

Body

Response

The authorization → clearing flow

Correlation fields

Payload — settlement (`status: CLEARED`)

Payload — reversal (`status: REVERSED`)

Payload Fields

Common Use Cases