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 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`)
operator	string	`momo` (MTN Mobile Money) ou `om` (Orange Money)

# 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": "momo"
    }
)
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: "momo"
  })
});
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" => "momo"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));

📲 Le client reçoit une confirmation directe sur son téléphone (USSD) — 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é

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. Votre client ouvre la page (hébergée par Flinpay), choisit son opérateur (MTN MoMo ou Orange Money) 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. 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 de signature sur ces notifications sortantes pour l'instant — vérifiez la cohérence des données reçues (montant, order_id) avec votre propre historique avant de considérer un paiement comme confirmé.