Documentation

L'API FiveOne Pay

Encaissez du Mobile Money en quelques appels. Cette documentation couvre l'essentiel : démarrage, authentification, création de paiement et webhooks.

Démarrage

Démarrage rapide

FiveOne Pay est une API REST qui vous permet d'encaisser des paiements Mobile Money à Madagascar (MVola aujourd'hui ; Orange Money et Airtel Money à venir). Toutes les requêtes se font sur la base URL suivante :

http

https://api.fiveonepay.com/v1

Les montants sont exprimés en Ariary (MGA), en nombres entiers — 50 000 MGA s'écrit 50000. Voici un premier appel pour créer un paiement :

Créer un paiementbash

curl -X POST https://api.fiveonepay.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "MGA",
    "reference": "CMD-1042",
    "mobile_money": true,
    "choice": "mvola",
    "number": "0341234567",
    "callback_url": "https://votre-site.com/webhooks/fiveonepay"
  }'

Démarrage

Authentification

Authentifiez chaque requête avec votre clé secrète, dans l'en-tête Authorization :

http

Authorization: Bearer sk_live_…

Vous disposez de deux environnements :

Clés de test (sk_test_…) — pour intégrer sans mouvement d'argent réel.
Clés live (sk_live_…) — pour la production.

Sécurité — Ne partagez jamais votre clé secrète côté client. En cas de fuite, révoquez-la depuis votre tableau de bord.

Paiements

Créer un paiement

Créez un paiement avec POST /v1/payments. Le marchand choisit le type de paiement ; FiveOne Pay renvoie une URL de paiement et notifie votre serveur via webhook.

POST /v1/paymentsbash

curl -X POST https://api.fiveonepay.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "MGA",
    "reference": "CMD-1042",
    "mobile_money": true,
    "choice": "mvola",
    "number": "0341234567",
    "callback_url": "https://votre-site.com/webhooks/fiveonepay"
  }'

Astuce — Indiquez un seul type de paiement à true (mobile_money, carte ou paypal). Les deux autres passent à false automatiquement.

Champ	Type	Requis	Description
`amount`	entier	Requis	Montant à encaisser, en Ariary (MGA), sans décimales.
`currency`	chaîne	Requis	Devise. « MGA » pour l'instant.
`reference`	chaîne	Requis	Votre référence de commande, renvoyée dans les webhooks.
`mobile_money`	booléen	Optionnel	Type de paiement. Mettez true pour encaisser via Mobile Money.
`carte`	booléen	Optionnel	Paiement par carte. false par défaut.
`paypal`	booléen	Optionnel	Paiement PayPal. false par défaut.
`choice`	chaîne	Requis	mvola, airtel_money ou orange_money (Mobile Money) ; e-mail du client pour carte/paypal.
`number`	chaîne	Si Mobile Money	Téléphone du client payeur. Obligatoire pour le Mobile Money.
`callback_url`	URL	Requis	URL appelée (webhook) à chaque changement de statut.

En réponse, vous recevez le paiement créé :

201 Createdjson

{
  "id": "pay_8f2k9d…",
  "status": "PENDING",
  "amount": 50000,
  "currency": "MGA",
  "reference": "CMD-1042",
  "fiveonepay_reference": "48205173",
  "payment_url": "https://pay.fiveonepay.com/pay_8f2k9d…",
  "created_at": "2026-06-22T09:30:00Z"
}

fiveonepay_reference est la référence unique FiveOne Pay (8 chiffres) générée pour la transaction, à conserver de votre côté pour le suivi et le rapprochement.

Redirigez votre client vers payment_url, ou déclenchez le paiement Mobile Money avec le numéro fourni.

Paiements

Webhooks & statuts

À chaque changement de statut, nous appelons votre callback_url en POSTavec l'événement :

Webhook reçujson

{
  "event": "payment.updated",
  "data": {
    "id": "pay_8f2k9d…",
    "status": "PAID",
    "amount": 50000,
    "currency": "MGA",
    "reference": "CMD-1042",
    "fiveonepay_reference": "48205173"
  }
}

Chaque webhook est signé. Vérifiez l'en-tête X-FiveOne-Signature (HMAC-SHA256) avec votre secret whsec_…avant de traiter l'événement :

Vérifier la signaturejavascript

import crypto from "node:crypto";

const signature = req.headers["x-fiveone-signature"];
const expected = crypto
  .createHmac("sha256", process.env.FIVEONE_WEBHOOK_SECRET)
  .update(rawBody) // corps brut de la requête
  .digest("hex");

if (signature !== expected) {
  return res.status(400).send("Signature invalide");
}

Statuts d'un paiement

PENDING	En attente de paiement.
PAID	Paiement réussi et confirmé.
FAILED	Le paiement a échoué.
REFUNDED	Paiement remboursé.
EXPIRED	Expiré sans paiement.

Nous réessayons l'envoi jusqu'à recevoir une réponse 2xx de votre serveur.