API

CHECKOUT
Réussir l’intégration de l’API Checkout de CinetPay

Page | 1
Table des matières
1. Note de version ............................................................................................................................................ 3
2. Présentation................................................................................................................................................. 4
3. Prérequis ...................................................................................................................................................... 4
4. Paiement ...................................................................................................................................................... 5
4.1. Initialisation de paiement .......................................................................................................................... 5
4.2. Page de paiement ...................................................................................................................................... 6
5. Notification .................................................................................................................................................. 7
5.1 Pourquoi la notification ? ........................................................................................................................... 7
5.2 Configurer l’url de notification .................................................................................................................... 7
6. Retour sur le site marchand.......................................................................................................................... 8
7. Mise à jour de la documentation.............................................................................................................. 9
8. Annexe 1 : Tableau de codes de l’api ...................................................................................................... 10

Page | 2
1. Note de version

Version Date Commentaires

1.0.0 23/06/21 - Version initiale
1.0.1 02/08/21 - Ajout de details

Page | 3
2. Présentation
Ce tutoriel s’adresse à tous les marchands CinetPay qui veulent encaisser des fonds via le mobile money, les
cartes bancaires ou les wallets par des processus automatiques (Site internet, App mobiles etc…).

3. Prérequis
Avant de procéder à l’intégration de l’api de collecte de fonds, vous devez :

• Avoir un compte marchand sur www.cinetpay.com ;

• Récupérer votre APIKEY et votre SITEID dans votre compte marchand ;
o Ci-dessous la procédure pour récupérer votre APIKEY et votre SITEID :
• Rendez-vous sur www.cinetpay.com/login et connectez-vous avec vos accès
• Cliquer ensuite sur le menu « Intégrations ») ;
• Vous y trouverez votre APIKEY et votre SITEID ;

Page | 4
4. Paiement

4.1. Initialisation de paiement

Nom Initialisation de paiement

Description Générer un lien de paiement.
Les informations suivantes sont à envoyer en JSON

URL https://api-checkout.cinetpay.com/v2/payment

Content Type application/json

Méthode POST
Paramètres apikey : votre apikey
site_id : votre site_id
POST transaction_id : Identification de la transaction (unique)
amount : Le montant de la transaction
currency : La devise monétaire (XOF, XAF, CDF, GNF)
description : Description du paiement en cours
customer_id: L’identifiant du client dans votre système
customer_name: Le nom du client
customer_surname: Le prénom du client
notify_url: Le lien de notification du paiement
return_url: Le lien où le client sera redirigé après le paiement
channels: sert à définir les univers présent sur le guichet (ALL, MOBILE_MONEY, CREDIT_CARD)
lang: La langue par défaut du guichet de paiement (fr, en)
metadata : toutes autre informations complémentaires, généralement vous mettrez des valeurs dont vous aurez besoin pour identifier ou
traiter facilement le paiement, exemple : la référence de la commande (falcultatif)
---- Pour encaisser des paiements bancaires, les paramètres suivantes sont obligatoires ----
customer_phone_number: Le numéro de téléphone du client
customer_email: L’adresse mail du client
customer_address: L’adresse du client
customer_city: La ville du client
customer_country: Le pays du client, la valeur à envoyer est le code ISO du pays (code à deux chiffre) ex : CI, BF, US, CA, FR
customer_state: L’état dans de la quel se trouve le client. Cette valeur est obligatoire si le client se trouve au États Unis d’Amérique
(US) ou au Canada (CA)
customer_zip_code: Le code zip du pays dans lequel se trouve le client
Exemple {
"amount": 2500,
Requête :
"currency": "XOF",
"apikey": "XXXXXXXXXXXXXXXX",
"site_id": "XXXXX",
"transaction_id": "REFID12354",
"description": "TRANSACTION DESCRIPTION",
"return_url": "https://www.exemple.com/return",
"notify_url": "https://www.exemple.com/notify",
"metadata": "user001",
"customer_id": "001",
"customer_name:": "John",
"customer_surname": "Doe",
"channels": "MOBILE_MONEY"
}
Exemple {
"code": "201",
Réponse :
"message": "CREATED",
Succès "description": "Transaction created with success",
"data": {
"payment_token": "YOUR_TOKEN_HERE",
"payment_url": "PAYMENT_URL_HERE"
},
"api_response_id": "RESPONSE_ID_HERE"
}

Page | 5
 Exemple {
"code": "ERROR_CODE",
Réponse :
"message": "ERROR_MESSAGE ",
Erreur "description": "ERROR_DESCRIPTION",
"api_response_id": "RESPONSE_ID_HERE"
}
NB : • Vous devez sauvegarder le payment_token dans votre base de données

4.2. Page de paiement

Après avoir obtenu l’url de paiement à la requête précédente, il vous suffit juste de lancer cette url dans un
navigateur web pour vous retrouver sur le guichet de paiement, dans le cas des applications mobile, vous
pouvez faire appel à une WebView pour l’exécution du guichet de paiement.
Vous avez ainsi fini la première partie de l’intégration CinetPay.

Page | 6
5. Notification
5.1 Pourquoi la notification ?
Le lien/url de notification (notify_url) est appelé par CinetPay pour vous notifier de l’état d’un paiement.
Cette url doit être disponible pour accueillir des requêtes HTTP de type GET et POST.
Le notify_url doit être le seul mécanisme à implémenter pour synchroniser automatiquement les paiements
vers votre site marchand. CinetPay appellera ce lien après chaque update pour vous notifier du changement
de statuts pendant le déroulement d'une transaction.
A la fin d’un paiement, CinetPay appelle systématiquement l’url de notification pour le service concerné.
Cet appel a pour but d’informer le site marchand de l’état du paiement (même si le client ne revient pas sur
le site). Le marchand pourra ainsi valider sa commande si le paiement est vérifié et accepté.
NB : l’url de notification n’est pas nécessaire si vous n’avez pas besoin d’avoir le statut des paiements dans
votre base de données, car vous avez l’historique de vos paiements dans votre backoffice CinetPay.
Ex : Application de collecte de dons

5.2 Configurer l’url de notification

Le serveur exécute une requête de type POST contenant :

• cpm_trans_id: la variable transaction_id que vous avez envoyé à l’initialisation

• cpm_site_id : la variable site_id que vous avez envoyé à l’initialisation

NB :
• CinetPay ne vous enverra pas les informations sur le statut de la transaction pour éviter certaine faille
de sécurité comme le man in the middle.
• L’url de notification peut être appelée plusieurs fois.
• Il faudra toujours effectuer un appel à l’API de « Vérification de transaction » de paiement pour
avoir les vraies valeurs du paiement.

Pour vous assurer de l’intégrité des données que vous traitez, vous devez effectuer certaines vérifications :
- Votre url de notification doit être une api qui attend un appel en POST et en paramètre le
cpm_trans_id (Correspondant à la variable transaction_id) ;
- Après l’avoir obtenu, vous devez vérifier dans votre base de données que le statut du paiement
concerné est déjà à succès ;
- Si oui alors vous ne faites plus de mise à jour ;
- Si non vous devez faire un appel à l’api de vérification de transaction avec le cpm_trans_id, pour
obtenir le statut de la transaction chez CinetPay et mettre ainsi à jour le statut dans votre base de
données.

Page | 7
 Nom Vérification de transaction
Description Utiliser cette requête pour avoir le statut d’un paiement

URL https://api-checkout.cinetpay.com/v2/payment/check

Content Type application/json

Method POST
Paramètres POST apikey : votre Apikey
site_id : votre site_id
obligatoire transaction_id : votre transaction_id | OU | token : Le payment_token obtenu lors de l’initialisation du paiement
Exemple Réponse : {
"code": "00",
Succès
"message": "SUCCES",
"api_response_id": "1617808789.7749",
"data": {
"operator_id": "8210407187720",
"payment_method": "FLOOZ",
"metadata": "user001",
"payment_date": "2021-04-07 14:07:24",
"phone_number": "0102324373",
"phone_prefix": "225"
}
}
Exemple Réponse : {
"code": "600",
Erreur
"message": "PAYMENT_FAILED",
"api_response_id": "1617808521.2503",
"data": {
"payment_method": "OM",
"payment_date": " ",
"metadata": "user001",
"phone_number": "0749012966",
"phone_prefix": "225"
}
}

6. Retour sur le site marchand

Après son paiement, le client sera redirigé vers l’url que vous avez soumis dans la variable return_url
définis à l’initialisation du paiement.
Le lien/url de retour (return_url) est appelé par CinetPay pour renvoyer le client sur votre site. Cette url
doit être disponible pour accueillir des requêtes HTTP de type GET et POST.
CinetPay ajoute en paramètre le payment_token qui vous permet d’identifier pour quel client le retour est
effectuer, vous pouvez ainsi affichez un message à vos utilisateurs après leur paiement pour les informer si

Page | 8
leur paiement est réussi ou non, cela est possible étant donné que vous avez le statut de la transaction via
votre url de notification (voir chapitre précédent).

7. Mise à jour de la documentation

Afin d’améliorer constamment la compréhension et la bonne utilisation de cette documentation, les
remarques constructives d’utilisateurs sont des éléments significatifs.
Merci d’envoyer vos commentaires et suggestions à l’adresse suivante : support@cinetpay.com

Page | 9
 8. Annexe 1 : Tableau de codes de l’api
Code Message

*00* SUCCES

*201* CREATED

*600* PAYMENT_FAILED

*602* INSUFFICIENT_BALANCE

*603* SERVICE_UNAVAILABLE

*604* OTP_CODE_ERROR

*608* MINIMUM_REQUIRED_FIELDS

*606* INCORRECT_SETTINGS

*609* AUTH_NOT_FOUND

*610* ERROR_PAYMETHOD_NOTFOUND

*611* ERROR_AMOUNT_TYPE

*612* ERROR_CURRENCY_NOTVALID

*613* ERROR_SITE_ID_NOTVALID

*614* ERROR_FORMAT_TRANSACTION_DATE

*615* ERROR_LANGUAGE_NOTVALID

*616* ERROR_PAGE_ACTION_NOTVALID

*617* ERROR_PAYMENT_CONFIG_NOTVALID

*618* ERROR_API_VERSION_NOTVALID

*619* ERROR_SIGNATURE_DONT_MATCHED

*620* ERROR_DOUBLE_PAYEMNT

*621* ERROR_OMPAY_UNAVAILABLE

*622* ERROR_MOMOPAY_UNAVAILABLE

*623* WAITING_CUSTOMER_TO_VALIDATE

*624* UNKNOWN_ERROR

*625* ABONNEMENT_OR_TRANSACTIONS_EXPIRED

*626* ERROR_FLOOZPAY_UNAVAILABLE

*627* TRANSACTION_CANCEL

*628* ERROR_AMOUNT_FORMAT

*635* ERROR_PHONE_NUMBER_NOT_FOUND

*636* ERROR_PHONE_NUMBER_NOT_SUPPORTED

*637* ERROR_PHONE_PREFIX_NOT_SUPPORTED

*641* ERROR_AMOUNT_TOO_LOW

*642* ERROR_AMOUNT_TOO_HIGH

*662* WAITING_CUSTOMER_PAYMENT

*663* WAITING_CUSTOMER_OTP_CODE

*664* WAITING_CUSTOMER_PAYMENT_AT_OPERATOR_SIDE

*804* OPERATOR_UNAVAILABLE

*807* DAILY_MAX_NUMBER_TRANSACTION_REACHED

Page | 10
*808* DAILY_MAX_AMOUNT_TRANSACTION_REACHED

*809* MONTHLY_MAX_AMOUNT_TRANSACTION_REACHED

*810* MONTHLY_MAX_NUMBER_TRANSACTION_REACHED

*811* WEEKLY_MAX_AMOUNT_TRANSACTION_REACHED

*812* WEEKLY_MAX_NUMBER_TRANSACTION_REACHED

Page | 11