Webhooks
Recevez les changements de statut en temps réel plutôt que d'interroger l'API en boucle.
Configuration
- Dashboard marchand → Paramètres → Webhooks (
/dashboard/settings/webhooks) - URL HTTPS de votre endpoint
- Abonnement aux événements souhaités
- Secret pour vérifier les signatures (recommandé)
Événements Collect
Format 2026-06 — utilisé par POST /collect/payments et callback_url par paiement.
- Name
collect.payment.created- Description
Paiement créé (direct ou hosted).
- Name
collect.payment.processing- Description
Traitement PSP en cours.
- Name
collect.payment.completed- Description
Paiement réussi — confirmer commande, envoyer reçu.
- Name
collect.payment.failed- Description
Échec définitif.
- Name
collect.payment.cancelled- Description
Annulation marchand ou client.
- Name
collect.payment.expired- Description
TTL dépassé (
expires_in_seconds).
- Name
collect.refund.completed- Description
Remboursement effectué.
Signature (body JSON brut, pas de re-tri) :
X-FluxPay-Signature: t=1719493200,v1=<hex_hmac_sha256>
X-FluxPay-Event: collect.payment.completed
Calcul : HMAC-SHA256(secret, "{timestamp}." + raw_body) → digest hex.
Vérification côté code : verifyWebhookSignature (@fluxx/collect). Anciens noms d'événements : voir Changelog.
Événements Payout
- Name
payout.initiated- Description
Décaissement créé.
- Name
payout.completed- Description
Fonds envoyés avec succès.
- Name
payout.failed- Description
Échec définitif.
- Name
payout.cancelled- Description
Décaissement annulé.
- Name
payout.updated- Description
Changement de statut intermédiaire.
Bonnes pratiques
- Name
Réponse rapide- Description
HTTP 2xx en moins de 30 secondes.
- Name
Idempotence- Description
Un même événement peut être renvoyé : traitez par
referenceou id transaction.
- Name
Traitement asynchrone- Description
Répondez 200 puis traitez en file d'attente.