Intégration MaishaPay

Intégrer MaishaPay à votre site marchand.


La présente documentation est destinée aux développeurs souhaitant intégrer le paiement MaishaPay sur un site marchand. Cette documentation n'est liée à aucune technologie. Le développeur est libre de faire l'intégration avec n'importe quel outil web.


1. Récupération du REDIRECT_URL

Depuis le site marchand, vous devez récupérer une URL de redirection de la forme https://maishapay.net/maishapay/webapp2/ avant de rediriger le client vers MaishaPay pour effectetuer le paiement. Les étapes suivantes expliquent le mécanisme de récupération de cette URL de redirection.

Pour récupérer une URL de redirection, vous devez effectuer l'appel POST suivant :

POST https://maishapay.net/maishapay/webapp2/

Important : Avant de passer en production vous devez avoir effectué au moins un payment concluant en mode sandbox (utiliser un numero joker).

Important : Vous pouvez effectuer cet appel depuis un formulaire ou faire un appel serveur à serveur

s
Paramètre Obligatoire Description
payment[gateway_mode] Oui Cette information vous permet de mettre votre api paiement en mode production ou test par defaut: 1 (Production).
Les codes supportés sont: 1, 0
payment[payment_devise] Oui La devise internationale (ISO-4217) de la transaction en cours. Par défault: USD ( Dollars Americains) )
payment[payment_description] Oui Une description de l'achat effectué par le client (160 caractères au maximum).
payment[payment_amount] Oui Le montant total de la transaction (x3). Ex: Si le montant du panier est de 120 USD, la valeur transmise à ce niveau doit être payment[payment_amount] = 360
payment[apiOptions] Non L'adresse IP du client qui effectue le paiement.
payment[page_callback_success] Oui URL de votre site marchand vers laquelle MaishaPay redirigera le client si le paiement est effectué avec succès.
payment[page_callback_failure] Oui URL de votre site marchand vers laquelle MaishaPay redirigera le client si le paiement est rejeté.
payment[page_callback_cancel] Oui URL de votre site marchand vers laquelle MaishaPay redirigera le client si ce(tte) dernie(ère) annule le paiement
client_api_key Oui Cette information vous est transmise par Maishapay lors de l'enregistrement de votre site marchand. Contactez l'administrateur du site pour lequel vous souhaitez faire l'intégration pour récupérer cette information.

En cas d'erreur lors de cet appel, MaishaPay retournera des informations pour vous aider à modifier votre code.

Si tous les paramètres attendus sont présents et valides, vous recevez une URL de la forme https://maishapay.net/maishapay/webapp2/ à utiliser à l'étape suivante.

2. Redirection vers MaishaPay

L'URL sécurisée retournée à l'étape précédente est utilisée pour rediriger l'utilisateur vers le site MaishaPay pour continuer la transaction et effectuer le paiement.
Il s'agit d'une redirection HTTP classique.

3. Confirmation du paiement

Le client est donc redirigé sur le site MaishaPay pour :

  • Renseigner le numéro de téléphone Orange Money à utiliser pour effectuer le paiement ;
  • Confirmer avoir pris connaissance des condiditions générales d'utilisation ;
  • Valider la demande de paiement.

4. Envoi de la demande de paiement sur le téléphone du client

MaishaPay fait appel au service Orange Money pour transmettre la demande de paiement au numéro de téléphone fourni par le client.
Une menu USSD développé par Orange permet au client de continuer la transaction sur son téléphone et de confirmer ou annuler le paiement.

5. Confirmation de la transaction sur votre site marchand

Quelle que soit le choix effectué par le client, nous en informons le site marchand en faisant un appel : POST callback_url (voir payment[callback_url] transmis lors de l'appel pour la récupération du REDIRECT_URL).
Cet appel server-à-server contient les paramètres suivants :

Paramètre Valeur Description
authenticity Chaîne Cette information permet de sécuriser la communication serveur-à-serveur. En effet, vous devez recalculer cette chaîne au niveau de votre intégration et la comparer à celle que nous vous transmettons. Ne modifier votre panier que s'il y a une correspondance parfaite.

Littéralement, authenticity est la valeur SHA1 de la concaténation du numéro de comande, montant de de la transaction (x3), devise et signature du site marchand.
authenticity = SHA1("order_id;amount_100;currency_code;api_secret")

order_id : doit être en masjucules lorsqu'il ne s'agit pas d'une valeur numérique

currency_code : doit être en lettre masucules

SHA1 : Le résultat du hashage SHA1 doit est transformé en majuscules

order_id Alpha/Numérique Numéro de la commande sur le site marchand transmis à MaishaPay à l'Etape 1
success ou failure success=1
ou
failure=0
Statut du paiement effectué depuis le téléphone du client.
sandbox 1 ou 0 Pour détecter les paiements en mode sandbox

Vous devez donc intégrer au niveau du site marchand le code nécessaire pour traiter ce callback server-à-serveur et effectuer les opérations suivantes :

  1. Recalculer la signature
  2. Compagner la signature calculée à celle transmise par MaishaPay
  3. Vérifier que le numéro de commande est valide et que la transaction est toujours ouverte
  4. Mettre à jour le panier en fonction du statut transmis (success=1 ou failure=0)
  5. Retourner une réponse JSON à MaishaPay pour confirmer ou infirmer le traitement de l'opération sur le site marchand :
    Dans le cas d'une confirmation, la réponse attendue est :
    { "status": "1" }
    Dans le cas contraire , la réponse attendue est :
    { "status": "0", "message": "Raison pour laquelle le traitement est rejeté." }

6. Notification du client

Le client reçoit un message sur son téléphone pour confirmer la transaction et effectuer le mouvements de fonds dans le cas d'une transaction concluante ou alors un message d'annulation de la transaction.

7. Redirection finale

Site la transaction est concluante, MaishaPay redirige le client vers le site du marchand à l'adresse page_callback_success.

Site la transaction n'est pas concluante, MaishaPay redirige le client vers le site du marchand à l'adresse page_callback_failure.