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.
Cardholder Events
Cardholder events fire whenever the state of a cardholder changes — including lifecycle transitions and KYC decisions. Subscribe to these events to react immediately without polling.
All cardholder events share the same outer envelope:
{
"event": "CARDHOLDER_CREATED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": { ... }
}
CARDHOLDER_CREATED
When it fires
Fires immediately after a successful POST /cardholders request. KYC verification starts automatically — subscribe to CARDHOLDER_KYC_APPROVED or CARDHOLDER_KYC_REJECTED to know when verification completes.
Payload
{
"event": "CARDHOLDER_CREATED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@example.com",
"status": "ACTIVE",
"kycStatus": "PENDING",
"externalId": "my-user-id-789"
}
}
Payload fields
| Field | Type | Description |
|---|
cardholderId | string | The newly created cardholder ID |
firstName | string | Cardholder first name |
lastName | string | Cardholder last name |
email | string | Cardholder email address |
status | string | Always ACTIVE at creation |
kycStatus | string | Always PENDING at creation |
externalId | string or null | Your internal user ID, if provided |
Common use cases
- Record the cardholder in your system with the FYATU
cardholderId
- Show a “Verification in progress” state in your UI
CARDHOLDER_SUSPENDED
When it fires
Fires after a successful POST /cardholders/{id}/suspend request. All cards belonging to the cardholder are automatically frozen.
Payload
{
"event": "CARDHOLDER_SUSPENDED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"status": "SUSPENDED",
"suspendedAt": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardholderId | string | The suspended cardholder ID |
status | string | Always SUSPENDED |
suspendedAt | string | ISO 8601 timestamp of suspension |
Common use cases
- Block the cardholder’s access to your platform
- Alert your compliance team for review
- Notify the cardholder (if warranted) that their account is under review
CARDHOLDER_REACTIVATED
When it fires
Fires after a successful POST /cardholders/{id}/reactivate request. Cards that were automatically frozen on suspension are unfrozen.
Payload
{
"event": "CARDHOLDER_REACTIVATED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"status": "ACTIVE"
}
}
Payload fields
| Field | Type | Description |
|---|
cardholderId | string | The reactivated cardholder ID |
status | string | Always ACTIVE after reactivation |
Common use cases
- Restore the cardholder’s platform access
- Notify the cardholder that their account is active again
CARDHOLDER_DELETED
When it fires
Fires when a cardholder is permanently deleted. This is irreversible. All cards are terminated and any remaining card balances are returned to the program ledger.
Payload
{
"event": "CARDHOLDER_DELETED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:00Z",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"status": "DELETED",
"deletedAt": "2026-05-22T10:00:00Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardholderId | string | The deleted cardholder ID |
status | string | Always DELETED |
deletedAt | string | ISO 8601 timestamp of deletion |
Common use cases
- Remove all cardholder data from your active user database
- Log the deletion for compliance and audit records
CARDHOLDER_KYC_APPROVED
When it fires
Fires when KYC verification is successfully completed. The cardholder can now have cards issued to them.
Payload
{
"event": "CARDHOLDER_KYC_APPROVED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:05Z",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"kycStatus": "APPROVED",
"kycVerifiedAt": "2026-05-22T10:00:05Z"
}
}
Payload fields
| Field | Type | Description |
|---|
cardholderId | string | The approved cardholder ID |
kycStatus | string | Always APPROVED |
kycVerifiedAt | string | ISO 8601 timestamp of approval |
Common use cases
- Issue a card immediately upon receiving this event
- Unlock the full set of platform features for the cardholder
- Send a “You’re verified!” notification to the cardholder
This is the most important cardholder event. Build your card issuance flow around it — listen for CARDHOLDER_KYC_APPROVED and then call POST /cards.
CARDHOLDER_KYC_REJECTED
When it fires
Fires when KYC verification fails. The rejection reason is included so you can guide the cardholder on next steps.
Payload
{
"event": "CARDHOLDER_KYC_REJECTED",
"eventId": "evt_01HXY123456ABCDEF",
"businessId": "BUS1A2B3C4D5E6F",
"environment": "LIVE",
"timestamp": "2026-05-22T10:00:10Z",
"data": {
"cardholderId": "chl_01HXYZ1234ABCDEF5678",
"kycStatus": "REJECTED",
"kycRejectionReason": "DOCUMENT_EXPIRED"
}
}
Payload fields
| Field | Type | Description |
|---|
cardholderId | string | The rejected cardholder ID |
kycStatus | string | Always REJECTED |
kycRejectionReason | string | Machine-readable rejection reason — see values below |
| Value | Meaning |
|---|
DOCUMENT_EXPIRED | The submitted ID document has expired |
DOCUMENT_UNREADABLE | The document image was too blurry or incomplete |
NAME_MISMATCH | Name on document does not match cardholder profile |
UNDER_AGE | Cardholder is under 18 years old |
WATCHLIST_MATCH | Name matched a regulatory watchlist |
DUPLICATE_IDENTITY | Identity documents already used by another cardholder |
UNSUPPORTED_COUNTRY | Cardholder’s country is not supported for card issuance |
OTHER | Contact support for details |
Common use cases
- Show a specific rejection reason to the cardholder with guidance on how to fix it
- Allow the cardholder to retry KYC with corrected documents (where policy permits)
- Alert your compliance team for
WATCHLIST_MATCH rejections
