Introduction
Cette API vous permet de rembourser vos partenaires (clients, fournisseur etc..) via MTN Money. Une opération de remboursement est réalisée en utilisant les informations fournies dans votre demande, et une réponse concernant le traitement de cette demande est envoyée à l’URL que vous avez spécifiée. 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: Création d’une requête de remboursement
Pour effectuer un Cashout (remboursement), utilisez le jeton sur le point de terminaison https://omapi.ynote.africa/prod/refund 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« ,
« webhook »:« webhook« ,
« amount »:« amount« ,
« refund_method »: « refund_method« ,
« final_customer_phone »:« final_customer_phone« ,
« final_customer_name »:« final_customer_name« ,
« fees_included »:« fees_included« ,
« payer_message »:« payer_message«
}
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
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 |
eVraWQiOiJcL2NucXVJYjNqaTJnRDBKYXVR UGlCdlc0QVpjTmszbTV3b3lQY0VwM3pNVT0……… |
| 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 |
| webhook | 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. il faut noter que la commission contractuelle sera soustraite du montant que vous souhaitez rembourser, pour un remboursement de 1000 FCFA par exemple, le client recevra 979 FCFA | 100 |
| refund_method | Chaine de caractère | La méthode de remboursement MTN. Pour les remboursements par MTN , la valeur est toujours “MTN_MOMO_CMR” | MTN_MOMO_CMR |
| final_customer_phone | Chaîne de caractère | le numéro de téléphone du bénéficiaire | 67XXXXXXX |
| final_customer_name | Chaîne de caractère | le nom du bénéficiaire | daniel Ngatcheussi |
| fees_included | Chaîne de caractère | Ce paramètre est non obligatoire et permet de calculer automatiquement la commission pour vous: Si ce paramètre n’est pas présent ou s’il est renseigné et vaut “Yes” alors la commission contractuelle sera simplement déduite de votre solde MI. Si ce paramètre vaut “No” alors le montant de la commission sera automatiquement calculé et prélevé du compte du client. Exemple: pour un remboursement de 1000 FCFA, si le paramètre vaut “Yes” votre compte sera débité de 22F afin que le client reçoive exactement 1000 FCFA, par contre si le paramètre vaut “No”, cela suppose que vous avez considéré un montant de 21F dès le départ et le client recevra 979 F CFA | “Yes” / “No” |
| payer_message | Chaîne de caractère | Ce paramètre permet de rajouter un message dans le SMS de confirmation que votre destinataire recevra | Ref12345678 |
La donnée renvoyée par cet appel est un dictionnaire sous la forme:
{
« MessageId »: « MessageId »,
« QueueId »: {
« MessageId »: « MessageId »
}
}
Il faut noter que le paramètre MessageId (le premier, pas celui dans QueueId) vous permettra plus tard de retrouver le statut de votre transaction à tout moment, nous y reviendrons plus bas dans la documentation.
Etape 2: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 webhook.
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 remboursement (paramètre webhook) 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 remboursement, qui a été transmis ici parce qu’on a copier l’URL en haut de l’écran pour l’insérer comme paramètre webhook dans le body de notre requête de remboursement).
Après avoir copié l’URL de votre propre webhook et copier le lien dans le paramètre webhook de votre requête de remboursement, 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: SUCCESSFUL | 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é. |
| 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é. |
| 5013 | Error on Customer Key / Customer Secret | Le customer Key et le Customer Secret ne correspondent pas |
| 5015 | Error on webhook | Le webhook n’est pas renseigné. |
| 5016 | Error on amount | Le montant n’est pas renseigné. |
| 5017 | 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é. |
| 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. |
| 50201 | The amount is a string and should be inside double quotes | Vous devez definis le montant comme un “string” au sein de votre requete |
| 50202 | Amount is too big and should be below 500.000 Fcfa | Le montant que vous souhaitez envoyer est trop important et doit etre inferieur a 500.000 Fcfa |
| 50203 | Amount is too small and should be more than 2 Fcfa’ | Le montant demandé est trop petit et doit être de plus de 2 Fcfa |
| 50204 | Problem on disbursment rate calculation | Le calcul des frais sur votre transaction a échoué. Veuillez contacter le support SVP. |
| 50205 | Amount available in your account is too low | Le montant disponible dans votre sous-compte MTN n’est pas suffisant pour effectuer votre opération. |
| 5021 | Error on refund method | La méthode de remboursement n’est pas renseignée. |
| 5022 | Unknown refund method | La méthode de remboursement n’est pas correcte. |
| 5023 | Le signe de l’indicatif n’est pas autorisé sur le numéro du bénéficiaire, les exemples de numéros valides sont: 692954629, 237692954629 | Le signe de l’indicatif n’est pas autorisé sur le numéro du bénéficiaire. |
| 5024 | Le numéro du bénéficiaire ne doit contenir que des chiffres, les exemples de numéros valides sont: 692954629, 237692954629 | 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, les exemples de numéros valides sont: 692954629, 237692954629 | 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 mobile Camerounais valide, les exemples de numéros valides sont: 692954629, 237692954629 | Le numéro du bénéficiaire n’est pas un numéro orange valide. |
| 5027 | fees_included should be either « Yes » or « No » | Le paramètre “fees_included” doit être soit “Yes”, soit “No” |
| 5031 | Error Customer Key has never allowed MTN Cmr Cashout | Votre compte MTN n’a jamais été autorisé pour le Cashout MTN. Veuillez contacter le support svp. |
| 5032 | Error Customer Key is currently not allowed MTN Cmr Cashout |
Votre compte MTN n’est pas autorisé pour le cashout actuellement. Veuillez contacter le support SVP. |
Etape 3: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 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 remboursement.
Ensuite faire un GET sur l’url
https://omapi.ynote.africa/prod/refund/status/id id correspondant au paramètre MessageId renvoyé lors du POST sur l’url de remboursement.
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 »,
« refund_method »: « MTN_MOMO_CMR »
}
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:
{
« statusCode »: 200,
« body »: « Disbursment Request Status Accepted »,
« ErrorMessage »: « »,
« Status »: « SUCCESSFUL »,
« parameters »: {
« operation »: « Get Status Disbursment Request Mtn »,
« currency »: « XAF »,
« amount »: « 2000 »,
« referenceId »: « XXXXXXXX-3a26-4cdc-9247-XXXXXXXXXXXX »,
« final_customer_name »: « daniel Ngatcheussi »,
« final_customer_phone »: « 67XXXXXXX »,
« notifUrl »: « https://webhook.site/XXXXXXXX-87d6-44ad-b9db-12d3f4e407cb »
},
« CreateAt »: « 04-09-2024 12:56:53 »,
« MessageId »: « XXXXXXXX-f8a8-4203-83e3-XXXXXXXXXXXX »
}
Description des paramètres:
| parameters | Il s’agit des paramètres initialement envoyés par l’utilisateur. |
| MessageId | Il s’agit du paramètre qui permet de récupérer le statut de la transaction a tout moment. |
La table ci-dessous décrit les autres possibilités de réponse en cas d’erreur :
| Codes réponse | body | Description |
| Missing body | La donnée reçue n’a pas de corps, il faut renseigner le customer_key ainsi que le customer_secret | |
| 502 | Aucune requete avec ce Message_id | Aucune transaction ne correspond à l’ID spécifié, vérifier que l’ID est correct. |
| 503 | La transaction ne correspond pas à ce customer_key | La transaction que vous demandez ne correspond pas au customer_key que vous avez transmis |
| 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é. |
| 5013 | Unauthorized | L’utilisateur n’est pas autorisé, vérifiez que le customer key et le customer secret correspondent |
| 5031 | Error Customer Key has never allowed MTN Cmr Cashout | Votre compte MTN n’a jamais été autorisé pour le Cashout MTN. Veuillez contacter le support svp. |
| 5032 | Error Customer Key is currently not allowed MTN Cmr Cashout |
Votre compte MTN n’est pas autorisé pour le cashout actuellement. Veuillez contacter le support SVP. |
Les différents statuts d’une transaction peuvent être:
- SUCCESSFUL
- INITIATED
- PENDING
- FAILED
- EXPIRED
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 de remboursement MTN Mobile Money vous permettant de Rembourser vos partenaires (clients,fournisseur etc..).
Cette API MTN Mobile Money est valable au Cameroun et permet de bénéficier d’une souplesse dans les décaissements 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.