API Collect

Version 2026-06 — encaissement Mobile Money (Bénin, Togo, Côte d'Ivoire) en push direct ou via lien de paiement hébergé.

Base URL : https://api.fluxxpay.me/api/v1/collect/

OpenAPI : cdn.fluxxpay.me/v2/collect/openapi.json — aussi servi par GET /api/v1/collect/openapi.json.

Vue d'ensemble

Capacité	Détail
Push MoMo (STK)	`mode: "direct"`
Lien checkout (`checkout_url`)	`mode: "hosted"`
Montants API	Unités majeures (`3000` = 3 000 FCFA)
Idempotence	Header `Idempotency-Key` obligatoire (24 h)
Webhooks	`collect.payment.*` + signature HMAC body brut
`callback_url`	Optionnel par paiement

Testez sans code : Playground Collect. Intégration backend : SDK @fluxx/collect.

Authentification & scopes

Authorization: Bearer <clé_api_uuid>
Content-Type: application/json
Idempotency-Key: <uuid>

L'environnement test / live est déterminé par la clé API, pas par un header client.

Scopes sur les clés API (tableau permissions) :

Scope	Usage
`collect:read`	GET paiement, catalogue opérateurs
`collect:write`	POST création, confirm, cancel
`collect:refund`	POST remboursement

Liste vide = accès complet. Sinon : 403 insufficient_scope.

Rate limits (par clé, par minute) : création 30 · lecture 120 · remboursement 10. Réponse 429 + Retry-After.

Créer un paiement

POST /api/v1/collect/payments

Direct (push MoMo) :

{
  "reference": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 3000,
  "currency": "XOF",
  "country": "BJ",
  "mode": "direct",
  "customer": { "phone": "+22997000001" },
  "operator": "mtn",
  "description": "Commande #123",
  "callback_url": "https://api.partner.com/webhooks/payment",
  "expires_in_seconds": 900
}

Réponse 201 : objet collect.payment, statuts en minuscules (processing, awaiting_otp, …), next_action pour la suite.

Mode hosted

{
  "reference": "order-hosted-001",
  "amount": 5000,
  "currency": "XOF",
  "country": "BJ",
  "mode": "hosted",
  "description": "Paiement WhatsApp"
}

Réponse : checkout_url + next_action.type = redirect_to_checkout. Le client paie sur la page FluxPay ; vous recevez collect.payment.completed.

Sandbox TEST : simuler le checkout sans page réelle :

POST /api/v1/collect/payments/{reference}/pay
{ "phone": "22997000001", "operator": "mtn" }

Consulter un paiement

GET /api/v1/collect/payments/{reference_or_id}?sync=true

sync=true interroge l'orchestrateur si le statut n'est pas terminal.

Annuler / rembourser

POST /api/v1/collect/payments/{reference_or_id}/cancel
POST /api/v1/collect/payments/{reference_or_id}/refunds

Remboursement : scope collect:refund, paiement source completed.

Montants

Devise	Exposé API	Exemple
XOF, XAF	Entiers majeurs	`"amount": 3000` → 3 000 FCFA
Minimum	100 unités	`"amount": 100`

Les montants sont toujours en unités majeures, jamais en centimes.

Statuts

pending · processing · awaiting_otp · awaiting_payment (hosted) · completed · failed · cancelled · expired · refunded

Webhooks

Événements : collect.payment.created, .processing, .completed, .failed, .cancelled, .expired, collect.refund.*

Signature header :

X-FluxPay-Signature: t=1719493200,v1=<hex>

HMAC-SHA256 de {timestamp}.{raw_body} (body JSON brut, digest hex).

Voir aussi Webhooks.

Sandbox

Clé API TEST : simulateur sans PSP réel.

Numéro (BJ)	Résultat
`22997000001`	Succès
suffixe `…0001`	Échec
Coris + OTP `123456`	Succès après `/confirm`

Essayez ces scénarios dans le Playground Collect ou avec le SDK @fluxx/collect.

OpenAPI & outils

Ressource	URL
OpenAPI CDN	v2/collect/openapi.json
OpenAPI live	`GET /api/v1/collect/openapi.json`
Vérif. signature	`verifyWebhookSignature` (`@fluxx/collect`)

Webhooks

Changelog