Documentation Flinpay

Flinpay est un agrégateur de paiement mobile money couvrant 7 pays d'Afrique francophone. 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 300 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. La confirmation lui est envoyée directement sur son téléphone.

POST /api/pay

Champ	Type	Description
amount	number	Montant à encaisser, dans la devise de votre pays marchand
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 du client — voir la liste ci-dessous
operator	string	Opérateur mobile money du client — voir la liste ci-dessous
otp (optionnel)	string	Requis uniquement si l'opérateur choisi l'exige (rare) — sinon omettez ce champ

Pays et opérateurs couverts (codes ISO2 réellement pris en charge — n'en inventez pas d'autres, la requête serait rejetée) :

CM — mtn, orange CI — mtn, orange, moov, wave BF — moov, orange BJ — mtn, moov TG — tmoney, moov CD — vodacom, airtel, orange GA — airtel

ℹ️ La disponibilité exacte des opérateurs peut évoluer sans préavis côté prestataire. En cas de doute, testez d'abord en sandbox.

# Python
import requests

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

print(response.json())

// JavaScript
const res = await fetch("https://www.flinpay.cfd/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",
    operator: "wave"
  })
});

const data = await res.json();

<?php // PHP
$ch = curl_init("https://www.flinpay.cfd/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",
    "operator" => "wave"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));

📲 Le client reçoit une confirmation directe sur son téléphone — il n'y a pas de page de paiement à ouvrir ni de redirection à gérer.

Réponses & statuts

Une requête réussie renvoie :

{
  "ok": true,
  "token": "fp_tx_a1b2c3d4e5f6...",
  "order_id": "ORD-001",
  "amount": 10000,
  "status": "pending"
}

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é

Ces trois statuts sont une abstraction stable de notre côté : ils ne changent pas même si le prestataire mobile money sous-jacent évolue.

Erreurs

Code HTTP	Cause probable
400	Champ requis manquant ou invalide (montant, opérateur non reconnu pour ce pays...)
401	Clé API absente, invalide ou révoquée
403	Quota mensuel du plan Starter atteint, ou compte restreint
429	Trop de requêtes envoyées trop vite (limite : 60 paiements/minute par IP)
500 / 502	Erreur serveur ou prestataire de paiement momentanément indisponible — réessayez

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. Votre client ouvre la page (hébergée par Flinpay), choisit son opérateur parmi ceux disponibles pour son pays et confirme directement depuis son téléphone — aucune redirection vers un site tiers.

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, et ne comptent pas dans votre quota mensuel. Basculez vers fp_live_ uniquement en production, une fois votre intégration testée.

Webhooks

Configurez un endpoint depuis Dashboard → Webhooks pour recevoir une notification à chaque paiement confirmé ou échoué.

{
  "event": "payment.success",
  "data": {
    "token": "fp_tx_a1b2c3d4e5f6...",
    "order_id": "ORD-001",
    "amount": 10000,
    "status": "paid",
    "client_name": "Kouamé Diallo",
    "client_phone": "0700000000"
  }
}

Événements disponibles : payment.success, payment.failed.

⚠️ Flinpay n'envoie pas encore de signature sur ces notifications sortantes. Avant de considérer un paiement comme confirmé, vérifiez la cohérence des données reçues (montant, order_id) avec votre propre historique, ou mieux : interrogez votre propre API pour re-confirmer le statut de la transaction plutôt que de faire confiance au webhook seul.

🌐 Seule une URL publique et en HTTPS, non hébergée sur votre réseau interne, sera acceptée comme destination de webhook.