Introduction
A la fin de cette documentation vous avez des exemples concrets faits avec Postman.
Si vous n’avez pas ces informations , n’hésitez pas à nous contacter.
Pour tout besoin d’assistance vous pouvez nous contacter directement:
Nom: Support Paynote,
Tél: 243 232 240 poste 6054
Email: support-paynote@y-note.cm
Notre site web : https://www.y-note.cm/
Etape 1: Récupération de l'accès token
L’Access Token est un jeton d’authentification récupéré auprès de l’API, ce qui nous permettra d’effectuer le remboursement. l’URL à utiliser est la suivante : https://omapi-token.ynote.africa/oauth2/token en fournissant les paramètres suivants:
| ClientId | L’id du client qui effectue la requête (Ce paramètre sera communiqué par mail après souscription) |
| ClientSecret | Le code secret du client qui effectue la requête (Ce paramètre sera également communiqué par mail après souscription) |
Dans l’interface postman, ces valeurs sont à placer respectivement dans les champs “Username” et “Password” et le type d’authentification est “Basic Auth” comme sur la figure ci-dessous:
NB: le body devrait être de type x-www-form-urlencoded et avoir comme paramètre “grant_type” avec pour valeur client_credentials comme sur la capture ci-dessous:
Vous devriez avoir comme réponse un acces_token avec une durée de validité et le type:
{
"access_token":"BLJraWQiOiJcL2NucXVJYjNqaTJnRDBKYXVRUGlCdlc0QVpjTmszbTV3b3lQY0VwM3pNVT0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIzYXEwZjE4NTAzY25kN3R0c2Yzb2ZtY2JxIiwidG9rZW5fdXNlIjoi8xytPyL_fRUM1q7ehk147zWZWZYkcCJCsjOXt8kOp4s_jyknBKjftol5bW2BX3hjsbUSbCAjutflWFPzVIp_dNMCigoL52-RqtBG9rYgCCXT0P0tkMpHnX9hlz6Ih7nt31wV626a43Kmxhvjvaes9R-5Hprqk4EH4p5lFAki2zHJTS7Sn-GHmhQlpFeOL2hTZ5IFNFBpuHyzv5EEFsh8uoBu6bbiR_6kpiBgSk6e_v7FQuM3YogkZiX7LVVchjWlDS…",
"expires_in":300,
"token_type":"Bearer"
}
Détails des paramètres:
- token_type: le type de jeton
- acces_token: le jeton, c’est le paramètre que nous avons besoin pour initialiser la demande de requête de paiement
- expires_in: la durée de validité exprimée en secondes, dans notre exemple nous pouvons utiliser ce jeton dans un délais de 300 secondes, passé ce délais l’API renvoi un message:{
« message »: « The incoming token has expired »
}
NB le token reçu dans cette réponse sera votre jeton d’authentification que vous allez utiliser pour pouvoir effectuer des requêtes vers les différents APIs.
Etape 2:Fonctionnement de l’API Web paiement
a. Création d’une requête de paiement
N/B: Avant de commencer, il est bon de noter que la requête de CashIn (Ou Web Paiement) se fait en USSD (traitement en temps réel et le client va être invité dans l’application pour approuver le paiement en entrant son code secret)
Pour effectuer un web paiement (autrement appelé CashIn), utilisez le jeton sur le point de terminaison https://omapi.ynote.africa/prod/webpayment avec le type d’authentification Bearer Token. Ensuite, saisissez le ‘access_token’ que vous avez reçu lors de la dernière requête dans la case à côté de « Token » qui s’affiche à droite.
Passer ensuite le corps de la requête en json dans body (se trouve juste en bas de l’URL de la requête)
{
« API_MUT »: {
« notifUrl »: « notifUrl »,
« subscriberMsisdn »: « subscriberMsisdn »,
« description »: « description »,
« amount »: »amount »,
« order_id »: »orderId »,
« customersecret »: »customersecret »,
« customerkey »: »customerkey »,
« PaiementMethod »: « MTN_CMR »
}
}
N/B: – Il est conseillé de copier et coller exactement le texte ci-dessus et juste changer manuellement les valeurs des différents attributs.
- A noter que les paramètres ‘customerkey’ et ‘customersecret’ vous ont été communiqués par mail avec les accès du token ci-dessus
- Veuillez noter que le champ “order_id” n’accepte pas d’espace comme valeur vu que c’est un champ de type ref (ex: “order_id” =❌ “ref32 Ynote” / “order_id” = ✅ “ref32_Ynote” )
Voici un aperçu:
Explication des différents paramètres
| Paramètres | Type | Description | Exemple |
| access_token | Bearer | access_token récupéré plus haut |
eVraWQiOiJcL2NucXVJYjNqaTJnRDBKYXVRU GlCdlc0QVpjTmszbTV3b3lQY0VwM3pNVT0iLC JhbGciOiJSUzI1NiJ9.eyJzdWIiOiIzYXEwZjE4 NTAzY25kN3R0c2Yzb2ZtY2JxIiwidG9rZW5ffdX… |
| customerkey | Chaîne de caractère | Login de l’utilisateur (communiqué par mail) | knnWJwrxaVgHzXQSloPePxAAwavB |
| customersecret | Chaîne de caractère | Mot de passe de l’utilisateur (communiqué par mail) | knnWJwrxaVgHzXQSloPePxAAwavB |
| subscriberMsisdn | Chaîne de caractère | Le numéro de téléphone du compte, l’indicatif du pays n’est pas requis. | 679947943 |
| order_id | Chaîne de caractère | L’id de la demande de paiement | 22123122 |
| notifUrl | Chaîne de caractère | L’url de réception de la notification | https://www.y-note.cm/notification |
| amount | Chaîne de caractère | Le montant de l’opération, les flottants ne sont pas autorisés | 100 |
| PaiementMethod | Chaine de caractère | La méthode de paiement MTN. Pour les encaissements par MTN , la valeur est toujours “MTN_CMR” | MTN_CMR |
La donnée renvoyée par cet appel est un dictionnaire sous la forme:
{
« ErrorCode »: 200,
« body »: « Pay Request Accepted »,
« ErrorMessage »: « »,test
« parameters »: {
« operation »: « collection Mtn »,
« currency »: « XAF »,
« amount »: « 1250 »,
« subscriberMsisdn »: « 6XXXXXXXX »,
« order_id »: « 12323312 »,
« notifUrl »: « https://webhook.site/XXX«
},
« CreateAt »: « 01-29-2024 12:09:28 »,
« MessageId »: « 558ad7f3-25ff-4e89-8090-XXXX »
}
Il faut noter que le paramètre MessageId vous permettra plus tard de retrouver le statut de votre transaction à tout moment, nous y reviendrons plus bas dans la documentation.
b. Réponse de l’API sur le webhook
L’API renvoie la réponse de traitement de chaque demande sur l’URL spécifié dans le paramètre notifUrl.
N/B : Si vous n’avez pas encore d’URL de notification
- Vous pouvez aller sur cette page pour créer un webhook et copier le lien pour la mettre dans la requête de paiement (paramètre notifUrl) afin de visualiser les réponses de traitements des requêtes qui sont transmises.
- Si vous avez cliqué sur le lien pour créer un webhook, après la création, vous allez être renvoyé sur cette page mais sans les données que vous voyez (les requêtes POST avec leurs données qui sont enfaite le retour du traitement de la requête de paiement, qui a été transmis ici parce qu’on a copier l’URL en haut de l’écran pour l’insérer comme paramètre notifUrl dans notre requête de paiement).
- Après avoir copié l’URL de votre propre webhook et copier le lien dans le paramètre notifUrl de votre requête de paiement, chaque fois qu’une requête est traité, le retour va être envoyé ici avec les informations correspondants.
La table ci-dessous fournit des détails sur les réponses renvoyées
| Codes réponse | body | Description |
| Missing body | Le corps de la requête est manquant. | |
| The incoming token has expired | Le jeton a expiré, il faut récupérer un autre jeton. | |
| Unauthorized | L’utilisateur n’est pas autorisé à effectuer la demande, vérifier que l’URL est correcte, vérifier que vous avez fourni un access_token avec le bon type Bearer | |
| 200 | status: SUCCESSFULL | La demande a abouti et des informations sur le résultat se trouvent dans le corps de la réponse et peut être récupéré par le développeur sur le webhook spécifié. |
| 5017 | Error on Customer Key | Erreur sur la valeur du Customer Key |
| 5017 | Error on Customer Secret | Erreur sur la valeur du Customer Secret |
| 5013 | Error on Channel User Msisdn | Le numéro de téléphone du compte n’est pas renseigné. |
| 5015 | Error on webhook | Le webhook n’est pas renseigné. |
| 5012 | Error on amount | Le montant n’est pas renseigné / montant trop petit |
| 5016 | Error on Final Customer Phone | Le numéro du bénéficiaire n’est pas renseigné. |
| 5018 | Error on Final Customer Name | Le nom du bénéficiaire n’est pas renseigné. |
| 5018 | notifUrl missing on API_MUT | le paramètre notifUrl n’est pas défini ou est vide. |
| 5019 | Le contenu de l’erreur variera, cependant il sera affiché dans le paramètre body. | Une erreur est survenue sur le traitement d’une opération. Le contenu du paramètre ErrorMessage vous donnera les détails sur l’erreur. |
| 5020 | Floating numbers not allowed | Le montant renseigné contient des virgules. |
| 5021 | Error on refund method | La méthode de requête de paiement n’est pas renseignée. |
| 5022 | Unknown refund method | La méthode de requête de paiement n’est pas correcte. |
| 5023 | Le signe de l’indicatif n’est pas autorisé sur le numéro du bénéficiaire. | |
| 5023 | Amount should be a string | le montant contient des caractères différent des chiffres |
| 5024 | Le numéro du bénéficiaire ne doit contenir que des chiffres. | |
| 5025 | Le numéro du bénéficiaire n’a pas la longueur requise. | |
| 5026 | Le numéro du bénéficiaire n’est pas un numéro MTN valide. | |
| Bad Request | l’un des paramètres de la requête a une valeur anormal |
- N/B : Pour récupérer ou ‘‘catcher’’ ces notifications venant de l’API vers votre route (url) personnelle dédiée à la réception des notifications
Vous pouvez utiliser cette parcelle de code (en PHP) au début de votre route,
et ensuite les stocker où vous voulez (database, logs, session, etc..) afin d’effectuer vos opérations plus tard
c. Statut de la transaction
Afin de vérifier à tout moment le statut d’une transaction faite, vous devez récupérer de nouveau un acces_token sur l’url https://omapi-token.ynote.africa/oauth2/token (revoir le début de l’étape de receupperation du token) en fournissant l’id et le secret, vous recevrez un acces_token avec le type et sa durée de validité comme c’était le cas lorsqu’il s’agissait du acces_token pour la requête de paiement.
Ensuite faire un POST sur l’url https://omapi.ynote.africa/prod/webpaymentmtn/status
Les paramètres à fournir sont d’abord le access_token de type Bearer ensuite le corps de la requête en json (Body):
{
« customerkey »: « customerkey »,
« customersecret »: « customersecret »,
“message_id”: “message_id”
}
N/B: Souvenez-vous de l’attribut MessageId (réponse de la requête précédente), c’est donc dans le body ci-dessus que vous allez mettre cette valeur.
Voici un exemple de réponse lors de l’appel a cet API:
{
« updateDate »: « 2024-01-22 10:15:05 »,
« currency »: « XAF »,
« operation »: « collection Mtn »,
« notifurl »: « https://www.y-note.cm »,
« paytoken »: « eyXXXXXXXXXX »,
« status »: « SUCCESSFUL »,
« paymentRef »: « XXXXXXXX-8a09-421c-919d-a4edd4dc4e35 »,
« message »: « {\ »ErrorCode\ »: 200, \ »body\ »: \ »Pay Request
Accepted\ », \ »ErrorMessage\ »: \ »\ », \ »parameters\ »: {\ »operation\ »:
\ »collection Mtn\ », \ »currency\ »: \ »XAF\ », \ »amount\ »: \ »523\ »,
\ »subscriberMsisdn\ »: \ »237693600164\ », \ »order_id\ »:
\ »Request-1234\ », \ »notifUrl\ »: \ »https://www.y-note.cm\« },
\ »CreateAt\ »: \ »01-09-2024 18:08:29\ », \ »MessageId\ »:
\ »XXXXXXXX-8a09-421c-919d-a4edd4dc4e35\ »} »,
« creationDate »: « 2024-01-09 18:08:31 »,
« customer_key »: « XXXXXXX »,
« request_id »: « Request-1234 »,
« amount »: « 523 »,
« subscriberMsisdn »: « 693600164«
}
Description des paramètres:
| paytoken | Il s’agit d’un identifiant unique attribué à la méthode de paiement utilisée lors de la transaction. |
| paymentRef | Il s’agit du paramètre qui permet de récupérer le statut de la transaction a tout moment comme le messageId enfaite. |
| request_id | ID de la requête de paiement, similaire à « order_id » dans la l’étape précédente. |
| currency | la devise |
| operation | Ce paramètre représente la « collection », c’est-à-dire un groupe dans lequel se trouvent toutes les requêtes de paiement attribuées à votre API. |
La table ci-dessous décrit les autres possibilités de réponse:
| Codes réponse | body | Description |
| Missing body | La donnée reçue n’a pas de corp, il faut renseigner le customerkey ainsi que le customersecret | |
| Unauthorized | L’utilisateur n’est pas autorisé, vérifiez que le acces_token est présent dans la requête avec le bon type Bearer, vérifier que l’ID passé dans l’url est correct. | |
| Transactions not found | Aucune transaction ne correspond à l’ID spécifié, vérifier que l’ID est correct. | |
| 5011 | Error on Customer Key | Le nom d’utilisateur n’est pas renseigné. |
| 5012 | Error on Customer Secret | Le mot de passe n’est pas renseigné. |
| Input should be a valid dictionary or object to extract fields from | Format de données retournes dans le body inconnu. Assurez-vous que votre requête (Curl, Guzzle, Http etc..) contient l’en-tête (headers) Content-Type: application/json |
Etape 3:Fonctionnement de l’API Get Balance
Afin de vérifier le solde de votre compte, vous pouvez faire une requête de GetBalance
a. Création d’une requête de get Balance
Pour effectuer une vérification de solde (GetBalance), utilisez le jeton sur le point de terminaison https://omapi.ynote.africa/prod/balance/ avec le type d’authentification Bearer Token. Ensuite, saisissez le ‘access_token’ que vous avez reçu lors de la dernière requête dans la case à côté de « Token » qui s’affiche à droite.
Passer ensuite le corps de la requête en json dans body (se trouve juste en bas de l’URL de la requête)
{
« customerkey »:« customerkey« ,
« customersecret »:« customersecret« ,
« payment_method »: « MTN_MOMO_CMR »
}
N/B: – Il est conseillé de copier et coller exactement le texte ci-dessus et juste changer manuellement les valeurs des différents attributs.
Explication des différents paramètres
| Paramètres | Type | Description | Exemple |
| customerkey | Chaîne de caractère | Login de l’utilisateur (communiqué par mail) | knnWJwrxaVgHzXQSloPePxAAwavB |
| customersecret | Chaîne de caractère | Mot de passe de l’utilisateur (communiqué par mail) | knnWJwrxaVgHzXQSloPePxAAwavB |
| payment_method | Chaîne de caractère | Sous-Compte correspondant | MTN_MOMO_CMR |
La donnée renvoyée par cet appel est un dictionnaire sous la forme:
{
« errorCode »: 200,
« body »: « Votre solde est de 530000 FCFA »,
« value »: « 530000 »
}
Etape 4 :Voir notre exemple dan postman
Nous avons préparé un exemple complet de ces requêtes dans postman, cliquez Ici pour voir .
Et voila , vous avez maintenant implémenté l’API MNT Mobile Money vous permettant de recevoir les paiements de vos clients.
Cette API MTN Mobile Money est valable au Cameroun et permet de bénéficier d’une souplesse dans les encaisements inégalé.
Vous avez une activité ? Vous souhaitez faire payer vos clients par Orange Money au Cameroun ?
Y-Note est Agrégateur Orange Money Cameroun officiel depuis 2018. Accompagnant des centaines de eCommerçant au Cameroun, nous proposons la mise en place de solution d’encaissement et de remboursement Orange Money.