Créer un compte et obtenir une clé API

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

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.

1. Créer votre compte utilisateur

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

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)

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"}'

Réponse

{ "tokens": { "access": "eyJhbGciOi...", "refresh": "eyJhbGciOi..." } }

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.

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”)

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

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

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

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 :

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

Réponse

{ "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) :

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

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"
  }'

Réponse

{
  "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"
}

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.

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 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 (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
Webhooks (consultation des points de réception, abonnements, historique de livraison)	Lecture seule — voir 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.

​1. Créer votre compte utilisateur

​2. Vérifier votre email

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

​4. Créer votre marchand (votre “boutique”)

​5. Soumettre votre dossier KYC

​6. Attendre la validation

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

​Accès dashboard vs. clé API

1. Créer votre compte utilisateur

2. Vérifier votre email

3. Vous connecter (obtenir un jeton de session)

4. Créer votre marchand (votre “boutique”)

5. Soumettre votre dossier KYC

6. Attendre la validation

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

Accès dashboard vs. clé API