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": {
},
"channels": ["expresso-sn","mtn-benin"],
"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
}
}
By default, the payment methods activated in your integration configuration will all be displayed on the payment page for all of your invoices.
However, if you wish to restrict the list of payment methods to be displayed on the payment page of a given invoice, we offer you the possibility of doing so by using the channels key.
To obtain the names of the operators to assign as values to the channels key, please consult this link which lists the different operators available.
{
// Adding a single payment method
"channels":"card"
// Adding multiple payment methods at once
"channels":["card", "mtn-benin", "orange-money-senegal"]
}
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 creating an invoice with PayDunya, a token is generated. This token is used to initiate payment and to check the status of the transaction. The status of a transaction can be PENDING, CANCELLED, or COMPLETED, depending on whether the customer has paid the invoice.
Here is an explanation of each status :
Pending : This status means that the payment is being processed. You can check the final status of the transaction in using the Check Status. This status can automatically change after 24 hours (when the invoice is created) to cancelled if the invoice has not been paid.
Cancelled : This status indicates that the payment has been canceled.
Completed : This status indicates that the payment was made successfully.
Failed : This status indicates that the payment failed.
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"
}