Documentation de l’API
L’API Flixy Pay est une API REST. Les requêtes utilisent des paramètres de formulaire ou du JSON, les réponses sont en JSON. Les montants sont toujours en centimes (2500 = 25,00).
Authentification
Chaque requête envoie votre clé secrète dans l’en-tête Authorization. Les clés commencent par fp_test_ en mode test et fp_live_ en mode réel. Ne mettez jamais la clé secrète dans une page web ou une application mobile.
curl https://flixypay.net/v1/balance \ -H "Authorization: Bearer fp_test_sk_…"
| Clé | Usage |
|---|---|
fp_test_pk_… / fp_live_pk_… | Clé publique : navigateur et application (formulaire intégré). |
fp_test_sk_… / fp_live_sk_… | Clé secrète : uniquement sur votre serveur. |
Mode test
Le mode test est disponible dès l’inscription, avant toute vérification d’identité. Aucun argent réel ne circule. Utilisez ces cartes avec une date d’expiration future et n’importe quel code à 3 chiffres :
| Numéro | Résultat |
|---|---|
4242 4242 4242 4242 | Paiement réussi |
5555 5555 5555 4444 | Paiement réussi (Mastercard) |
4000 0025 0000 3155 | Authentification 3D Secure demandée |
4000 0000 0000 9995 | Refusé : fonds insuffisants |
4000 0000 0000 0002 | Refusé : carte refusée |
Erreurs
Les erreurs renvoient un code HTTP 4xx ou 5xx et un objet error avec un type et un message lisible.
{
"error": { "type": "invalid_request", "message": "amount is required" }
}
400 | Paramètre manquant ou invalide |
401 | Clé absente, invalide ou révoquée |
403 | Compte suspendu ou mode réel pas encore activé |
404 | Ressource introuvable |
429 | Trop de requêtes, réessayez dans un instant |
Paiements
POST/v1/paymentsCrée un paiement. Paramètres : amount (obligatoire, en centimes), currency (eur par défaut), description, customer_email, success_url, cancel_url, metadata[clé].
curl https://flixypay.net/v1/payments \ -H "Authorization: Bearer fp_test_sk_…" \ -d amount=4900 -d currency=eur \ -d description="Abonnement mars" \ -d success_url="https://exemple.fr/merci" \ -d "metadata[order_id]=1048"
{
"id": "pay_9fK2…", "object": "payment", "livemode": false,
"amount": 4900, "currency": "eur", "status": "requires_payment",
"checkout_url": "https://flixypay.net/pay/pay_9fK2…",
"client_secret": "…", "metadata": { "order_id": "1048" }
}
GET/v1/payments/{id} GET/v1/payments?limit=20&status=succeeded Statuts possibles : requires_payment, succeeded, failed, partially_refunded, refunded.
Page de paiement hébergée
La façon la plus simple : redirigez le client vers checkout_url. Après le paiement, il revient sur success_url avec ?payment=pay_… ; vérifiez toujours le statut côté serveur ou attendez le webhook payment.succeeded avant de livrer.
Formulaire intégré
Pour garder le client sur votre page, créez le paiement côté serveur puis affichez le formulaire avec flixypay.js et votre clé publique.
<div id="pay"></div> <script src="https://flixypay.net/js/flixypay.js"></script> <script> const fp = FlixyPay('fp_test_pk_…'); fp.mount('#pay', { payment: 'pay_9fK2…', clientSecret: '…', onSuccess: () => location.href = '/merci' }); </script>
Remboursements
POST/v1/payments/{id}/refundsRembourse tout ou partie d’un paiement réussi. Paramètres : amount (facultatif, tout le reste par défaut), reason.
curl https://flixypay.net/v1/payments/pay_9fK2…/refunds \ -H "Authorization: Bearer fp_test_sk_…" -d amount=1000
Liens de paiement
POST/v1/links GET/v1/linksCrée un lien réutilisable. Paramètres : title, amount, currency. La réponse contient url, à partager tel quel.
Solde
GET/v1/balanceRenvoie les montants en attente et disponibles du compte, dans la devise du compte.
Tap to Pay
POST/v1/terminal/connection_tokensRenvoie un jeton de connexion à transmettre à votre application mobile pour encaisser en personne. À appeler depuis votre serveur, à chaque fois que l’application en demande un.
Webhooks
Ajoutez l’adresse de votre serveur dans Espace → Webhooks. Chaque évènement est envoyé en POST JSON avec l’en-tête Flixy-Signature: t=horodatage,v1=signature. La signature est un HMAC SHA-256 de « horodatage.corps » avec le secret du point de terminaison (whsec_…). Répondez 2xx rapidement.
// PHP — vérifier la signature $payload = file_get_contents('php://input'); parse_str(str_replace(',', '&', $_SERVER['HTTP_FLIXY_SIGNATURE']), $sig); $expected = hash_hmac('sha256', $sig['t'] . '.' . $payload, getenv('FLIXYPAY_WHSEC')); if (!hash_equals($expected, $sig['v1']) || abs(time() - $sig['t']) > 300) { http_response_code(400); exit; } $event = json_decode($payload, true); if ($event['type'] === 'payment.succeeded') { /* livrer la commande */ }
Types d’évènements
payment.succeeded | Un paiement a réussi |
payment.failed | Un paiement a échoué |
payment.refunded | Un paiement a été remboursé en tout ou partie |
refund.created | Un remboursement a été créé |
dispute.created | Un client a contesté un paiement |
dispute.closed | Un litige est clos |
payout.paid | Un virement est arrivé sur le compte bancaire |
account.updated | Le statut du compte a changé |
link.paid | Un lien de paiement a été payé |