Workflow d'intégration
L’implémentation technique se résume à 3 étapes:
Etape 1
Vous devez avoir un compte et un service valide sur CinetPay
Sinon, Veuillez Créer votre compte et votre premier service marchand.
Une fois cela fait, vous devez récupérer votre APIKEY et votre SITE ID dans votre interface une fois connecté avant de continuer votre intégration.
Etape 2
NB: vous devez definir le "Content Type" de toutes vos requête sur: "x-www-form-urlencoded"
Formulaire de paiement :
L’appel à la plateforme de paiement est réalisé via l’envoi d’un formulaire posté en https. Ce formulaire contient au minimum les paramètres obligatoires listés ci-dessous ainsi qu’une variable signature unique par formulaire attestant de son authenticité.
Signature :
Pour calculer la signature, il est nécessaire de poster (Envoyer les données en POST) exactement les informations ci-dessous dans le tableau à cette url: https://api.cinetpay.com/v1/?method=getSignatureByPost
Vous obtiendriez en retour une chaine de caractère représentant la signature de votre paiement en cour.
Vous devez stocker dans une variable cette « signature » pour la suite.
NB : Le montant doit être un multipe de 5, le montant minimum par devise etant de 100 XAF ou XOF, 0.2 USD et 400 CDF
Exemple de réponse bonne : '95db7a68358e8cb8831db947d8abcfef002af755' Exemple de réponse JSON obtenu en cas d’erreur:
{
"status": {
"code": "609",
"message": "AUTH_NOT_FOUND"
}
}
NB: Quel que soit la réponse obtenue, il faudra décoder cette réponse car cette réponse est considérée comme un JSON
Création du Formulaire de paiement :
L’URL de la page de paiement est : https://secure.cinetpay.com
Vous pouvez activer le mode debug en ajoutant un champs 'debug' avec comme valeur 1
L’utilisation des balises iframes pour afficher la page de paiement est interdite pour des raisons de sécurité
URL de notification :
L’URL de notification serveur est le seul mécanisme à implémenter pour synchroniser automatiquement le site de paiement et votre site marchand.
NB: l'url de notification est un webhook que vous mettez en place, CinetPay appelera ce hook à chaque update pour vous notifier du changement de status pendant le déroulement d'une transaction.
A la fin d’un paiement, la plateforme de paiement appelle systématiquement l’url de notification serveur renseignée dans le back-office marchand 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é.
Pour le renseigner, veuillez vous connecter avec vos identifiants marchand CinetPay, puis cliquez sur l’onglet « Préférences » et allez à la section « Notification de paiement instantanée ».
Remarque importante:
L’url de notification serveur est le seul mécanisme qui doit permettre le lancement des tâches dépendantes du paiement. (Mise à jour du statut de la commande dans votre back office boutique, envoie d’émail, déstockage produit etc …)
l’URL de notification serveur peut être appelée plusieurs fois, il est donc nécessaire que votre implémentation prenne cela en considération.
les valeurs de « notify_url », « return_url » et « cancel_url » renseigner via le code écrasent celle parametré dans le backoffice.
Une fois ces paramètres reçus par « POST » sur votre Url de notification, vous devez envoyer par POST les trois variables suivantes « apikey », « cpm_site_id » et « cpm_trans_id » à cette Url :
https://api.cinetpay.com/v1/?method=checkPayStatus
vous obtiendrez le statut de votre paiement au format JSON.
Un exemple de réponse reçu ci-dessous :
{
"transaction": {
"cpm_site_id": "296911",
"signature": "4dfbf5b8f40818abffe754b8a8aa04e4d29af25f",
"cpm_amount": "11",
"cpm_trans_date": "04092017140045",
"cpm_trans_id": "50445985950",
"cpm_custom": "08373459U",
"cpm_currency": "XOF",
"cpm_payid": "MP170904.1401.A91088",
"cpm_payment_date": "2017-09-04",
"cpm_payment_time": "14:01:35",
"cpm_error_message": "SUCCES",
"payment_method": "OM",
"cpm_phone_prefixe": "225",
"cel_phone_num": "79557788",
"cpm_ipn_ack": "Y",
"created_at": "2017-09-04 14:00:54",
"updated_at": "2017-09-04 14:01:06",
"cpm_result": "00",
"cpm_trans_status": "ACCEPTED",
"cpm_designation": "Test",
"buyer_name": ""
}
}
Après avoir décodé le JSON, si la valeur de la variable « cpm_result » est égale à « 00 » et si la valeur de la variable « cpm_amount » est égale à la valeur du montant stocké dans votre base de données et que finalement la valeur de la variable « signature » est la même que celle que vous avez préalablement stockée en base de données lors de l’achat ou du paiement, alors votre paiement est bon. Vous pouvez délivrer le service à votre client.
Attention aux paiements en double
vous devez obligatoirement bien vérifier que la transaction que vous allez traiter n’avait pas été traitée et validée préalablement afin d’éviter de délivrer deux ou n-fois le même service au même client.
Raisons de non synchronisation des paiements :
- URL de notification serveur non renseignée dans le back office « Onglet Préférences une fois connecté »,
- URL de notification serveur qui pointe sur la page d’accueil du site marchand et qui n’exécute aucun traitement,
- URL de notification serveur qui ne peut être appelée car bloquée par un fichier .htaccess
- URL de notification serveur bloquée par votre firewall,
- Redirection à l’arrivée qui entraine la perte des valeurs postées. L’url serveur contient toujours les paramètres
postés. Ne pas les trouver est toujours une erreur d’implémentation du côté du site marchand,
NB: Les paramètres postés dans l’URL serveur peuvent évoluer par ajout de nouveaux champs.
Etape 3
Retour à la boutique :
Le retour à la boutique permet à l’internaute de revenir à la boutique après un clic sur le bouton « Retour boutique » présent sur la page de paiement.
Dans le formulaire de paiement il est possible de renseigner deux URLs de retour :
- cancel_url en cas d'annulation
- return_url au cas ou l'utilisateur termine le processus de paiement (success ou echec)
