> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saspay.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Soumettez votre dossier d'identité et ses pièces justificatives pour faire vérifier votre compte marchand.

## Vue d'ensemble

Le KYC (*Know Your Customer*) est le dossier d'identité de votre marchand — c'est son approbation qui fait passer `kyc_status` à `VERIFIED` et active réellement votre compte (`is_active: true`). Un dossier appartient toujours à UN marchand précis : deux marchands possédés par le même compte dashboard ont chacun leur propre dossier.

<Warning>
  **Tout ce groupe est dashboard uniquement en écriture.** Soumettre un dossier, y attacher un document ou uploader un fichier ne fonctionne **jamais** avec une clé API (`Authorization: Bearer sk_...`) — utilisez le jeton de session obtenu par connexion, voir [Créer un compte et obtenir une clé API](/account-setup). Une tentative via clé API renvoie `403 dashboard_only`. La **lecture** (historique, détail) reste, elle, accessible via clé API.
</Warning>

```
Dossier KYC (MerchantKyc)
│
├── kyc_type ── INDIVIDUAL | BUSINESS
├── Identité ── first_name, last_name, date_of_birth, id_document_type
├── Entreprise (BUSINESS) ── company_name, rccm_number, ifu_number
│
├── status ── PENDING | APPROVED | REJECTED  (lecture seule, décidé par un admin)
│
└── documents[] ── pièces jointes, ajoutées en 2 étapes
    ├── 1. upload du binaire   → obtention d'une URL
    └── 2. attachement au dossier avec document_type
```

<Note>
  Aucune validation croisée n'est faite côté serveur entre `kyc_type` et les champs remplis : soumettre un dossier `BUSINESS` sans `company_name`/`rccm_number`/`ifu_number` est accepté (tous ces champs sont optionnels au niveau API). C'est votre formulaire qui doit imposer ce qui est pertinent selon `kyc_type`.
</Note>

Soumettre un **nouveau** dossier repasse votre marchand en `kyc_status: PENDING`, même s'il était déjà `VERIFIED` — pratique pour mettre à jour vos informations (changement de représentant légal, nouveau document...). Votre accès API reste actif pendant la ré-instruction : `is_active` n'est pas affecté par une nouvelle soumission.

## Soumettre un dossier

* [Soumettre un dossier](/api-reference/kyc/submit) — dashboard uniquement
* [Historique de vos dossiers](/api-reference/kyc/list) — clé API OK (lecture)
* [Détail d'un dossier](/api-reference/kyc/get) — clé API OK (lecture)

| Champ                                         | Type   | Requis  | Description                                                                                  |
| --------------------------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------- |
| `merchant`                                    | uuid   | **oui** | Toujours votre propre marchand — forcé au vôtre si un autre id est fourni                    |
| `kyc_type`                                    | string | oui     | `INDIVIDUAL` ou `BUSINESS`                                                                   |
| `first_name` / `last_name`                    | string | non     | —                                                                                            |
| `date_of_birth`                               | string | non     | Format `YYYY-MM-DD`                                                                          |
| `id_document_type`                            | string | non     | Texte libre, ex. `ID_CARD`/`PASSPORT` — pas de contrainte stricte côté serveur malgré le nom |
| `company_name` / `rccm_number` / `ifu_number` | string | non     | Pertinents uniquement pour `BUSINESS`                                                        |

Champs en plus, renvoyés en lecture seule : `id`, `status`, `reviewed_by_admin`, `review_note`, `reviewed_at`, `documents` (vide à la création), `created_at`, `updated_at`.

Il n'y a pas de `PATCH`/`DELETE` sur un dossier — il n'évolue que par l'ajout de documents ou une nouvelle soumission.

## Documents

Rattacher une pièce justificative se fait en **deux appels distincts**, tous deux dashboard uniquement :

1. **Upload du binaire** — `POST /merchant-kyc/upload/`, `multipart/form-data`. Renvoie une URL absolue.
2. **Attachement au dossier** — `POST /merchant-kyc/{kyc_id}/documents/` avec cette URL et un `document_type`.

* [Uploader un fichier](/api-reference/kyc/upload) — dashboard uniquement
* [Attacher un document au dossier](/api-reference/kyc/add-document) — dashboard uniquement
* [Lister les documents d'un dossier](/api-reference/kyc/documents-list) — clé API OK (lecture)

**Exemple de flux complet**, pour attacher un recto de carte d'identité à un dossier existant (jeton de session, pas une clé API) :

```bash theme={null}
# 1. Upload du binaire
curl -X POST https://api.saspay.me/api/v1/merchant-kyc/upload/ \
  -H "Authorization: Bearer <jeton de session>" \
  -F "file=@cni-recto.jpg"

# → {"url": "https://cdn.saspay.me/kyc/8f2c1e9a-....jpg"}

# 2. Attachement au dossier
curl -X POST https://api.saspay.me/api/v1/merchant-kyc/b6b0.../documents/ \
  -H "Authorization: Bearer <jeton de session>" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "ID_CARD",
    "label": "Recto CNI",
    "file_url": "https://cdn.saspay.me/kyc/8f2c1e9a-....jpg"
  }'
```

Types de documents acceptés (`document_type`) : `ID_CARD`, `PASSPORT`, `SELFIE`, `BUSINESS_REGISTRATION`, `FISCAL`, `OTHER`. `label` sert surtout à préciser `OTHER`.

<Warning>
  Sur un dossier n'appartenant pas à votre marchand, `GET /merchant-kyc/{kyc_id}/documents/` renvoie `200` avec une liste **vide**, plutôt qu'un `404` (contrairement au `POST` sur ce même chemin, qui lui renvoie bien `404`). Ne vous fiez donc pas à une liste vide pour conclure qu'un dossier n'existe pas.
</Warning>

Types de fichiers acceptés à l'upload : `image/jpeg`, `image/png`, `image/webp`, `application/pdf` — 10 Mo maximum.