PYTHON


  IMPORTANT


Lire toutes les sections en bleues pour mieux comprendre la documentation et les sections en orange signifiant l'alerte afin d'éviter des erreurs à commettre durant les intégrations et les procédures détaillées pour les intégration.

Génération de vos clés 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 chronologiquement la marche à suivre :

Installation


Installation via pip


pip install paydunya

Installation depuis les sources


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

Configuration de base

Info

Connectez-vous à votre compte et cliquez sur Intégration API au niveau du menu à gauche 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

Info

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.

Info

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 de l'URL de notification instantanée de paiement sur une instance de facture

Alerte

Cette configuration écrasera les paramètres globaux de redirection 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"

Important

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

Info

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

Info

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']

Info

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

Alerte

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:
   print "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.

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:

  • 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).

  • 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 PAIMENT


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",
    description="Belle chemise"
    total_price="5000"
  ),
]
invoice = paydunya.Invoice(store)
invoice.add_items(items)

Info

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

Info

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.

Info

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.

Info

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

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%"),
])

Restriction des moyens de paiement à afficher (facultatif)


Par défaut, les moyens de paiement activés au niveau de la configuration de votre intégration seront tous affichés sur la page de paiement pour l'ensemble de vos factures.

Si toutefois vous souhaitez resteindre la liste des moyens de paiements à afficher sur la page de paiement d'une facture donnée, nous vous offrons la possibilité de le faire en utilisant les méthodes AddChannel et AddChannels.

Info

Actuellement, les moyens de paiement disponibles sont les suivants: card, wari, jonijoni-senegal, orange-money-senegal, paydunya.


# Ajout des moyens de paiement de manière individuelle
invoice.add_channel('wari')
invoice.add_channel('card')

# Ajout de plusieurs moyens de paiement à la fois
invoice.add_channels(['card', 'jonijoni-senegal', 'orange-money-senegal'])

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.

Info

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"

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.

Info

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