Paiements
Création, lecture, annulation et statuts via l’API v1 (clé secrète).
Créer un paiement
/v1/paymentsScope requis : payments:write. Header Idempotency-Key obligatoire.
{
"amount": 25000,
"provider": "SANDBOX_SIMULATOR",
"merchantReference": "order_001",
"customer": { "name": "Client Demo" },
"metadata": { "source": "docs" },
"sandboxScenario": "SUCCESS"
}provider:MVOLA,ORANGE_MONEYou, en Sandbox,SANDBOX_SIMULATOR. Sans ce champ : le simulateur en Sandbox, MVola en Production.GET /v1/payment-methodsindique ce qui est disponible pour votre clé.- MVola :
customer.phoneest obligatoire. description(facultatif, 200 caractères maximum, à la racine ou dansmetadata.description) : la « Raison » que MVola montre au client, réduite à 50 caractères sans accents. Sans ce champ : « Paiement », le nom de la boutique etmerchantReference(voir Intégration directe).- Orange Money :
successUrlest obligatoire,cancelUrlest 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é.
{
"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
/v1/payments/:idScope : payments:read. Le paiement doit appartenir à la boutique / environnement de la clé.
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.
{
"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
DISPUTEDAnnuler un paiement
/v1/payments/:id/cancel{ "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).