Skip to Content
Version démo ✨

Tutoriel : Intégrer l’API Payment Gateway

Ce guide est destiné aux développeurs qui souhaitent intégrer Ultimate Pay comme solution de paiement sur leur site e-commerce ou leur application.

Pourquoi notre API ?

Nous avons aussi été frustrés par les solutions existantes. Beaucoup ont des barrières à l’entrée élevées (frais, paperasse) ou des documentations complexes.

Notre API est conçue pour être :

  • Simple : Moins de 5 endpoints pour être opérationnel.
  • Accessible : Pas de frais d’installation ni de barrière à l’entrée pour la V1.
  • Locale : Conçue pour et par des Malgaches, adaptée à nos contraintes.
⚠️

Contrainte Majeure de la V1 : Le Pont de Paiement

Pour cette première release, notre système repose sur l’application mobile du Vendeur (le compte qui reçoit l’argent) pour confirmer les transactions.

Cela signifie que pour que le Payment Gateway fonctionne :

  1. Le compte Mobile Money du Vendeur doit être lié à un Projet sur notre plateforme.
  2. Le Vendeur doit avoir l’application Ultimate Pay installée.
  3. L’application du Vendeur doit être ouverte (ou en premier plan) et connectée à internet pour notifier notre backend à chaque paiement reçue, qui vous enverra ensuite le callback.

Nous travaillons sur une solution plus robuste, mais c’est la réalité de notre MVP pour garantir la sécurité des fonds.

Le Flux de Paiement

Voici les 3 étapes dont vous (le développeur) devez vous soucier :

Étape 1 : Initialiser la Transaction

Votre serveur appelle notre API pour signaler qu’un paiement doit être créé. Vous envoyez le montant et votre référence, et nous vous retournons ce qu’il faut mettre dans le QR code.

curl -X POST 'https://api.ultimatepay.app/v1/transactions/init' \
-H 'X-PROJECT-API-KEY: VOTRE_CLE_API_PROJET' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 10000,
  "operator": "MVola",
  "includeFees": false,
  "details": "[{\"item\":\"boky\",\"price\":\"10000\"}]"
}'

Réponse du Serveur :

{
  "transactionId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  "encryptedPayload": "eyJh...encryptedData...J9",
  "receiverDeviceName": "Boutique Haja",
  "receiverPhoneNumber": "+26134..."
}
  • transactionId : Gardez-le. C’est votre moyen de suivre ce paiement.
  • encryptedPayload : C’est le contenu crypté que vous devez transformer en QR code.
  • receiverDeviceName et receiverPhoneNumber : Informations que vous pouvez afficher au client (“Vous allez payer à …”)

Étape 2 : Afficher le QR Code

Utilisez une librairie (ex: qrcode.react) pour convertir la chaîne encryptedPayload en un QR code visible.

Le client scanne ce QR code avec son application Ultimate Pay (en mode online) et suit les instructions pour payer.

Étape 3 : Gérer la Confirmation de Paiement

Comment savoir si le client a payé ? Vous avez deux options :

Recommandé pour la production.

Une fois que le téléphone de votre Vendeur confirme la réception du paiement (via SMS, comme décrit dans la contrainte), notre serveur envoie une requête POST à l’URL que vous avez définie dans votre Projet (callbackUrl).

Ce que vous recevez :

{
  "transactionId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  "status": "SUCCESS",
  "amount": 10000,
  "receiverPhoneNumber": "+26134...",
}

Validez cet appel (nous recommandons de vérifier la signature JWT/HMAC que nous ajouterons bientôt) et mettez à jour votre commande.

Et c’est tout ! Vous avez un flux de paiement fonctionnel.

A Propos de la Sécurité Pour cette V1, l’authentification se fait par X-PROJECT-API-KEY. Assurez-vous qu’elle reste secrète et ne l’exposez jamais côté client.

Last updated on