Intégration VitePay

Intégrer VitePay à votre site marchand.

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.

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://checkout1.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"))` Concaténez les différentes valeurs `order_id`, `amount_100`, `currency_code`, `callback_url` et `api-secret` en utilisant `; (point-virgule)`comme séparateur Faites passer toute la chaîne en majuscules 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://checkout1.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 :

Recalculer la signature
Compagner la signature calculée à celle transmise par VitePay
Vérifier que le numéro de commande est valide et que la transaction est toujours ouverte
Mettre à jour le panier en fonction du statut transmis (success=1 ou failure=1)
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.