Intégration VitePay

Intégrer VitePay à votre site marchand.

Logo

La présente documentation est destinée aux développeurs souhaitant intégrer le paiement VitePay 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.


Flow
Vue d'ensemble du paiement avec VitePay

1. Récupération du REDIRECT_URL

Depuis le site marchand, vous devez récupérer une URL de redirection de la forme https://checkout.vitepay.com/Ytr515 avant de rediriger le client vers VitePay 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://api.vitepay.com/v1/prod/payments

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

Paramètre Obligatoire Description
payment[language_code] Oui Langue dans laquelle la transaction est effectuée. Par défault: fr (français).
Les codes supportés sont: fr, en
payment[currency_code] Oui La devise internationale (ISO-4217) de la transaction en cours. Par défault: XOF ( Communauté Financière Africaine (BCEAO) )
payment[country_code] Oui Le code ISO du pays du site marchant. Valeur par défaut: ML (Mali)
payment[order_id] Oui Le numéro de commande sur le site marchand. Les numéros de commande doivent être uniques sur le site marchand car VitePay n'accepte pas les doublons à ce niveau.
payment[description] Oui Une description de l'achat effectué par le client (160 caractères au maximum).
payment[amount_100] Oui Le montant total de la transaction (x100). Ex: Si le montant du panier est de 12500 XOF, la valeur transmise à ce niveau doit être payment[amount_100] = 1250000
payment[buyer_ip_adress] Non L'adresse IP du client qui effectue le paiement.
payment[return_url] Oui URL de votre site marchand vers laquelle VitePay redirigera le client si le paiement est effectué avec succès.
payment[decline_url] Oui URL de votre site marchand vers laquelle VitPay redirigera le client si le paiement est rejeté.
payment[cancel_url] Oui URL de votre site marchand vers laquelle VitePay redirigera le client si ce(tte) dernie(ère) annule le paiement
payment[callback_url] Oui Cette URL sera utilisé à l'étape 5 pour confirmer la transaction.
payment[email] Non Email du client qui effectue la transaction.
payment[p_type] Oui Vous devez obligatoirement transmettre la valeur fixe: orange_money pour spécifier qu'il s'agit bien d'une transaction de paiement avec Orange Money.
redirect Oui Poisitionnez cette valeur à 1 lors d'un appel depuis un formulaire pour rediriger automatique le client vers la page de paiement.
Transmettez la valeur 0 (valeur par défaut) lors d'un appel serveur-à-serveur. Vous devrez par la suite faire la redirection du client depuis votre site marchand vers l'url transmise par VitePay.
api_key Oui Cette information vous est transmise par VitePay lors de l'enregistrement de votre site marchand. Contactez l'adminsitrateur du site pour lequel vous souhaitez faire l'intégration pour récupérer cette information.
hash Oui Le hash est une valeur calculée avec la formule suivante : SHA1(UPPERCASE("order_id;amount_100;currency_code;callback_url;api_secret"))
  1. Concaténez les différentes valeurs order_id, amount_100, currency_code, callback_url et api-secret en utilisant ; (point-virgule)comme séparateur
  2. Faites passer toute la chaîne en majuscules
  3. Appliquer la fonction SHA1(SHA1)

api_secret : Cette information vous est transmise par VitePay lors de l'enregistrement de votre site marchand. Contactez l'adminsitrateur du site pour lequel vous souhaitez faire l'intégration pour récupérer cette information.

En cas d'erreur lors de cet appel, VitePay 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://checkout.vitepay.com/Ytr515 à utiliser à l'étape suivante.

Pour information : Vous pouvez simuler un paiement en mode sandbox sans passer par orange money en utilisant les numéro suivants:
77000001 pour confirmer le paiement.
77000009 pour annuler le paiement.

2. Redirection vers VitePay

L'URL sécurisée retournée à l'étape précédente est utilisée pour rediriger l'utilisateur vers le site VitePay 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 VitePay 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

VitePay 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 (x100), 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 à VitePay à l'Etape 1
success ou failure success=1
ou
failure=1
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 VitePay
  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=1)
  5. Retourner une réponse JSON à VitePay 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, VitePay redirige le client vers le site du marchand à l'adresse return_url.

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