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

Même endpoint et même flux que documentés dans KYC — la seule différence ici est le header d’authentification (Authorization: Bearer <jeton de session> plutôt qu’une clé API, puisqu’aucune clé n’existe encore à ce stade).

curl -X POST https://api.saspay.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 et attachez vos pièces justificatives (voir le détail).

6. Attendre la validation

Un administrateur SasPay 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.saspay.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.

Ce qui reste dashboard/JWT uniquement, même après avoir une clé

Une clé API ne peut jamais gérer les clés API elles-mêmes (créer, modifier, révoquer — y compris se révoquer elle-même) — voir Clés API pour l’explication complète de cette restriction volontaire.

​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

​Ce qui reste dashboard/JWT uniquement, même après avoir une clé

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

Ce qui reste dashboard/JWT uniquement, même après avoir une clé