Référence de l’API

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).

https://flixypay.net/v1

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éroRésultat
4242 4242 4242 4242Paiement réussi
5555 5555 5555 4444Paiement réussi (Mastercard)
4000 0025 0000 3155Authentification 3D Secure demandée
4000 0000 0000 9995Refusé : fonds insuffisants
4000 0000 0000 0002Refusé : 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" }
}
400Paramètre manquant ou invalide
401Clé absente, invalide ou révoquée
403Compte suspendu ou mode réel pas encore activé
404Ressource introuvable
429Trop de requêtes, réessayez dans un instant

Paiements

POST/v1/payments

Cré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}/refunds

Rembourse 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

Solde

GET/v1/balance

Renvoie les montants en attente et disponibles du compte, dans la devise du compte.

Tap to Pay

POST/v1/terminal/connection_tokens

Renvoie 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.succeededUn paiement a réussi
payment.failedUn paiement a échoué
payment.refundedUn paiement a été remboursé en tout ou partie
refund.createdUn remboursement a été créé
dispute.createdUn client a contesté un paiement
dispute.closedUn litige est clos
payout.paidUn virement est arrivé sur le compte bancaire
account.updatedLe statut du compte a changé
link.paidUn lien de paiement a été payé