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 »

}

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 »

}

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.
  • 69994xxxx
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
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

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.

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.

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 ?