HTTP/JSON

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.

GENERATION OF API KEYS

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:

  • First you need have a PayDunya Business account activated. Create one if it is not yet the case.
  • Login to your account and click on oneAPI at the menu level on the left.
  • Click on the button Set up a new application and fill out the form.
  • Choose Test mode, I want to make payment tests and Enable production mode.

APIs

PayDunya offers you three 03 APIs:

  • two 02 Payment APIs allowing you to get paid PAR and PSR .
  • and a third redistribution 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 HTTP API is exclusively based on the 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.

Info


All of the success responses return a JSON object containing a response_code equal to 00 .

Payment And Redirection

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.


Endpoints API TEST

https://app.paydunya.com/sandbox-api/v1/checkout-invoice/create


Endpoints API PRODUCTION

https://app.paydunya.com/api/v1/checkout-invoice/create


request HTTP POST


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"

Expected answer


{
    "response_code":"00",
    "response_text":"https://app.paydunya.com/sandbox-checkout/invoice/test_RHICF0HboN",
    "description":"Checkout Invoice Created",
    "token":"test_RHICF0HboN"
}

Trick


To receive the complete payment information structure, you can make a request with the received token in the above response.

Payment And Redistribution

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.


Endpoints API

https://app.paydunya.com/api/v1/direct-pay/credit-account


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

Expected answer


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

BASIC CONFIGURATION

1- JSON structure complete data to send


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

2 - Adding items or items to the PayDunya invoice (optional)


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

3 - Add taxes (optional)


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

4 - Restricting payment methods to display (optional)


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.

Trick


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

5 - Adding custom data (optional)


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.

Info


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.


Example 1


"custom_data": {
    "categorie": "Contest",
    "periode":  "Christmas 2015",
    "numero_gagnant": 5,
    "prix" : "50% discount voucher"
}

Example 2


"custom_data": {
    "phone_brand": "Nokia",
    "IMEI": "72892821010728",
    "model": "Luna"
}

6 - Configuring a redirect URL after canceling payment


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

7 - Configuring a redirect URL after confirming payments


You can optionally define a URL where your customers will be redirected after they have successfully paid for their order.

Info


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

8 - Configuring IPN (Instant Payment Notification)


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

  Mandatory


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.


Expected answer:


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',
    ),
  )  

  Mandatory


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.

 Mandatory


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

PAYMENT STATUS

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.

Info


Remember to always add the value of your bill token to endpoints.


Endpoints API TEST

https://app.paydunya.com/sandbox-api/v1/checkout-invoice/confirm/[invoice_token]


Endpoints API PRODUCTION

https://app.paydunya.com/api/v1/checkout-invoice/confirm/[invoice_token]

REQUEST HTTP GET


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"

EXPECTED ANSWER


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

 Mandatory


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.


Example of expected response: Highlighted failure



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