Introduction

Cette page d'introduction vous montre les étapes à suivre et à valider avant d'intégrer nos APIs.

1. Génération de vos clés d'API

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 la marche à suivre :

  • Vous devez d'abord avoir un compte PayDunya Business activé. Créez-en un si ce n'est pas encore le cas.
  • Connectez-vous à votre compte et cliquez sur Intégration 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 test de paiements au niveau de l'option du formulaire Activer le mode production.
  • Vos clés API de test et de production seront automatiquement générées après que vous ayez spécifié les détails de votre application au niveau du formulaire.

2. Création d'un compte client fictif (pour les tests)

Un compte fictif ou compte de test vous permet de simuler des paiements lors de vos tests d'intégration avec nos APIs. Vous pouvez spécifier le nom, l'adresse email et le solde du client fictif. PayDunya retire du solde du client fictif le montant des factures de test lorsque les paiements sont effectués.

À noter que vous avez la possibilité de créer plusieurs comptes fictifs et de les recharger manuellement à tout moment.

ATTENTION: Il est fortement recommandé de procéder à des tests de paiements avant de passer en mode production car cela vous permet de vous assurer que tout fonctionne comme vous le souhaitez.

3. Données internes fictives

C'est un outil de débogage qui vous permet de voir les informations transmises à notre serveur lorsque vous effectuez vos tests de paiements. Pour avoir accès à ces données :

  • Connectez-vous à votre compte et cliquez sur Intégration API au niveau du menu à gauche.
  • Cliquer sur l'onglet Données internes fictives afin d'avoir la liste des données internes des paiements de test.
  • Cliquez sur le lien Détails situé à droite de chaque donnée interne présente au niveau de la liste pour plus d'informations.

4. Passage en mode Production (Transactions réelles)

Après vous être assuré que votre intégration PayDunya fonctionne en mode test, vous pouvez passer en mode production en mettant à jour les informations de configuration de l'application concernée.

ATTENTION: Il ne s'agit plus là de paiements tests mais de paiements réels! Après chaque paiement réussi, PayDunya génère une facture en format PDF qui est envoyée au client dans sa boite mail.
  • Connectez-vous à votre compte et cliquez sur Intégration API au niveau du menu à gauche.
  • Sous l'onglet Applications, cliquer sur le lien Détails de l'application concernée.
  • Descendez tout en bas et cliquez sur le bouton Modifier la configuration
  • Choisissez Oui, l'application est prête au niveau de l'option Activer le mode production du formulaire de mise à jour.
  • Rappelez-vous de bien remplacer les clés API de test par celles de production dans votre application.
  • Spécifier le mode live au niveau de l'API client.

Vous pouvez maintenant intégrer le Client API de votre choix :

Définitions

Vous trouverez ici les définitions de tous les termes dont vous pourriez avoir besoin afin de comprendre la documentation de nos APIs.

1. AppDunya

Il s’agit d’un ensemble de clés qui permettent d’identifier et d’authentifier votre site web ou application mobile lors de la connexion aux serveurs de PayDunya. Créez une AppDunya pour chacun de vos sites web ou application au niveau du dashboard (tableau de bord) de votre compte PayDunya.

2. PAR

Il s’agit de l’API de "Paiement Avec Redirection (PAR)" de PayDunya qui vous permet de rediriger votre client sur la plateforme PayDunya afin qu'il puisse achever le processus de paiement. Nous recommandons d'utiliser l'API de "Paiement Avec Redirection (PAR)" 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.

3. PSR

Il s’agit de l’API de "Paiement Sans Redirection (PSR)" de PayDunya qui vous permet de faire payer votre client directement sur votre site web ou application mobile. La procédure se déroule en deux (2) étapes : le client saisi d’abord son email ou numéro de téléphone et vous envoyez cette donnée au serveur de PayDunya, ensuite PayDunya envoie un code par SMS au client et il saisit le code sur votre interface. L’inconvénient de cette API est que le client est obligé d’avoir un compte PayDunya crédité. Il ne pourra pas par exemple payer avec Orange Money, Joni Joni, Tigo Cash...

4. PER

Il s’agit de l’API de "Paiement Et Redistribution (PER)" de PayDunya qui vous permet de faire des transferts d’argent vers d’autres comptes PayDunya. Cette API est utile pour les marketplaces ou services d’intermédiation qui perçoivent un pourcentage sur toutes les ventes effectuées par les fournisseurs sur leurs sites web. Cette API doit être associé au PAR ou PSR. Le paiement est effectué avec le PAR ou PSR et le partage est effectué avec le PER.

5. IPN

Il s’agit de "Instant Payment Notification (IPN)" ou Notification Instantanée de Paiement. Ce service envoie l’ensemble des données réponse attendues sur un endpoint (URL vers un fichier sur votre serveur) que vous déclarez afin de pourvoir traiter ces données en backoffice. Il est très utile pour confirmer les paiements qui ne se font pas de manière instantanée à cause d’une latence des serveurs ou du réseau mobile ou du réseau internet ou encore à cause de temps que met le client à confirmer le paiement sur son téléphone. Quoi qu’il en soit l'IPN vous permet de vous assurer que le statut d’un paiement est confirmé par nos serveurs.

HTTP/JSON

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. APIs

PayDunya vous propose trois (3) APIs :

  • deux (2) APIs de paiement qui vous permettent de vous faire payer (PAR et PSR);
  • et une troisième API (PER) de redistribution qui vous permet de partager l'argent des paiements avec vos fournisseurs.

Vous devez intégrer l'une des APIs de paiement et celle de redistribution si vous desirez partager l'argent des paiements avec des partenaires.

Notre API HTTP est exclusivement basée sur le format d'échange de données JSON. Toutes les réponses aux requêtes HTTP POST/GET depuis/vers notre API reposent sur des objets JSON.

Tous les objets JSON retournés au niveau d'une réponse contiennent au minimum les nœuds response_code et response_text. Le nœud response_code représente le code technique de la réponse, et le noeud response_text fournit quant à lui des explications sur la réponse. Votre intégration doit fortement s'appuyer sur ces nœuds afin de fonctionner correctement.

NOTE: Toutes les réponses de succès renvoient un objet JSON contenant un nœud response_code égal à 00.

~ Paiement Avec Redirection (PAR)

Le service de "Paiement Avec Redirection (PAR)" de PayDunya vous permet 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 (PAR)" 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.

Endpoints API

#Endpoint de test
https://app.paydunya.com/sandbox-api/v1/checkout-invoice/create

#Endpoint de production
https://app.paydunya.com/api/v1/checkout-invoice/create
Requête POST HTTP

curl -H "Content-Type: application/json" \
-H "PAYDUNYA-MASTER-KEY: wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW" \
-H "PAYDUNYA-PRIVATE-KEY: test_private_rMIdJM3PLLhLjyArx9tF3VURAF5" \
-H "PAYDUNYA-TOKEN: IivOiOxGJuWhc5znlIiK" \
-X POST -d '{"invoice": {"total_amount": 5000, "description": "Chaussure VANS dernier modèle"},"store": {"name": "Magasin le Choco"}}' \
"https://app.paydunya.com/sandbox-api/v1/checkout-invoice/create"
Réponse attendue
{
    "response_code":"00",
    "response_text":"https://app.paydunya.com/sandbox-checkout/invoice/test_RHICF0HboN",
    "description":"Checkout Invoice Created",
    "token":"test_RHICF0HboN"
}

Pour recevoir la structure complète des informations de paiements, vous pouvez faire une requête avec le token reçu dans la réponse ci-dessus (voir la démarche à suivre au point Vérification de l'état du paiement).

~ Paiement Sans Redirection (PSR)

Le service de "Paiement Sans Redirection (PSR)" vous permet de facturer vos clients PayDunya directement sur votre site web ou votre application mobile. Le processus d'exécution du service PSR se fait en deux(2) étapes. Pensez à créer un compte client fictif PayDunya pour tester l'API PSR.

# Etape 1 (Demande d'un token PSR)

À cette étape, vous devez recupérer l'adresse email ou le numéro mobile du client et le donner comme valeur à account_alias de opr_data.

"opr_data" :{"account_alias" : "774563209"}

Astuce

Vous pouvez récupérer ces informations par exemple grâce à un formulaire que vous présenterez au client.

Endpoints API

#Endpoint de test
https://app.paydunya.com/sandbox-api/v1/opr/create

#Endpoint de production
https://app.paydunya.com/api/v1/opr/create
Requête POST HTTP

curl -H "Content-Type: application/json" \
-H "PAYDUNYA-MASTER-KEY: wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW" \
-H "PAYDUNYA-PRIVATE-KEY: test_private_rMIdJM3PLLhLjyArx9tF3VURAF5" \
-H "PAYDUNYA-TOKEN: IivOiOxGJuWhc5znlIiK" \
-X POST -d '{"invoice_data" : {"invoice": {"total_amount": 5000, "description": "Chaussure VANS dernier modèle"},"store": {"name": "Magasin le Choco"}},"opr_data" :{"account_alias" : "774563209"}}' \
"https://app.paydunya.com/sandbox-api/v1/opr/create"
Réponse attendue

La validation réussie de la première étape retourne un objet JSON contenant un noeud token. Votre application devra enregistrer ledit token afin de l'utiliser à la deuxième étape ou étape finale du processus PSR. À ce stade, le client PayDunya reçoit également un code de confirmation par e-mail et par SMS. À noter que les SMS sont uniquement envoyés pour les transactions réelles.

{
    "response_code":"00",
    "response_text":"PSR-test_oAe8AB",
    "description":"Onsite Payment Request successfully sent.",
    "token":"PSR-test_oAe8AB",
    "invoice_token":"test_eSVLdP8Fas"
}
# Etape 2 (Facturation PSR)

Cette dernière étape nécessite votre token PSR ainsi que le code de confirmation que nous avons envoyé au client.

Endpoints API

#Endpoint de test
https://app.paydunya.com/sandbox-api/v1/opr/charge

#Endpoint de production
https://app.paydunya.com/api/v1/opr/charge
Requête POST HTTP

curl -H "Content-Type: application/json" \
-H "PAYDUNYA-MASTER-KEY: wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW" \
-H "PAYDUNYA-PRIVATE-KEY: test_private_rMIdJM3PLLhLjyArx9tF3VURAF5" \
-H "PAYDUNYA-TOKEN: IivOiOxGJuWhc5znlIiK" \
-X POST -d '{"token" : "PSR-test_oAe8AB", "confirm_token" : "5838"}' \
"https://app.paydunya.com/sandbox-api/v1/opr/charge"
Réponse attendue

La validation réussie de cette dernière étape retourne un objet JSON contenant les informations sur le client et l'URL de sa facture PayDunya en version PDF.

{
    "response_code": "00",
    "response_text": "Payment received",
    "description": "Customer has been charged successfully",
    "invoice_data": {
        "invoice": {
            "total_amount": 5000,
            "description": "Chaussure VANS dernier modèle"
        },
        "mode": "test",
        "status": "completed",
        "customer": {
            "name": "Alioune Faye",
            "phone": "774563209",
            "email": "aliounefaye@gmail.com"
        },
        "receipt_url": "https://app.paydunya.com/sandbox-checkout/receipt/pdf/test_eSVLdP8Fas.pdf"
    }
}

~ Paiement Et Redirection (PER)

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. L'argent est reçu sur les comptes 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 Redirection (PER). Pour des raisons de sécurité, vous devez explicitement activer l'option de Paiement Et Redirection (PER) dans la configuration de votre intégration/application en vous connectant à votre compte Business PayDunya. Vous pouvez toujours activer ou désactiver le Paiement Et Redirection (PER) en mettant à jour la configuration de votre intégration/application en vous connectant à votre compte Business PayDunya.

Endpoints API

#Endpoint de test
https://app.paydunya.com/sandbox-api/v1/direct-pay/credit-account

#Endpoint de production
https://app.paydunya.com/api/v1/direct-pay/credit-account
Requête POST HTTP

curl -H "Content-Type: application/json" \
-H "PAYDUNYA-MASTER-KEY: wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW" \
-H "PAYDUNYA-PRIVATE-KEY: test_private_rMIdJM3PLLhLjyArx9tF3VURAF5" \
-H "PAYDUNYA-TOKEN: IivOiOxGJuWhc5znlIiK" \
-X POST -d '{ "account_alias" : "771111111", "amount" : 4500 }' \
"https://app.paydunya.com/sandbox-api/v1/direct-pay/credit-account"
Réponse attendue
{
    "response_code":"00",
    "response_text":"Transaction completed successfully",
    "description":"Success! Amount of 4500 FCFA has been transfered to Sandbox Account BOUBACAR BAH",
    "transaction_id":"TEST000001"
}

3. Configurations de base des informations à envoyer au serveur PayDunya

~ Structure JSON complète des données à envoyer

Voici présentée ci-dessous, la structure complète de l'objet JSON de facturation PayDunya. La plupart des éléments sont optionnels, mais prenez l'habitude de tous les fournir car cela vous offrira beaucoup plus de flexibilité.

Les nœuds JSON obligatoires pour la soumission d'une requête HTTP POST de paiement de facture vers nos Endpoints API sont : le nœud racine invoice et son noeud enfant total_amount ainsi que le nœud racine store et son noeud enfant name.

{
  "invoice": {
    "items": {

    },
    "taxes": {

    },
    "total_amount": 5000,
    "description": ""
  },
  "store": {
    "name": "Magasin le Choco",
    "tagline": "",
    "postal_address": "",
    "phone": "",
    "logo_url": "",
    "website_url": ""
  },
  "custom_data": {

  },
  "actions": {
    "cancel_url": "",
    "return_url": "",
    "callback_url": ""
  }
}

~ Ajout d'articles ou d'éléments sur la facture PayDunya (facultatif)

Référez-vous à la structure complète JSON afin de savoir de manière exacte où insérer la structure suivante. Les "items" sont utilisés pour afficher au client sur la page de paiement la liste des articles qu'il a commandé. PayDunya n'utilisera en aucun cas l'un des montants déclarés dans "items" pour facturer le client.

"items": {
    "item_0": {
      "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": {
      "name": "Chemise Glacée",
      "quantity": 1,
      "unit_price": "5000",
      "total_price": "5000",
      "description": ""
    }
}

~ Ajout de taxes (facultatif)

Si vous désirez afficher sur la facture PayDunya les taxes que vous appliquez (TVA, Frais de livraison...) vous pouvez le faire en utilisant le noeud JSON taxes comme illustré ci-dessous.

"taxes": {
  "tax_0": {
    "name": "TVA (18%)",
    "amount": 6300
  },
  "tax_1": {
    "name": "Livraison",
    "amount": 1000
  }
}

~ Ajout de données personnalisées (facultatif)

Si vous avez besoin d'ajouter des données supplémentaires (par exemple pour un jeu concours, vous pouvez enregistrer des informations sur chaque gagnant) à des fins d'utilisation ultérieure, nous vous offrons la possibilité de sauvegarder ces données sur nos serveurs et de pouvoir les récupérer une fois le paiement réussi.

NOTE: Les données personnalisées ne sont affichées ni sur la page de paiement, ni sur les factures/reçus, ni sur les téléchargements et impressions. Elles sont uniquement récupérées à l'aide de notre action de callback confirm au niveau de l'API.
Exemple 1
"custom_data": {
  "categorie": "Jeu concours",
  "periode":  "Noël 2015",
  "numero_gagnant": 5,
  "prix" : "Bon de réduction de 50%"
}
Exemple 2
"custom_data": {
  "phone_brand": "Nokia",
  "IMEI": "72892821010728",
  "model": "Luna"
}

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après qu'ils aient cliqué sur le bouton "Annuler le paiement".

"actions": {
  "cancel_url": "http://www.magasin-le-choco.com/cancel_url.php"
}

~ Configuration d'une URL de redirection après confirmation de paiements

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après qu'ils aient réussi le paiement de leur commande.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquons comment utiliser ce token au niveau de la documentation des différents clients API (PHP, Java, .NET, Ruby, Python, Node JS).
"actions": {
  "return_url": "http://www.magasin-le-choco.com/return_url.php"
}

~ Configuration de l'IPN (Instant Payment Notification)

Il se peut que pour des raisons x ou y, que la confirmation de paiement ne soit pas instantanée (par exemple le temps que le client tape son code secret sur son téléphone ou le temps de latence du réseau téléphonique), l'IPN vous permet de recevoir instantanément les informations de la transaction au moment où le paiement est confirmé.

L'IPN correspond à l'URL d'un fichier sur votre serveur sur lequel vous souhaitez recevoir les informations de la transaction de paiement, ces informations sont à traiter en backoffice. PayDunya utilise cette URL afin de vous envoyer instantanément, par requête POST, les informations relatives à la transaction de paiement.

"actions": {
  "callback_url": "http://www.magasin-le-choco.com/callback_url.php"
}

La validation réussie de la transaction de paiement retourne la structure ci-dessous contenant les informations sur le client, l'URL de sa facture PayDunya en version PDF et également un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue :
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NOTE: 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.
Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé "data" avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index "data").

4. Vérification de l'état du paiement

Lorsque vous faites une requête de Paiement Avec Redirection (PAR) ou une requête de Paiement Sans Redirection (PSR), PayDunya retourne un objet JSON contenant un noeud représentant le token de facture. Vous pouvez utiliser la valeur de ce token afin de vérifier le statut de paiement de votre 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.

NOTE: Rappelez-vous de toujours rajouter la valeur de votre token de facture aux endpoints.
Endpoints API
#Endpoint de test
https://app.paydunya.com/sandbox-api/v1/checkout-invoice/confirm/[invoice_token]

#Endpoint de production
https://app.paydunya.com/api/v1/checkout-invoice/confirm/[invoice_token]
Requête GET HTTP
curl -H "Content-Type: application/json" \
-H "PAYDUNYA-MASTER-KEY: wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW" \
-H "PAYDUNYA-PRIVATE-KEY: test_private_rMIdJM3PLLhLjyArx9tF3VURAF5" \
-H "PAYDUNYA-TOKEN: IivOiOxGJuWhc5znlIiK" \
https://app.paydunya.com/sandbox-api/v1/checkout-invoice/confirm/test_P8FaseSVLd
Réponse attendue
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "cancel_url": "http://magasin-le-choco.com/cancel_url.php",
    "callback_url": "http://magasin-le-choco.com/callback_url.php",
    "return_url": "http://magasin-le-choco.com/return_url.php"
  },
  "mode": "test",
  "status": "completed",
  "customer": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NOTE: 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.

Android

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

Cliquez sur paydunya_java_latest.jar pour télécharger la dernière version de notre package JAVA ainsi que ses dépendances. Ajouter par la suite paydunya_java_latest.jar à votre CLASSPATH en suivant les instructions suivantes :

  • Dans votre IDE (Android Studio), cliquez sur Project dans le menu à gauche puis affichez votre application sous forme de projet en sélectionnant Project dans le menu déroulant de la fenêtre qui s'est affiché;
  • Cherchez le dossier libs qui se trouve le dossier app. Copiez le fichier paydunya_java_latest.jar précédement téléchargé et collez le à l'intérieur du dossier libs;
  • Ensuite faites un clic droit sur paydunya_java_latest.jar et cliquez sur Add as Library pour ajouter le plugin PayDunya à la liste des librairies.
Intégration PayDunya sous Android Studio
Intégration PayDunya sous Android Studio

Pour finir, importez toutes les classes du package com.paydunya.neptune dans le ou les fichier(s) où vous souhaitez utiliser la librairie PayDunya:

import com.paydunya.neptune.*;

3. Configuration de base

~ Configuration de l'API

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au niveau de l'application que vous avez créée, récupérez les clés d'API et donnez les en argument au méthodes suivantes:


PaydunyaSetup setup = new PaydunyaSetup();
setup.setMasterKey("wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW");
setup.setPrivateKey("test_private_rMIdJM3PLLhLjyArx9tF3VURAF5");
setup.setPublicKey("test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja");
setup.setToken("IivOiOxGJuWhc5znlIiK");
setup.setMode("test"); // Optionnel. Utilisez cette option pour les paiements tests.
  
NB: Si vous êtes en mode 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.

~ Configuration des informations de votre service/activité/entreprise

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, les reçus imprimés et les téléchargements PDF.

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
PaydunyaCheckoutStore store = new PaydunyaCheckoutStore();
store.setName("Magasin Chez Sandra"); // Seul le nom est requis
store.setTagline("L'élégance n'a pas de prix");
store.setPhoneNumber("336530583");
store.setPostalAddress("Dakar Plateau - Etablissement kheweul");
store.setWebsiteUrl("http://www.chez-sandra.sn");
store.setLogoUrl("http://www.chez-sandra.sn/logo.png");

4. APIs

~ Le service PSR

# Initialisation

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface. Vous envoyez par la suite cette adresse email ou numéro de téléphone à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. À noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.
PaydunyaOnsiteInvoice invoice = new PaydunyaOnsiteInvoice(setup, store);

Procédez ainsi si vous souhaitez accepter des paiements directement au niveau de votre application.

Il est important de remarquer que le constructeur requiert respectivement comme paramètres une instance des classes PaydunyaSetup et PaydunyaCheckoutStore.

# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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.

/* 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("Clavier DELL", 2, 3000, 6000);
invoice.addItem("Ordinateur Lenovo L440", 1, 400000, 400000, "Description optionelle");
invoice.addItem("Casque Logitech", 1, 8000, 8000);
/* 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("Description Optionnelle");
* Configuration du montant total de la facture :

PayDunya s'attend à ce que vous précisez 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.

Note: 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(414000);
# Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Il est nécéssaire d'excécuter la requête PSR en background.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

//Il est nécéssaire d'excécuter la requête PSR en background
import android.os.AsyncTask;
private class MyTask extends AsyncTask {

  private Exception exception;

  @Override
  protected Void doInBackground(String... params){

    String email_ou_numero_du_client_paydunya = params[0];

    try {
      // Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
      if (invoice.create(email_ou_numero_du_client_paydunya)) {
        System.out.println ("Token PSR: " + invoice.getToken());
        System.out.println ("Statut: " + invoice.getStatus());
        System.out.println ("Réponse: " + invoice.getResponseText());
      } else {
        System.out.println("Réponse: " + invoice.getResponseText());
      }

    } catch(Exception e){
      e.printStackTrace();
      this.exception = e;
    }
    return null;

  }

  @Override
  protected void onPostExecute(Void result) {
    // TODO: check this.exception
    // TODO: do something with the feed
    super.onPostExecute(result);
  }

}

Pour exécuter le code précédent en background, rajoutez au niveau de la méthode protected void onCreate la ligne suivante:

new MyTask().execute("EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA");
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Il est nécéssaire d'excécuter la requête de facturation PSR en background.

Une demande de facturation PSR nécessite à la fois le code de confirmation et le token PSR.

//Il est nécéssaire d'excécuter la requête de facturation PSR en background
import android.os.AsyncTask;
private class MyTask extends AsyncTask {

  private Exception exception;

  @Override
  protected Void doInBackground(String... params){

    String token_psr = params[0];
    String code_de_confirmation_du_client = params[1];
    try {

      // Une demande de facturation PSR nécessite à la fois le code de confirmation et le token PSR
      if (invoice.charge(token_psr, code_de_confirmation_du_client)) {
        System.out.println("Statut: " + invoice.getStatus());
        System.out.println("Réponse: " + invoice.getResponseText());
        System.out.println("URL du reçu électronique: " + invoice.getReceiptUrl());
        System.out.println("Nom du client: " + invoice.getCustomerInfo("name"));
        System.out.println("Email du client: " + invoice.getCustomerInfo("email"));
      } else {
        System.out.println("Réponse: " + invoice.getResponseText());
      }

    } catch(Exception e){
      e.printStackTrace();
      this.exception = e;
    }
    return null;

  }

  @Override
  protected void onPostExecute(Void result) {
    // TODO: check this.exception
    // TODO: do something with the feed
    super.onPostExecute(result);
  }

} 

Pour excécuter le code précédent en background, rajoutez au niveau de la méthode protected void onCreate la ligne suivante:

new MyTask().execute("TOKEN_PSR", "CODE_DE_CONFIRMATION_DU_CLIENT");

~ Paiement Et Redistribution (PER)

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.

Il est nécéssaire d'excécuter la requête de facturation PER de Paiement Et Redirection en background.

//Il est nécéssaire d'excécuter la requête PER de Paiement Et Redirection en background
import android.os.AsyncTask;
private class MyTask extends AsyncTask {

  private Exception exception;

  @Override
  protected Void doInBackground(String... params){

    String email_ou_numero_du_client_paydunya = params[0];
    Double montant_a_transferer = Double.valueOf(params[1]);
    try {

      PaydunyaDirectPay direct_pay = new PaydunyaDirectPay(setup);
      if(direct_pay.creditAccount(email_ou_numero_du_client_paydunya, montant_a_transferer)){
        System.out.println("Statut: " + direct_pay.getStatus());
        System.out.println("Description: " + direct_pay.getDescription());
        System.out.println("ID de la Transaction: " + direct_pay.getTransactionId());
      }else{
        System.out.println("Réponse: " + direct_pay.getResponseText());
      }

    } catch(Exception e){
      e.printStackTrace();
      this.exception = e;
    }
    return null;

  }

  @Override
  protected void onPostExecute(Void result) {
    // TODO: check this.exception
    // TODO: do something with the feed
    super.onPostExecute(result);
  }

}

Pour excécuter le code précédent en background, rajoutez au niveau de la méthode protected void onCreate la ligne suivante:

new MyTask().execute("EMAIL_OU_NUMERO_MOBILE_DU_CLIENT_PAYDUNYA", "MONTANT_A_TRANSFERER");

WordPress

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. La passerelle de paiement PayDunya sur WooCommerce/WordPress

PayDunya est un service vous permettant d'effectuer et de recevoir des paiements en ligne via Orange Money, les cartes bancaires VISA/MASTERCARD/GIM, JONI JONI... Afin de vous faciliter l'intégration du service PayDunya sous WordPress, nous avons conçu un plugin WordPress servant de passerelle de paiement WooCommerce pour le service PayDunya.

WooCommerce est l'un des plugins WordPress les plus populaires. C'est un plugin eCommerce extensible qui vous aide à vendre tout ce que vous voulez via votre site web WordPress.

ATTENTION: Avant de passer aux étapes suivantes et installer le plugin WordPress PayDunya,vous devez tout d'abord avoir le plugin WooCommerce installé et activé sur votre site WordPress.

~ Installation Automatique

  • Connectez-vous à votre espace d'administration WordPress.
  • Allez ensuite au niveau de Extensions > Ajouter en vous servant du menu de gauche.
  • Au niveau du champ de recherche, veuillez entrer Woocommerce PayDunya Plugin, puis validez avec la touche Entrée.
  • Au niveau des résultats de recherche, vous devez voir normalement apparaitre WooCommerce PayDunya Plugin. Cliquez sur Installer maintenant afin d'installer le plugin.
  • Une fois l'installation terminée, cliquez pour finir sur Activer l'extension afin d'activer le plugin PayDunya.

~ Installation Manuelle

Cliquez sur paydunya_woocommerce_payment_gateway_latest.zip pour télécharger la dernière version de notre plugin WordPress.

  • Connectez-vous à votre espace d'administration WordPress.
  • Allez ensuite au niveau de Extensions > Ajouter en vous servant du menu de gauche.
  • Cliquez sur le bouton Mettre une extension en ligne présent tout juste en haut.
  • Cliquez ensuite sur Parcourir et choisissez le fichier zip que vous venez de télécharger.
  • Cliquez sur Installer maintenant afin d'installer le plugin.
  • Une fois l'installation terminée, cliquez pour finir sur Activer l'extension afin d'activer le plugin PayDunya.

~ Changement de la devise

Pour configurer la devise BCEAO XOF(FCFA), allez sur WooCommerce > Paramètres en vous servant du menu de gauche.

Au niveau de la section Options devise, choisissez BCEAO XOF(FCFA) comme valeur pour le champ Devise.

3. Configuration du plugin

Pour configurer le plugin WordPress PayDunya, allez sur WooCommerce > Paramètres en vous servant du menu de gauche.

  • Dans le menu à onglets présent tout juste en haut, cliquez sur Commande.
  • Vous devez normalement voir Paydunya dans les options de commande présentes tout juste en bas du menu à onglets.
  • Descendez tout en bas de page jusqu'à atteindre la section Passerelles de Paiement, vous verrez normalement dans la colonne "Passerelle", l'option Payer avec PayDunya. Si vous souhaitez faire du service PayDunya, votre option de paiement principale, déplacez votre curseur au niveau de l'icône "menu burger" (3 traits horizontaux) présente à gauche de "Paiement avec PayDunya" au niveau de la colonne "Passerelle" et faites un glisser-déposer afin de déplacer la passerelle "Paiement avec PayDunya" en première position au niveau de la liste. PayDunya sera dorénavant votre option de paiement de premier choix.
  • Cliquez ensuite sur le lien Paiement avec PayDunya afin de passer à la configuration du plugin.

Les options de configuration sont les suivantes:

  • Activer/Désactiver: Cochez/Décochez cette case afin d'activer/désactiver le module de paiement PayDunya.
  • Titre: Il vous permet préciser le texte que verra le client sur la page de paiement de sa commande. (Il est recommandé de laisser le titre par défaut)
  • Description: Elle vous permet de donner beaucoup plus de détails sur la solution de paiement. (Il est recommandé de laisser la description par défaut).
  • Clé Principale: Entrez la Clé principale fournie par PayDunya lors de la création de votre application.
  • Clé Privée de Production: Entrez la Clé Privée de production fournie par PayDunya lors de la création de votre application.
  • Token de Production: Entrez le Token de production fourni par PayDunya lors de la création de votre application.
  • Clé Privée de Test: Entrez la Clé Privée de test fournie par PayDunya lors de la création de votre application.
  • Token de Test: Entrez le Token de test fourni par PayDunya lors de la création de votre application.
  • Activer le mode test: Cochez cette case si vous êtes encore à l'etape des paiements tests. N'oubliez pas de la décocher une fois que vous serez prêt à accepter des paiements réels.
  • Cliquez sur Enregistrer les changements afin que vos modifications soient prises en compte.

4. Questions Fréquentes

De quoi ai-je besoin pour d'utiliser le plugin WordPress PayDunya?

  1. Vous devez tout d'abord avoir le plugin WooCommerce installé et activé sur votre site WordPress.
  2. Vous devez créer un compte Paydunya afin de pouvoir disposer de clés d'API. Cliquez ici pour suivre notre guide expliquant comment générer vos API d'intégration PayDunya.

PHP

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

~ Installation via Composer

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

~ Installation manuelle

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.

Astuce

Si vous ne savez pas dans quel sous-dossier mettre la librairie PayDunya, nous vous proposons les noms de sous-dossiers suivants: libs, libraries ou encore vendor.

3. Configuration de base

~ Configuration de l'API

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.

* Cas d'une installation manuelle
require('chemin_vers_le_dossier_du_client_php_paydunya/paydunya.php');
* Cas d'une installation via Composer

Si vous avez choisi par contre l'installation via Composer, il vous suffira d'inclure le fichier vendor/autoload.php.

require('vendor/autoload.php');

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au 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

* Cas d'une installation manuelle

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. Utilisez cette option pour les paiements tests.
  
NB: 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.

* Cas d'une installation via Composer

\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. Utilisez cette option pour les paiements tests.
  
NB: 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.

~ Configuration des informations de votre service/activité/entreprise

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.

Pour la configuration des informations de votre service/entreprise, seul le nom est requis, toutes les autres informations sont optionnelles.

* Cas d'une installation manuelle
//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");
* Cas d'une installation via Composer
//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 de l'IPN (Instant Payment Notification)

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.

NOTE: 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.

# Configuration globale de l'URL de notification instantanée de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

* Cas d'une installation manuelle
Paydunya_Checkout_Store::setCallbackUrl("http://magasin-le-choco.com/callback_url.php");
* Cas d'une installation via Composer

  \Paydunya\Checkout\Store::setCallbackUrl("http://magasin-le-choco.com/callback_url.php");
# Configuration de l'URL de notification instantanée de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux précédants si ceux-ci ont déjà été définis.

$invoice->setCallbackUrl("http://magasin-le-choco.com/callback_url.php");

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 PDF et un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue:
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NB: Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé "data" avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index "data").

Par exemple pour récupérer le statut du paiement, le nom du client et le hash, voici le code à excécuter:

Récupération du statut du paiement
$status = $_POST['data']['status'];
Récupération du montant total du paiement
$amount = $_POST['data']['invoice']['total_amount'];
Récupération du hash
$hash = $_POST['data']['hash'];

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.

Exemple de code de vérification IPN

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();
}

Bonne pratique

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.

4. APIs

~ Les services PAR & PSR

# Initialisation
* Initialisation d'un Paiement Avec Redirection (PAR) :

Le service de "Paiement Avec Redirection (PAR)" 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 (PAR)" 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.

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:

* Cas d'une installation manuelle
$invoice = new Paydunya_Checkout_Invoice();
* Cas d'une installation via Composer
$invoice = new \Paydunya\Checkout\CheckoutInvoice();
* Initialisation d'un Paiement Sans Redirection (PSR) :

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface et vous envoyez ce dernier à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. A noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.

Dans le fichier du code source qui doit effectuer l'action procédez ainsi si vous souhaitez accepter des paiements directement au niveau de votre application

* Cas d'une installation manuelle
$invoice = new Paydunya_Onsite_Invoice();
* Cas d'une installation via Composer
$invoice = new Paydunya\Checkout\OnsiteInvoice();
# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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);

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("Description Optionnelle");
Configuration du montant total de la facture :

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.

Note: 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);
# Cas du PAR: Redirection vers la page de paiement PayDunya

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;
}
# Cas de PSR:
* Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

//A insérer dans le fichier du code source qui doit effectuer l'action

// Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
if ($invoice->create("EMAIL_OU_NUMERO_DU_CLIENT_PayDunya")) {
  echo $invoice->getStatus();
  echo $invoice->token;
  echo $invoice->getReceiptUrl();
} else {
  echo $invoice->response_text;
}
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR.

//A insérer dans le fichier du code source qui doit effectuer l'action

// Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR
if($invoice->charge("TOKEN_PSR", "CODE_DE_CONFIRMATION_DU_CLIENT")) {
  echo $invoice->getStatus();
  echo $invoice->response_text;
  echo $invoice->getReceiptUrl();
  echo $invoice->getCustomerInfo("name");
  echo $invoice->getCustomerInfo("email");
} else {
  echo $invoice->response_text;
}

~ Paiement Et Redistribution (PER)

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;
}

5. Méthodes API supplémentaires

~ Ajout de taxes (facultatif)

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);
  

~ Ajout de données supplémentaires (facultatif)

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.

NOTE: 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 confirm au 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%");

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.

NOTE: 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.

L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.

* Configuration globale de l'URL de redirection après annulation de paiement

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");
* Configuration de l'URL de redirection après annulation de paiement sur une instance de facture

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");

~ Configuration d'une URL de redirection après confirmation de paiement

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.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquerons comment utiliser ce token dans le chapitre suivant.
Configuration globale de l'URL de redirection après confirmation de paiement.

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");
  
Configuration de l'URL de redirection après confirmation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

$invoice->setReturnUrl("http://magasin-le-choco.com/return_url.php");

6. Vérification de l'état du paiement

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.

NOTE: 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.
* Cas d'une installation manuelle
//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;
}
* Cas d'une installation via Composer
//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;
}

.NET

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

Cliquez sur paydunya_dotnet_latest.zip ou paydunya_dotnet_latest.tar.gz pour télécharger la dernière version de notre fichier Assembly .NET ainsi que ses dépendances.

3. Configuration de base

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au 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


PaydunyaSetup setup = new PaydunyaSetup {
  MasterKey = "wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW",
  PrivateKey = "test_private_rMIdJM3PLLhLjyArx9tF3VURAF5",
  PublicKey = "test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja",
  Token = "IivOiOxGJuWhc5znlIiK",
  Mode = "test" // Optionnel. Utilisez cette option pour les paiements tests.
};
  
NB: 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.

~ Configuration des informations de votre service/activité/entreprise

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.

//Configuration des informations de votre service/entreprise
PaydunyaStore store = new PaydunyaStore {
  Name = "Magasin Chez Sandra", // Seul le nom est requis
  Tagline = "L'elegance n'a pas de prix",
  PhoneNumber = "336530583",
  PostalAddress = "Dakar Plateau - Etablissement kheweul",
  WebsiteUrl = "http://www.chez-sandra.sn",
  LogoUrl = "http://www.chez-sandra.sn/logo.png"
};

~ Configuration de l'IPN (Instant Payment Notification)

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.

NOTE: 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.

# Configuration globale de l'URL de notification instantanée de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

PaydunyaStore store = new PaydunyaStore {
  CallbackUrl = "http://magasin-le-choco.com/callback_url.aspx"
};
# Configuration de l'URL de notification instantanée de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux précédants si ceux-ci ont déjà été définis.

invoice.SetCallbackUrl("http://magasin-le-choco.com/callback_url.aspx");

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 PDF et un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue:
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NB: Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé "data" avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index "data").
Récupération du hash

Le hash renvoyé par PayDunya est le hash SHA512 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.

Bonne pratique

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.

4. APIs

~ Les services PAR & PSR

# Initialisation
* Initialisation d'un Paiement Avec Redirection (PAR) :

Le service de "Paiement Avec Redirection (PAR)" 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 (PAR)" 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.

/* Procédez ainsi si vous souhaitez rediriger vos clients vers notre site Web
  afin qu'il puisse achever le processus de paiement.

  Il est important de remarquer que le constructeur requiert respectivement comme paramètres
  une instance des classes PaydunyaSetup et PaydunyaStore. */
PaydunyaCheckoutInvoice invoice = new PaydunyaCheckoutInvoice(setup, store);
* Initialisation d'un Paiement Sans Redirection (PSR) :

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface et vous envoyez ce dernier à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. A noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.
/* Procédez ainsi si vous souhaitez accepter
des paiements directement au niveau de votre application.

Il est important de remarquer que le constructeur
requiert respectivement comme paramètres
une instance des classes PaydunyaSetup et PaydunyaStore. */
PaydunyaOnsiteInvoice invoice = new PaydunyaOnsiteInvoice(setup, store);
# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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.

/* 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);

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("Description Optionnelle");
Configuration du montant total de la facture :

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.

Note: 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);
# Cas du PAR: Redirection vers la page de paiement PayDunya

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.

// 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()) {
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);
  Console.WriteLine(invoice.GetInvoiceUrl());
} else {
  Console.WriteLine(invoice.ResponseText);
  Console.WriteLine(invoice.Status);
}
# Cas de PSR:
* Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

// Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
if (invoice.Create("EMAIL_OU_NUMERO_DU_CLIENT_PayDunya")) {
  Console.WriteLine(invoice.Token);
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);
} else {
  Console.WriteLine(invoice.ResponseCode);
  Console.WriteLine(invoice.ResponseText);
}
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR.

// Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR
if (invoice.Charge("TOKEN_PSR", "CODE_DE_CONFIRMATION_DU_CLIENT")) {
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);
  Console.WriteLine(invoice.GetReceiptUrl());
  Console.WriteLine(invoice.GetCustomerInfo("name"));
  Console.WriteLine(invoice.GetCustomerInfo("email"));
} else {
  Console.WriteLine(invoice.ResponseCode);
  Console.WriteLine(invoice.ResponseText);
}

~ Paiement Et Redistribution (PER)

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.

PaydunyaDirectPay direct_pay = new PaydunyaDirectPay(setup);

if(direct_pay.CreditAccount("EMAIL_OU_NUMERO_MOBILE_DU_CLIENT_PAYDUNYA", MONTANT_A_TRANSFERER)){
  Console.WriteLine(direct_pay.Description);
  Console.WriteLine(direct_pay.Status);
  Console.WriteLine(direct_pay.ResponseText);
}else{
  Console.WriteLine(direct_pay.ResponseText);
}

5. Méthodes API supplémentaires

~ Ajout de taxes (facultatif)

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.

// Les paramètres sont l'intitulé de la taxe et le montant de la taxe.
invoice.AddTax("TVA (18%)", 6300);
invoice.AddTax("Livraison", 1000);

~ Ajout de données supplémentaires (facultatif)

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.

NOTE: 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 Confirm au niveau de l'API.
// 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.SetCustomData("categorie", "Jeu concours");
invoice.SetCustomData("periode", "Noël 2015");
invoice.SetCustomData("numero_gagnant", 5);
invoice.SetCustomData("prix","Bon de réduction de 50%");

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.

NOTE: 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.

L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.

* Configuration globale de l'URL de redirection après annulation de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

PaydunyaStore store = new PaydunyaStore {
  CancelUrl = "http://magasin-le-choco.com/cancel_url.aspx"
};
* Configuration de l'URL de redirection après annulation de paiement sur une instance de facture

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.aspx");

~ Configuration d'une URL de redirection après confirmation de paiement

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.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquerons comment utiliser ce token dans le chapitre suivant.
Configuration globale de l'URL de redirection après confirmation de paiement.

Cette instruction devra être incluse au niveau de la configuration de votre service/activité

PaydunyaStore store = new PaydunyaStore {
  ReturnUrl = "http://magasin-le-choco.com/return_url.aspx"
};
  
Configuration de l'URL de redirection après confirmation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

invoice.SetReturnUrl("http://magasin-le-choco.com/return_url.aspx");

6. Vérification de l'état du paiement

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.

NOTE: 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.
// PayDunya rajoutera automatiquement le token de la facture sous forme de QUERYSTRING "token"
// si vous avez configuré un "return_url" ou "cancel_url".
string InvoiceToken = Request.QueryString["token"];

PaydunyaCheckoutInvoice invoice = new PaydunyaCheckoutInvoice(setup, store);
if (invoice.Confirm(InvoiceToken)) {

  // Récupérer le statut du paiement
  // Le statut du paiement peut être soit completed, pending, cancelled
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);

  // 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
  Console.WriteLine(invoice.GetCustomerInfo("name"));
  Console.WriteLine(invoice.GetCustomerInfo("email"));
  Console.WriteLine(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
  Console.WriteLine(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.
  Console.WriteLine(invoice.GetCustomData("Catégorie"));
  Console.WriteLine(invoice.GetCustomData("Période"));
  Console.WriteLine(invoice.GetCustomData("Gagnant N°"));
  Console.WriteLine(invoice.GetCustomData("Prix"));

  // Vous pouvez aussi récupérer le montant total spécifié précédemment
  Console.WriteLine(invoice.GetTotalAmount());

}else{
  Console.WriteLine(invoice.Status);
  Console.WriteLine(invoice.ResponseText);
  Console.WriteLine(invoice.ResponseCode);
}

JAVA

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

Cliquez sur paydunya_java_latest.jar pour télécharger la dernière version de notre package JAVA ainsi que ses dépendances. Ajouter par la suite paydunya_java_latest.jar à votre CLASSPATH.

Pour finir, importez toutes les classes du package com.paydunya.neptune dans le ou les fichier(s) où vous souhaitez utiliser la librairie PayDunya:

import com.paydunya.neptune.*;

3. Configuration de base

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au 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

PaydunyaSetup setup = new PaydunyaSetup();
setup.setMasterKey("wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW");
setup.setPrivateKey("test_private_rMIdJM3PLLhLjyArx9tF3VURAF5");
setup.setPublicKey("test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja");
setup.setToken("IivOiOxGJuWhc5znlIiK");
setup.setMode("test"); // Optionnel. Utilisez cette option pour les paiements tests.
NB: 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.

~ Configuration des informations de votre service/activité/entreprise

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.

//Configuration des informations de votre service/entreprise
PaydunyaCheckoutStore store = new PaydunyaCheckoutStore();
store.setName("Magasin Chez Sandra"); // Seul le nom est requis
store.setTagline("L'élégance n'a pas de prix");
store.setPhoneNumber("336530583");
store.setPostalAddress("Dakar Plateau - Etablissement kheweul");
store.setWebsiteUrl("http://www.chez-sandra.sn");
store.setLogoUrl("http://www.chez-sandra.sn/logo.png");

~ Configuration de l'IPN (Instant Payment Notification)

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.

NOTE: 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.

# Configuration globale de l'URL de notification instantanée de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

PaydunyaCheckoutStore store = new PaydunyaCheckoutStore();
store.setCallbackUrl("http://magasin-le-choco.com/callback_url");
# Configuration de l'URL de notification instantanée de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux précédants si ceux-ci ont déjà été définis.

invoice.setCallbackUrl("http://magasin-le-choco.com/callback_url");

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 PDF et un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue:
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NB: Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé "data" avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index "data").
Récupération du hash

Le hash renvoyé par PayDunya est le hash SHA512 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.

Bonne pratique

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.

4. APIs

~ Les services PAR & PSR

# Initialisation
* Initialisation d'un Paiement Avec Redirection (PAR) :

Le service de "Paiement Avec Redirection (PAR)" 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 (PAR)" 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.

/* Procédez ainsi si vous souhaitez rediriger vos clients vers notre site Web
  afin qu'il puisse achever le processus de paiement.

  Il est important de remarquer que le constructeur requiert respectivement comme paramètres
  une instance des classes PaydunyaSetup et PaydunyaCheckoutStore. */
PaydunyaCheckoutInvoice invoice = new PaydunyaCheckoutInvoice(setup, store);
* Initialisation d'un Paiement Sans Redirection (PSR) :

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface et vous envoyez ce dernier à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. A noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.
/* Procédez ainsi si vous souhaitez accepter
des paiements directement au niveau de votre application.

Il est important de remarquer que le constructeur
requiert respectivement comme paramètres
une instance des classes PaydunyaSetup et PaydunyaCheckoutStore. */
PaydunyaOnsiteInvoice invoice = new PaydunyaOnsiteInvoice(setup, store);
# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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.

/* 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);

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("Description Optionnelle");
Configuration du montant total de la facture :

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.

Note: 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);
# Cas du PAR: Redirection vers la page de paiement PayDunya

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.

// Le code suivant décrit comment créer une facture de paiement au niveau de nos serveurs,
// et afficher ensuite son reçu de paiement en cas de succès.
if (invoice.create()) {
  System.out.println(invoice.getStatus());
  System.out.println(invoice.getResponseText());
  System.out.println(invoice.getInvoiceUrl());
} else {
  System.out.println(invoice.getResponseText());
  System.out.println(invoice.getResponseCode());
}
# Cas de PSR:
* Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

// Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
if (invoice.create("EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA")) {
  System.out.println ("Token PSR: " + invoice.getToken());
  System.out.println ("Statut: " + invoice.getStatus());
  System.out.println ("Réponse: " + invoice.getResponseText());
} else {
  System.out.println("Réponse: " + invoice.getResponseText());
}
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR.

// Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR
if (invoice.charge("TOKEN_PSR", "CODE_DE_CONFIRMATION_DU_CLIENT")) {
  System.out.println("Statut: " + invoice.getStatus());
  System.out.println("Réponse: " + invoice.getResponseText());
  System.out.println("URL du reçu électronique: " + invoice.getReceiptUrl());
  System.out.println("Nom du client: " + invoice.getCustomerInfo("name"));
  System.out.println("Email du client: " + invoice.getCustomerInfo("email"));
} else {
  System.out.println("Réponse: " + invoice.getResponseText());
}

~ Paiement Et Redistribution (PER)

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.

PaydunyaDirectPay direct_pay = new PaydunyaDirectPay(setup);

if(direct_pay.creditAccount("EMAIL_OU_NUMERO_MOBILE_DU_CLIENT_PAYDUNYA", MONTANT_A_TRANSFERER)){
  System.out.println("Statut: " + direct_pay.getStatus());
  System.out.println("Description: " + direct_pay.getDescription());
  System.out.println("ID de la Transaction: " + direct_pay.getTransactionId());
}else{
  System.out.println("Réponse: " + direct_pay.getResponseText());
}

5. Méthodes API supplémentaires

~ Ajout de taxes (facultatif)

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.

// Les paramètres sont l'intitulé de la taxe et le montant de la taxe.
invoice.addTax("TVA (18%)", 6300);
invoice.addTax("Livraison", 1000);

~ Ajout de données supplémentaires (facultatif)

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.

NOTE: 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 confirm au niveau de l'API.
// 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%");

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.

NOTE: 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.

L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.

* Configuration globale de l'URL de redirection après annulation de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

PaydunyaCheckoutStore store = new PaydunyaCheckoutStore();
store.setCancelUrl("http://magasin-le-choco.com/cancel_url");
* Configuration de l'URL de redirection après annulation de paiement sur une instance de facture

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");

~ Configuration d'une URL de redirection après confirmation de paiement

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.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquerons comment utiliser ce token dans le chapitre suivant.
Configuration globale de l'URL de redirection après confirmation de paiement.

Cette instruction devra être incluse au niveau de la configuration de votre service/activité

PaydunyaCheckoutStore store = new PaydunyaCheckoutStore();
store.setReturnUrl("http://magasin-le-choco.com/return_url");
Configuration de l'URL de redirection après confirmation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

invoice.setReturnUrl("http://magasin-le-choco.com/return_url");

6. Vérification de l'état du paiement

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.

NOTE: 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.
// PayDunya rajoutera automatiquement le token de la facture sous forme de QUERYSTRING "token"
// si vous avez configuré un "return_url" ou "cancel_url".
String invoiceToken = "l21sjklsdl-s0mw";

PaydunyaCheckoutInvoice invoice = new PaydunyaCheckoutInvoice(setup, store);
if (invoice.confirm(invoiceToken)) {

  // Récupérer le statut du paiement
  // Le statut du paiement peut être soit completed, pending, cancelled
  System.out.println(invoice.getStatus());
  System.out.println(invoice.getResponseText());

  // 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
  System.out.println(invoice.getCustomerInfo("name"));
  System.out.println(invoice.getCustomerInfo("email"));
  System.out.println(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
  System.out.println(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.
  System.out.println(invoice.getCustomData("Catégorie"));
  System.out.println(invoice.getCustomData("Période"));
  System.out.println(invoice.getCustomData("Gagnant N°"));
  System.out.println(invoice.getCustomData("Prix"));

  // Vous pouvez aussi récupérer le montant total spécifié précédemment
  System.out.println(invoice.getTotalAmount());

}else{
  System.out.println(invoice.getStatus());
  System.out.println(invoice.getResponseText());
  System.out.println(invoice.getResponseCode());
}

Ruby

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

~ Installation via la commande gem

gem install paydunya

~ Installation via Bundler

Ajouter cette ligne au niveau de votre fichier Gemfile:

gem "paydunya"

3. Configuration de base

Si vous utilisez Ruby on Rails vous pouvez créer un fichier au niveau du dossier config/initializers et y insérer les configurations décrites plus bas.

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au 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.master_key = "wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW"
Paydunya::Setup.public_key = "test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja"
Paydunya::Setup.private_key = "test_private_rMIdJM3PLLhLjyArx9tF3VURAF5"
Paydunya::Setup.mode = "test" # Optionnel. Utilisez cette option pour les paiements tests.
Paydunya::Setup.token = "IivOiOxGJuWhc5znlIiK"
NB: 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.

~ Configuration des informations de votre service/activité/entreprise

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.

# Configuration des informations de votre service/entreprise
Paydunya::Checkout::Store.name = "Magasin Chez Sandra" # Seul le nom est requis
Paydunya::Checkout::Store.tagline = "L'élégance n'a pas de prix"
Paydunya::Checkout::Store.postal_address = "Dakar Plateau - Etablissement kheweul"
Paydunya::Checkout::Store.phone_number = "336530583"
Paydunya::Checkout::Store.website_url = "http://www.chez-sandra.sn"
Paydunya::Checkout::Store.logo_url = "http://www.chez-sandra.sn/logo.png"

~ Configuration de l'IPN (Instant Payment Notification)

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.

NOTE: 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.

# Configuration globale de l'URL de notification instantanée de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

Paydunya::Checkout::Store.callback_url = "http://www.ma-super-boutique.com/fichier_de_reception_des_données_de_facturation"
# Configuration de l'URL de notification instantanée de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux précédants si ceux-ci ont déjà été définis.

invoice.callback_url = "http://www.ma-super-boutique.com/fichier_de_reception_des_données_de_facturation"

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 PDF et un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue:
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NB: Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé :data avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index :data).

Par exemple pour récupérer le statut du paiement, le nom du client et le hash, voici le code à excécuter:

Récupération du statut du paiement
status = params[:data][:status]
Récupération du montant total du paiement
amount = params[:data][:invoice][:total_amount]
Récupération du hash
hash = params[:data][:hash]

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.

Exemple de code de vérification IPN

Hashez votre clé principale et comparez le résultat au hash reçu par IPN.

begin
  #Prenez votre MasterKey, hashez la et comparez le résultat au hash reçu par IPN
  if(params[:data][:hash] == Digest::SHA2.new(512).hexdigest("VOTRE_CLE_PRINCIPALE"))
    if params[:data][:status] == "completed"
      # Faites vos traitements backoffice ici...
    end
  else
    puts "Cette requête n'a pas été émise par PayDunya"
  end
rescue
  # Une erreur est survenue...
end

Bonne pratique

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.

4. APIs

~ Les services PAR & PSR

# Initialisation
* Initialisation d'un Paiement Avec Redirection (PAR) :

Le service de "Paiement Avec Redirection (PAR)" 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 (PAR)" 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.

# Procédez ainsi si vous souhaitez rediriger vos clients vers notre site Web
# afin qu'il puisse achever le processus de paiement.
invoice = Paydunya::Checkout::Invoice.new
* Initialisation d'un Paiement Sans Redirection (PSR) :

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface et vous envoyez ce dernier à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. A noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.
# Procédez ainsi si vous souhaitez accepter
# des paiements directement au niveau de votre application.
invoice = Paydunya::Onsite::Invoice.new
# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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 l'attribut total_amount de l'objet invoice afin de préciser le montant exact à facturer au client.

# 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.add_item("Clavier DELL", 2, 3000, 6000)
invoice.add_item("Ordinateur Lenovo L440", 1, 400000, 400000, "Description optionelle")
invoice.add_item("Casque Logitech", 1, 8000, 8000)

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.description = "Description Optionnelle"
Configuration du montant total de la facture :

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.

Note: 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.total_amount = 42300
# Cas du PAR: Redirection vers la page de paiement PayDunya

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.

# Le code suivant décrit comment créer une facture de paiement au niveau de nos serveurs,
# et afficher ensuite son reçu de paiement en cas de succès.
if invoice.create
  puts invoice.status
  puts invoice.response_text
  # Vous pouvez par exemple faire un "redirect_to invoice.invoice_url"
  # au niveau d'un controller Rails
  puts invoice.invoice_url
else
  puts invoice.status
  puts invoice.response_text
end
# Cas de PSR:
* Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

# Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
if invoice.create("EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA")
  puts invoice.status
  puts invoice.response_text
  puts invoice.token
else
  puts invoice.response_code
  puts invoice.response_text
end
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR.

# Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR
if invoice.charge("TOKEN_PSR","CODE_DE_CONFIRMATION_DU_CLIENT")
  puts invoice.status
  puts invoice.response_text
  puts invoice.receipt_url
  puts invoice.get_customer_info("name")
  puts invoice.get_customer_info("email")
else
  puts invoice.response_code
  puts invoice.response_text
end

~ Paiement Et Redistribution (PER)

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.

direct_pay = Paydunya::DirectPay.new

if (direct_pay.credit_account("EMAIL_OU_NUMERO_MOBILE_DU_CLIENT_PAYDUNYA", MONTANT_A_TRANSFERER))
  puts direct_pay.description
  puts direct_pay.response_text
  puts direct_pay.transaction_id
else
  puts direct_pay.response_text
end

5. Méthodes API supplémentaires

~ Ajout de taxes (facultatif)

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.

# Les paramètres sont l'intitulé de la taxe et le montant de la taxe.
invoice.add_tax("TVA (18%)", 6300)
invoice.add_tax("Livraison", 1000)

~ Ajout de données supplémentaires (facultatif)

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.

NOTE: 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 confirm au niveau de l'API.
# 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.add_custom_data("categorie", "Jeu concours")
invoice.add_custom_data("periode", "Noël 2015")
invoice.add_custom_data("numero_gagnant", 5)
invoice.add_custom_data("prix","Bon de réduction de 50%")

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.

NOTE: 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.

L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.

* Configuration globale de l'URL de redirection après annulation de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

Paydunya::Checkout::Store.cancel_url = "http://magasin-le-choco.com/cancel_url"
* Configuration de l'URL de redirection après annulation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

invoice.cancel_url = "http://magasin-le-choco.com/cancel_url"

~ Configuration d'une URL de redirection après confirmation de paiement

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.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquerons comment utiliser ce token dans le chapitre suivant.
Configuration globale de l'URL de redirection après confirmation de paiement.

Cette instruction devra être incluse au niveau de la configuration de votre service/activité

Paydunya::Checkout::Store.return_url = "http://magasin-le-choco.com/return_url"
Configuration de l'URL de redirection après confirmation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

invoice.return_url = "http://magasin-le-choco.com/return_url"

6. Vérification de l'état du paiement

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.

NOTE: 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.
# 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 via le QUERYSTRING si vous utilisez Rails ou Sinatra.
token = params[:token]

invoice = Paydunya::Checkout::Invoice.new
if invoice.confirm(token)

  # Récupérer le statut du paiement
  # Le statut du paiement peut être soit completed, pending, cancelled
  puts invoice.status

  # 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
  puts invoice.get_customer_info "name"
  puts invoice.get_customer_info "email"
  puts invoice.get_customer_info "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
  puts invoice.receipt_url

  # 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.
  puts invoice.get_custom_data "Catégorie"
  puts invoice.get_custom_data "Période"
  puts invoice.get_custom_data "Gagnant N°"
  puts invoice.get_custom_data "Prix"

  # Vous pouvez aussi récupérer le montant total spécifié précédemment
  puts invoice.total_amount

else
  puts invoice.status
  puts invoice.response_text
  puts invoice.response_code
end

Python

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

~ Installation via pip

pip install paydunya

~ Installation depuis les sources

Ajouter cette ligne au niveau de votre fichier Gemfile:

git clone https://github.com/paydunya/paydunya-python
cd paydunya-python
python setup.py install

3. Configuration de base

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au 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

import paydunya

PAYDUNYA_ACCESS_TOKENS = {
  'PAYDUNYA-MASTER-KEY': "wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW",
  'PAYDUNYA-PRIVATE-KEY': "test_private_rMIdJM3PLLhLjyArx9tF3VURAF5",
  'PAYDUNYA-TOKEN': "IivOiOxGJuWhc5znlIiK"
}

# Activer le mode 'test'. Le debug est à False par défaut
paydunya.debug = True

# Configurer les clés d'API
paydunya.api_keys = PAYDUNYA_ACCESS_TOKENS
NB: 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.

~ Configuration des informations de votre service/activité/entreprise

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.

from paydunya import Store

# Configuration des informations de votre service/entreprise
infos = {
  'name': "Magasin Chez Sandra", # Seul le nom est requis
  'tagline': "L'élégance n'a pas de prix",
  'postal_address': "Dakar Plateau - Etablissement kheweul",
  'phone_number': "336530583",
  'website_url': "http://www.chez-sandra.sn",
  'logo_url': "http://www.chez-sandra.sn/logo.png"
}

store = Store(**infos)

~ Configuration de l'IPN (Instant Payment Notification)

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.

NOTE: 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 la possibilité ci-dessous.

# Configuration de l'URL de notification instantanée de paiement sur une instance de facture
invoice.callback_url = "http://www.ma-super-boutique.com/fichier_de_reception_des_données_de_facturation"

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 PDF et un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue:
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NB: Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé :data avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index :data).

Par exemple pour récupérer le statut du paiement, le nom du client et le hash, voici le code à excécuter:

Récupération du statut du paiement
# Si vous utilisez Django ou Flask
status = request.POST['data']['status']
Récupération du montant total du paiement
# Si vous utilisez Django ou Flask
amount = request.POST['data']['invoice']['total_amount']
Récupération du hash
# Si vous utilisez Django ou Flask
hash = request.POST['data']['hash']

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.

Exemple de code de vérification IPN

Hashez votre clé principale et comparez le résultat au hash reçu par IPN.

import hashlib

try:
  #Prenez votre MasterKey, hashez la et comparez le résultat au hash reçu par IPN
  if(request.POST['data']['hash'] == hashlib.sha512(b"VOTRE_CLE_PRINCIPALE").hexdigest()):
    if(request.POST['data']['status'] == "completed"):
      # Faites vos traitements backoffice ici...
  else:
    puts "Cette requête n'a pas été émise par PayDunya"
except:
  # Une erreur est survenue...

Bonne pratique

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.

4. APIs

~ Les services PAR & PSR

# Initialisation
* Initialisation d'un Paiement Avec Redirection (PAR) :

Le service de "Paiement Avec Redirection (PAR)" 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 (PAR)" 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.

# Procédez ainsi si vous souhaitez rediriger vos clients vers notre site Web
# afin qu'il puisse achever le processus de paiement.
import paydunya

store = paydunya.Store(name='Magasin Chez Sandra')
invoice = paydunya.Invoice(store)
* Initialisation d'un Paiement Sans Redirection (PSR) :

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface et vous envoyez ce dernier à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. A noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.
# Procédez ainsi si vous souhaitez accepter
# des paiements directement au niveau de votre application.
import paydunya

opr_data = {
  'account_alias': 'EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA',
  'description': 'Description optionelle',
  'total_amount': 6500
}
store = paydunya.Store(name='Magasin Chez Sandra')
opr = paydunya.OPR(opr_data, store)
# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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 l'attribut total_amount de l'objet invoice afin de préciser le montant exact à facturer au client.

import paydunya
from paydunya import InvoiceItem, Store

store = Store(name='Magasin Chez Sandra')

# 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.
items = [
  InvoiceItem(
    name="Chaussures Croco",
    quantity=3,
    unit_price="10000",
    total_price="30000",
    description="Chaussures faites en peau de crocrodile authentique qui chasse la pauvreté"
  ),
  InvoiceItem(
    name="Chemise Glacée",
    quantity=1,
    unit_price="5000",
    total_price="5000"
  ),
]
invoice = paydunya.Invoice(store)
invoice.add_items(items)

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.description = "Description Optionnelle"
Configuration du montant total de la facture :

PayDunya s'attend à ce que vous précisez 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. Afin de vous faciliter la tâche, une méthode calculate_total_amt calculant le montant total de la facture à partir du montant total de chaque élément de facture est présente au niveau de la classe Invoice.

Note: 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.total_amount = 42300
# Cas du PAR: Redirection vers la page de paiement PayDunya

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.

# Le code suivant décrit comment créer une facture de paiement au niveau de nos serveurs,
# et faire ce que vous souhaitez en cas de succès.
successful, response = invoice.create()
if successful:
  # Faire quelque chose avec la variable reponse
# Cas de PSR:
* Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

# Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
import paydunya

opr_data = {
  'account_alias': 'EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA',
  'description': 'Description optionelle',
  'total_amount': 6500
}
store = paydunya.Store(name='Magasin Chez Sandra')
opr = paydunya.OPR(opr_data, store)

# Vous pouvez aussi passer les données opr `opr_data` à la méthode `create`
successful, response = opr.create()

if successful:
  # Faire quelque chose avec la variable reponse
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR.

# Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR
successful, response = opr.charge({
  'token': "TOKEN_PSR",
  'confirm_token': "CODE_DE_CONFIRMATION_DU_CLIENT"
})

~ Paiement Et Redistribution (PER)

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.

account_alias = "EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA"
amount = 6500

direct_pay = paydunya.DirectPay(account_alias, amount)
successful, response = direct_pay.process()

if successful:
  # Faire quelque chose avec la variable reponse

5. Méthodes API supplémentaires

~ Ajout de taxes (facultatif)

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.

# Les paramètres sont l'intitulé de la taxe et le montant de la taxe.
invoice.add_taxes([("TVA (18%)", 6300), ("Livraison", 1000)])

~ Ajout de données supplémentaires (facultatif)

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.

NOTE: 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 confirm au niveau de l'API.
# 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.add_custom_data([
  ("categorie", "Jeu concours"),
  ("periode", "Noël 2015"),
  ("numero_gagnant", 5),
  ("prix","Bon de réduction de 50%"),
])

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.

invoice.cancel_url = "http://magasin-le-choco.com/cancel_url"

~ Configuration d'une URL de redirection après confirmation de paiement

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.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquerons comment utiliser ce token dans le chapitre suivant.
invoice.return_url = "http://magasin-le-choco.com/return_url"

6. Vérification de l'état du paiement

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.

NOTE: 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.
# 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 via le QUERYSTRING si vous utilisez Django ou Flask.
token = request.GET.get('token') # Exemple ici avec Django

successful, response = invoice.confirm(token)

if successful:
  # Faire quelque chose avec la variable reponse

NodeJS

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. Installation

Installer PayDunya via la commande npm

yarn add paydunya

3. Configuration de base

Connectez-vous à votre compte PayDunya, cliquez sur Integration API puis sur détails au 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

var paydunya = require('paydunya');

var setup = new paydunya.Setup({
  masterKey: 'wQzk9ZwR-Qq9m-0hD0-zpud-je5coGC3FHKW',
  privateKey: 'test_private_rMIdJM3PLLhLjyArx9tF3VURAF5',
  publicKey: 'test_public_kb9Wo0Qpn8vNWMvMZOwwpvuTUja',
  token: 'IivOiOxGJuWhc5znlIiK',
  mode: 'test' // Optionnel. Utilisez cette option pour les paiements tests.
});
NB: 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.

Bonne Pratique

Il pourrait être généralement adapté de mettre la configuration de vos clés d'API au niveau des variables d'environnement. Dans ce cas, vous pouvez initialiser paydunya.Setup sans passer de paramètres de configuration. Le package se chargera de détecter automatiquement les variables d'environnement pour ensuite les utiliser. Les noms de variables d'environnement attendus sont: PAYDUNYA_MASTER_KEY, PAYDUNYA_PRIVATE_KEY, PAYDUNYA_PUBLIC_KEY et PAYDUNYA_TOKEN.

~ Configuration des informations de votre service/activité/entreprise

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.

// Configuration des informations de votre service/entreprise
var store = new paydunya.Store({
  name: 'Magasin Chez Sandra', // Seul le nom est requis
  tagline: "L'élégance n'a pas de prix",
  phoneNumber: '336530583',
  postalAddress: 'Dakar Plateau - Etablissement kheweul',
  websiteURL: 'http://www.chez-sandra.sn',
  logoURL: 'http://www.chez-sandra.sn/logo.png'
});

~ Configuration de l'IPN (Instant Payment Notification)

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.

NOTE: 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.

# Configuration globale de l'URL de notification instantanée de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.

var store = new paydunya.Store({
  name: 'Magasin chez Sandra',
  callbackURL: 'http://www.ma-super-boutique.com/fichier_de_reception_des_données_de_facturation'
});
# Configuration de l'URL de notification instantanée de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux précédants si ceux-ci ont déjà été définis.

invoice.callbackURL = 'http://www.ma-super-boutique.com/fichier_de_reception_des_données_de_facturation'

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 PDF et un hash permettant de vérifier que les données reçues proviennent bien de nos serveurs.

Réponse attendue:
{
  "response_code": "00",
  "response_text": "Transaction Found",
  "hash": "85c6564b0e29c7955633594bc8aca0d007dc1fce3f67bd3accb00ae4e9d39ae528574be9a6ea8bde81fcbb0bc0fae3e56eb1bbedcd4d119a7fd24b0d44ab3770",
  "invoice": {
    "items": {
        "item_0": {
        "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": {
        "name": "Chemise Glacée",
        "quantity": 1,
        "unit_price": "5000",
        "total_price": "5000",
        "description": ""
      }
    },
    "taxes": {
      "tax_0": {
        "name": "TVA (18%)",
        "amount": 6300
      },
      "tax_1": {
        "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": {
    "categorie": "Jeu concours",
    "periode":  "Noël 2015",
    "numero_gagnant": 5,
    "prix" : "Bon de réduction de 50%"
  },
  "actions": {
    "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": {
    "name": "Alioune Faye",
    "phone": "774563209",
    "email": "aliounefaye@gmail.com"
  },
  "receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
NB: Vous n'avez pas besoin de faire un json_decode pour traiter les données reçues et vous devez utiliser la clé :data avant de récupérer un noeud (La strucutre renvoyée se trouve sous l'index :data).

Par exemple pour récupérer le statut du paiement, le nom du client et le hash, voici le code à excécuter:

Si vous utilisez Express
yarn add body-parser
var bodyParser = require('body-parser')
app.use( bodyParser.json() );       // to support JSON-encoded bodies
app.use(bodyParser.urlencoded({     // to support URL-encoded bodies
  extended: true
})); 
Récupération du statut du paiement
app.post('/ipn-url', function(req, res) {
    var status = req.body.data.status;
});
Récupération du montant total du paiement
app.post('/ipn-url', function(req, res) {
    var amount = req.body.data.invoice.total_amount;
});
Récupération du hash
app.post('/ipn-url', function(req, res) {
    var hash = req.body.data.hash;
});

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.

yarn add js-sha512
Exemple de code de vérification IPN

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(hash == sha512("VOTRE_CLE_PRINCIPALE")) {
    if(status == "completed") {
      // Faites vos traitements backoffice ici...
    }
  }
  } else {
    console.log("Cette requête n'a pas été émise par PayDunya");
  }
} catch() {}

Bonne pratique

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.

4. APIs

~ Les services PAR & PSR

# Initialisation
* Initialisation d'un Paiement Avec Redirection (PAR) :

Le service de "Paiement Avec Redirection (PAR)" 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 (PAR)" 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.

// Procédez ainsi si vous souhaitez rediriger vos clients vers notre site Web  afin qu'il puisse achever le processus de paiement
// Il est important de remarquer que le constructeur requiert respectivement comme paramètres
// une instance des classes paydunya.Setup et paydunya.Store
var invoice = new paydunya.CheckoutInvoice(setup, store);
* Initialisation d'un Paiement Sans Redirection (PSR) :

Si vous souhaitez que vos clients paient directement via votre site web ou application mobile sans pour autant les rediriger sur notre page de paiement, PayDunya vous donne la possibilité d'utiliser le service PSR (Paiement Sans Redirection) afin de facturer en toute sécurité vos clients sans communiquer de données sensibles.

Le service PSR est un processus en deux étapes:

  1. Le client saisi son adresse email ou numéro de téléphone de son compte PayDunya sur votre interface et vous envoyez ce dernier à PayDunya. PayDunya vous renvoie un token PSR. Le client PayDunya reçoit également un code de confirmation par e-mail et SMS. A noter que les SMS sont uniquement envoyés pour les transactions réelles (en production).
  2. Le client saisi le code reçu. Vous renvoyez le couple Token PSR et Code de confirmation à PayDunya afin de facturer le client. PayDunya vous envoie une réponse de succès ou échec.
// Procédez ainsi si vous souhaitez accepter des paiements directement au niveau de votre application
// Il est important de remarquer que le constructeur requiert respectivement comme paramètres
// une instance des classes paydunya.Setup et paydunya.Store
var invoice = new paydunya.OnsiteInvoice(setup, store);
# Ajout des informations de paiement
* Ajout d'articles et de description de facture :

Il 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 l'attribut total_amount de l'objet invoice afin de préciser le montant exact à facturer au client.

// 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', 1, 10000, 30000, 'Chaussures faites en peau de crocrodile authentique qui chasse la pauvreté');
invoice.addItem('Chemise Glacée', 1, 5000, 5000);

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.description = 'Description Optionnelle';
Configuration du montant total de la facture :

PayDunya s'attend à ce que vous précisez 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.

Note: 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.totalAmount = 42300;
# Cas du PAR: Redirection vers la page de paiement PayDunya

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.

// 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.
invoice.create()
  .then(function (){
    console.log(invoice.status);
    console.log(invoice.token); // Token de facture
    console.log(invoice.responseText);
    console.log(invoice.url); // URL de redirection de paiement de facture PayDunya
  })
  .catch(function (e) {
    console.log(e);
  });
# Cas de PSR:
* Emission d'une requête de facturation PSR

Après avoir rajouté des articles à votre facture et configuré le montant total de la facture, récupérez l'adresse email ou le numéro de téléphone du client et envoyez une requête PSR.

Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre.

// Une requête PSR requiert l'email ou le numéro mobile du client comme paramètre
invoice.create('EMAIL_OU_NUMERO_DU_CLIENT_PAYDUNYA')
  .then(function(){
    console.log(invoice.oprToken); // Vous devez utiliser le token PSR lors de la deuxième étape.
    console.log(invoice.token); // Token de facture token
    console.log(invoice.responseText);
  })
  .catch(function (e) {
    console.log(e);
  });
* Paiement de facture Sans Redirection (PSR)

Avant d'effectuer une requête de facturation PSR, vous devez avoir votre token PSR et le code de confirmation envoyé au client. Après un paiement réussi, vous pourrez accéder aux informations du client, à son reçu électronique et bien plus encore.

Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR.

// Une demande de facturation PSR nécessite à la fois le code de confirmation ou et le token PSR
invoice.charge('TOKEN_PSR', 'CODE_DE_CONFIRMATION_DU_CLIENT')
  .then(function (){
    console.log(invoice.status);
    console.log(invoice.responseText);
    console.log(invoice.receiptURL);
    console.log(invoice.customer); // {name: 'Alioune Badara', phone: '773629373', email: 'aliounebadara@gmail.com'}
  })
  .catch(function (e) {
    console.log(e);
  });

~ Paiement Et Redistribution (PER)

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.

var directPay = new paydunya.DirectPay(setup);
directPay.creditAccount('EMAIL_OU_NUMERO_MOBILE_DU_CLIENT_PAYDUNYA', MONTANT_A_TRANSFERER)
  .then(function (){
    console.log(directPay.description);
    console.log(directPay.responseText);
    console.log(directPay.transactionID);
  })
  .catch(function (e) {
    console.log(e);
  });

5. Méthodes API supplémentaires

~ Ajout de taxes (facultatif)

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.

// Les paramètres sont l'intitulé de la taxe et le montant de la taxe.
invoice.addTax('TVA (18%)', 6300);
invoice.addTax("Livraison", 1000);

~ Ajout de données supplémentaires (facultatif)

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.

NOTE: 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 confirm au niveau de l'API.
// 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%");

~ Configuration d'une URL de redirection après annulation de paiement

Vous pouvez optionnellement définir une URL sur laquelle seront redirigés vos clients après une annulation de commande.

NOTE: 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.

L'utilisation de la seconde option écrase les paramètres globaux si ceux-ci ont déjà été définis.

* Configuration globale de l'URL de redirection après annulation de paiement

Cette instruction devra être incluse au niveau de la configuration de votre service/activité.


var store = new paydunya.Store({
  name: 'Magasin chez Sandra',
  cancelURL: 'http://magasin-le-choco.com/cancel_url'
});
* Configuration de l'URL de redirection après annulation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

invoice.cancelURL = 'http://magasin-le-choco.com/cancel_url';

~ Configuration d'une URL de redirection après confirmation de paiement

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.

NOTE: PayDunya rajoutera ?token=INVOICE_TOKEN à votre URL. Nous expliquerons comment utiliser ce token dans le chapitre suivant.
Configuration globale de l'URL de redirection après confirmation de paiement.

Cette instruction devra être incluse au niveau de la configuration de votre service/activité

var store = new paydunya.Store({
  name: 'Magasin chez Sandra',
  returnURL: 'http://magasin-le-choco.com/return_url'
});
  
Configuration de l'URL de redirection après confirmation de paiement sur une instance de facture

Cette configuration écrasera les paramètres globaux de redirection si ceux-ci ont déjà été définis.

invoice.returnURL = 'http://magasin-le-choco.com/return_url';

6. Vérification de l'état du paiement

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.

NOTE: 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.
// PayDunya rajoutera automatiquement le token de la facture sous forme de QUERYSTRING "token"
// si vous avez configuré un "return_url" ou "cancel_url".
var token = 'test_VPGPZNnHOC';

var invoice = new paydunya.CheckoutInvoice(setup, store);
invoice.confirm(token)
  .then(function (){
    // Récupérer le statut du paiement
    // Le statut du paiement peut être soit completed, pending, cancelled
    console.log(invoice.status);

    console.log(invoice.responseText);  // Réponse du serveur

    // Les champs qui suivent seront disponibles si et
    // seulement si le statut du paiement est égal à "completed".

    // Vous pouvez récupérer le nom, l'adresse email et le
    // numéro de téléphone du client en utilisant l'objet suivant
    console.log(invoice.customer); // {name: 'Alioune', phone: '773830274', email: 'aliounebadara@gmail.com'}

    // URL du reçu PDF électronique pour téléchargement
    console.log(invoice.receiptURL); // 'https://app.paydunya.com/sandbox-checkout/receipt/pdf/test_VPGPZNnHOC.pdf'
  })
  .catch(function (e) {
    console.log(e);
  });

PrestaShop

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. La passerelle de paiement PayDunya sur PrestaShop

~ Installation manuelle

  • Téléchargez notre module PayDunya PrestaShop;
  • Uploader le module PayDunya comme tout autre module Prestashop, en cliquant sur Modules -> Modules et services puis en cliquant en haut à droite sur Ajouter un nouveau module.

~ Configuration de la devise BCEAO XOF(FCFA)

Pour configurer la devise BCEAO XOF(FCFA), dans le menu de gauche de l'interface admin de PrestaShop cliquez sur Localisation > Devises.

Cliquez ensuite sur Ajouter une nouvelle devise en haut à droite, puis créez la devise XOF(FCFA) et configurez son taux de change.

# Options de configuration de la devise :
  • Nom de la devise: Entrez le nom de la devise (Franc CFA).
  • Code ISO: Entrez le code ISO de la devise (XOF).
  • ISO code numérique: Entrez le code ISO numérique correspondant à la devise (4217).
  • Symbole: Entrez le symbole correspondant à la devise (FCFA).
  • Taux de change: Entrez le taux de change actuel de la devise par rapport à la devise principale (l'EURO par défaut).
  • Format de la devise: Choisissez un format pour la devise.
  • Décimales: Permet d'accepter les montants en décimales.
  • Espace: Espace entre les centaines.
  • Activer: Activez la devise.
  • Cliquez sur Enregistrer afin que vos modifications soient prises en compte.

3. Configuration du plugin

  • Activez et configurez le module PayDunya en cliquant, dans le menu de gauche de PrestaShop, sur Modules -> Paiement. Cliquez sur Afficher toutes les solutions de paiement et recherchez le module PayDunya.
  • Connectez-vous sur PayDunya et récupérez les clés d'API en cliquant au niveau de Intégration API puis sur Détails de votre application.
  • Retournez sur l’interface d’administration de Prestashop et renseignez les champs requis de configuration du plugin PayDunya.

Les options de configuration sont les suivantes:

  • Clé Principale: Entrez la Clé principale fournie par PayDunya lors de la création de votre application.
  • Clé Privée de Production: Entrez la Clé Privée de production fournie par PayDunya lors de la création de votre application.
  • Token de Production: Entrez le Token de production fourni par PayDunya lors de la création de votre application.
  • Clé Privée de Test: Entrez la Clé Privée de test fournie par PayDunya lors de la création de votre application.
  • Token de Test: Entrez le Token de test fourni par PayDunya lors de la création de votre application.
  • Mode: Choisissez Test si vous êtes encore à l'etape des paiements tests et Live une fois que vous serez prêt à accepter des paiements réels.
  • Texte du bouton de paiement: Texte que verra le client lors du paiement de sa commande (il est conseillé de laisser la valeur par défaut).
  • Description du bouton de paiement: Description de la solution de paiement PayDunya que verra le client lors du paiement de sa commande (il est conseillé de laisser la valeur par défaut).
  • Message affiché en cas de succès de paiement: Message que verra le client après avoir effectué sa commande.
  • Message affiché en cas d'erreur de paiement: Message que verra client si pour une raison ou une autre la transaction n'a pu être effectuée.
  • Cliquez sur Enregistrer afin que vos modifications soient prises en compte.

WHMCS

1. Génération de vos clés d'API

Cliquez ici pour suivre notre guide expliquant comment générer vos clés API d'intégration PayDunya.

2. La passerelle de paiement PayDunya sur WHMCS

~ Installation manuelle

  • Téléchargez notre module PayDunya WHMCS ici
  • Extraire le contenu du fichier téléchargé.
  • Copiez le fichier paydunyagatewaymodule.php dans le dossier /modules/gateways/ de votre plateforme WHMCS, ensuite copiez les fichiers se trouvant dans le dossier callback au niveau du dossier /modules/gateways/callback/ de votre plateforme WHMCS.

~ Configuration de la devise BCEAO XOF(FCFA)

Pour configurer la devise BCEAO XOF(FCFA), dans l'interface d'administration WHMCS cliquez sur Setup -> Payments -> Currencies.

Créez ensuite la devise XOF(FCFA) et configurez son taux de change.

# Options de configuration de la devise :
  • Currency Code: Entrez le code ISO de la devise (XOF).
  • Prefix: Entrez le symbole qui vas précéder le montant (FCFA).
  • Suffix: Entrez le symbole qui s'affichera à droite du montant (XOF).
  • Format: Choisissez un format pour la devise.
  • Base Conv. Rate: Entrez le taux de change actuel de la devise par rapport à la devise principale.
  • Update Pricing: Permet de mettre à jour les prix en se basant sur le taux de change.
  • Cliquez sur Save Changes afin que vos modifications soient prises en compte.

3. Configuration du plugin

  • Activez le module de paiment PayDunya au niveau de Setup -> Payments -> Payment Gateways. Cliquez sur All Payment Gateways, cherchez PayDunya et cliquez dessus.
  • Connectez-vous sur PayDunya et récupérez les clés d'API en cliquant au niveau de Intégration API puis sur Détails de votre application.
  • Retournez sur l’interface d’administration de WHMCS et renseignez les champs requis de configuration du plugin PayDunya.

Les options de configuration sont les suivantes:

  • Show on Order form: Cochez/Décochez cette case afin d'activer/désactiver le module de paiement PayDunya.
  • Master Key: Entrez la Clé principale fournie par PayDunya lors de la création de votre application.
  • Live Private Key: Entrez la Clé Privée de production fournie par PayDunya lors de la création de votre application.
  • Live Token: Entrez le Token de production fourni par PayDunya lors de la création de votre application.
  • Test Private Key: Entrez la Clé Privée de test fournie par PayDunya lors de la création de votre application.
  • Test Token: Entrez le Token de test fourni par PayDunya lors de la création de votre application.
  • Sandbox Mode: Cochez cette case si vous êtes encore à l'etape des paiements tests. N'oubliez pas de la décocher une fois que vous serez prêt à accepter des paiements réels.
  • Convert To for Processing: Sélectionnez la devise XOF.
  • Cliquez sur Save Changes afin que vos modifications soient prises en compte.

Images, Logos & Branding PAYDUNYA

Nous mettons à votre disposition nos images de branding et logos afin que vous puissiez les utiliser au niveau de vos applications web et mobile au cas où le besoin se ferait ressentir.

Faites un clic droit sur l'image que vous souhaitez télécharger et choisissez l'option "Enregistrer l'image sous".

Payer avec PayDunya
Payer avec PayDunya
Payer avec PayDunya
Payer avec PayDunya
Payer avec PayDunya
Payer avec PayDunya