Paiements

Création, lecture, annulation et statuts via l’API v1 (clé secrète).

Créer un paiement

POST/v1/payments

Scope requis : payments:write. Header Idempotency-Key obligatoire.

Request body
{
  "amount": 25000,
  "provider": "SANDBOX_SIMULATOR",
  "merchantReference": "order_001",
  "customer": { "name": "Client Demo" },
  "metadata": { "source": "docs" },
  "sandboxScenario": "SUCCESS"
}
  • provider : MVOLA, ORANGE_MONEY ou, en Sandbox, SANDBOX_SIMULATOR. Sans ce champ : le simulateur en Sandbox, MVola en Production. GET /v1/payment-methods indique ce qui est disponible pour votre clé.
  • MVola : customer.phone est obligatoire.
  • description (facultatif, 200 caractères maximum, à la racine ou dans metadata.description) : la « Raison » que MVola montre au client, réduite à 50 caractères sans accents. Sans ce champ : « Paiement », le nom de la boutique et merchantReference (voir Intégration directe).
  • Orange Money : successUrl est obligatoire, cancelUrl est facultatif (voir le parcours complet).
  • sandboxScenario : uniquement avec le simulateur (voir Sandbox).

L’environnement et la boutique sont déduits de la clé API. Ne pas envoyer un organizationId / storeId différent du contexte de la clé.

Réponse 201 (forme)
{
  "payment": {
    "id": "…",
    "storeId": "…",
    "environment": "SANDBOX",
    "amount": "25000",
    "currency": "MGA",
    "status": "SUCCEEDED",
    "provider": "SANDBOX_SIMULATOR",
    "providerReference": "…",
    "operatorReference": null,
    "merchantReference": "order_001",
    "paymentUrl": "…",
    "createdAt": "…"
  }
}

paymentUrl : avec Orange Money, c’est l’adresse de la page d’Orange vers laquelle rediriger le client, car il y confirme toujours son paiement. Ne l’utilisez pas avec les autres moyens de paiement : avec le simulateur, ce champ peut contenir un chemin interne, qui n’ouvre aucune page.

Récupérer un paiement

GET/v1/payments/:id

Scope : payments:read. Le paiement doit appartenir à la boutique / environnement de la clé.

cURL
curl https://api.aifipay.pro/v1/payments/PAYMENT_ID \
  -H "Authorization: Bearer sk_test_…"

Référence opérateur (reçu du client)

Quand le paiement est réussi, operatorReference contient le numéro que le client voit sur le reçu de son opérateur : le « Ref » du SMS MVola, ou l’« ID de transaction » Orange Money. Il vaut null tant que l’opérateur ne l’a pas communiqué, et toujours null avec le simulateur Sandbox.

Il figure dans la réponse de GET /v1/payments/:id et dans la notification (webhook) payment.succeeded. Enregistrez-le avec la commande : quand un client vous donne son numéro de reçu, vous retrouvez la commande. Dans le tableau de bord, la recherche des transactions accepte aussi ce numéro.

Exemple
{
  "payment": {
    "id": "cmv…",
    "status": "SUCCEEDED",
    "provider": "MVOLA",
    "providerReference": "c0ffee00-…",
    "operatorReference": "9185680971",
    "merchantReference": "order_001"
  }
}

Statuts

Statuts de paiement utilisés par la plateforme :

CREATED
PENDING
PROCESSING
SUCCEEDED
FAILED
CANCELLED
EXPIRED
REFUNDED
PARTIALLY_REFUNDED
DISPUTED

Annuler un paiement

POST/v1/payments/:id/cancel
Body optionnel
{ "reason": "client_abandoned" }

Alternative session marchand

Le dashboard peut aussi créer via POST /api/merchant/payments (cookie + CSRF + Idempotency-Key ou idempotencyKey dans le body, avec storeId).