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

# KYC Verification

> Identity verification is required before cards can be issued. Two paths: self-service (cardholder completes themselves) or shared KYC (your business submits documents directly).

# KYC Verification

KYC (Know Your Customer) verification is **required** — a cardholder cannot be issued a card until their `kycStatus` reaches `ACCEPTED`. Two verification paths are available depending on your use case and onboarding status.

## Verification Paths

| Path             | Endpoint                                | Use When                                                                            |
| ---------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| **Self-Service** | `POST /cardholders/{id}/kyc/session`    | The cardholder completes verification themselves via a secure link                  |
| **Shared KYC**   | `POST /cardholders/{id}/kyc`            | Your business is pre-approved and already holds the cardholder's verified documents |
| **At Creation**  | `POST /cardholders` (with `kyc` object) | Shared KYC only — submit documents in the same request as cardholder creation       |

## Path 1: Self-Service

The cardholder completes verification themselves using a hosted link. Best for consumer-facing products where the end user is present.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant FYATU as FYATU API
    participant V as Verification Provider
    participant User as Cardholder

    App->>FYATU: POST /cardholders/{id}/kyc/session
    FYATU-->>App: { verificationUrl, sessionId }
    App->>User: Redirect to verificationUrl
    User->>V: ID scan + liveness check
    V->>FYATU: Verification result
    FYATU->>App: Webhook: cardholder.kyc_approved
    Note over App: kycStatus: ACCEPTED → can now issue cards
```

## Path 2: Shared KYC

Available only to businesses that have completed FYATU's Shared KYC onboarding. You submit document URLs directly and the background verification happens asynchronously.

To apply for Shared KYC access, contact FYATU through your dedicated Slack channel — a due diligence review and use of a recognised KYC provider (e.g. Sumsub, Persona, Onfido) are required.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant FYATU as FYATU API

    App->>FYATU: POST /cardholders/{id}/kyc (document URLs)
    FYATU-->>App: { kycStatus: "PENDING" }
    FYATU->>FYATU: Process documents (background)
    FYATU->>App: Webhook: cardholder.kyc_approved
    Note over App: kycStatus: ACCEPTED → can now issue cards
```

You can also submit documents at cardholder creation by including a `kyc` object in `POST /cardholders`.

## KYC Status Flow

| kycStatus     | Description              | Can Issue Cards | Can Initiate Verification     |
| ------------- | ------------------------ | --------------- | ----------------------------- |
| `UNSUBMITTED` | No verification started  | No              | Yes                           |
| `PENDING`     | Verification in progress | No              | No (returns existing session) |
| `ACCEPTED`    | Identity verified        | **Yes**         | No                            |
| `REJECTED`    | Verification failed      | No              | Yes (retry allowed)           |

## Verification Fee

Fee per plan, added to your invoice only when verification is **approved**:

| Plan       | Fee    |
| ---------- | ------ |
| Startup    | \$1.20 |
| Enterprise | \$0.80 |
| Premium    | \$0.40 |

* No upfront charge — fee is not deducted from your wallet when initiating verification
* Added to your next monthly invoice only on successful verification
* Not charged on failure, abandonment, or expiry

## Webhook Events

| Event                     | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `cardholder.kyc_approved` | KYC verification approved — cards can now be issued |
| `cardholder.kyc_rejected` | KYC verification failed — retry is allowed          |

## Endpoints

* `POST /cardholders/{id}/kyc/session` — [Initiate self-service KYC session](/v3/api-reference/cardholders/kyc-session)
* `POST /cardholders/{id}/kyc` — [Submit documents (Shared KYC)](/v3/api-reference/cardholders/kyc)