Documentation Flinpay

Flinpay est un agrégateur de paiement mobile money couvrant 12 pays d'Afrique francophone et anglophone. Une seule intégration API pour encaisser dans tous les corridors supportés.

💡 Pas encore de compte ? Créez-en un gratuitement — le plan Starter inclut 100 transactions/mois sans frais fixes.

Authentification

Toutes les requêtes à l'API de paiement doivent inclure votre clé API dans l'en-tête Authorization, au format Bearer token.

Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxx

Vous trouverez vos clés dans Dashboard → Clés API. Chaque clé existe en deux versions :

Préfixe	Environnement	Effet
fp_live_	Production	Transactions réelles, argent réellement déplacé
fp_test_	Sandbox	Transactions simulées, aucun argent déplacé

⚠️ Ne partagez jamais votre clé fp_live_ côté client (navigateur, app mobile). Utilisez-la uniquement depuis votre serveur.

Vérification d'identité (KYC)

Pour des raisons de sécurité et de conformité, la génération de clés API nécessite une vérification d'identité préalable. Rendez-vous sur Vérification, soumettez une pièce d'identité (CNI, passeport ou permis), et attendez la validation (généralement sous 24-48h).

Tant que votre compte n'est pas vérifié, la page Clés API reste verrouillée.

Initier un paiement

Déclenche une demande de paiement mobile money vers le numéro du client.

POST /api/pay

Champ	Type	Description
amount	number	Montant à encaisser (dans la devise du pays du client)
phone	string	Numéro mobile money du client
client_name	string	Nom complet du client
order_id	string	Identifiant unique de la commande côté marchand
country	string	Code pays ISO2 (ex: `CI`, `CM`, `SN`)

# Python
import requests

response = requests.post(
    "https://flinpay.vercel.app/api/pay",
    headers={"Authorization": "Bearer fp_live_votre_cle"},
    json={
        "amount": 10000,
        "phone": "0700000000",
        "client_name": "Kouamé Diallo",
        "order_id": "ORD-001",
        "country": "CI"
    }
)
print(response.json())

// JavaScript
const res = await fetch("https://flinpay.vercel.app/api/pay", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fp_live_votre_cle",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 10000,
    phone: "0700000000",
    client_name: "Kouamé Diallo",
    order_id: "ORD-001",
    country: "CI"
  })
});
const data = await res.json();

<?php // PHP
$ch = curl_init("https://flinpay.vercel.app/api/pay");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer fp_live_votre_cle",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "amount" => 10000,
    "phone" => "0700000000",
    "client_name" => "Kouamé Diallo",
    "order_id" => "ORD-001",
    "country" => "CI"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));

Réponses & statuts

Une requête réussie renvoie :

{
  "ok": true,
  "token": "fp_tx_a1b2c3d4e5f6...",
  "order_id": "ORD-001",
  "amount": 10000,
  "status": "pending",
  "payment_url": "https://flinpay.vercel.app/pay/fp_tx_..."
}

Statuts possibles pour une transaction :

Statut	Signification
pending	En attente de confirmation par l'opérateur mobile money
paid	Paiement confirmé et encaissé
failed	Paiement refusé, expiré ou annulé

Erreurs

Code HTTP	Cause probable
400	Champ requis manquant ou invalide
401	Clé API absente, invalide ou révoquée
500	Erreur serveur — réessayez ou contactez le support

Le corps de la réponse d'erreur contient toujours {"ok": false, "error": "..."} avec un message explicite.

Liens de paiement

Pour encaisser sans écrire de code, créez un lien de paiement partageable depuis Dashboard → Liens de paiement. Le lien ouvre une page de paiement hébergée par Flinpay où votre client saisit son numéro mobile money.

Sandbox vs Production

Utilisez votre clé fp_test_ pendant le développement : les transactions sont marquées environment: "sandbox" et n'impliquent aucun mouvement d'argent réel. Basculez vers fp_live_ uniquement en production, une fois votre intégration testée.

Webhooks

🚧 Les webhooks de confirmation de paiement (notification automatique vers votre serveur) sont en cours de développement et arrivent prochainement.

En attendant, interrogez le statut de vos transactions depuis votre tableau de bord.