Intégration directe (votre propre design)

Votre client choisit son moyen de paiement sur votre site, avec votre design. Votre serveur appelle l’API AIFI PAY ; le client valide sur son téléphone (MVola) ou sur la page d’Orange (Orange Money).

Paiement hébergé ou intégration directe ?

C’est la même API, avec la même clé secrète, les mêmes notifications et la même commission. Seul l’appel de départ change.

  • Paiement hébergé (POST /v1/checkout/sessions) : vous redirigez le client vers la page AIFI PAY. Le plus simple, recommandé pour démarrer.
  • Intégration directe (POST /v1/payments) : vous construisez votre page de paiement, vous collectez le numéro MVola du client et vous affichez vous-même l’attente et le résultat. Orange Money se confirme toujours sur la page d’Orange.

Vous pouvez utiliser les deux, par exemple le paiement hébergé sur votre site et l’intégration directe dans votre application.

Comment ça marche

  1. Votre serveur demande les moyens de paiement disponibles et votre page n’affiche que ceux-là.
  2. Le client choisit son moyen de paiement sur votre page, et votre serveur crée le paiement.
  3. MVola : vous envoyez le numéro saisi par le client. Il reçoit la demande sur son téléphone et la valide avec son code secret MVola, pendant que votre page affiche votre propre écran d’attente.
  4. Orange Money : vous redirigez le client vers la page d’Orange. Il y confirme son paiement, puis revient sur votre site.
  5. Votre serveur apprend le résultat par la notification signée (recommandé) ou en lisant le paiement. Vous validez alors la commande.

1. Lister les moyens de paiement disponibles

GET/v1/payment-methods

Renvoie les moyens de paiement de l’environnement de votre clé (Sandbox ou Production). N’affichez comme payables que ceux où available vaut true ; les autres peuvent apparaître comme « Bientôt ».

Réponse 200 (exemple en Production)
{
  "environment": "PRODUCTION",
  "methods": [
    { "id": "MVOLA", "name": "MVola", "available": true,
      "flow": "phone_confirmation", "requiredFields": ["provider", "customer.phone"] },
    { "id": "ORANGE_MONEY", "name": "Orange Money", "available": true,
      "flow": "redirect", "requiredFields": ["provider", "successUrl"] },
    { "id": "AIRTEL_MONEY", "name": "Airtel Money", "available": false,
      "flow": "phone_confirmation", "requiredFields": [] }
  ]
}
  • phone_confirmation : le client valide sur son téléphone. Envoyez son numéro dans customer.phone.
  • redirect : le client confirme sur la page de l’opérateur (Orange Money). Envoyez successUrl, puis redirigez le client vers payment.paymentUrl. L’opérateur ne permet pas de payer entièrement sur votre page (détail ci-dessous).
  • simulated : simulateur, uniquement en Sandbox.

2. Créer le paiement

POST/v1/payments

En-têtes : Authorization: Bearer VOTRE_CLE_SECRETE et Idempotency-Key (obligatoire, une valeur par commande : si votre serveur réessaie, le même paiement est renvoyé au lieu d’en créer un second).

Corps de la requête (MVola)
{
  "amount": 15000,                         // en Ariary, entier (nombre ou texte)
  "provider": "MVOLA",
  "merchantReference": "CMD-2026-0042",    // votre numéro de commande
  "customer": { "phone": "0340000000" },   // numéro MVola du client (034, 036 ou 038)
  "description": "Forfait 30 jours",       // facultatif : la « Raison » du SMS MVola
  "metadata": { "orderId": "42" }          // facultatif, renvoyé dans la notification
}

Raison affichée au client. MVola montre au payeur une « Raison » dans son SMS. C’est votre description (à la racine ou dans metadata.description, jusqu’à 200 caractères). MVola n’accepte que 50 caractères, sans accents : les lettres accentuées deviennent simples (é → e), les autres signes deviennent des espaces, et le texte est coupé à 50 caractères sur un mot entier. Sans description, la raison est « Paiement », le nom de votre boutique et votre merchantReference (par exemple Paiement TikMan CMD-2026-0042) : préférez une référence courte et lisible. Le nom « AIFI » du SMS est celui du compte marchand MVola et ne change pas.

Réponse 201 (exemple)
{
  "payment": {
    "id": "cm_exemple_123",
    "status": "PENDING",
    "amount": "15000",
    "fee": "450",
    "netAmount": "14550",
    "currency": "MGA",
    "provider": "MVOLA",
    "merchantReference": "CMD-2026-0042"
  }
}

Gardez payment.id avec votre commande. Le client reçoit la demande MVola en quelques secondes ; affichez par exemple « Validez le paiement sur votre téléphone ».

Créer un paiement Orange Money

Orange Money impose sa propre page : le client y confirme toujours son paiement, il ne peut pas le faire sur votre site. L’appel est le même, avec les mêmes en-têtes, mais sans numéro de client. L’API vous renvoie l’adresse de la page d’Orange dans payment.paymentUrl.

Corps de la requête (Orange Money)
{
  "amount": 15000,
  "provider": "ORANGE_MONEY",
  "merchantReference": "CMD-2026-0042",
  "successUrl": "https://votre-site/paiement/retour",   // obligatoire : retour après la page d'Orange
  "cancelUrl": "https://votre-site/panier",              // facultatif : retour si le client annule
  "metadata": { "orderId": "42" }
}
Réponse 201 (exemple)
{
  "payment": {
    "id": "cm_exemple_123",
    "status": "PENDING",
    "amount": "15000",
    "fee": "450",
    "netAmount": "14550",
    "currency": "MGA",
    "provider": "ORANGE_MONEY",
    "merchantReference": "CMD-2026-0042",
    "paymentUrl": "https://…orange-money.com/…"     // redirigez le client vers cette adresse
  }
}
  1. Gardez payment.id avec votre commande et redirigez le client vers payment.paymentUrl.
  2. Il confirme sur la page d’Orange, puis revient sur successUrl. S’il annule, il revient sur cancelUrl, ou sur successUrl si vous n’avez pas donné de cancelUrl.
  3. Votre page de retour lit le statut par votre serveur (section suivante) : ce retour seul ne prouve pas le paiement.

3. Connaître le résultat

Recommandé : la notification. AIFI PAY envoie à votre URL de notification un événement signé payment.succeeded, payment.failed, payment.cancelled ou payment.expired, comme pour le paiement hébergé. Vérifiez la signature AIFI-Signature avant de valider la commande (voir Vérifier la notification).

En complément : lire le paiement depuis votre serveur, par exemple toutes les 3 secondes pendant que votre page d’attente est affichée :

GET/v1/payments/:id
  • SUCCEEDED : payé. Validez la commande.
  • FAILED, CANCELLED, EXPIRED : non payé, rien n’a été débité. Proposez de réessayer (avec une nouvelle Idempotency-Key).
  • CREATED, PENDING, PROCESSING : en attente de la validation du client. Ne proposez pas de payer une seconde fois.

Tester en Sandbox

Avec une clé sk_test_…, utilisez "provider": "SANDBOX_SIMULATOR" et "sandboxScenario" (SUCCESS, FAILED, PENDING, EXPIRED, TIMEOUT) pour reproduire chaque cas sans argent réel. Voir Sandbox.

Pour tester le parcours Orange Money, voir la page de test d’Orange.

Exemple Node.js (serveur)

server.js
// La clé reste côté serveur (variable d'environnement), jamais dans le navigateur.
const API = "https://api.aifipay.pro";
const KEY = process.env.AIFIPAY_SECRET_KEY;

// Votre page appelle cette route avec le numéro saisi par le client.
app.post("/paiement/mvola", async (req, res) => {
  const order = await findOrder(req.body.orderId);          // votre commande
  const r = await fetch(`${API}/v1/payments`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${KEY}`,
      "content-type": "application/json",
      "idempotency-key": `order-${order.id}`,
    },
    body: JSON.stringify({
      amount: order.total,
      provider: "MVOLA",
      merchantReference: order.reference,
      customer: { phone: req.body.phone },
    }),
  });
  const data = await r.json();
  if (!r.ok) return res.status(400).json({ message: data.error?.message });
  await savePaymentId(order.id, data.payment.id);
  res.json({ status: data.payment.status });                 // votre page affiche l'attente
});

// Orange Money : pas de numéro à demander, le client confirme sur la page d'Orange.
app.post("/paiement/orange", async (req, res) => {
  const order = await findOrder(req.body.orderId);
  const r = await fetch(`${API}/v1/payments`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${KEY}`,
      "content-type": "application/json",
      "idempotency-key": `order-${order.id}`,
    },
    body: JSON.stringify({
      amount: order.total,
      provider: "ORANGE_MONEY",
      merchantReference: order.reference,
      successUrl: `https://votre-site/commande/${order.id}`,
      cancelUrl: "https://votre-site/panier",
    }),
  });
  const data = await r.json();
  if (!r.ok) return res.status(400).json({ message: data.error?.message });
  await savePaymentId(order.id, data.payment.id);
  res.json({ redirectTo: data.payment.paymentUrl });       // votre page y envoie le client
});

// Votre page interroge cette route pendant l'attente, ou au retour d'Orange.
app.get("/paiement/:orderId/statut", async (req, res) => {
  const paymentId = await getPaymentId(req.params.orderId);
  const r = await fetch(`${API}/v1/payments/${paymentId}`, {
    headers: { authorization: `Bearer ${KEY}` },
  });
  const { payment } = await r.json();
  res.json({ status: payment.status });
});

Erreurs fréquentes

  • 400 VALIDATION_ERROR : numéro absent ou non MVola, montant invalide, successUrl absente pour Orange Money ou invalide. Le message indique le champ.
  • 401 INVALID_API_KEY : clé absente, révoquée ou d’un autre environnement.
  • 409 IDEMPOTENCY_CONFLICT : même Idempotency-Key avec un contenu différent.
  • 409 MERCHANT_REFERENCE_CONFLICT : cette référence est déjà utilisée, par exemple par une tentative qui a échoué. Recommencez avec une nouvelle Idempotency-Key, et un nouveau merchantReference si vous en envoyez un.
  • 400 PROVIDER_REJECTED : MVola a refusé la demande (par exemple solde insuffisant). Rien n’a été débité.
  • 429 PROVIDER_RATE_LIMITED ou 503 : MVola est momentanément saturé ou indisponible. Réessayez un peu plus tard avec la même Idempotency-Key : aucun second paiement ne peut être créé.
  • 503 ORANGE_MONEY_NOT_CONFIGURED : Orange Money n’est pas disponible pour l’environnement de votre clé. Vérifiez GET /v1/payment-methods.
  • 502 ou 503 PROVIDER_UNAVAILABLE : Orange Money n’a pas pu ouvrir le paiement, qui est annulé. Recommencez un peu plus tard avec une nouvelle Idempotency-Key, et un nouveau merchantReference si vous en envoyez un.

Voir aussi Erreurs, Idempotence et Webhooks.