CinetPay SDK-PHP integration
The technical implementation boils down to 3 steps:
- Requirement
- Preparing the notification and return pages
- Preparation and display of the payment counter
Etape 1 : Requirement
Before integrating our APIs, you must:
- Have a merchant account on:
www.cinetpay.com - Recover your APIKEY and your SITEID in your merchant account:
- Go to [www.cinetpay.com/login Danemark(https://app.cinetpay.com/login) and log in with your accesses
- Then click on the “Integrations” menu
- You will find your APIKEY and your SITEID there.
Pour utiliser pleinement le sdk, insérer vos informations dans le ficher marchand.php
<?php
$marchand = array(
"apikey" => "", // Enrer votre apikey
"site_id" => "", //Entrer votre site_ID
"secret_key" => "" //Entrer votre clé secret
);{warning.fa-close} Make sure you have some money in your Mobile Money as you will need it throughout your integration.
Etape 2 : Preparing the notification and return pages
Notification Page(Notify_url)
For those who have services that do not require processing of payment notifications from CinetPay, you can proceed directly to the next phase, for example donation services.
With each payment, CinetPay notifies you via a notification link.
NB :
- It's a silent link
- This is the only link that is able to update the information in the database relating to the transaction
Example :
if (isset($_POST['cpm_trans_id'])) {
try {
require_once __DIR__ . '/../src/new-guichet.php';
require_once __DIR__ . '/../commande.php';
require_once __DIR__ . '/../marchand.php';
//Création d'un fichier log pour s'assurer que les éléments sont bien exécuté
$log = "User: ".$_SERVER['REMOTE_ADDR'].' - '.date("F j, Y, g:i a").PHP_EOL.
"TransId:".$_POST['cpm_trans_id'].PHP_EOL.
"SiteId: ".$_POST['cpm_site_id'].PHP_EOL.
"-------------------------".PHP_EOL;
//Save string to log, use FILE_APPEND to append.
file_put_contents('./log_'.date("j.n.Y").'.log', $log, FILE_APPEND);
//La classe commande correspond à votre colonne qui gère les transactions dans votre base de données
$commande = new Commande();
// Initialisation de CinetPay et Identification du paiement
$id_transaction = $_POST['cpm_trans_id'];
// apiKey
$apikey = $marchand["apikey"];
// siteId
$site_id = $_POST['cpm_site_id'];
$CinetPay = new CinetPay($site_id, $apikey);
//On recupère le statut de la transaction dans la base de donnée
/* $commande->set_transactionId($id_transaction);
//Il faut s'assurer que la transaction existe dans notre base de donnée
* $commande->getCommandeByTransId();
*/
// On verifie que la commande n'a pas encore été traité
$VerifyStatusCmd = "1"; // valeur du statut à recupérer dans votre base de donnée
if ($VerifyStatusCmd == '00') {
// La commande a été déjà traité
// Arret du script
die();
}
// Dans le cas contrait, on verifie l'état de la transaction en cas de tentative de paiement sur CinetPay
$CinetPay->getPayStatus($id_transaction, $site_id);
$amount = $CinetPay->chk_amount;
$currency = $CinetPay->chk_currency;
$message = $CinetPay->chk_message;
$code = $CinetPay->chk_code;
$metadata = $CinetPay->chk_metadata;
//Something to write to txt log
$log = "User: ".$_SERVER['REMOTE_ADDR'].' - '.date("F j, Y, g:i a").PHP_EOL.
"Code:".$code.PHP_EOL.
"Message: ".$message.PHP_EOL.
"Amount: ".$amount.PHP_EOL.
"currency: ".$currency.PHP_EOL.
"-------------------------".PHP_EOL;
//Save string to log, use FILE_APPEND to append.
file_put_contents('./log_'.date("j.n.Y").'.log', $log, FILE_APPEND);
// On verifie que le montant payé chez CinetPay correspond à notre montant en base de données pour cette transaction
if ($code == '00') {
// correct, on delivre le service
echo 'Felicitation, votre paiement a été effectué avec succès';
die();
} else {
// transaction n'est pas valide
echo 'Echec, votre paiement a échoué pour cause : ' .$message;
die();
}
// mise à jour des transactions dans la base de donnée
/* $commande->update(); */
} catch (Exception $e) {
echo "Erreur :" . $e->getMessage();
}
} else {
// direct acces on IPN
echo "cpm_trans_id non fourni";
}Notification Page(Hmac)
You can use the HMAC on your notification url
<?php
if (isset($_POST['cpm_trans_id'])) {
try {
require_once __DIR__ . '/../src/new-guichet.php';
require_once __DIR__ . '/../commande.php';
require_once __DIR__ . '/../marchand.php';
/* Implementer le HMAC pour une vérification supplémentaire .*/
//Etape 1 : Concatenation des informations posté
$data_post = implode('',$_POST);
//Etape 2 : Créer le token suivant la technique HMAC en appliquant l'algorithme SHA256 avec la clé secrète
$generated_token = hash_hmac('SHA256', $data_post, $marchand["secret_key"]);
if ($_SERVER["HTTP_X_TOKEN"])
{
$xtoken = $_SERVER["HTTP_X_TOKEN"];
}
else{
$xtoken = "indisponible";
}
//Etape 3: Verifier que le token reçu dans l’en-tête correspond à celui que vous aurez généré.
if(hash_equals($xtoken, $generated_token))
{
// Valid Token
$validtoken = True;
//Création d'un fichier log pour s'assurer que les éléments sont bien exécuté
$log = "User: ".$_SERVER['REMOTE_ADDR'].' - '.date("F j, Y, g:i a").PHP_EOL.
"TransId:".$_POST['cpm_trans_id'].PHP_EOL.
"SiteId: ".$_POST['cpm_site_id'].PHP_EOL.
"HMAC RECU: ".$xtoken.PHP_EOL.
"HMAC GENERATE: ".$generated_token.PHP_EOL.
"VALID-TOKEN: ".$validtoken.PHP_EOL.
"-------------------------".PHP_EOL;
file_put_contents('./log_'.date("j.n.Y").'.log', $log, FILE_APPEND);
//La classe commande correspond à votre colonne qui gère les transactions dans votre base de données
$commande = new Commande();
// Initialisation de CinetPay et Identification du paiement
$id_transaction = $_POST['cpm_trans_id'];
// apiKey
$apikey = $marchand["apikey"];
// siteId
$site_id = $_POST['cpm_site_id'];
$CinetPay = new CinetPay($site_id, $apikey);
//On recupère le statut de la transaction dans la base de donnée
/* $commande->set_transactionId($id_transaction);
//Il faut s'assurer que la transaction existe dans notre base de donnée
* $commande->getCommandeByTransId();
*/
// On verifie que la commande n'a pas encore été traité
$VerifyStatusCmd = "1"; // valeur du statut à recupérer dans votre base de donnée
if ($VerifyStatusCmd == '00') {
// La commande a été déjà traité
// Arret du script
die();
}
// Dans le cas contrait, on verifie l'état de la transaction en cas de tentative de paiement sur CinetPay
$CinetPay->getPayStatus($id_transaction, $site_id);
$payment_date = $CinetPay->chk_payment_date;
$amount = $CinetPay->chk_amount;
$currency = $CinetPay->chk_currency;
$message = $CinetPay->chk_message;
$code = $CinetPay->chk_code;
$metadata = $CinetPay->chk_metadata;
//Enregistrement du statut dans le fichier log
$log = "User: ".$_SERVER['REMOTE_ADDR'].' - '.date("F j, Y, g:i a").PHP_EOL.
"Code:".$code.PHP_EOL.
"Message: ".$message.PHP_EOL.
"Amount: ".$amount.PHP_EOL.
"currency: ".$currency.PHP_EOL.
"-------------------------".PHP_EOL;
//Save string to log, use FILE_APPEND to append.
file_put_contents('./log_'.date("j.n.Y").'.log', $log, FILE_APPEND);
// On verifie que le montant payé chez CinetPay correspond à notre montant en base de données pour cette transaction
if ($code == '00') {
// correct, on delivre le service
echo 'Felicitation, votre paiement a été effectué avec succès';
die();
} else {
// transaction n'est pas valide
echo 'Echec, votre paiement a échoué pour cause : ' .$message;
die();
}
// mise à jour des transactions dans la base de donnée
/* $commande->update(); */
}
else{
echo "HMAC non-conforme";
die();
}
} catch (Exception $e) {
echo "Erreur :" . $e->getMessage();
}
} else {
// direct acces on IPN
echo "cpm_trans_id non fourni";
}Return Page (Return_url)
The return page is the page to which the customer is redirected after a transaction on CinetPay (whatever the status of the transaction). No database update should be processed on this page
Example of return page :
<?php
require_once __DIR__ . '/../src/new-guichet.php';
require_once __DIR__ . '/../commande.php';
include('../marchand.php');
if (isset($_POST['transaction_id']) || isset($_POST['token'])) {
$commande = new Commande();
$id_transaction = $_POST['transaction_id'];
try {
// Verification d'etat de transaction chez CinetPay
$CinetPay = new CinetPay($marchand["site_id"], $marchand["apikey"]);
$CinetPay->getPayStatus($id_transaction, $marchand["site_id"]);
$message = $CinetPay->chk_message;
$code = $CinetPay->chk_code;
//recuperer les info du clients pour personnaliser les reponses.
/* $commande->getUserByPayment(); */
// redirection vers une page en fonction de l'état de la transaction
if ($code == '00') {
echo 'Felicitation, votre paiement a été effectué avec succès';
die();
}
else {
// header('Location: '.$commande->getCurrentUrl().'/');
echo 'Echec, votre paiement a échoué';
die();
}
} catch (Exception $e) {
echo "Erreur :" . $e->getMessage();
}
} else {
echo 'transaction_id non transmis';
die();
}Step 3: Preparation and display of the payment counter
To initiate a payment you must generate a payment link by sending the following information in JSON.
- apikey: your apikey
- site_id: your site_id
- transaction_id: Identification of the transaction (unique)
- amount: The amount of the transaction
- currency: The monetary currency (XOF, XAF, CDF, GNF)
- description: Description of the current payment customer_name: The name of the customer
- customer_surname: The customer's first name
- notify_url: The payment notification link
- return_url: The link where the customer will be redirected after payment
- channels: the payment methods we want to display
- alternative_currency: conversion currency
- invoice_data: Any additional information you want to display on the CinetPay invoice (Supports three variables that you name at your convenience)
- metadata: any other additional information, generally you will put values you need to identify or process the payment easily, example: the order reference
- lang :the default language of the payment gateway (fr, en)
- alternative_currency : Value of the transaction in the currency chosen by the Merchant
To display the payment by credit card option, you must add this optional information to the previous information:
- customer_email: the customer's email address,
- customer_phone_number: customer number,
- customer_address: the customer's address,
- customer_city: name of the city,
- customer_country: country code,
- customer_state: name of the state,
- customer_zip_code: number prefix.
After having obtained the payment url from the previous request, you just have to launch this url in a web browser to find yourself on the payment counter.
{info.fa-info} For more security, it is necessary to record the information on the payment in the database before displaying the counter.
The data sent via email are processed in the action.php file
Exemple:
<?php
/*Commenter ses deux lines si vous êtes en production
error_reporting(E_ALL);
ini_set('display_errors', 1);*/
// required libs
require_once __DIR__ . '/src/new-guichet.php';
include('marchand.php');
include('commande.php');
// La class gère la table "Commande"( A titre d'exemple)
$commande = new Commande();
try {
if(isset($_POST['valider']))
{
$customer_name = $_POST['customer_name'];
$customer_surname = $_POST['customer_surname'];
$description = $_POST['description'];
$amount = $_POST['amount'];
$currency = $_POST['currency'];
}
else{
echo "Veuillez passer par le formulaire";
}
//transaction id
$id_transaction = date("YmdHis"); // or $id_transaction = Cinetpay::generateTransId()
//Veuillez entrer votre apiKey
$apikey = $marchand["apikey"];
//Veuillez entrer votre siteId
$site_id = $marchand["site_id"];
//notify url
$notify_url = $commande->getCurrentUrl().'cinetpay-sdk-php/notify/notify.php';
//return url
$return_url = $commande->getCurrentUrl().'cinetpay-sdk-php/return/return.php';
$channels = "ALL";
//
$formData = array(
"transaction_id"=> $id_transaction,
"amount"=> $amount,
"currency"=> $currency,
"customer_surname"=> $customer_name,
"customer_name"=> $customer_surname,
"description"=> $description,
"notify_url" => $notify_url,
"return_url" => $return_url,
"channels" => $channels,
"metadata" => "", // utiliser cette variable pour recevoir des informations personnalisés.
"alternative_currency" => "",//Valeur de la transaction dans une devise alternative
//pour afficher le paiement par carte de credit
"customer_email" => "", //l'email du client
"customer_phone_number" => "", //Le numéro de téléphone du client
"customer_address" => "", //l'adresse du client
"customer_city" => "", // 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 postal du client
);
// enregistrer la transaction dans votre base de donnée
/* $commande->create(); */
$CinetPay = new CinetPay($site_id, $apikey);
$result = $CinetPay->generatePaymentLink($formData);
if ($result["code"] == '201')
{
$url = $result["data"]["payment_url"];
// ajouter le token à la transaction enregistré
/* $commande->update(); */
//redirection vers l'url de paiement
header('Location:'.$url);
}
} catch (Exception $e) {
echo $e->getMessage();
}To activate the credit card payment universe, you need to provide some information about your customer in the $formData table
<?php
$formData = array(
...
...
//These variables must be provided for credit card payments
"customer_email" => "",
"customer_phone_number" => "",
"customer_address" => "",
"customer_city" => "",
"customer_country" => "",
"customer_state" => "", //Usa (US) or Canada (CA)
"customer_zip_code" => ""
);Exemple
