Cardholders

A cardholder is an end-user who will hold and spend on cards issued through your business. Cardholders belong to the Business, not to a specific program. A single cardholder can receive cards from any program your business has access to — if one program is paused, the same cardholder can be issued a card from another active program without any re-registration or re-KYC.

The Cardholder Lifecycle

POST /cardholders  (personal info only — no programId or productId required)
        │
        ▼
  status: ACTIVE
  kycStatus: PENDING  ◄── KYC starts (MANAGED programs)
        │                                    OR
        │             kycStatus: WAIVED  ◄── KYC waived (MINIMAL programs) ── POST /cards is now allowed
        │
        ├── KYC passes ──► kycStatus: APPROVED  ── POST /cards is now allowed
        │                                           (for any product under any active program)
        │
        └── KYC fails ───► kycStatus: REJECTED  ── Retry via KYC session or document upload

Account Status

Status	Description	Can receive new cards	Existing cards
`ACTIVE`	Normal operating state	Yes (if KYC approved)	Unaffected
`SUSPENDED`	Manually suspended by your business	No	Continue working*
`TERMINATED`	Permanently closed — irreversible	No	All terminated

Suspending a cardholder does not automatically freeze their cards. If you need to immediately stop spending, freeze each active card individually via POST /cards/{id}/freeze in addition to suspending the cardholder.

Suspend / Reactivate

Suspension is the right tool when you suspect fraud or a policy violation but are not ready to permanently close the account:

# Suspend
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ.../suspend \
  -H "Authorization: Bearer $FYATU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspicious activity detected" }'

# Reactivate
curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ.../reactivate \
  -H "Authorization: Bearer $FYATU_API_KEY"

KYC (Identity Verification)

The kycStatus field tracks where a cardholder stands in the verification flow. Both APPROVED and WAIVED allow card issuance.

kycStatus	Can issue cards	Description
`PENDING`	No	KYC initiated, awaiting result
`APPROVED`	Yes	Identity fully verified
`WAIVED`	Yes	KYC waived by program policy (MINIMAL programs only) — cardholder not identity-verified
`REJECTED`	No	Verification failed — see `kycRejectionReason`, retry allowed

KYC Mode

The KYC flow your cardholders go through depends on the kycMode configured on your program by the FYATU team:

kycMode	kycStatus after create	Card issuance
`MANAGED`	`PENDING`	After `CARDHOLDER_KYC_APPROVED` webhook
`SHARED`	`APPROVED`	Immediately — your KYC documents are accepted on creation
`MINIMAL`	`WAIVED`	Immediately — no identity verification required

SHARED and MINIMAL require explicit authorization from FYATU and are negotiated as part of your program agreement.

KYC Paths

MANAGED (default) — cardholder completes verification themselves

The default mode. After creating the cardholder (kycStatus: PENDING), initiate a KYC session to get a hosted verification link and redirect your user to it:

curl -X POST https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ.../kyc/session \
  -H "Authorization: Bearer $FYATU_API_KEY"

The user uploads their ID and completes a liveness check. FYATU fires CARDHOLDER_KYC_APPROVED or CARDHOLDER_KYC_REJECTED when done.Best for: consumer products where the end-user is present.

SHARED — your business submits documents directly

If you already hold verified identity documents from your own KYC provider (Sumsub, Persona, Onfido, etc.), submit them at creation time via the kycDocument field. FYATU accepts them immediately and sets kycStatus: APPROVED — no webhook wait required.Requires: Shared KYC authorization from FYATU — contact your account manager.

MINIMAL — no KYC required

On MINIMAL programs, cardholders are created with kycStatus: WAIVED and can be issued a card immediately. No identity documents are collected or verified.The WAIVED status is permanent — it does not upgrade to APPROVED. It signals that the cardholder was onboarded under a reduced-KYC agreement.Requires: MINIMAL program authorization from FYATU — contact your account manager.

Handling KYC Rejection

When kycStatus is REJECTED, the response includes kycRejectionReason with a human-readable explanation. Retry by generating a new KYC session or resubmitting documents with better-quality images.

Field Lock After KYC Approval

Once kycStatus reaches APPROVED, identity fields are locked and cannot be changed via PATCH /cardholders/{id}. Attempting to update a locked field returns 409 KYC_FIELD_LOCKED.

Locked after KYC approval	Always editable
`firstName`, `lastName`	`phone`
`dateOfBirth`, `nationality`	`externalId`, `metadata`
`address.*`	`email`

This is a compliance requirement — the KYC approval is bound to the identity document submitted.

Fields are not locked when kycStatus is WAIVED. Since no identity document was verified, all profile fields remain editable throughout the cardholder’s lifetime.

External ID

Always set externalId to your internal user ID. It lets you look up cardholders without storing FYATU cardholder IDs in your own database:

{
  "externalId": "user_12345"
}

externalId must be unique within your business and environment. Two cardholders cannot share the same externalId.

Cardholder Termination

Termination is permanent and irreversible. Before terminating, all of the cardholder’s cards must be terminated first — otherwise the API returns 422 CARDHOLDER_HAS_ACTIVE_CARDS. After termination, personal data is retained for the legally required period (7 years) and then anonymized in compliance with applicable data retention law.

Webhook Events

Event	Fired when
`CARDHOLDER_CREATED`	New cardholder created
`CARDHOLDER_UPDATED`	Profile fields updated
`CARDHOLDER_SUSPENDED`	Cardholder suspended
`CARDHOLDER_REACTIVATED`	Cardholder reactivated from suspended
`CARDHOLDER_TERMINATED`	Cardholder permanently closed
`CARDHOLDER_KYC_SUBMITTED`	KYC documents submitted for review
`CARDHOLDER_KYC_SUBMISSION_FAILED`	KYC document submission failed
`CARDHOLDER_KYC_REVIEW_PENDING`	KYC is under manual review
`CARDHOLDER_KYC_APPROVED`	KYC passed — cards can now be issued
`CARDHOLDER_KYC_REJECTED`	KYC failed — see `kycRejectionReason`

Integration Patterns

MANAGED — Full KYC Flow

// 1. Create cardholder
const ch = await fyatu.post('/cardholders', {
  firstName:   'Jane', lastName: 'Doe',
  email:       'jane.doe@example.com', phone: '+12025551234',
  dateOfBirth: '1992-03-20', nationality: 'US',
  address:     { address: '456 Elm St', city: 'Austin', state: 'TX', postalCode: '78701', country: 'US' },
  externalId:  'my-user-id-789',
});
// ch.kycStatus === 'PENDING'

// 2. Start self-service KYC — redirect user to the verification link
const session = await fyatu.post(`/cardholders/${ch.cardholderId}/kyc/session`);
redirectUser(session.verificationUrl);

// 3. On CARDHOLDER_KYC_APPROVED webhook — issue a card
const card = await fyatu.post('/cards', {
  cardholderId: ch.cardholderId,
  productId:    'prd_01HXYZABC123',
});

MINIMAL — Instant Card Issuance

// 1. Create cardholder — kycStatus is WAIVED immediately
const ch = await fyatu.post('/cardholders', {
  firstName:   'Jane', lastName: 'Doe',
  email:       'jane.doe@example.com', phone: '+12025551234',
  dateOfBirth: '1992-03-20', nationality: 'US',
  address:     { address: '456 Elm St', city: 'Austin', state: 'TX', postalCode: '78701', country: 'US' },
  externalId:  'my-user-id-789',
});
// ch.kycStatus === 'WAIVED' — no webhook wait needed

// 2. Issue a card immediately
const card = await fyatu.post('/cards', {
  cardholderId: ch.cardholderId,
  productId:    'prd_01HXYZABC123',
});

Endpoints

POST /cardholders — Create cardholder
GET /cardholders — List cardholders
GET /cardholders/{id} — Get cardholder
PATCH /cardholders/{id} — Update cardholder
POST /cardholders/{id}/suspend — Suspend cardholder
POST /cardholders/{id}/reactivate — Reactivate cardholder
POST /cardholders/{id}/kyc/session — Initiate KYC session
POST /cardholders/{id}/kyc — Submit KYC documents (Shared KYC)

Getting Started

Concepts

Cardholders

Cardholders

The Cardholder Lifecycle

Account Status

Suspend / Reactivate

KYC (Identity Verification)

KYC Mode

KYC Paths

Handling KYC Rejection

Field Lock After KYC Approval

External ID

Cardholder Termination

Webhook Events

Integration Patterns

MANAGED — Full KYC Flow

MINIMAL — Instant Card Issuance

Endpoints

​Cardholders

​The Cardholder Lifecycle

​Account Status

​Suspend / Reactivate

​KYC (Identity Verification)

​KYC Mode

​KYC Paths

​Handling KYC Rejection

​Field Lock After KYC Approval

​External ID

​Cardholder Termination

​Webhook Events

​Integration Patterns

​MANAGED — Full KYC Flow

​MINIMAL — Instant Card Issuance

​Endpoints

Cardholders

The Cardholder Lifecycle

Account Status

Suspend / Reactivate

KYC (Identity Verification)

KYC Mode

KYC Paths

Handling KYC Rejection

Field Lock After KYC Approval

External ID

Cardholder Termination

Webhook Events

Integration Patterns

MANAGED — Full KYC Flow

MINIMAL — Instant Card Issuance

Endpoints