Read all the blue sections to better understand the documentation and the orange sections signifying the alert so avoid mistakes to be made during integrations and detailed integration procedures.
API keys are your digital references towards PayDunya systems. We use them to identify your account and the applications you will create. These keys are necessary for any integration of the APIs of PayDunya's payments APIs. Here are the steps to follow:
Test mode, I want to make payment tests and
Enable production mode.
PayDunya offers you three 03 APIs:
02 Payment APIs allowing you to get paid PAR and PSR .
API (PER) that allows you to split transaction amount with your suppliers.
You need to integrate one of the payment APIs depending on the desired workflow. The redistribution API is optional, so feel free to integrate it depending on your needs.
Our JSON data exchange format. All responses to HTTP POST/GET requests from/to our API are based on JSON objects, except the data format that we post on the url callback which is of type HTTP application/x-www-form-urlencoded.
All JSON objects returned at a response level contain at least the response_code and response_text nodes. The response_code node represents the technical code of the response, and the response_text node provides explanations of the response. Your integration must rely heavily on these nodes in order to function properly.
All of the success responses return a JSON object containing a response_code equal to 00 .
PayDunya's "Payment And Redirection" service allows you to redirect your customer to our platform so that it can complete the payment process. We recommend using the "Payment And Redirection" API as it is the most suitable in 99% of cases. The main advantage of this option is that customers can choose to pay from a variety of payment options available on our platform. In addition, if a new option is added in the future, it will appear directly on the payment page without you having to change anything in your source code.
https://app.paydunya.com/sandbox-api/v1/checkout-invoice/createhttps://app.paydunya.com/api/v1/checkout-invoice/create
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"
{
"response_code":"00",
"response_text":"https://app.paydunya.com/sandbox-checkout/invoice/test_RHICF0HboN",
"description":"Checkout Invoice Created",
"token":"test_RHICF0HboN"
}
To receive the complete payment information structure, you can make a request with the received token in the above response.
This option is very interesting if you want to create your own payment solution over PayDunya or if you have to pay back a certain percentage for each sale. Money is received on the accounts recipients and the service is not charged.
You can transfer funds to other PayDunya customer accounts from your account via
the API of Payment And Redistribution. For security reasons, you must explicitly enable the option to Payment And Redistribution in the configuration of your integration/application by logging into your Business PayDunya account. You can always enable or disable the Payment And Redistribution by updating the configuration of your integration/application by logging into your Business PayDunya account.
https://app.paydunya.com/api/v1/direct-pay/credit-account
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"
{
"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"
}
Here is the complete structure of the PayDunya Billing JSON object. Most of the items are optional, but make it a habit to provide them all as it will give you a lot more flexibility. The required JSON nodes for submitting an HTTP POST invoice payment request to our API Endpoints are: the invoice root node and its total_amount child node and the node root store and its child node name .
{
"invoice": {
"items": {
},
"taxes": {
},
"total_amount": 5000,
"description": ""
},
"store": {
"name": "The Choco store",
"tagline": "",
"postal_address": "",
"phone": "",
"logo_url": "",
"website_url": ""
},
"custom_data": {
},
"actions": {
"cancel_url": "",
"return_url": "",
"callback_url": ""
}
}
Refer to the complete JSON structure to know exactly where to insert the following structure. The "items" are used to display to the customer on the payment page the list of items he has ordered. PayDunya will not use any of the amounts declared in "items" to bill the customer.
{"items": {
"item_0": {
"name": "Croco shoes",
"quantity": 3,
"unit_price": "10000",
"total_price": "30000",
"description": "Shoes made of genuine crocodile skin that hunts poverty"
},
"item_1": {
"name": "Ice Shirt",
"quantity": 1,
"unit_price": "5000",
"total_price": "5000",
"description": ""
}
}
If you wish to display on the PayDunya invoice the taxes that you apply (VAT, delivery costs ...) you can do it using the JSON node taxes as shown below.
"taxes": {
"tax_0": {
"name": "TVA (18%)",
"amount": 6300
},
"tax_1": {
"name": "Delivery",
"amount": 1000
}
}
If you need to add additional data (eg for a contest, you can save information about each winner) for later use, we offer you the possibility to save this data on our servers and to be able to recover them once the payment is successful.
Custom data is not displayed on the payment page, invoices/receipts, downloads, or impressions. They are only retrieved using our confirm callback action at the API level.
"custom_data": {
"categorie": "Contest",
"periode": "Christmas 2015",
"numero_gagnant": 5,
"prix" : "50% discount voucher"
}
"custom_data": {
"phone_brand": "Nokia",
"IMEI": "72892821010728",
"model": "Luna"
}
You can optionally define a URL where your customers will be redirected after they have clicked the "Cancel payment" button.
"actions": {
"cancel_url": "http://www.magasin-le-choco.com/cancel_url.php"
}
You can optionally define a URL where your customers will be redirected after they have successfully paid for their order.
PayDunya will add ?token=invoice_token to your URL. We explain how to use this token at the documentation level of different API clients (PHP, Java, .NET, Ruby, Python, Node JS).
"actions": {
"return_url": "http://www.magasin-le-choco.com/return_url.php"
}
It may be that for somes reasons, that the confirmation of payment is not instantaneous (for example the time that the client types his secret code on his phone or the latency of the telephone network), the IPN allows you instantly receive transaction information when the payment is confirmed.
The IPN corresponds to the URL of a file or an endpoint on your server which you want to receive the information of the payment transaction, this information is to be processed in backoffice. PayDunya uses this URL to send you information about the payment transaction instantly by POST .
"actions": {
"callback_url": "http://www.magasin-le-choco.com/callback_url.php"
}
The successful validation of the payment transaction returns the structure below containing the customer information, the URL of its PayDunya invoice in PDF format and also a hash to verify that the received data come from our servers.
Furthermore, it is essential to understand for information that canceled or failed payments keep the same response format except the value of the status which changes: for failed payments the status becomes failed and for canceled payments becomes canceled.
array (
'data' =>
array (
'response_code' => '00',
'response_text' => 'Transaction Found',
'hash' => '8c6666a27fe5daeb76dae6abc7308a557dca5be1bda85dfe5d81fa330cdc0bc3c4b37765fe5d2cc36aa2ba0f9284226a80f5488d14740fa70769d6079a179406',
'invoice' =>
array (
'token' => 'test_jkEdPY8SuG',
'items' =>
array (
'item_0' =>
array (
'name' => 'Chaussures Croco',
'quantity' => '3',
'unit_price' => '10000',
'total_price' => '30000',
'description' => 'Chaussures faites en peau de crocrodile authentique qui chasse la pauvreté',
),
'item_1' =>
array (
'name' => 'Chemise Glacée',
'quantity' => '1',
'unit_price' => '5000',
'total_price' => '5000',
'description' => '',
),
),
'taxes' =>
array (
'tax_0' =>
array (
'name' => 'TVA (18%)',
'amount' => '6300',
),
'tax_1' =>
array (
'name' => 'Livraison',
'amount' => '1000',
),
),
'token': 'test_Jh2T8skw1j',
'total_amount' => '42300',
'description' => 'Paiement de 42300 FCFA pour article(s) achetés sur Magasin le Choco',
),
'custom_data' =>
array (
'categorie' => 'Jeu concours',
'periode' => 'Noël 2015',
'numero_gagnant' => '5',
'prix' => 'Bon de réduction de 50%',
),
'actions' =>
array (
'cancel_url' => 'http://magasin-le-choco.com/cancel_url.aspx',
'callback_url' => 'http://magasin-le-choco.com/callback_url.aspx',
'return_url' => 'http://magasin-le-choco.com/return_url.aspx',
),
'mode' => 'test',
'status' => 'completed',
'customer' =>
array (
'name' => 'Alioune Faye',
'phone' => '774563209',
'email' => '[email protected]',
),
'receipt_url' => 'https://paydunya.com/sandbox-checkout/receipt/pdf/test_jkEdPY8SuG.pdf',
),
)
The hash returned by PayDunya is the hash of your MasterKey. This hash will allow you to make sure that the data you have received comes from our servers. The algorithm used to obtain the hash is SHA-512. In the expected response, a failure message is entered in the fail_reason node only for failed or canceled bank card transactions.
PayDunya Make a Post request of type application/x-www-form-urlencoded on your callback endpoint and post a data table containing the payment information. You must use the "data" key before recovering a node. The returned structure is located under the index "data".
When you make a Payment With Redirection (PAR) request or a Payment Without Redirection (PSR) request, PayDunya returns a JSON object containing a node representing the invoice token. You can use the value of this token to check the payment status of your bill. The status of an invoice can be either pending (pending) , canceled (canceled) , or completed (completed) depending on if yes or not the customer has paid the bill.
Remember to always add the value of your bill token to endpoints.
https://app.paydunya.com/sandbox-api/v1/checkout-invoice/confirm/[invoice_token]https://app.paydunya.com/api/v1/checkout-invoice/confirm/[invoice_token]
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"
{
"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",
"fail_reason": "",
"customer": {
"name": "Alioune Faye",
"phone": "774563209",
"email": "[email protected]"
},
"receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}
The hash returned by PayDunya is the hash of your MasterKey. This hash will allow you to make sure that the data you have received comes from our servers. The algorithm used to obtain the hash is SHA-512. In the expected response, a failure message is entered in the fail_reason node only for failed or canceled bank card transactions.
For PCI-DSS certified companies, in the expected response the card number is entered in the pan node.
In the expected response, a failure message and his description is entered in theerrors node only for failed or canceled bank card transactions.
{
"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": "live",
"status": "cancelled",
"fail_reason": "Payment cancelled by customer",
"customer": {
"name": "Alioune Faye",
"phone": "774563209",
"email": "[email protected]"
},
"errors": {
"message": "Payment cancelled by customer",
"description": "Payment cancelled by customer"
},
"receipt_url": "https://paydunya.com/sandbox-checkout/receipt/pdf/test_Jh2T8skw1j.pdf"
}