> ## 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.

# Cardholders

> Cardholders are business-level identities — not tied to any single program. KYC approval is required before a card can be issued. One cardholder can hold cards across multiple programs.

# 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     |

<Note>
  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.
</Note>

### Suspend / Reactivate

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

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### 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.

<Note>
  Fields are **not** locked when `kycStatus` is `WAIVED`. Since no identity document was verified, all profile fields remain editable throughout the cardholder's lifetime.
</Note>

***

## 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:

```json theme={null}
{
  "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

```javascript theme={null}
// 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

```javascript theme={null}
// 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](/v3.20/api-reference/cardholders/create)
* `GET /cardholders` — [List cardholders](/v3.20/api-reference/cardholders/list)
* `GET /cardholders/{id}` — [Get cardholder](/v3.20/api-reference/cardholders/get)
* `PATCH /cardholders/{id}` — [Update cardholder](/v3.20/api-reference/cardholders/update)
* `POST /cardholders/{id}/suspend` — [Suspend cardholder](/v3.20/api-reference/cardholders/suspend)
* `POST /cardholders/{id}/reactivate` — [Reactivate cardholder](/v3.20/api-reference/cardholders/reactivate)
* `POST /cardholders/{id}/kyc/session` — [Initiate KYC session](/v3.20/api-reference/cardholders/kyc-session)
* `POST /cardholders/{id}/kyc` — [Submit KYC documents (Shared KYC)](/v3.20/api-reference/cardholders/kyc)