{danger.fa-close} Lire toutes les sections en bleues pour mieux comprendre la documentation et les sections en orange signifiant l'alerte afin d'éviter des erreurs à commettre durant les intégrations et les procédures détaillées pour les intégration.
Les clés d'API sont vos références numériques auprès des systèmes de PayDunya. Nous les utilisons afin d'identifier votre compte et les applications que vous allez créer. Ces clés sont nécessaires pour toute intégration des APIs de paiements PayDunya. Voici chronologiquement la marche à suivre :
Vous devez d'abord avoir un compte PayDunya Business activé. Créez-en un si besoin y est.
Connectez-vous à votre compte et cliquez sur Intégrez notre API au niveau du menu à gauche.
Cliquez sur le bouton Configurer une nouvelle application et remplissez le formulaire.
Choisissez MODE TEST, JE VEUX FAIRE DES TESTS DE PAIEMENT. puis
ACTIVER LE MODE DE PRODUCTION.
Composer est un outil pour gérer les dépendances en PHP. Les dépendances, dans un projet, ce sont toutes les bibliothèques dont votre projet dépend pour fonctionner. Par exemple, votre projet utilisera la bibliothèque PayDunya pour gérer les paiements, il « dépend » donc de PayDunya. Autrement dit, PayDunya est une dépendance dans votre projet. Pour plus d'informations, veuillez vous rendre sur LE SITE OFFICIEL DE COMPOSER.
composer require paydunya/paydunya{info.fa-lightbulb-o}
Cliquez ici pour télécharger la dernière version de notre client PHP. Ensuite décompressez le fichier puis copiez le contenu dans un emplacement du dossier contenant le code source de votre application.
Si vous ne savez pas dans quel sous-dossier mettre la librairie PayDunya, nous vous proposons les noms de sous-dossiers suivants:libs,librariesou encorevendor.
Vous pouvez créer un fichier de configuration globale contenant les paramètres ci-dessous et l'inclure par la suite dans chacun de vos fichiers nécessitant de faire appel à l'API. Pensez premièrement à inclure le client PHP de PayDunya au niveau du fichier de configuration globale.
require('chemin_vers_le_dossier_du_client_php_paydunya/paydunya.php');{info.fa-lightbulb-o}
Si vous avez choisi par contre l'installation via Composer, il vous suffira d'inclure le fichier
vendor/autoload.php.
require('vendor/autoload.php');{info.fa-lightbulb-o}
Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur
détailsau niveau de l'application que vous avez créée, récupérez les clés d'API et donnez-les en arguments aux méthodes suivantes :
Paydunya_Setup::setMasterKey("wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW");
Paydunya_Setup::setPublicKey("test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja");
Paydunya_Setup::setPrivateKey("test_private_rMIdJM3PLLhLjyArx9tF3VURAF5");
Paydunya_Setup::setToken("IivOiOxGJuWhc5znlIiK");
Paydunya_Setup::setMode("test"); // Optionnel en mode test. Utilisez cette option pour les paiements tests.
\Paydunya\Setup::setMasterKey("wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW");
\Paydunya\Setup::setPublicKey("test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja");
\Paydunya\Setup::setPrivateKey("test_private_rMIdJM3PLLhLjyArx9tF3VURAF5");
\Paydunya\Setup::setToken("IivOiOxGJuWhc5znlIiK");
\Paydunya\Setup::setMode("test"); // Optionnel en mode test. Utilisez cette option pour les paiements tests.
{info.fa-lightbulb-o}
Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur
détailsau niveau de l'application que vous avez créée, récupérez les clés d'API et donnez-les en arguments aux méthodes suivantes. Si vous êtes en test utilisez les clés de test sinon utilisez les clés de production et spécifiez le mode en remplaçant"test"par"live"dans le code ci-dessus.
Pour plus de détails sur le passage en production cliquez ici.
Vous pouvez configurer les informations de votre service/activité/entreprise comme illustré ci-dessous. PayDunya utilise ces paramètres afin de configurer les informations qui s'afficheront sur la page de paiement, les factures PDF et les reçus imprimés.
Vous pouvez inclure également ces informations au niveau du fichier de configuration globale.
{info.fa-lightbulb-o}
Pour la configuration des informations de votre service/entreprise, seul le nom est requis, toutes les autres informations sont optionnelles.
//Configuration des informations de votre service/entreprise
Paydunya_Checkout_Store::setName("Magasin Chez Sandra"); // Seul le nom est requis
Paydunya_Checkout_Store::setTagline("L'élégance n'a pas de prix");
Paydunya_Checkout_Store::setPhoneNumber("336530583");
Paydunya_Checkout_Store::setPostalAddress("Dakar Plateau - Etablissement kheweul");
Paydunya_Checkout_Store::setWebsiteUrl("http://www.chez-sandra.sn");
Paydunya_Checkout_Store::setLogoUrl("http://www.chez-sandra.sn/logo.png");
//Configuration des informations de votre service/entreprise
\Paydunya\Checkout\Store::setName("Magasin Chez Sandra"); // Seul le nom est requis
\Paydunya\Checkout\Store::setTagline("L'élégance n'a pas de prix");
\Paydunya\Checkout\Store::setPhoneNumber("336530583");
\Paydunya\Checkout\Store::setPostalAddress("Dakar Plateau - Etablissement kheweul");
\Paydunya\Checkout\Store::setWebsiteUrl("http://www.chez-sandra.sn");
\Paydunya\Checkout\Store::setLogoUrl("http://www.chez-sandra.sn/logo.png");
L'IPN correspond à l'URL du fichier sur lequel vous souhaitez recevoir les informations de la transaction de paiement pour un éventuel traitement en backoffice. PayDunya utilise cette URL afin de vous envoyer instantanément, par requête POST, les informations relatives à la transaction de paiement.
{info.fa-lightbulb-o}
Il existe deux façons de configurer l'URL de notification instantanée de paiement: soit en vous rendant dans votre compte PayDunya au niveau des informations de configuration de votre application ou soit directement dans votre code. L'utilisation de la seconde option vous offre les deux possibilités ci-dessous.
Cette instruction devra être incluse au niveau de la configuration de votre service/activité.
Paydunya_Checkout_Store::setCallbackUrl("http://magasin-le-choco.com/callback_url.php");
\Paydunya\Checkout\Store::setCallbackUrl("http://magasin-le-choco.com/callback_url.php");{warning}
Cette configuration écrasera les paramètres globaux précédants si ceux-ci étaient définis.
$invoice->setCallbackUrl("http://magasin-le-choco.com/callback_url.php");{info.fa-lightbulb-o}
La confirmation du paiement par le client retourne la structure ci-dessous contenant les détails du client, l'URL de sa
facture en version PDFet unhashpermettant de vérifier que les données reçues proviennent bien de nos serveurs.
array (
'data' =>
array (
'response_code' => '00',
'response_text' => 'Transaction Found',
'hash' => '8c6666a27fe5daeb76dae6abc7308a557dca5be1bda85dfe5d81fa330cdc0bc3c4b37765fe5d2cc36aa2ba0f9284226a80f5488d14740fa70769d6079a179406',
'invoice' =>
array (
'token' => 'test_jkEdPY8SuG',
'items' =>
array (
'item_0' =>
array (
'name' => 'Chaussures Croco',
'quantity' => '3',
'unit_price' => '10000',
'total_price' => '30000',
'description' => 'Chaussures faites en peau de crocrodile authentique qui chasse la pauvreté',
),
'item_1' =>
array (
'name' => 'Chemise Glacée',
'quantity' => '1',
'unit_price' => '5000',
'total_price' => '5000',
'description' => '',
),
),
'taxes' =>
array (
'tax_0' =>
array (
'name' => 'TVA (18%)',
'amount' => '6300',
),
'tax_1' =>
array (
'name' => 'Livraison',
'amount' => '1000',
),
),
'token': 'test_Jh2T8skw1j',
'total_amount' => '42300',
'description' => 'Paiement de 42300 FCFA pour article(s) achetés sur Magasin le Choco',
),
'custom_data' =>
array (
'categorie' => 'Jeu concours',
'periode' => 'Noël 2015',
'numero_gagnant' => '5',
'prix' => 'Bon de réduction de 50%',
),
'actions' =>
array (
'cancel_url' => 'http://magasin-le-choco.com/cancel_url.aspx',
'callback_url' => 'http://magasin-le-choco.com/callback_url.aspx',
'return_url' => 'http://magasin-le-choco.com/return_url.aspx',
),
'mode' => 'test',
'status' => 'completed',
'customer' =>
array (
'name' => 'Alioune Faye',
'phone' => '774563209',
'email' => '[email protected]',
),
'receipt_url' => 'https://paydunya.com/sandbox-checkout/receipt/pdf/test_jkEdPY8SuG.pdf',
),
)
{info.fa-lightbulb-o}
Le hash renvoyé par PayDunya est le hash de votre MasterKey (clé principale). Ce hash vous permettra de vous assurer que les données que vous avez reçues proviennent de nos serveurs. L'algorithme utilisé pour obtenir le hash est du
SHA-512. Dans la réponse attendue un message d'échec est renseigné dans le noeudfail_reasonseulement pour les transactions parcarte bancaires échouéesouannulées.
PayDunya Fait une requête Post de type application/x-www-form-urlencoded sur votre endpoint de callback et poste un tableau de données contenant les informations du paiement. Vous devez utiliser de ce part la clé"data"avant de récupérer un noeud. La strucutre renvoyée se trouve sous l'index"data". Il faut aussi observer que la structure de la réponse que vous recevez est un tableau.
Par exemple pour récupérer le statut du paiement, le nom du client et le hash, voici le code à excécuter :
$status = $_POST['data']['status'];$amount = $_POST['data']['invoice']['total_amount'];
$hash = $_POST['data']['hash'];{info.fa-lightbulb-o}
Le hash renvoyé par PayDunya est le hash de votre MasterKey (clé principale). Ce hash vous permettra de vous assurer que les données que vous avez reçu proviennent de nos serveurs. L'algorithme de hashage utilisé ici est le
SHA-512
{info.fa-lightbulb-o}
Hashez votre clé principale et comparez le résultat au hash reçu par IPN.
try {
//Prenez votre MasterKey, hashez la et comparez le résultat au hash reçu par IPN
if($_POST['data']['hash'] === hash('sha512', "VOTRE_CLE_PRINCIPALE")) {
if ($_POST['data']['status'] == "completed") {
//Faites vos traitements backoffice ici...
}
} else {
die("Cette requête n'a pas été émise par PayDunya");
}
} catch(Exception $e) {
die();
}
{info.fa-lightbulb-o}
Ne jamais mettre en clair vos clés d'API dans un fichier de votre code source, utilisez à la place par exemple des variables d'environnement.
Dans le fichier du code source qui doit effectuer l'action procédez ainsi si vous souhaitez rediriger vos clients vers notre site Web afin qu'il puisse achever le processus de paiement:
$invoice = new Paydunya_Checkout_Invoice();$invoice = new \Paydunya\Checkout\CheckoutInvoice();
l est important de savoir que les éléments de facture sont essentiellement utilisés à des fins de présentation sur la page de paiement. PayDunya n'utilisera en aucun cas l'un des montants déclarés pour facturer le client. Pour ce faire, vous devez explicitement utiliser la méthode setTotalAmount de l'API afin de préciser le montant exact à facturer au client.
//A insérer dans le fichier du code source qui doit effectuer l'action
/* L'ajout d'éléments à votre facture est très basique.
Les paramètres attendus sont nom du produit, la quantité, le prix unitaire,
le prix total et une description optionelle. */
$invoice->addItem("Chaussures Croco", 3, 10000, 30000, "Chaussures faites en peau de crocrodile authentique qui chasse la pauvreté");
$invoice->addItem("Chemise Glacée", 1, 5000, 5000);
{info.fa-lightbulb-o}
Vous pouvez de manière optionelle définir une description générale de facture qui sera utilisée dans les cas où vous avez besoin d'inclure des informations supplémentaires à votre facture.
$invoice->setDescription("Optional Description");PayDunya s'attend à ce que vous préciser le montant total de la facture du client. Ce sera ce montant qui sera facturé à votre client. Nous considérons que vous auriez déjà fait tous les calculs au niveau de votre serveur avant de fixer ce montant.
{info.fa-lightbulb-o}
PayDunya n'effectuera pas de calculs au niveau de ses serveurs. Le montant total de la facture fixé à partir de votre serveur sera celui que PayDunya utilisera pour facturer votre client.
$invoice->setTotalAmount(42300);Le service de "Paiement Avec Redirection" de PayDunya vous permet de créer une facture et de rediriger votre client vers notre plateforme afin qu'il puisse achever le processus de paiement. Nous vous recommandons d'utiliser l'API de "Paiement Avec Redirection" car elle est la plus adaptée dans 99% des cas. L'avantage principal de cette option est que les clients peuvent choisir de payer à partir d'une variété d'options de paiement disponibles sur notre plateforme. De plus, si une nouvelle option est rajoutée dans le futur, celle-ci apparaitra directement sur la page de paiement sans que vous ayez à modifier quoi que ce soit au niveau de votre code source.
Après avoir rajouté des articles à votre facture et configurer le montant total de la facture, vous pouvez rediriger votre client vers la page de paiement en appelant la méthode create depuis votre objet facture $invoice. Veuillez s'il vous plaît noter que la méthode $invoice->create() retourne un booléen (true ou false) selon le fait que la facture ait été créée avec succès ou non. Cela vous permet de mettre une instruction if - else et gérer le résultat comme bon vous semble.
//A insérer dans le fichier du code source qui doit effectuer l'action
// Le code suivant décrit comment créer une facture de paiement au niveau de nos serveurs,
// rediriger ensuite le client vers la page de paiement
// et afficher ensuite son reçu de paiement en cas de succès.
if($invoice->create()) {
header("Location: ".$invoice->getInvoiceUrl());
}else{
echo $invoice->response_text;
}Cette option s'avère très intéressante si vous souhaitez créer votre propre solution de paiement par dessus celle de PayDunya ou si vous devez reverser un certain pourcentage à chaque vente (dans le cas d'une marketplace par exemple). L'argent est redistribué sur les différents comptes PayDunya des destinataires et le service n'est pas facturé.
Vous pouvez transférer des fonds vers d'autres comptes clients PayDunya à partir de votre compte via l'API de Paiement Et Redistribution (PER). Pour des raisons de sécurité, vous devez explicitement activer l'option de Paiement Et Redistribution (PER) dans la configuration de votre intégration/application en vous rendant dans votre compte PayDunya. Vous pouvez toujours activer ou désactiver le service de Paiement Et Redistribution (PER) en mettant à jour la configuration de votre intégration/application en vous rendant dans votre compte PayDunya.
//A insérer dans le fichier du code source qui doit effectuer l'action
$direct_pay = new Paydunya_DirectPay();
if ($direct_pay->creditAccount("EMAIL_OU_NUMERO_MOBILE_DU_CLIENT_PAYDUNYA", "MONTANT_A_TRANSFERER")) {
echo $direct_pay->description;
echo $direct_pay->response_text;
echo $direct_pay->transaction_id;
}else{
echo $direct_pay->response_text;
}Vous pouvez ajouter des informations relatives aux taxes appliquées au niveau de la page de paiement. Ces informations seront ensuite affichées sur la page de paiement, les factures PDF et les reçus imprimés, les reçus électroniques.
//A insérer dans le fichier du code source qui doit effectuer l'action// Les paramètres sont l'intitulé de la taxe et le montant de la taxe.
$invoice->addTax("TVA (18%)", 6300);
$invoice->addTax("Livraison", 1000);
Si vous avez besoin d'ajouter des données supplémentaires à vos informations de requête de paiement à des fins d'utilisation ultérieure, nous vous offrons la possibilité de sauvegarder des données personnalisées sur nos serveurs et de les récupérer une fois le paiement réussi.
{info.fa-lightbulb-o}
Les données personnalisées ne sont affichées nulle part sur la page de paiement, les factures/reçus, les téléchargements et impressions. Elles sont uniquement récupérées à l'aide de notre action de callback
confirmau niveau de l'API.
//A insérer dans le fichier du code source qui doit effectuer l'action
// Les données personnalisées vous permettent d'ajouter des données supplémentaires à vos informations de facture
// que pourrez récupérer plus tard à l'aide de notre action de callback Confirm
$invoice->addCustomData("categorie", "Jeu concours");
$invoice->addCustomData("periode", "Noël 2015");
$invoice->addCustomData("numero_gagnant", 5);
$invoice->addCustomData("prix","Bon de réduction de 50%");Par défaut, les moyens de paiement activés au niveau de la configuration de votre intégration seront tous affichés sur la page de paiement pour l'ensemble de vos factures.
Si toutefois vous souhaitez resteindre la liste des moyens de paiements à afficher sur la page de paiement d'une facture donnée, nous vous offrons la possibilité de le faire en utilisant les méthodes addChannel et addChannels.
Pour obtenir les noms des opérateurs à attribuer comme valeur à la clé channels, veuillez consulter ce lien qui liste les différents opérateurs disponibles.
# Ajout des moyens de paiement de manière individuelle
$invoice->addChannel('free-money-senegal')
$invoice->addChannel('card')
# Ajout de plusieurs moyens de paiement à la fois
$invoice->addChannels(['card', 'wave-senegal','orange-money-senegal'])Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.
{info.fa-lightbulb-o}
Il existe deux façons de configurer l'URL d'annulation de commande: soit de manière globale au niveau des informations de configuration de votre application ou soit par commande.
{warning}
L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.
Cette instruction devra être incluse au niveau de la configuration de votre service/activité.
// Cas d'une installation manuelle
Paydunya_Checkout_Store::setCancelUrl("http://magasin-le-choco.com/cancel_url.php");
// Cas d'une installation via Composer
\Paydunya\Checkout\Store::setCancelUrl("http://magasin-le-choco.com/cancel_url.php");{warning}
Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.
$invoice->setCancelUrl("http://magasin-le-choco.com/cancel_url.php");PayDunya fait un excellent travail de gestion de téléchargements et d'impressions de reçus de paiements après que votre client ait effectué avec succès le paiement de sa commande. Cependant, il peut y avoir des cas où vous souhaiteriez rediriger vos clients vers une autre URL après qu'ils aient réussi le paiement de leur commande. La configuration ci-dessous vient répondre à ce besoin.
{info.fa-lightbulb-o}
PayDunya rajoutera
?token=invoice_tokenà votre URL. Nous expliquerons comment utiliser ce token dans le chAPItre suivant.
Cette instruction devra être incluse au niveau de la configuration de votre service/activité
// Cas d'une installation manuelle
Paydunya_Checkout_Store::setReturnUrl("http://magasin-le-choco.com/return_url.php");
// Cas d'une installation via Composer
\Paydunya\Checkout\Store::setReturnUrl("http://magasin-le-choco.com/return_url.php");
{warning}
L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.
$invoice->setReturnUrl("http://magasin-le-choco.com/return_url.php");Notre API vous permet de vérifier le statut de toutes les transactions de paiement en utilisant le token de facture. Vous pouvez donc conserver votre token de facture et l'utiliser pour vérifier le statut de paiement de ladite facture. Le statut d'une facture peut être soit pending (en attente), cancelled (annulé) ou completed (complété) en fonction de si oui ou non le client a réglé la facture.
{info.fa-lightbulb-o}
Cette option s'avère toutefois adaptée pour les paiements PAR dans la mesure où cela vous permettrait par exemple de connaitre le statut de paiement de votre facture même si le client se trouve toujours sur notre page de paiement.
//A insérer dans le fichier du code source qui doit effectuer l'action
// PayDunya rajoutera automatiquement le token de la facture sous forme de QUERYSTRING "token"
// si vous avez configuré un "return_url" ou "cancel_url".
// Récupérez donc le token en pur PHP via $_GET['token']
$token = $_GET['token'];
$invoice = new Paydunya_Checkout_Invoice();
if ($invoice->confirm($token)) {
// Récupérer le statut du paiement
// Le statut du paiement peut être soit completed, pending, cancelled
echo $invoice->getStatus();
// Vous pouvez récupérer le nom, l'adresse email et le
// numéro de téléphone du client en utilisant
// les méthodes suivantes
echo $invoice->getCustomerInfo('name');
echo $invoice->getCustomerInfo('email');
echo $invoice->getCustomerInfo('phone');
// Les méthodes qui suivent seront disponibles si et
// seulement si le statut du paiement est égal à "completed".
// Récupérer l'URL du reçu PDF électronique pour téléchargement
echo $invoice->getReceiptUrl();
// Récupérer n'importe laquelle des données personnalisées que
// vous avez eu à rajouter précédemment à la facture.
// Merci de vous assurer à utiliser les mêmes clés que celles utilisées
// lors de la configuration.
echo $invoice->getCustomData("categorie");
echo $invoice->getCustomData("periode");
echo $invoice->getCustomData("numero_gagnant");
echo $invoice->getCustomData("prix");
// Vous pouvez aussi récupérer le montant total spécifié précédemment
echo $invoice->getTotalAmount();
}else{
echo $invoice->getStatus();
echo $invoice->response_text;
echo $invoice->response_code;
}//A insérer dans le fichier du code source qui doit effectuer l'action
// PayDunya rajoutera automatiquement le token de la facture sous forme de QUERYSTRING "token"
// si vous avez configuré un "return_url" ou "cancel_url".
// Récupérez donc le token en pur PHP via $_GET['token']
$token = $_GET['token'];
$invoice = new \Paydunya\Checkout\CheckoutInvoice();
if ($invoice->confirm($token)) {
// Récupérer le statut du paiement
// Le statut du paiement peut être soit completed, pending, cancelled
echo $invoice->getStatus();
// Vous pouvez récupérer le nom, l'adresse email et le
// numéro de téléphone du client en utilisant
// les méthodes suivantes
echo $invoice->getCustomerInfo('name');
echo $invoice->getCustomerInfo('email');
echo $invoice->getCustomerInfo('phone');
// Les méthodes qui suivent seront disponibles si et
// seulement si le statut du paiement est égal à "completed".
// Récupérer l'URL du reçu PDF électronique pour téléchargement
echo $invoice->getReceiptUrl();
// Récupérer n'importe laquelle des données personnalisées que
// vous avez eu à rajouter précédemment à la facture.
// Merci de vous assurer à utiliser les mêmes clés que celles utilisées
// lors de la configuration.
echo $invoice->getCustomData("categorie");
echo $invoice->getCustomData("periode");
echo $invoice->getCustomData("numero_gagant");
echo $invoice->getCustomData("prix");
// Vous pouvez aussi récupérer le montant total spécifié précédemment
echo $invoice->getTotalAmount();
}else{
echo $invoice->getStatus();
echo $invoice->response_text;
echo $invoice->response_code;
}