Débuter avec YeraPay!

YeraPay est une API de paiement en ligne lié aux comptes utilisateurs de la plateforme mobile de partage de vidéos YeraTube.

Elle permet aux utilisateurs de YeraTube de pouvoir payer en ligne sur les sites webs partenaires à l'aide de leurs points (Yeeras). Cette documentation, explique en détaille comment intégrer l'API de paiement sur votre site web et bénéficier de tous les avantages qui viennent avec ce mode de paiement simple, rapide et surtout très abordable.

  • 2

    Comment débuter ?

    Pour commencer le déploiement de la solution YeraPay sur votre site web, il faut procéder en 2 étapes :
    • Enregistrer votre business chez MCorp-Mali en tant que business sur YeraTube;
    • Obtenir votre clé API personnalisée.
    Toutes ces 2 étapes sont très simples et sont les seuls pré-requis pour l'acquisition d'un droit d'accès à YeraPay.

    2.1. Enregistrer votre business

    Tous les YeraTubers sont automatiquement autorisés à s'enregistrer en tant que business chez YeraTube. Pour enregistrer votre business auprès de YeraTube, il vous faut tout d'abord créer un compte YeraTube. Il faut donc télécharger l'application mobile YeraTube et créer un compte YeraTube.
    Une fois votre compte YeraTube créée, vous devez contacter MCorp-Mali pour confirmer votre compte en tant que compte business et ainsi conclure l'enregistrement.

    2.2. Obtenir votre clé API

    Une fois votre business enregistré auprès de YeraTube, vous pouvez demander l'obtention d'une clé API propre à votre business valable pendant 1 an. Les clés API sont valables sur une durée d'un an (1an) renouvellable annuellement et coûte 25.000 FCFA/an. Pour obtenir votre clé, contactez MCorp-Mali et faites une demande explicite au service client.

  • 3

    Intégration de l'API

    Cette section détaille de toutes les étapes à suivre pour intégrer correctement YeraPay sur votre site web et permettre à vous clients de payer des articles grâce à leurs points YeraTube. Il est important de garder en tête que YeraTube prélève 5% sur chaque transaction sur votre site qui passe par YeraPay et garde un trace de la transaction.

    3.1. Composition de l'API

    l'API YeraPay est d'une simplicité déconcertante dans sa composition et dans son utilisation. Il permet d'éffectuer respectivement et dans l'ordre 2 types de requettes :

    • Vérification des identifiants des utilisateurs (vos clients) ;
    • Traitement des requettes de paiement.

    YeraPay est une API conçue entièrement en PHP et n'utilise donc que ce language pour communiquer. La manière la plus éfficace de communication avec YeraPay reste donc les protocoles "curl" sur PHP et AJAX pour les modules Javascript.
    Quelque soit la méthode choisie, les inputs et outputs de l'API restent identiques et sont les seuls informations qui vous seront d'une grande utilité.
    De façon condensée, les inputs de l'API sont des variables POST (GET & PUT ne sont pas pris en charge), et les outputs sont des reponses HTTP (HTTP/1.1).
    Une transaction avec l'API YeraPay se fait en 2 étapes : La vérification de votre clé et des identifiants du client qui une fois validés reçois un code temporaire pour la transaction, suivie par la requette de paiement.

    3.2. Authentification de votre clé API et de votre client

    La 1ère étape dans la réalisation d'une transaction avec YeraPay consiste à authentifier votre clé API et votre client. Cette authentification se fait à travers une requette PHP (Curl). Le domaine (URL) principal pour l'authentification de la clé API et la validation du client est : https://www.yeratube.com/api/v1/credentialsValidationPasserel.php
    La requette supporte uniquement la méthode POST (ni GET, ni PUT ne sont acceptées). Ci-dessous se trouve une table contenant toutes les variables nécéssaires pour faire une requette réussie!

    Nom de la variable Description de la variable
    apiKey ($_POST['apiKey']) Cette variable doit contenir en format texte votre clé API valide. Si votre clé est expirée, contactez MCorp-Mali pour la renouveller.
    businessPass ($_POST['businessPass']) Cette variable doit contenir votre mot de passe YeraTube. C'est le mot de passe que vous utilisez pour vous connecter sur l'application mobile YeraTube
    userData ($_POST['userData']) Cette variable doit contenir le numéro de téléphone ou l'email de l'utilisateur. C'est le numéro de téléphone que l'utilisateur utilise pour se connecter sur son compte YeraTube. N'oubliez surtout pas que le format du numéro de téléphone de l'utilisateur est (223XXXXXXXX)
    userPass ($_POST['userPass']) Cette variable doit contenir le mot de passe de l'utilisateur. C'est le mot de passe que l'utilisateur utilise pour se connecter sur son compte YeraTube. Cette information est hautement confidentiel et votre business doit repondre à plusieurs critères de sécurité discutés durant l'enregistrement du business avant de pouvoir faire transiter ses informations.
    balance ($_POST['balance']) Cette variable doit contenir la somme à prélever chez l'utilisateur. Noté bien que YeraPay prélève 5% du solde à prélever. Une bonne pratique consiste donc à informer l'utilisateur de ce prélèvement sur votre interface graphique.

    NB : Tout comme précisé dans le contrat d'enregistrement de votre business sur YeraTube, vous n'êtes pas autorisés à enregistrer les informations des utilisateurs (Numéro de téléphone, email et mot de passe YeraTube) sous peine de poursuites judiciaires.

    Une fois la requette effectuée, l'API vous fournit les réponses HTTP et les status correspondant aux résultats de votre requette. L'API renvoit en cas de requette réussie un objet JSON. Le tableau ci-dessous détaille les réponses possibles à votre requette et leurs descriptions.

    Status code de la réponse Message de la réponse Corps de la réponse Description de la reponse
    200 Valid Credentials Rien Cette reponse spécifie que la requette a réussi avec succès et que votre clé API et les identifiants de l'utilisateur sont tous corrects! vous pouvez donc passer à l'étape du paiement
    412 Unexpected Error Occured Rien Cette reponse spécifie que la requette a échoué. Cet echec n'est pas forcement fatal. Il peut être du à un problème de connexion internet. Vous pouvez relancer la requette.
    412 Insufficient Funds Rien Cette reponse spécifie que le solde du paiement est supérieur au solde du compte de l'utilisateur. Il n'a donc pas assez de points (Yeeras) pour effectuer ce paiement.
    412 Invalid User Pass Rien Cette reponse spécifie que le mot de passe de l'utilisateur est incorrect.
    412 Invalid User Data Rien Cette reponse spécifie que le numéro de téléphone ou l'email de l'utilisateur est incorrect.
    412 Invalid Business Pass Rien Cette reponse spécifie que votre mot de passe business (Mot de passe de votre compte entreprise) est incorrect.
    412 Invalid Business Account Rien Cette reponse spécifie que votre compte entreprise n'est plus valide.
    412 Invalid Key Rien Cette reponse spécifie que votre clé API est invalide (ou a plutot expiré).
    412 Precondition Failed Rien Cette reponse spécifie que votre requette est incomplète. Une des variables requises n'y figure pas. Consulter le tableau ci-dessus pour verifier la liste des variables POST requises pour une requette complète.

    L'utilisateur reçoit donc un code temporaire pour confirmer la transaction.
    Vous pouvez donc analyser les résultats de la requette, obtenir le code status de la reponse et traiter la requette en fonction du resultat. Ci-dessous se trouve une illustration d'une requette d'authentification en PHP.

    3.3. Effectuer une transaction

    La 2ème étape d'une requette de paiement sur YeraPay consiste à traiter le paiement. Tout comme l'authentification, elle passe par une requette PHP (Curl), reçoit des variables POST et renvois des reponses HTTP.
    Ci-dessous se trouve un tableau spécifiant les variables en input pour effectuer une requette de paiement. l'URL pour une requette de paiement est :

    https://www.yeratube.com/api/v1/transactionsHandlingPasserel.php

    Nom de la variable Description de la variable
    apiKey ($_POST['apiKey']) Cette variable doit contenir en format texte votre clé API valide. Si votre clé est expirée, contactez MCorp-Mali pour la renouveller.
    businessPass ($_POST['businessPass']) Cette variable doit contenir votre mot de passe YeraTube. C'est le mot de passe que vous utilisez pour vous connecter sur l'application mobile YeraTube
    userData ($_POST['userData']) Cette variable doit contenir le numéro de téléphone ou l'email de l'utilisateur. C'est le numéro de téléphone que l'utilisateur utilise pour se connecter sur son compte YeraTube. N'oubliez surtout pas que le format du numéro de téléphone de l'utilisateur est (223XXXXXXXX)
    userPass ($_POST['userPass']) Cette variable doit contenir le mot de passe de l'utilisateur. C'est le mot de passe que l'utilisateur utilise pour se connecter sur son compte YeraTube. Cette information est hautement confidentiel et votre business doit repondre à plusieurs critères de sécurité discutés durant l'enregistrement du business avant de pouvoir faire transiter ses informations.
    balance ($_POST['balance']) Cette variable doit contenir la somme à prélever chez l'utilisateur. Noté bien que YeraPay prélève 5% du solde à prélever. Une bonne pratique consiste donc à informer l'utilisateur de ce prélèvement sur votre interface graphique.
    tempCode ($_POST['tempCode']) Cette variable doit contenir le code temporaire reçu par l'utilisateur après la requette d'authentification.

    NB : Tout comme précisé dans le contrat d'enregistrement de votre business sur YeraTube, vous n'êtes pas autorisés à enregistrer les informations des utilisateurs (Numéro de téléphone, email et mot de passe YeraTube) sous peine de poursuites judiciaires.

    Une fois la requette effectuée, l'API vous fournit les réponses HTTP et les status correspondant aux résultats de votre requette. L'API renvoit en cas de requette réussie un objet JSON. Le tableau ci-dessous détaille les réponses possibles à votre requette et leurs descriptions.

    Status code de la réponse Message de la réponse Corps de la réponse Description de la reponse
    200 Transaction Completed Sucessfully Rien Cette reponse spécifie que la requette a réussi avec succès et que la transaction a été effectué correctement!
    412 Balance Updating Error Rien Cette reponse spécifie que la requette a échoué. Cet echec n'est pas forcement fatal. Il peut être du à un problème de connexion internet. Vous pouvez relancer la requette.
    412 Invalid Verification Code Rien Cette reponse spécifie que le code temporaire de transaction reçu par sms par l'utilisateur n'est pas correct.
    412 Insufficient Funds Rien Cette reponse spécifie que le solde du paiement est supérieur au solde du compte de l'utilisateur. Il n'a donc pas assez de points (Yeeras) pour effectuer ce paiement.
    412 Invalid User Pass Rien Cette reponse spécifie que le mot de passe de l'utilisateur est incorrect.
    412 Invalid User Data Rien Cette reponse spécifie que le numéro de téléphone ou l'email de l'utilisateur est incorrect.
    412 Invalid Business Pass Rien Cette reponse spécifie que votre mot de passe business (Mot de passe de votre compte entreprise) est incorrect.
    412 Invalid Business Account Rien Cette reponse spécifie que votre compte entreprise n'est plus valide.
    412 Invalid Key Rien Cette reponse spécifie que votre clé API est invalide (ou a plutot expiré).
    412 Precondition Failed Rien Cette reponse spécifie que votre requette est incomplète. Une des variables requises n'y figure pas. Consulter le tableau ci-dessus pour verifier la liste des variables POST requises pour une requette complète.
    Vous pouvez donc analyser les résultats de la requette, obtenir le code status de la reponse et traiter la requette en fonction du resultat. C'est ainsi que se termine un requette de paiement avec YeraPay! Ci-dessous se trouve une illustration d'une requette de transaction en PHP.

    3.4. Exemple complet de transaction

    Ci-dessous se trouve une exemple complet de l'implémentation d'une requette de paiement par YeraPay. Vous pouvez l'éditer pour l'adapter à votre situation. Téléchargez-le document ici!


  • 4

    Informations supplémentaires

    Comme vous l'avez surement constaté, l'API YeraPay est très facile à utiliser. Pour toujours obtenir une experience client fluide, nous vous demandons de visiter cette page au moins une fois chaque mois pour être informer des mises à jour et des modifications faites sur l'API.
    L'API est implémentable sur tous les business en ligne, aucune restriction à cet effet.

Conclusion

L'API YeraPay est unique en son genre en Afrique de l'Ouest. Son implémentation est très rapide et facile et son utilisation est très sécurisée.
L'équipe YeraTube mets cependant à la disposition de tous les business désirant adopter YeraPay comme solution de paiement électronique une aide totale dans l'implémentation et le suivi de la fiabilité du système. Si vous avez donc besoin d'aide n'hesitez surtout pas à nous contacter et des développeurs vous seront assignés pour vous aider à mettre en place le système.

Liens utiles