{ "openapi": "3.1.0", "info": { "title": "FluxPay Collect API", "version": "2026-06", "description": "API de collecte Mobile Money (push direct et lien de paiement hébergé). Montants en **unités majeures** : `amount: 3000` = 3 000 FCFA. Remplace `/collect/mobile-money/` (v1, dépréciée).", "contact": { "name": "FluxPay Integrations", "email": "integrations@fluxxpay.me" } }, "servers": [ { "url": "https://api.fluxxpay.me/api/v1", "description": "API v1" } ], "tags": [ { "name": "Collect", "description": "Paiements Mobile Money" }, { "name": "Catalog", "description": "Opérateurs et pays" } ], "security": [ { "BearerApiKey": [] } ], "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer", "description": "Clé API marchand (UUID). Alternative : header `X-API-Key`." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Clé idempotente (24 h). Requis sur POST création." }, "FluxxEnvironment": { "name": "X-Fluxx-Environment", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "test", "live" ] }, "description": "Ignoré si authentification par clé API (environnement = clé)." } }, "schemas": { "CollectPaymentCreate": { "type": "object", "required": [ "reference", "amount", "currency", "country" ], "properties": { "reference": { "type": "string", "maxLength": 100, "description": "Référence unique partenaire (UUID recommandé).", "example": "550e8400-e29b-41d4-a716-446655440000" }, "amount": { "type": "integer", "minimum": 100, "description": "Montant en unités majeures (3000 = 3 000 XOF).", "example": 3000 }, "currency": { "type": "string", "example": "XOF", "enum": [ "XOF", "XAF" ] }, "country": { "type": "string", "enum": [ "BJ", "TG", "CI" ] }, "mode": { "type": "string", "enum": [ "direct", "hosted" ], "default": "direct" }, "customer": { "type": "object", "properties": { "phone": { "type": "string", "example": "+22997000001" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "operator": { "type": "string", "description": "Obligatoire en mode `direct`.", "example": "mtn" }, "description": { "type": "string", "maxLength": 255 }, "callback_url": { "type": "string", "format": "uri", "description": "URL webhook HTTPS pour ce paiement (override marchand)." }, "expires_in_seconds": { "type": "integer", "minimum": 300, "maximum": 3600, "default": 900 }, "external_merchant_id": { "type": "string", "maxLength": 100 }, "metadata": { "type": "object", "additionalProperties": true } } }, "NextAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redirect_to_checkout", "await_customer_validation", "confirm_otp", "none" ] }, "message": { "type": "string" }, "checkout_url": { "type": "string", "format": "uri", "nullable": true } } }, "CollectPayment": { "type": "object", "properties": { "object": { "type": "string", "const": "collect.payment" }, "api_version": { "type": "string", "example": "2026-06" }, "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "awaiting_otp", "awaiting_payment", "completed", "failed", "cancelled", "expired", "refunded" ] }, "amount": { "type": "integer", "example": 3000 }, "amount_minor": { "type": "integer", "description": "Centimes internes (audit)." }, "currency": { "type": "string" }, "country": { "type": "string" }, "mode": { "type": "string", "enum": [ "direct", "hosted" ] }, "operator": { "type": "string", "nullable": true }, "customer": { "type": "object", "nullable": true }, "next_action": { "$ref": "#/components/schemas/NextAction" }, "checkout_url": { "type": "string", "format": "uri", "nullable": true }, "psp_reference": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "idempotent_replay": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "CollectPaymentConfirm": { "type": "object", "required": [ "otp" ], "properties": { "otp": { "type": "string", "minLength": 4, "maxLength": 8 } } }, "CollectPaymentCancel": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 64 } } }, "CollectRefundCreate": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Omission = remboursement total." }, "reason": { "type": "string", "default": "customer_dispute" }, "metadata": { "type": "object" } } }, "CollectRefund": { "type": "object", "properties": { "object": { "type": "string", "const": "collect.refund" }, "id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "amount": { "type": "integer" }, "currency": { "type": "string" } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "doc_url": { "type": "string", "format": "uri" } } } } }, "WebhookEvent": { "type": "object", "description": "Événement webhook v2 (signature body brut).", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "event" }, "api_version": { "type": "string" }, "type": { "type": "string", "example": "collect.payment.completed", "enum": [ "collect.payment.created", "collect.payment.processing", "collect.payment.completed", "collect.payment.failed", "collect.payment.cancelled", "collect.payment.expired", "collect.refund.completed", "collect.refund.failed" ] }, "created": { "type": "integer" }, "environment": { "type": "string" }, "merchant_id": { "type": "string", "format": "uuid" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/CollectPayment" } } } } } } }, "paths": { "/collect/openapi.json": { "get": { "tags": [ "Catalog" ], "summary": "Schéma OpenAPI Collect v2", "security": [], "responses": { "200": { "description": "Document OpenAPI 3.1", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/collect/payments": { "post": { "tags": [ "Collect" ], "summary": "Créer un paiement", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/FluxxEnvironment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPaymentCreate" }, "examples": { "direct_mtn_bj": { "summary": "Push MoMo direct (Bénin MTN)", "value": { "reference": "550e8400-e29b-41d4-a716-446655440000", "amount": 3000, "currency": "XOF", "country": "BJ", "mode": "direct", "customer": { "phone": "+22997000001" }, "operator": "mtn", "description": "Commande #abc-123", "callback_url": "https://api.partner.com/webhooks/payment", "expires_in_seconds": 900 } }, "hosted": { "summary": "Lien de paiement hébergé", "value": { "reference": "660e8400-e29b-41d4-a716-446655440001", "amount": 5000, "currency": "XOF", "country": "BJ", "mode": "hosted", "expires_in_seconds": 900 } } } } } }, "responses": { "201": { "description": "Paiement créé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPayment" } } } }, "200": { "description": "Replay idempotent" }, "400": { "description": "Validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/collect/payments/{reference_or_id}": { "get": { "tags": [ "Collect" ], "summary": "Consulter un paiement", "parameters": [ { "name": "reference_or_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sync", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Interroger le PSP si statut non terminal." } ], "responses": { "200": { "description": "Paiement trouvé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPayment" } } } }, "404": { "description": "Introuvable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/collect/payments/{reference_or_id}/confirm": { "post": { "tags": [ "Collect" ], "summary": "Confirmer OTP (Coris BJ)", "parameters": [ { "name": "reference_or_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPaymentConfirm" } } } }, "responses": { "200": { "description": "OTP confirmé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPayment" } } } } } } }, "/collect/payments/{reference_or_id}/cancel": { "post": { "tags": [ "Collect" ], "summary": "Annuler un paiement en cours", "parameters": [ { "name": "reference_or_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPaymentCancel" } } } }, "responses": { "200": { "description": "Annulé", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectPayment" } } } } } } }, "/collect/payments/{reference_or_id}/refunds": { "post": { "tags": [ "Collect" ], "summary": "Rembourser un paiement complété", "parameters": [ { "name": "reference_or_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectRefundCreate" } } } }, "responses": { "201": { "description": "Remboursement initié", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectRefund" } } } } } } }, "/collect/payments/operators/": { "get": { "tags": [ "Catalog" ], "summary": "Catalogue opérateurs", "parameters": [ { "name": "country", "in": "query", "schema": { "type": "string", "enum": [ "BJ", "TG", "CI" ] } } ], "responses": { "200": { "description": "Catalogue pays / opérateurs" } } } } }, "x-webhooks": { "collectPaymentCompleted": { "post": { "summary": "Paiement complété", "description": "Header `X-FluxPay-Signature: t={unix},v1={hex}` — HMAC-SHA256 de `{timestamp}.{raw_body}` avec le secret webhook.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Événement traité" } } } } } }