Guide de configuration & intégration technique du module de paiement UPay sur votre site web ou application e-commerce.

Documentation UPay

A PROPOS DE CE GUIDE

La solution de paiement en ligne « All-in-One »

UPay est une plateforme de paiement en ligne qui permet aux marchands d’accepter plusieursmoyens de paiement : Carte bancaire, espèce, comptes prépayés, et d’autres.

Ce guide a pour but de vous aider à mieux comprendre le fonctionnement de UPay et vousguider dans tout le processus de la mise en place du module de paiement sur votre site web ouapplication e-commerce.

Besoin d’aide ?

N’hésitez pas à faire appel à notre centre de relation clients ou notre support technique pourtoute question ou demande d’assistance technique. Nous serons à votre écoute.

Fini les redirections vers une page de paiement externe

UPay utilise les dernières technologies et bonnes pratiques en termed’expérience utilisateur (UX) et interface graphique(UI) pour rendrel’expérience d’achat de votre client la plus agréable et fluide qui soit.

Lors du règlement de l’achat, aucune redirection vers une page depaiement externe n’est faite.

Le client ne quitte jamais le site pour effectuer le paiement : un Widgetvient s’ajouter au dessus de la page, sans en altérer l’apparence, où le clientsaisit ses informations de paiement et finalise son achat, sans qu’il soitperturbé par l’ouverture d’une autre page, redirections, et autrescomplications qui le poussent souvent à abandonner le panier.

Le Widget UPay est compatible avec tous les supports et écrans denavigation modernes : Mobiles, Tablettes et Desktop.

WIDGET UPAY

Dashboard d’administration de vos transactions

Nous avons développé le Dashboard UPay afin qu’il soit le plusergonomique possible et le plus évolutif possible.

Aussi, le Dashboard UPay est entièrement responsive.

Comment y accéder ?

Depuis le Web : Rendez-vous sur le site www.upay.africa puiscliquez sur Mon Compte, renseignez le login et mot de passe quivous a été communiqué par votre agent UPay lors de votreinscription.

Lors du premier accès au Dashboard vous devez changer votremot de passe avant de pouvoir paramétrer votre site.

DASHBOARD UPAY

DashboardPage d’accueil de suivi de vos transactions. Ici vous pouvezconsulter un résumé chiffré de vos transactions sur lapériode et le moyen de paiement choisi, et administrerces dernières.

AnalytiquesCette page reprend les transactions filtrées sous unformat de rapport d’activité qui vous permet d’avoir desstatistiques très utiles quant à vos ventes sur une périodedonnée.

ParamètresIci vous pouvez modifier les paramètres techniques devotre site ou application, et ici vous avez la main sur lesmoyens de paiement que vous voulez afficher sur lemodule Upay intégré à votre site.

DASHBOARD UPAY

</LET’S UNPACK>

L’intégration de UPay peut se faire de manière manuelle, en 3 étapes et en quelques minutes.

INTÉGRATION

Créez un compte

Rendez-vous sur le site www.upay.africa pour procéder à la création devotre compte, ou contactez nous via le Centre de Relation Client UPayau contact@upay.africa.

Un de nos agents vous sera assigné, et vous assistera dans vosdémarches administratives et techniques.

Configurez votre site

Une fois votre compte crée et activé, connectez vous sur le DashboardUPay via le site en cliquant sur Mon Compte, à l’aide de votre login etmot de passe.

Rendez-vous sur l’onglet Paramètres et vérifiez ou renseignez sinécessaire les paramètres techniques de votre site ou web app.

Une fois votre compte crée et activé, votre agent Upay vouscommuniquera une clé privée, gardez la précieusement.

ÉTAPE 1 : MISE EN ROUTE

L’intégration du module de paiement UPay peut se faire sur votresite en quelques minutes en utilisant l’une des deux méthodessuivantes.

Intégration manuelle (widget.js)

Le module UPay peut également être intégré “à la main” vouspermettant de l’adapter à tous les cas de figure, et à vosdéveloppements spécifiques, le tout en une ligne de code.L’intégration manuelle a été pensée pour faciliter au maximuml’opération, tout en restant sécurisée et très simple.

UPay {developers}

<script id="upay-js" src="https://app.upay.sn/widget.js"data-mode="button"data-merchant_id="{{ merchant_id }}"data-access_key="{{ access_key }}"data-order_id="{{ cart_id }}"data-amount="{{ cart_amount }}"data-hmac="{{ signature }}"

</script>

ÉTAPE 2 : INTÉGRATION Manuelle

Pour vous renseigner sur la méthode de génération de lasignature hmac rendez-vous sur www.upay.africa puis surSignature

Insérez cette ligne dans votre page de checkout*<script id="upay-js" src="https://app.upay.sn/widget.js"

data-mode="button" data-merchant_id="" data-access_key=""data_currency=""

data-order_id="" data-amount="" data-hmac="" data-redirect_url=""></script>

Paramètres obligatoires du Widget Upaymode mode du widget order_desc description de la commandemerchant_id identifiant marchand amount montant total de la commandeaccess_key identifiant du site currency devise du montant communiquéorder_id identifiant commande hmac signature sécurisée de la transaction

Si vous choisissez le mode “Bouton” data-mode=“button”2

1

Le bouton s’affichera automatiquement là où vous avez inséré la ligne de code. Et c’est tout ce que vous avez à faire. Pas de requêtes à construire ni de développement serveur.

Si vous choisissez le mode “JavaScript” data-mode=“js”Vous pourrez enclencher l’ouverture du module de paiement suite à l’action que vous désirez suivant l’expérience utilisateur que vous souhaitez pour votre site ou web app. Il suffit d’appeler la fonction d’ouverture du module UPay.loadModal() dans votre code JavaScript.

Est-ce que c’est sécurisé ?

Absolument. La signature hmac nous permet d’identifierl’ensemble des données de la commande et de nous assurerqu’elles proviennent bien de votre serveur sans qu’elles aiété modifiées, avant de traiter la transaction.

Aussi, le système anti-fraude de la plateforme nous permetde détecter tout type de phishing et de n’autoriser que lesrequêtes provenant du module UPay, hébergé dans notredatacenter.

Quel langage dois-je utiliser ?

Vous êtes libres d’utiliser le langage de programmation quevous voulez. Le Widget UPay a été conçu pour fonctionnerentièrement côté navigateur, et rester indépendant destechnologies que vous utilisez côté serveur.

ÉTAPE 2 (suite) : INTÉGRATION Manuelle

<!—- EXAMPLE —-> <script id="upay-js" src="https://app.upay.sn/widget.js"data-lang="fr"data-mode="button"data-merchant_id=""data-access_key=""data-order_id=""data-order_description=""data-products_ids=""data-amount=""data-currency="XOF"data-hmac=""data-redirect_url="">

</script>

id* UPay-js CONST Identifiant de l’élément script à inclure. Toujours utiliser “UPay-js”

src* /widget.js CONST Lien vers le Widget. Toujours utiliser la valeur “https://app.UPay.net/widget.js”

data-mode* button|js Mode de fonctionnement Bouton “button” ou JavaScript “js”

data-lang {str} OPT Langue dans laquelle le widget de paiement sera affiché au client - “fr-FR” par défaut

data-merchant_id* (int) Identifiant Marchand, à récupérer depuis le Dashboard

data-access_key* (str:hex) Clé publique d’accès à la plateforme, à récupérer depuis le Dashboard

data-order_id* (str) Identifiant de la commande ou du panier en cours

data-order_description (str) OPT Description libre de la commande, 255 caractères au maximum

data-products_ids (array) OPT Identifiants des produits constituant la commande pour une utilisation ultérieur

data-amount* (int) Montant total de la commande, exprimé en centime, 245 = 2.45 MAD (ou autre devise)

data-currency* MAD|USD|EUR Devise dans laquelle le montant est exprimé (parmis les devises supportées)

data-hmac* (str:hex) Signature sécurisée de la transaction, Voir page “How to HMAC-TOKEN”.

data-client_name (str) OPT Nom et prénom du client pour envoi personnalisé du reçu de paiement

data-client_mail (str:mail) OPT E-mail du client pour envi du reçu de paiement par e-mail

data-client_phone (str:phone) OPT Numéro de mobile du client pour envoi du reçu par SMS (si l’option est disponible)

data-redirect_url {str:url} OPT URL de redirection quand le client termine son paiement (ID transaction en GET)

data-expiration_date {YYYYMMDDhhmmss} OPT Date d'expiration du code de commande

data-onload_callback {str} OPT Nom d’une fonction callback appelée à la fin du chargement du widget

data-onclose_callback {str} OPT Nom d’une fonction callback appelée quand l’utilisateur quitte le widget

data-onopen_callback {str} OPT Nom d’une fonction callback appelée quand le widget est affiché

data-default_method {str} OPT Indique au module d’afficher par défaut un moyen de paiement (‘cash’,’card’,’amanty’)

ÉTAPE 2 (suite) : INTÉGRATION Manuelle

Afin de vérifier l’intégrité des données envoyées depuis votre page de paiement, UPay se base sur une signature unique hmac_token qui lui permet d’identifier l’ensemble desdonnées de la commande et de s’assurer qu’elles proviennent bien de votre serveur sans qu’elles aient été altérées en chemin.

La génération de cette clé dans votre page est très simple et se définit comme suit :

hmac-sha1(“<merchant_id>:<order_id>:<amount>:<currency>”, secret_key)

Exemples de génération du hmac dans les langages les plus populaires :

PHP $hmac = hash_hmac("sha1", "$merchant_id:$order_id:$amount:$currency", $my_secret_key);

Python hmac = hmac.new(my_secret_key, merchant_id+':'+order_id+':'+amount+':'+currency, hashlib.sha1).hexdigest()

Ruby hmac = OpenSSL::HMAC.hexdigest('sha1', my_secret_key, '{merchant_id}:{order_id}:{amount}:{currency}')

Java * String hmac = hmacDigest(merchant_id+':'+order_id+':'+amount+':'+currency, my_secret_key, "HmacSHA1");

C# * var hmac = new HMACToken().CreateToken(merchant_id+':'+order_id+':'+amount+':'+currency, my_secret_key);

ÉTAPE 2 (suite) : INTÉGRATION Manuelle // SPECS: HMAC

PAIEMENT ESPECES / RESERVATION CODE

1. L’acheteur se rend sur le site marchand avec son navigateur ou via unewebview dans le cas du mobile.

2. Si l’intégration s’est bien passée, le navigateur charge le Widget UPaydepuis nos serveurs.

3. La page de paiement s’affiche au client, puis l’acheteur ouvre le modulede paiement Widget et choisi de payer par Espèces comme moyen depaiement.

4. L’acheteur saisi les données demandées puis valide5. Ces données sont envoyées au serveur UPay qui génère un code de

paiement.6. Le serveur UPay retourne ce code au navigateur qui affiche ce dernier à

l’acheteur.7. Le serveur UPay envoi les notifications suivantes :

1. Notification JSON (cash-reservation) au serveur dumarchand sur l’adresse de retour serveur renseignéedans le Dashboard. Le contenu de la notification (cf.Notifications) permet au marchand de mettre à jour la

commande.2. Notification E-Mail à l’acheteur.3. Notification E-Mail au marchand sur l’adresse saisie dans le

Dashboard.8. L’acheteur note son code de paiement et se rend à l’un points de

paiement partenaire pour régler sa commande dans le délais de validitédu code commande renseigné par le marchand dans le Dashboard (48hpar défaut).

9. L’acheteur quitte le Widget et est redirigé vers une page du site marchandredirect_url (cf. Specs Widget.js)

UPay

UpayCASH RESERVATIONV 1,0 // ATPS

ÉTAPE 3 (optionnelle) : INTÉGRATION Manuelle // FLOW: CASH RESERVATION

PAIEMENT ESPECES / PAIEMENT D’UNE COMMANDE

1. L’acheteur se rend à un point de paiement partenaire muni du codecommande généré

2. L’acheteur communique son numéro de commande à l’agent du point depaiement

3. L’agent du point de paiement saisi le code pour demander le relevé de lacommande correspondante

4. Le serveur répond avec le montant due

5. L’acheteur remet le montant due de la commande à l’agent de point depaiement

6. L’agent saisi qu’il a bien reçu le montant demandé et valide l’achat

7. Le serveur UPay envoi les notifications suivantes :

1. Notification JSON (cash-transaction) au serveur dumarchand sur l’adresse de retour serveur renseignéedans le Dashboard. Le contenu de la notification (cf.Notifications) permet au marchand de mettre à jour lacommande.

2. Notification E-Mail à l’acheteur.

3. Notification E-Mail au marchand sur l’adresses saisiedans le Dashboard.

8. L’acheteur récupère son reçu de paiement.

UpayServer

UpayCASH RESERVATIONV 1,0 // ATPS

ÉTAPE 3 (optionnelle) : INTÉGRATION Manuelle // FLOW: CASH RESERVATION

Cash : {

"type": "upay-cash","payment_type": "cash-transaction","merchant_id": "","order_id": "","transaction_id": "","partner_transaction_id": "","partner_approval_code": "","amount": "","currency": "","datetime": "","client_email": "","client_name": "","hmac": "","description": "","products_ids": ""

}

{"type": "upay-cash","payment_type": "cash-transaction","merchant_id": "","order_id": "","transaction_id": "","partner_transaction_id": "","partner_approval_code": "","amount": "","currency": "","datetime": "","client_email": "","client_name": "","hmac": "","description": "","products_ids": ""

}

Orange Money{

"type": "upay-orange_money","payment_type": "cash-transaction","merchant_id": "","order_id": "","transaction_id": "","partner_transaction_id": "","partner_approval_code": "","amount": "","currency": "","datetime": "","client_phone": "","client_name": "","hmac": "","description": "","products_ids": ""

}

Wizall : {

"type": "upay-wizall","payment_type": "cash-transaction","merchant_id": "","order_id": "","transaction_id": "","partner_transaction_id": "","partner_approval_code": "","amount": "","currency": "","datetime": "","client_phone": "","client_name": "","hmac": "",

"description": "","products_ids": ""

}

Carte : {

"type": "upay-card","payment_type": "cash-transaction","merchant_id": "","order_id": "","transaction_id": "","partner_transaction_id": "","partner_approval_code": "","amount": "","currency": "","datetime": "","client_phone": "","client_name": "","hmac": "","description": "","products_ids": ""

}

READ ME. PLEASE.

Vous recevez une notification (HTTP-POST au format JSON) surl’adresse de retour serveur qu’on appelle callback_url que vousrenseignez sur le Dashboard (à ne pas confondre avecredirect_url qui ne sert que pour rediriger l’utilisateur à la fin deson achat). Le traitement de ce callback n’est pas obligatoire, vouspouvez le faire si vous souhaitez mettre à jour l’état du panier dansvotre système de commande.

ÉTAPE 3 (optionnelle) : INTÉGRATION Manuelle // SPECS: NOTIFICATIONS

PLUG IT IN.

Après l’intégration du module de paiement à votresite, sa mise en route est instantanée.

Mise en route

1 Rendez-vous sur la page de paiement où vous avez intégréle module de paiement

2 Lancez le module de paiement, en cliquant sur le boutonou en appelant la fonction UPay.loadModal() commeexpliqué auparavant.

3 Vous devrez voir le module de paiement s’afficher commele montre le screen à droite. Si une page d’erreur s’affiche àla place, vous pouvez consulter la signification de l’erreurdans le slide suivant. Si cette dernière nécessite notreintervention, contactez-nous.

4 Vérifiez que toutes les informations affichées sur le Widgetsont bonnes. A savoir le nom de votre site, le logo de votresite, le montant total de la commande à payer, et le numérode la commande à payer.

5 Maintenant vous pouvez effectuer un paiement avec l’undes moyens de paiements disponibles sur votre site. Il estpréférable de tous les tester avec des commandesdifférentes.

6 Si le paiement ne retourne pas d’erreur, vous devrezretrouver la transaction dans le Dashboard, et recevoir unenotification sur votre url_callback.

TEST D’UN PAIEMENT

Activer les différentes méthodes de paiement

Vous pouvez choisir d’activer ou de désactiver certains modes depaiement.

Pour cela, allez sur les paramètres du compte et cocher les cases à côté desmodes de paiement que vous voulez voir apparaitre sur votre site.

Modifier le nom et le logo de votre site ou application

Vous pouvez également modifier le logo qui s’affiche en haut à gauche duWidget, ainsi que le nom du site marchand qui s’affiche à sa droite.

D’autres personnalisations à venir

Nous vous informerons au fur et à mesure que nous ajoutons de nouvellesoptions à personnaliser, comme les couleurs, la langue et autres.

PERSONNALISATION DU WIDGET

NOW YOU CAN START THEENGINE AND GET PAID.

THE END. UP

Support Technique

Notre équipe technique se charge de vous accompagner danstoutes les opérations de configuration et d'installation de lasolution sur votre site e-commerce.

En cas de besoin technique - tech@upay.sn

Centre de Relations Clients - Commercial

Besoin d'informations supplémentaires sur notre solution?Notre Centre de Relation Client (CRC) vous apporte de l'aidedans toutes les démarches de souscription à UPay pour voussimplifier la vie et assurer le suivi tout le long de notrepartenariat.

En cas de besoin commercial - contact@upay.sn

N’hésitez pas à passer nous saluer, rencontrer l’équipe etvisiter notre Data Center.

AIDE