Vous avez surement parcouru nos tutoriels d’encaisement Orange Money via l’API web ou via l’API USSD et vous souhaitez sortir de l’argent de votre compte marchand vers des numéros ordinaires tels que ceux de vos clients ou vos fournisseurs. Le présent article décrit la démarche à suivre en tant que développeur (ou non) pour pouvoir réaliser ce genre d’opération.
Pour intégrer l’API de remboursement , vous devez avoir à votre disposition les informations suivantes :
- le idClient
- le secretClient
- le customerkey
- customersecret
- le ChannelUserMsisdn
- Et enfin le pin
Ces informations sont fournies par votre agrégateur WebPaiement Orange Money. Si vous n’avez pas de contrat Orange Money , n’hésitez pas à nous contacter.
Etape 1: Récupération de l'access 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
Cette requête doit comporter un header contenant les paramètres:
- Conten-Type:application/x-www-form-urlencoded
- Authorization: elle doit avoir comme valeur votre login:votre_mot_de_passe encodé en base64
La requête CURL est la suivante:
1 2 3 4 | curl --location 'https://omapi-token.ynote.africa/oauth2/token' \<br /><br /> --header 'Content-Type: application/x-www-form-urlencoded' \<br /><br /> --header 'Authorization: Basic base64(login:mot_de_passe)' \<br /><br /> --data-urlencode 'grant_type=client_credentials' -k |
La réponse a cette requête est un element en JSON comprenant votre Access Token Bearer:
1 | {"access_token":"eyJraWQiOiJcL2NucXVJYjNxx.eyJzdWIiOiIzYXEwZjE4NTAzY25kN3R0c2Yzb2ZtY2JxIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJzZW5kcmVxdWVzdFwvc2VuZHJlcXVlc3QiLCJhdXRoX3RxxoxNzA2MTk3NTI5LCJ2ZXJzaW9uIjoyLCJqdGkiOiI4YjdjOGI1MC0yMDA4LTRhOTQtODQ2MS0zMjc2OGUxZTRmZTgiLCJjbGllbnRfaWQiOiIzYXEwZjE4NTAzY25kN3R0c2Yzb2ZtY2JxIn0.XvOwsC8rW5ZZqL_IfnFSzZNdiAOZvdS6TpZmR5annmJsY2htG-OW0Ybm3KUHxxxbYrFaKhRNB-_IzU0_nna7B4NnraF3M8NjWsQZj_lJZ98eu4AEqw3gS6kPgdrrrouqWXCr5PwK1hQkRZmF_71f-4I4mJmz_243L0G461C4eCnTVsFGiVKU_q3lj-dNBRt7CgxxM-e0TtH03t-iYtQscR8bfP0SXWu-DiRJ4XX2KRZzFBKb1KFDiSHws2_42eTcXJEOENkZEh39w","expires_in":300,"token_type":"Bearer"} |
Le paramètre à récupérer pour la suite de nos opérations est « access_token« . Son délai d’expiration est précisé dans la paramètre « expires_in » et exprimé en secondes.
Etape 2: Requête de remboursement
Par la suite, utilisez ce jeton obtenu à l’étape 1 dans votre requête de remboursement sur le point de terminaison https://omapi.ynote.africa/prod/refund avec le type d’auhtentification Bearer :
Passer ensuite corps de la requête en json dans le dody:
{
« customerkey »: « customerkey »,
« customersecret »: « customersecret »,
« channelUserMsisdn »: « channelUserMsisdn »,
« pin »: « channelUserPin »,
« webhook »: « WebhookUrl »,
« amount »: « amount »,
« final_customer_phone »: « finalCustomerPhone »,
« final_customer_name »: « finalCustomerName »,
« refund_method »: « OrangeMoney »,
« fees_included »: « Yes/No »,
« final_cutomer_name_accuracy »: « 50 »
}
Explication des différents paramètres
| Paramètres | Type | Description | Exemple |
| access_token | Bearer | access_token récupéré plus haut | eVraWQiOiJcL2RUbGciOidsI1NiJ9.eyJzdW………………… |
| customerkey | Chaîne de caractère | Login de l’utilisateur | knnWJwrxaVgHzXQSloPePxAAwavB |
| customersecret | Chaîne de caractère | Mot de passe de l’utilisateur | knnWJwrxaVgHzXQSloPePxAAwavB |
| channelUserMsisdn | Chaîne de caractère | Le numéro de téléphone du compte, l’indicatif du pays n’est pas requis. |
|
| pin | Chaîne de caractère | Votre code PIN | 2222 |
| 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 985 FCFA | 100 |
| final_customer_phone | Chaîne de caractère | le numéro de téléphone du bénéficiaire | 692954629 |
| final_customer_name | Chaîne de caractère | le nom du bénéficiaire | Kevel Tiah |
| refund_method | Chaîne de caractère | La méthode de paiement | OrangeMoney |
| 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 ce montant. Si ce paramètre vaut “No” alors le montant de la commission sera automatiquement calculé et prélevé dans votre compte. Exemple: pour un remboursement de 1000 FCFA, si le paramètre vaut “No” votre compte sera débité de 102F afin que le client reçoive exactement 100 FCFA, par contre si le paramètre n’est pas présent ou vaut “Yes”, cela suppose que vous avez mis un montant de 102F dès le départ et le client recevra 100 F CFA | |
| final_cutomer_name_accuracy |
chaîne de caractères |
Précision à utiliser lors de la vérification du nom du client qui possède la puce. La valeur va de 0% à 100%. Par exemple si dans le paramètre final_customer_name vous avez écrit “Jean-Luc Arribart” et que votre précision est a 100%, alors notre système va faire une vérification pour s’assurer que le nom le nom du client est enregistré chez Orange avec le nom “Jean-Luc Arribart” exactement comme vous avez écrit. Par contre si votre précision est à 50% par exemple, il suffirait que le final_customer_name puisse correspondre au moins à 50%. L’argent ne sera pas envoyé au client si la valeur calculée par le système est inférieure à celle que vous avez précisé, vous recevez alors un mail de notification, c’est ca le principe |
Exemple d’appel avec CURL:
1 | curl --location 'https://omapi.ynote.africa/prod/refund' \ |
–header ‘Content-Type: application/json’ \
–header ‘Authorization: Bearer xxxxxxxxxxxxxx’ \
–data ‘{
« customerkey »: »customerkey »,
« customersecret »: »customersecret »,
« channelUserMsisdn »: »channelUserMsisdn »,
« pin »: »xxxx »,
« webhook »: »http://cloudfacile.com »,
« amount »: »1″,
« final_customer_phone »: »final_customer_phone »,
« final_customer_name »: »final_customer_name »,
« refund_method »: »OrangeMoney »,
« fees_included »: »Yes »
}’ -k
La donnée renvoyée par cet appel est un dictionnaire sous la forme:
{
« MD5OfMessageBody »: « 4b55cf6629b5f0ee3c8ac91435a2eb35 »,
« MD5OfMessageAttributes »: « a8131b3b71091fac4bcb2ca91c0ce5f4 »,
« MessageId »: « 88bca5ce-6e19-4e23-a6db-5526af30769b »,
« ResponseMetadata »: {
« RequestId »: « 956e59b1-9f8b-51d6-8dbb-020bf55d54ca »,
« HTTPStatusCode »: 200,
« HTTPHeaders »: {
« x-amzn-requestid »: « 956e59b1-9f8b-51d6-8dbb-020bf55d54ca »,
« x-amzn-trace-id »: « Root=1-63406895-34a2465355b540ad13d22abd;Parent=5552ed3a0a225582;Sampled=0 »,
« date »: « Fri, 07 Oct 2022 17:57:42 GMT »,
« content-type »: « text/xml »,
« content-length »: « 459 »
},
« RetryAttempts »: 0
}
}
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.
3. 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, 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é. |
| 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 Channel User Msisdn | Le numéro de téléphone du compte n’est pas renseigné. |
| 5014 | Error on PIN Number | Le PIN n’est pas renseigné. |
| 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. |
| 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. | |
| 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 orange valide. | |
| 5027 | fees_included should be either « Yes » or « No » | Le paramètre “fees_included” doit être soit “Yes”, soit “No” |
|
5029 |
final_customer_name_accuracy should be a digit. Ex. « 50 » or « 100 » |
Le paramètre final_customer_name_accuracy doit être un entier (entre double quotes) |
|
5030 |
final_customer_name_accuracy should be between 0 and 100. Ex. « 0 » or « 50 » |
Le paramètre final_customer_name_accuracy doit être entre “0” et “100” |
4. Vérification du statut des transactions
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 le 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:
{
« customerkey »: « customerkey »,
« customersecret »: « customersecret »
}
Voici un exemple de réponse lors de l’appel a cet API:
{
« result »: {
« message »: « Cash in performed successfully »,
« data »: {
« createtime »: « 1671094515 »,
« subscriberMsisdn »: « 692954629 »,
« amount »: 1,
« payToken »: « CXXXXXXXXXXXXXXXX »,
« txnid »: « XXXX.1000.B34550 »,
« txnmode »: « rembourse »,
« txnstatus »: « 200 »,
« orderId »: « rembourse »,
« status »: « SUCCESSFULL »,
« channelUserMsisdn »: « 69xxxxxxxx »,
« description »: « Remboursement »
}
},
« parameters »: {
« amount »: « 1 »,
« xauth »: « WU5XXXXXXXXXXXXXXXXXXX »,
« channel_user_msisdn »: « 69xxxxxx »,
« customer_key »: « xxxxxxxxxxxxxxxxxxx »,
« customer_secret »: « xxxxxxxxxxxxxxxxxxxxx »,
« final_customer_name »: « TIAH kevel »,
« final_customer_phone »: « 692954629 »
},
« CreateAt »: « 12-15-2022 09:00:05 »,
« MessageId »: « a16add05-73d0-44db-a30a-89c91658df99 »,
« RefundStep »: « 2 »
}
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. |
|
RefundStep |
Ce paramètre est très important, il permet de savoir à quel niveau se trouvent les fonds pour une transaction donnée. Si le paramètre vaut “1” alors votre compte n’a pas encore été débité, s’il vaut “2” alors le montant de la transaction a déjà été prélevé de votre compte. |
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é. |
|
Max cashin check status retry exceeded |
La vérification du statut du paiement final vers le client a échoué. (Vous allez recevoir un mail), le statut ici sera UNKNOWN. Généralement il est recommandé de nous laisser vérifier ce cas afin que le client perçoive effectivement ses fonds. |
|
|
Max c2c check status retry exceeded |
La vérification du prélèvement (ou non) de votre compte a échoué, le statut sera également UNKNOWN. Il est possible ici que votre compte ait été débité mais votre client n’ait pas reçu les fonds. Il est également recommandé de nous laisser vérifier ce cas afin que le client perçoive effectivement ses fonds. |
Les différents statuts d’une transaction peuvent être:
- SUCCESFUL
- INITIATED
- PENDING
- FAILED
- EXPIRED
Et voila , vous avez maintenant implémenté l’API de remboursement Orange Money vous permettant d’envoyer de l’argent vers des numéros ordianires tels que ceux de vos client ou vos fournisseurs.
Cette API Orange Money est valable au Cameroun et permet de bénéficier d’une souplesse dans les remboursements inégalé.
Vous avez une activité ? Vous souhaitez payer vos partenaires 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.
Intéressé ?
Vous souhaitez mettre en place Orange Money sur votre site web ? Vous souhaitez proposez des encaissements Orange Money à vos clients sur votre application mobile ?