Documentation de l'API de paiement FrikPay

!Limites actuelles

Cette API est en tout début de vie. Voici précisément ce qu'elle sait faire aujourd'hui — et ce qu'elle ne sait pas encore faire. Merci d'en tenir compte avant d'intégrer.

Ces limites reflètent l'état réel du système en production aujourd'hui, pas une restriction arbitraire de cette documentation. Toute tentative de paiement avec une devise, un réseau ou un pays non supporté sera refusée par l'API (le plus souvent avec le message Aucune route de paiement disponible. ou Réseau introuvable pour le numéro fourni.).

→Démarrage rapide

1. Créez votre compte marchand et une application

   Rendez-vous sur le portail marchand FrikPay et créez votre compte, puis une application (menu Applications). Une application représente un projet / intégration : vous pouvez en avoir plusieurs.

   Cette étape ne nécessite aucun document KYC.

2. Générez vos clés API sandbox

   Dans votre application, ouvrez Clés API et générez une paire de clés sandbox :

   X-FRIKLABEL-PUBLIC-KEY: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   X-FRIKLABEL-SECRET-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   La secret_key ne s'affiche qu'une seule fois à la génération — stockez-la immédiatement dans un endroit sûr (gestionnaire de secrets, variables d'environnement). Ne la commitez jamais dans votre code.

   ✅ Aucun KYC requis pour le sandbox

   Contrairement à la production, générer et utiliser des clés sandbox ne nécessite pas que votre compte marchand ait terminé sa vérification KYC. Vous pouvez tester votre intégration dès aujourd'hui.

3. Effectuez votre premier paiement de test

   Appelez POST /api/v1/payments avec vos clés sandbox. En sandbox, aucun opérateur réel n'est appelé : le paiement est simulé à partir du numéro de téléphone envoyé dans customer_phone.

   curl -X POST https://api.frikpay.digital/api/v1/payments \
     -H "Content-Type: application/json" \
     -H "X-FRIKLABEL-PUBLIC-KEY: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "X-FRIKLABEL-SECRET-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -d '{
           "merchant_reference": "CMD-TEST-0001",
           "amount": 1500,
           "currency": "XOF",
           "customer_phone": "22961000001"
         }'

   ⚠️ Numéros de test sandbox

   Le résultat d'un paiement sandbox (succès, échec, etc.) dépend d'un numéro de téléphone de test préconfiguré côté FrikPay pour country_code = BJ, currency = XOF et payment_method = mobile_money — un numéro qui n'est pas préconfiguré renvoie l'erreur Numéro de test sandbox non configuré. Demandez la liste à jour des numéros de test (et du scénario associé — succès, échec, etc.) à l'équipe FrikPay ou consultez la section correspondante du portail marchand ; elle n'est pas reproduite ici car elle peut évoluer sans changer cette API.

   Réponse typique (simulation réussie) :

   {
     "success": true,
     "message": "Paiement sandbox simulé.",
     "data": {
       "success": true,
       "simulation_status": "success",
       "reference_id": "FRIK-20260821143012-A1B2C3D4",
       "merchant_reference": "CMD-TEST-0001",
       "status": "success",
       "network": "mtn",
       "amount": 1500,
       "fee_bearer": "beneficiary",
       "fee_amount": 22.5,
       "customer_debited_amount": 1522.5,
       "beneficiary_net_amount": 1500,
       "currency": "XOF",
       "sandbox": true,
       "message": "Paiement sandbox simulé."
     }
   }

   Conservez data.reference_id : c'est l'identifiant à utiliser à l'étape suivante.

4. Vérifiez le statut du paiement

   curl https://api.frikpay.digital/api/v1/payments/FRIK-20260821143012-A1B2C3D4 \
     -H "X-FRIKLABEL-PUBLIC-KEY: pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "X-FRIKLABEL-SECRET-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

   En production, un paiement passe par pending (demande envoyée au client) avant d'atteindre un statut terminal (success ou failed) une fois que le client a validé — ou non — l'opération sur son téléphone. Interrogez cet endpoint (toutes les 3 à 5 secondes pendant 1 à 2 minutes, par exemple) jusqu'à statut terminal ; ne vous fiez pas au seul appel de création pour connaître l'issue réelle du paiement.

5. Passez en production

   Une fois le KYC de votre compte marchand approuvé, générez une paire de clés production (pk_live_... / sk_live_...) depuis le portail marchand, dans la même section Clés API.

   Votre intégration n'a rien d'autre à changer : même URL (https://api.frikpay.digital), même format de requête/réponse. Seule la paire de clés utilisée détermine l'environnement réellement exécuté.

   🔒 KYC non approuvé = production refusée

   Tant que kyc_status de votre compte marchand n'est pas approved, tout appel authentifié avec une clé de production échoue avec HTTP 401 et le message KYC marchand non validé pour la production.

🔑Authentification

Chaque requête doit inclure deux en-têtes HTTP. Il n'y a pas d'OAuth, pas de jeton porteur (bearer token) : uniquement une paire de clés.

Les clés API se génèrent exclusivement depuis le portail marchand (Applications → Clés API) ; il n'existe pas d'endpoint public pour créer des clés par API — cette action nécessite une session authentifiée sur le portail.

✕Erreurs

L'API répond toujours en JSON avec success: false et un message en français lisible. Il n'y a pas de champ code machine-lisible aujourd'hui — distinguez les cas via le code HTTP, et au besoin le texte du message. Voici les messages observés dans le code, avec leur code HTTP réel :

Authentification (les deux endpoints)

POST /api/v1/payments

GET /api/v1/payments/{reference}

🔔Webhooks Bientôt disponible