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 Events
Card events fire whenever the state of a card changes. Subscribe to these events to keep your platform in sync with the card’s status and balance in real time.
All card events share the same outer envelope:
{
"event": "CARD_ISSUED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": { ... }
}
CARD_ISSUED
When it fires
Fires immediately after a successful POST /cards request — the card provider confirms the card is active and ready to be funded.
Payload
{
"event": "CARD_ISSUED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"programId": "prg_01HXYZ9876ABCDEF0000",
"status": "ACTIVE",
"cardType": "VIRTUAL",
"cardBrand": "VISA",
"maskedPan": "**** **** **** 4242",
"last4": "4242",
"expiryMonth": 5,
"expiryYear": 2029,
"currency": "USD"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The newly issued card ID |
cardholderId | string | The cardholder the card belongs to |
programId | string | The program the card belongs to |
status | string | Always ACTIVE at issuance |
cardType | string | Always VIRTUAL |
cardBrand | string | VISA or MASTERCARD |
maskedPan | string | Masked card number |
last4 | string | Last 4 digits of the PAN |
expiryMonth | integer | Expiry month (1–12) |
expiryYear | integer | Expiry year (4-digit) |
currency | string | Card currency (ISO 4217) |
Common use cases
- Display the new card to the cardholder in your UI
- Record the card in your internal database
- Trigger a “Your card is ready” notification to the cardholder
CARD_FROZEN
When it fires
Fires immediately after a successful POST /cards/{id}/freeze request, or when FYATU’s fraud systems freeze a card automatically.
Payload
{
"event": "CARD_FROZEN",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"programId": "prg_01HXYZ9876ABCDEF0000",
"status": "FROZEN",
"reason": "MANUAL"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The frozen card ID |
cardholderId | string | The cardholder the card belongs to |
programId | string | The program the card belongs to |
status | string | Always FROZEN |
reason | string | MANUAL (API call) or FRAUD (automated freeze) |
Common use cases
- Notify the cardholder that their card has been temporarily blocked
- Prevent new card loads until the situation is resolved
CARD_UNFROZEN
When it fires
Fires immediately after a successful POST /cards/{id}/unfreeze request.
Payload
{
"event": "CARD_UNFROZEN",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"programId": "prg_01HXYZ9876ABCDEF0000",
"status": "ACTIVE"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The unfrozen card ID |
cardholderId | string | The cardholder the card belongs to |
programId | string | The program the card belongs to |
status | string | Always ACTIVE after unfreezing |
Common use cases
- Notify the cardholder that their card is active again
- Resume normal card operations in your platform
CARD_TERMINATED
When it fires
Fires immediately after a successful POST /cards/{id}/terminate request. Termination is irreversible — the card cannot be reactivated.
Payload
{
"event": "CARD_TERMINATED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"programId": "prg_01HXYZ9876ABCDEF0000",
"status": "TERMINATED",
"remainingCents": 0,
"refundedToProgramCents": 0
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The terminated card ID |
cardholderId | string | The cardholder the card belonged to |
programId | string | The program the card belonged to |
status | string | Always TERMINATED |
remainingCents | integer | Card balance at termination time (in cents) |
refundedToProgramCents | integer | Amount returned to the program ledger (in cents) |
Common use cases
- Remove the card from the cardholder’s active card list in your UI
- Log the termination event for audit trail purposes
CARD_FUNDED
When it fires
Fires after a successful POST /cards/{id}/fund request. Indicates that funds have been moved from the program ledger to the card.
Payload
{
"event": "CARD_FUNDED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amount": 50.00,
"currency": "USD",
"programBalanceAfter": 9950.00,
"note": "Monthly allowance",
"ledgerTransactionId": "ltx_01HXYZ9999ABCDEF2222",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The funded card ID |
programId | string | The program the funds were taken from |
amount | number | Amount loaded (in dollars) |
currency | string | Currency code (ISO 4217) |
programBalanceAfter | number | Program ledger balance after funding (in dollars) |
note | string or null | Optional note provided in the fund request |
ledgerTransactionId | string | Internal ledger transaction reference |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Update the displayed card balance in your cardholder’s dashboard
- Confirm a load operation completed successfully without polling
- Trigger an SMS or push notification: “Your card has been topped up with $50”
CARD_FUND_FAILED
When it fires
Fires when a POST /cards/{id}/fund request fails at the card provider level. The program ledger debit is automatically reversed — the program balance is fully restored.
Payload
{
"event": "CARD_FUND_FAILED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amount": 50.00,
"currency": "USD",
"error": "CARD_NOT_ACTIVE",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The card that failed to receive funds |
programId | string | The program the funding was attempted from |
amount | number | Amount that failed to load (in dollars) |
currency | string | Currency code (ISO 4217) |
error | string | Provider error message |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Notify the cardholder that their card top-up failed
- Retry the funding operation or prompt the user to check their card status
CARD_UNLOADED
When it fires
Fires after a successful POST /cards/{id}/unload request. Indicates that funds have been returned from the card to the program ledger.
Payload
{
"event": "CARD_UNLOADED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amount": 25.00,
"currency": "USD",
"programBalanceAfter": 9975.00,
"note": null,
"ledgerTransactionId": "ltx_01HXYZ8888ABCDEF3333",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The card funds were unloaded from |
programId | string | The program the funds were returned to |
amount | number | Amount unloaded (in dollars) |
currency | string | Currency code (ISO 4217) |
programBalanceAfter | number | Program ledger balance after unloading (in dollars) |
note | string or null | Optional note provided in the unload request |
ledgerTransactionId | string | Internal ledger transaction reference |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Reflect the updated card balance in your UI
- Confirm a partial unload before proceeding with a withdrawal
CARD_UNLOAD_FAILED
When it fires
Fires when a POST /cards/{id}/unload request fails at the card provider level. No funds are moved — the program ledger is unchanged.
Payload
{
"event": "CARD_UNLOAD_FAILED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"programId": "prg_01HXYZ9876ABCDEF0000",
"amount": 25.00,
"currency": "USD",
"error": "INSUFFICIENT_CARD_BALANCE",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The card the unload was attempted from |
programId | string | The program the unload was targeted at |
amount | number | Amount that failed to unload (in dollars) |
currency | string | Currency code (ISO 4217) |
error | string | Provider error message |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Alert the operator that an unload attempt failed
- Retry with a lower amount if the failure was
INSUFFICIENT_CARD_BALANCE
CARD_3DS_OTP
When it fires
Fires when a 3D Secure authentication code is generated for a card transaction. Deliver this code to the cardholder immediately — 3DS codes expire within 5 minutes.
You must deliver the code to the cardholder within seconds. Late delivery will cause the 3DS challenge to fail and the transaction to be declined.
Payload
{
"event": "CARD_3DS_OTP",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"code": "847263",
"type": "3DS",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The card for which the 3DS code was generated |
code | string | The one-time 3DS authentication code |
type | string | Always 3DS for this event |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Push the code to the cardholder via SMS, in-app notification, or email
- Display the code in your cardholder-facing UI with a countdown timer
CARD_TOKENIZATION_OTP
When it fires
Fires when a tokenization code is generated — typically when the cardholder adds their card to Apple Pay or Google Pay. Deliver the code to the cardholder to complete the wallet provisioning flow.
Payload
{
"event": "CARD_TOKENIZATION_OTP",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"code": "513847",
"type": "WALLET_CODE",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The card being added to a digital wallet |
code | string | The one-time tokenization code |
type | string | Always WALLET_CODE for this event |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Deliver the code to the cardholder in-app or via push notification
- Show a “Enter this code in your wallet app” prompt in your UI
CARD_AUTHORIZATION
When it fires
Fires asynchronously after every authorization decision for a CaaS card — both approvals and declines. Note that the decision field in this webhook reflects the outcome FYATU returned to the card network, not the cardholder’s final charge result.
This event is dispatched asynchronously after the authorization response is sent to the card network. You cannot influence the authorization decision by responding to this webhook.
Payload
{
"event": "CARD_AUTHORIZATION",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardId": "crd_01HXYZ5555ABCDEF1111",
"amount": 42.50,
"currency": "USD",
"merchantName": "Amazon",
"decision": "APPROVED",
"timestamp": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardId | string | The card that was authorized |
amount | number | Authorization amount (in dollars) |
currency | string | Authorization currency (ISO 4217) |
merchantName | string | Merchant name from the authorization request |
decision | string | APPROVED or DECLINED |
timestamp | string | ISO 8601 timestamp |
Common use cases
- Log all authorization attempts for your compliance audit trail
- Show a real-time transaction feed in your cardholder dashboard
- Alert on large or unusual authorization amounts
