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

# Créer un compte et obtenir une clé API

> Le mécanisme complet, de zéro jusqu'à votre première clé API — inscription, vérification KYC, création de la clé.

Avant de pouvoir appeler l'API avec une clé (`Authorization: Bearer sk_...`), un compte doit exister, être vérifié (KYC), puis générer sa première clé. **Ces étapes préalables ne peuvent PAS se faire avec une clé API** — pour une raison structurelle simple : la clé n'existe pas encore. Elles utilisent un jeton de session (JWT), obtenu par connexion classique email/mot de passe, exactement comme le tableau de bord [app.alphapay.me](https://app.alphapay.me) lui-même. Une fois votre première clé générée, vous n'avez plus jamais besoin de JWT pour intégrer l'API.

<Info>
  Tout ce mécanisme est utilisable en API pure (pas seulement depuis le tableau de bord) si vous voulez automatiser votre propre onboarding — les mêmes appels sont ceux que fait l'interface web.
</Info>

## 1. Créer votre compte utilisateur

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/users/ \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Awa Sossou",
    "email": "awa@example.com",
    "country": "<uuid du pays, cf. GET /countries/>",
    "password": "un-mot-de-passe-solide"
  }'
```

Public — aucune authentification requise. Déclenche automatiquement l'envoi d'un code de vérification par email.

## 2. Vérifier votre email

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/auth/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "awa@example.com", "code": "123456"}'
```

Tant que l'email n'est pas vérifié, la connexion (étape 3) échoue avec `403 email_not_verified`.

## 3. Vous connecter (obtenir un jeton de session)

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "awa@example.com", "password": "un-mot-de-passe-solide"}'
```

```json Réponse theme={null}
{ "tokens": { "access": "eyJhbGciOi...", "refresh": "eyJhbGciOi..." } }
```

<Note>
  Si l'authentification à deux facteurs est activée sur le compte, cette réponse contient `pending_2fa_token` au lieu de `tokens` — une étape supplémentaire (`POST /auth/login/verify-2fa/`) est alors nécessaire. Non détaillée ici, hors périmètre de l'intégration API pure.
</Note>

Utilisez `access` dans le header `Authorization: Bearer <access>` pour toutes les requêtes des étapes suivantes — **ce n'est pas une clé API**, c'est un jeton de session classique, à ne jamais confondre avec `sk_live_.../sk_test_...`.

## 4. Créer votre marchand (votre "boutique")

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/merchants/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ma Boutique",
    "website_url": "https://maboutique.com",
    "category": "e-commerce"
  }'
```

Un même compte utilisateur peut posséder plusieurs marchands (plusieurs boutiques indépendantes). Le marchand créé démarre avec `kyc_status: "NONE"` et `is_active: false` — inutilisable tant que le KYC n'est pas validé.

## 5. Soumettre votre dossier KYC

<Note>
  Le KYC est un mécanisme dashboard/JWT uniquement, de bout en bout — jamais exposé par clé API, y compris en lecture. Il n'apparaît donc pas ailleurs dans cette documentation ; le détail ci-dessous est le seul endroit où ce flux est documenté.
</Note>

D'abord, créez le dossier lui-même :

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/merchant-kyc/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "<id du marchand créé à l'\''étape 4>",
    "kyc_type": "BUSINESS",
    "first_name": "Awa", "last_name": "Sossou",
    "company_name": "Ma Boutique SARL", "rccm_number": "BJ-COT-2023-B-1234", "ifu_number": "3202312345678"
  }'
```

Puis uploadez chaque pièce justificative (image ou PDF, 10 Mo max) — cet endpoint reçoit un binaire multipart et renvoie une URL à réutiliser à l'étape suivante :

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/merchant-kyc/upload/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -F "file=@/chemin/vers/piece-identite.jpg"
```

```json Réponse theme={null}
{ "url": "https://.../kyc/3f9a1b2c....jpg" }
```

Enfin, attachez chaque URL obtenue au dossier avec le type de pièce correspondant (`ID_CARD`, `PASSPORT`, `SELFIE`, `BUSINESS_REGISTRATION`, `FISCAL` ou `OTHER`) :

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/merchant-kyc/<id du dossier>/documents/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"document_type": "ID_CARD", "file_url": "https://.../kyc/3f9a1b2c....jpg"}'
```

## 6. Attendre la validation

Un administrateur AlphaPay examine le dossier. Vous recevez un email dès qu'une décision est prise. Une fois validé, `merchant.kyc_status` passe à `"VERIFIED"` et `is_active` à `true`.

## 7. Créer votre première clé API

```bash theme={null}
curl -X POST https://api.alphapay.me/api/v1/merchant-api-keys/ \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend production",
    "environment": "LIVE",
    "scope": "BOTH"
  }'
```

```json Réponse theme={null}
{
  "id": "d4e5...", "merchant": "8a2f...", "name": "Backend production",
  "key_prefix": "sk_live_AbCdEfGh", "environment": "LIVE", "scope": "BOTH",
  "is_active": true, "expires_at": null, "last_used_at": null,
  "secret": "sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789"
}
```

<Warning>
  Le champ `secret` (la clé complète) n'est renvoyé **qu'une seule fois**, dans cette réponse. Il n'est jamais récupérable après coup, même via le tableau de bord — s'il est perdu, générez-en une nouvelle. Copiez-le immédiatement dans votre gestionnaire de secrets.
</Warning>

* `environment` : `"LIVE"` (préfixe `sk_live_`, argent réel) ou `"SANDBOX"` (préfixe `sk_test_`, tests sans argent réel).
* `scope` : `"PAYIN"`, `"PAYOUT"` ou `"BOTH"` (défaut). Une clé `PAYIN` seule ne peut pas initier de retrait, et inversement — limitez le scope d'une clé exposée côté frontend/serveur web à ce qui est strictement nécessaire.

Vous avez maintenant une clé API utilisable pour tous les endpoints décrits dans le reste de cette documentation. Voir [Démarrage rapide](/quickstart) pour votre premier appel.

## Accès dashboard vs. clé API

Une fois votre clé API en main, une bonne partie de la gestion de votre compte reste néanmoins **exclusivement accessible depuis le [tableau de bord](https://app.alphapay.me)** (jeton de session), jamais par clé API — même en lecture pour la plupart. C'est un choix délibéré : ces opérations touchent au compte lui-même (qui peut agir, avec quels droits, vers quelles coordonnées) plutôt qu'aux opérations de paiement au jour le jour, pour lesquelles la clé API est faite.

| Domaine                                                                                                                                                                    | Accès par clé API                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Paiements, retraits, transactions, liens de paiement                                                                                                                       | Complet — c'est l'usage prévu de la clé API              |
| Soldes wallet (lecture) + taux de change (lecture)                                                                                                                         | Lecture seule — voir [Wallet](/api-reference/wallet)     |
| Webhooks (consultation des points de réception, abonnements, historique de livraison)                                                                                      | Lecture seule — voir [Webhooks](/api-reference/webhooks) |
| Compte marchand, KYC, clés API elles-mêmes, méthodes de retrait, demandes de retrait, transferts interwallet, relevé détaillé du wallet, création/modification de webhooks | Aucun — dashboard uniquement                             |

Une clé API ne peut par exemple **jamais** gérer les clés API elles-mêmes (créer, modifier, révoquer — y compris se révoquer elle-même), ni consulter ou modifier le profil de votre marchand.