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 et celle du DEPOSIT , 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 / DEPOSIT
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 »,
« maximum_retries »: « 9 »
}
Si vous souhaitez plutôt faire un DEPOSIT client, il faut absolument en plus des paramètres ci-dessus renseigner le paramètre supplémentaire « debit_policy »: « deposit_acc_only » ne rien changer sur ce paramètre. le corp de requête devient comme ceci:
{
« 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 »,
« debit_policy »: « deposit_acc_only »,
« maximum_retries »: « 9 »
}
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 | 692xxxxxx |
| 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 | « Yes » |
| 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 | « 50 » |
| debit_policy | Il faut faire très attention, ce paramètre lorsqu’il est présent et à la valeur “deposit_acc_only” précise que vous voulez faire une opération de DEPOSIT et non de remboursement. | « deposit_acc_only » | |
| maximum_retries | chaîne de caractères | Lorsque vous envoyez de l’argent via notre API, il est possible que les fonds n’arrivent chez le client qu’une heure après votre requête, généralement en raison d’une instabilité du serveur d’Orange. Nous avons mis en place un mécanisme de tentatives automatiques afin de garantir la satisfaction du client malgré l’indisponibilité temporaire du réseau. Bien que ce système soit très efficace, il peut sembler trop long pour certains clients qui ont besoin d’une réponse plus rapide (dans un délai de 5 secondes, 20 secondes, 1 minute, ou 5 minutes, mais pas jusqu’à 1 heure). Pour cela, il est possible de paramétrer le nombre de tentatives que le système doit effectuer à l’aide de ce paramètre. | « 9 » |
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” |
| 5028 | debit_policy should be either « customer_acc_only », « deposit_acc_only », « customer_acc_then_deposit_acc » or « deposit_acc_then_customer_acc » | La valeur du paramètre debit_policy doit être “deposit_acc_only” |
| 5042 | Sorry your account balance is not enough to process | Ce message concerne le DEPOSIT et signifie que votre compte de DEPOSIT n’a pas le solde nécessaire pour effectuer la transaction. |
| 4041 | Sorry your account was not found. Please contact Paynote Admin | Erreur concernant également le DEPOSIT: votre compte DEPOSIT n’existe pas et il faut contacter l’Admin Paynote. |
|
5031
|
maximum_retries
should be a digit. Ex. « 1 » or « 10 »
|
Le nombre de tentatives doit être une chaine contenant un entier. |
|
5031
|
maximum_retries
should be between 1 and 60.
Ex. « 0 » or « 10 »
|
Le nombre de tentatives doit être compris entre 1 et 10. |
|
5011
|
Customer Key mut be a string
|
Le nom d’utilisateur doit être une chaine de caractères. |
|
5012
|
Customer Secret mut be a string
|
Le mot de passe doit être une chaine de caractères. |
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 »: « 692xxxxxx »,
« 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 »: « 692xxxxxx »
},
« 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
5. Consulter le solde de votre compte (DEPOSIT uniquement)
Pour effectuer le DEPOSIT, il faudrait que vous ayez un solde suffisant pour que l’opération réussisse. Pour consulter votre solde il faut utiliser le end point: https://omapi.ynote.africa/prod/balance, avant cela il faut récupérer un jeton sur l’URL https://omapi-token.ynote.africa/oauth2/token en fournissant l’id et le secret client.
Le corps de la requête est le suivant:
{
« customerkey »: »XXXXXXXX »,
« customersecret »: »XXXXX »,
« payment_method »: « DEPOSIT »
}
Explication des paramètres:
|
customerkey |
Votre clé client |
|
customersecret |
Votre clé secrète |
|
payment_method |
La méthode de paiement. Sa valeur doit être DEPOSIT |
Voici les possibles retours suite au post sur cet endpoint:
|
Message |
Description |
Solution possible |
|
Unauthorized |
Vous n’êtes pas autorisé à faire cette opération |
Générer un nouveau token, vérifier que vous avez renseigné le customerkey et customersecret dans le corp de la requête. |
|
Sorry, your company was not found |
Vos données n’existent pas dans notre système. |
Il faut vérifier votre customerkey, contactez l’administrateur Paynote si le problème persiste. |
|
Sorry, your balance was not found |
La balance de votre compte n’a pas été trouvée. |
Contactez l’admin Paynote. |
|
Votre solde est de xxx FCFA |
C’est le retour attendu lorsque tout se passe bien. xxx correspond au montant (solde). |
Et voila , vous avez maintenant implémenté l’API de remboursement / DEPOSIT 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 ?