NAV
Example

Introduction

This Documentation is dedicated to dusupay Merchants or developers with websites/webapps that have/need to integrate dusupay Payment APIs available.

Welcome to the Dusupay’s Merchant/Website API Doc! Use this Documentation to receive payments on your website or webapp in a more reliable manner.

You can view examples/sample codes in the dark area to the right, where applicable.

Get started

Requirements

Live URL
https://dusupay.com

Sandbox URL
http://sandbox.dusupay.com

Create dusupay account from
https://dusupay.com/users/login

Create Merchant account from
https://dusupay.com/pages/dusupay_become_merchant

  1. Sign-In your Dusupay account, click “Merchant” from the top menu
  2. A list of your merchant accounts will display.
  3. Select “New merchant account” to create Merchant account if the list is empty
  4. From the list, click the merchant account name
  5. Next you will view a page with sample Dusupay buttons that might suit your Dusupay merchant account of your intended website
    They also include code you can copy and test with on your website

Create FormButton

<form method="post" action="https://dusupay.com/dusu_payments/dusupay" target="_blank">
  <input type="hidden" name="dusupay_merchantId" value="1000" required>
  <input type="hidden" name="dusupay_amount" value="5000" optional>
  <input type="hidden" name="dusupay_currency" value="UGX" required>
  <input type="hidden" name="dusupay_itemId" value="Item1" required>
  <input type="hidden" name="dusupay_itemName" value="MyItem" required>
  <input type="hidden" name="dusupay_transactionReference" value="112410" required>
  <input type="hidden" name="dusupay_redirectURL" value="" optional>
  <input type="hidden" name="dusupay_successURL" value="" optional>
  <!--<input type="hidden" name="dusupay_logo" value="" optional>-->
  <!--<input type="hidden" name="dusupay_hash" value="hashValue..." required>-->
  <input type="image" name="submit" src="https://dusupay.com/img/paybuttons/dusupaybtn6.png" />
</form>

This is an ordinary form that can process the transaction from dusupay in a new page. You can change its behavior using the target attribute

Create WidgetButton

<div id="dusupay-btn"><a href="javascript:void();"><img src="https://dusupay.com/img/paybuttons/dusupaybtn6.png" /></a></div>
<script 
dusupay_merchantId="1000"
dusupay_amount="5000"
dusupay_currency="UGX"
dusupay_itemId="Item1"
dusupay_itemName="MyItem"
dusupay_transactionReference="112410"
dusupay_render="widget"
dusupay_redirectURL=""
dusupay_successURL=""
dusupay_environment="sandbox" 
id="dusupay" type="text/javascript" async=true> 
document.write(unescape('%3Cscript src="' +
    (("https:" == document.location.protocol) ? "https://dusupay.com" : "http://dusupay.com") +
  '/js/widgets.js" type="text/javascript"%3E%3C/script%3E'
));
</script>

Data Parameters

The Dusupay API/form uses the following parameter names for transaction data:

<?php
    // PHP - creating dusupay_hash for the form data
    // Hashing algorithm = sha1
    // Copy your security mackey from your merchant page
    $mackey = 'My-Security-Mackey';
    $stringData = $dusupay_merchantId 
                . $dusupay_amount 
                . $dusupay_currency 
                . $dusupay_itemId 
                . $dusupay_itemName 
                . $dusupay_transactionReference;

    $dusupay_hash = hash_hmac('sha1',$stringData, $mackey);
?>
<?php
    //PHP Example - Decording hash sent through the IPN notification

    //Get the timestamp to identify all transaction
    $timestamp = '123243';

    //Concatenate the string data to post
    $stringData = $transaction->amount.$transaction->currency.$transaction->item_id.$transaction->transaction_ref.$timestamp;

    //Generate hash key - This is returned with the IPN notification POST request to dusupay_successURL
    $hashid = hash_hmac('sha1', $stringData, $mackey); //create hashing algorithm to SHA1

?>
Parameter Required Example Description
dusupay_hash No Security token/hash to protect your transaction data.
Hashing your data
Use sha1 algorithm to hash your data. Data should be concatenated as shown in the black box on the right.
dusupay_merchantId Yes 1030

Your MerchantID.
Click to create one

It can be found on your merchant page created

dusupay_amount Yes 5000 Amount to paid
dusupay_currency Yes UGX

ISO Currency.

dusupay_itemId Yes 12345 Unique ID of the item the customer is paying for.
dusupay_itemName Yes Bag

The item name the customer is paying for.

- Maximum length is 20 charaters

dusupay_transactionReference Yes GE34eRre34

Your unique transaction reference generated by your web app

- This uniquely identifies the transaction you want processed.

- This is also returned to your merchant website as a callback in-case your payment request contains a callback url in the dusupay_successURL parameter

dusupay_redirectURL No

This is a redirect URL when the user has completed the payment. The customer is redirected from Dusupay back to your the merchant website

dusupay_successURL No

This is a callback URL called by Dusupay with the transaction details when the status of the transaction changes or fails or is successful

You can use the transaction reference and your merchantId to verify the transaction status through the check_status API

dusupay_render No widget Use this option to show dusupay payment widget within website.

This is done by setting the value of input fields dusupay_render = “widget”

This also requires an element with id=“dusupay-btn” as your dusupay button
dusupay_logo No Full URL of Your company logo.
125px X 125px Square Logo Recommended
dusupay_environment No sandbox set dusupay_environment=sandbox when processing with the sandbox using the widget button only.

Transactions API

Check Transaction Status

Live URL
https://dusupay.com/transactions/check_status/param1/param2.json 

Sandbox URl
http://sandbox.dusupay.com/transactions/check_status/param1/param2.json
Example Response(.json)

{
  "Response":
  {
   "dusupay_transactionId":"1151001074",
   "dusupay_amount":5000,
   "dusupay_currency":"UGX",
   "dusupay_itemId":"Item1",
   "dusupay_transactionReference":"740",
   "dusupay_charge":0,
   "dusupay_chargeCurrency":"USD",
   "dusupay_transactionStatus":"COMPLETE",
   "status":"success"
  }
}

This API allows you to check the status of your transaction or payment made by the user that could be in a PENDING state in you web app.

URL-Parameters Description
param1 Replace this with your MerchantId
param2 Replace this with the transaction_reference of your webapp

Claim Delivery Code

  Live
  https://dusupay.com/merchant-api/transactions/payments/claimDeliveryCode.json
  Sandbox
  http://sandbox.dusupay.com/merchant-api/transactions/payments/claimDeliveryCode.json
    Sample Request Data
    {
      "merchant_id": "10246",
      "transaction_id": "1170209081619256704543171",
      "delivery_code": "9NKACN3GBC",
      "timestamp": "1485987100",
      "signature": "ab68e8b164ae2e3f3f852764f5f7e4e7960c3bed"
    }
  Note
  1. You can replace transaction_ref for transaction_id 
  2. But Make sure you have unique transaction_ref per transaction passed to us
  3. transaction_id is more reliable and recommended

  - transaction_ref is generated by your system. Usually the OrderId

    Sample Response Data
    {
      "Response":{
        "message":"Request completed successfully",
        "status":"success"
      }
    }
<?php
    // Generate Request Data
    // =======================

    // Create Data Array
    $requestData = [
        'merchant_id'=>'Your Merchant ID',
        'amount'=>100,
        'currency'=>'NGN',
        'account_number'=>'Receipient Account Number',
        'account_name'=>'Receipient Account Number Name',
        'bank_code'=>'058',
        'country'=>'NG',
        'phone'=>'256704543171',
        'timestamp'=>time(),
    ];

    // Generate Request Signature
    $requestData['signature'] = getSignature($requestData,'Your Merchant MacKey');

    // Function to generate request signature
    function getSignature($requestData, $merchantMackey){
        ksort($requestData);
        $stringData = '';
        foreach ($requestData as $key => $value) {
            if(in_array($key, ['signature'])) continue;
            $stringData .= $value;
        }
        return hash_hmac('sha1', $stringData, $merchantMackey);
    }
?>

This API allows you to complete the payment that required a DeliveryCode. Your transaction will be creditable to your merchant account when the DeliveryCode validated correctly

Request Method

POST

Request Data

application/json

Response Data

application/json

Generating the signature

To Generate a request Signature Please follow the steps below

step1 Get Your Merchant MacKey from your merchant account page

step2 Create an array of the data to be posted excluding the {signature} array key

step3 ksort the data array generated from step2. This arranges the ArrayKeys in ASCENDING Order

step4 Join the data array values into one string with no space

step5 Create the Signature like hash_hmac(‘sha1’, {joinedString}, {Mackey})

step6 Include the {signature} key to the request data

Note An Example of this implementation has been included in the sample on the right

Mobile Money Pay Outs API

Check Mobile Money Balance(Withdrawable)

Live URL
https://dusupay.com/merchants/check_mobile_money_withdrawable_balance/param1/param2/param3.json 

Sandbox URl
http://sandbox.dusupay.com/merchants/check_mobile_money_withdrawable_balance/param1/param2/param3.json
<?php $param3 = hash_hmac('sha1', ($param1.$param2), $mackey); ?>
Example Response(.json)

{
  "Response":
  {
   "merchant_id":"1001",
   "amount":5000,
   "currency":"UGX"
   "status":"true/false",
   "message":"",
  }
}
Example Response(.xml)

<Response>
  <merchant_id>1001</merchant_id>
  <amount>5000</amount>
  <currency>UGX</currency>
  <status>true/false</status>
  <message></message>
</Response> 

This API allows you to check how much you can withdraw/payout through mobile money from your merchant account.

URL-Parameters Description Example
param1 Replace this with your MerchantId 1001
param2 Replace this with UNIX Timestamp (Integer) 1460546650
param3 Replace this with Hash/Token (String) hash_hmac(‘sha1’, JOIN_STRING(param1,param2), mackey)

Note:
- The URLs end in .json
- You can also use a .xml extension to receive results in XML format.

Withdraw Mobile Money Balance

Live URL
https://dusupay.com/merchants/withdraw_mobile_money_withdrawable_balance_v1/param1/param2/param3/param4/param5/param6.json 

Sandbox URl
http://sandbox.dusupay.com/merchants/withdraw_mobile_money_withdrawable_balance_v1/param1/param2/param3/param4/param5/param6.json
<?php $param6 = hash_hmac('sha1', ($param1 . $param2 . $param3 . $param4 . $param5), $mackey); ?>
Example Response(.json)

{
  "Response":
  {
   "external_reference":"25591",
   "withdraw_request_id":"38",
   "merchant_id":"1001",
   "amount":5000,
   "currency":"UGX",
   "status":"true/false",
   "transaction_status":"PENDING",
   "message":"Request PENDING",
   "new_balance":"23000",
   "amount_sent":"20000",
   "currency_sent":"UGX",
   "charge_amount":"1500",
   "charge_currency":"UGX",
  }
}

This API allows you to withdraw/payout your mobile-money-withdrawable-balance from your merchant account to the mobile money number such that the target gets the exact intended money in their currency

i.e

If i request to payout amount of 100 to 254704543171, The 100 will be expected/assumed to be in KES since the operator with country code 254 is Kenya and expects KES

Therefore (100 + Charge) will be debited off your merchant account But this time the customer will receive exactly 100KES

This second API method is recommended if you are aware of the amount you want to payout your customer in the mobile money operator’s currency.

URL-Parameters Description Example
param1 Replace this with your MerchantId 1001
param2 Amount in mobile money operator’s currency. Currency(Integer) 100 where it is 100KES if sending to 254704543171
param3 AccountNumber/Phone (String) 256704543171
Supported Phone-Country-Codes = [256,254]
param4 AccountHolder Name (String) customer1
param5 UNIX Timestamp (Integer) 1460546650
param6 Replace this with Hash/Token (String) hash_hmac('sha1’, JOIN_STRING(param1,param2), mackey)

Note:
- The URLs end in .json

IPN - Payout Status(IPN) Webhook(URL)


    // POST Fields - The fields below will be Posted to your sub-account webhootk url

    "id":"3",
    "amount":"5600",
    "charge":"100",
    "currency":"KES",
    "rate":"1",
    "account_id":"4",
    "account_type":"MobileMoneyPayoutAccount",
    "transfer_type":"WITHDRAW",
    "created":"11/10/16, 1:37 PM",
    "modified":"5/23/17, 2:38 PM",
    "status":"COMPLETE",
    "external_reference":"53590",
    "customer_phone":"254704549719",
    "customer_name":"Hillary.N"

Simply set the Payout Status(IPN) Webhook(URL) url under your merchant account

Bank Payouts API

Send Funds To Bank (Withdraw to Bank)

Live URL
https://dusupay.com/merchant-api/payout/bank/sendFromSubAccount.json

Sandbox URl
http://sandbox.dusupay.com/merchant-api/payout/bank/sendFromSubAccount.json
Sample Request Data

{
    "merchant_id": 1000,
    "amount": 100,
    "currency": "NGN",
    "account_number": "0044823848",
    "account_name": "AccountName",
    "bank_code": "058",
    "country": "NG",
    "timestamp": "1486646942",
    "phone": "256704543171",
    "signature": "ecda7845918d9818e6f7c8485428291f52ecc934"
}
Example Response

{
  "response": {
    "message": "Request Sent",
    "transaction_id": 17,
    "charge_amount": 500,
    "charge_currency": "NGN",
    "status": true
  }
}

This API allows you to send Funds from your Merchant Bank SubAccount to the receipients Bank Account for the supported banks.

Request Method

POST

Request Data Type

application/json

Response Data Type

application/json

Generate Request Signature

<?php
    // Generate Request Data
    // =======================

    // Create Data Array
    $requestData = [
        'merchant_id'=>'Your Merchant ID',
        'amount'=>100,
        'currency'=>'NGN',
        'account_number'=>'Receipient Account Number',
        'account_name'=>'Receipient Account Number Name',
        'bank_code'=>'058',
        'country'=>'NG',
        'phone'=>'256704543171',
        'timestamp'=>time(),
    ];

    // Generate Request Signature
    $requestData['signature'] = getSignature($requestData,'Your Merchant MacKey');

    // Function to generate request signature
    function getSignature($requestData, $merchantMackey){
        ksort($requestData);
        $stringData = '';
        foreach ($requestData as $key => $value) {
            if(in_array($key, ['signature'])) continue;
            $stringData .= $value;
        }
        return hash_hmac('sha1', $stringData, $merchantMackey);
    }
?>

To Generate a request Signature Please follow the steps below

step1 Get Your Merchant MacKey from your merchant account page

step2 Create an array of the data to be posted excluding the {signature} array key

step3 ksort the data array generated from step2. This arranges the ArrayKeys in ASCENDING Order

step4 Join the data array values into one string with no space

step5 Create the Signature like hash_hmac(‘sha1’, {joinedString}, {Mackey})

step6 Include the {signature} key to the request data

Note An Example of this implementation has been included in the sample on the right

Get Countries Supported

    Live URL
    https://dusupay.com/merchant-api/payout/bank/getSupportedCountries/{country}.json

    Sandbox URl
    http://sandbox.dusupay.com/merchant-api/payout/bank/getSupportedCountries/{country}.json
    Sample Response
    {
        "response": {
            "countries": [
                "NG",
                "KE"
            ]
        }
    }

This API will help you get a list of the countries supporting bank payouts.

Request Method

GET

Request Data Type

application/json

Response Data Type

application/json

Get Banks Supported

    Live URL
    https://dusupay.com/merchant-api/payout/bank/getSupportedBanks/{country}.json

    Sandbox URl
    http://sandbox.dusupay.com/merchant-api/payout/bank/getSupportedBanks/{country}.json

    Default Country
    NG - Nigeria
    Sample Response
    {
        "response": {
            "banks": {
                "401": "ASO Savings and \u0026 Loans",
                "044": "Access Bank",
                "323": "Access Money",
                "317": "Cellulant",
                "303": "ChamsMobile",
                "023": "CitiBank"
            }
        }
    }

You can fetch a list of the banks supported per country supported

Request Method

GET

Request Data Type

application/json

Response Data Type

application/json

IPN - Payout Status(IPN) Webhook(URL)


    // POST Fields - The fields below will be Posted to your sub-account webhootk url

    "id":"13",
    "amount":"10",
    "charge":"13.5694",
    "currency":"USD",
    "rate":"1",
    "account_id":"6",
    "account_type":"BankPayoutAccount",
    "transfer_type":"WITHDRAW",
    "created":"5/2/17, 10:48 PM",
    "modified":"5/23/17, 2:51 PM",
    "status":"COMPLETE",
    "external_reference":"",
    "customer_phone":"256704543171",
    "customer_name":"Hillary",
    "customer_bank_account":"334343",
    "customer_bank_name":"Eco Bank"

Simply set the Payout Status(IPN) Webhook(URL) url under your merchant account

Transaction/Request statuses

Status Meaning
PENDING Transaction is pending.
COMPLETE Transaction completed successfully.
NOTVERIFIED Transaction completed but waiting user validation via phone and email. Status will change to either REFUNDED or COMPLETE
REFUNDED Transaction was detected as a fraud transaction. Cash was refunded.
FAILED Transaction failed.
CANCELLED Transaction was cancelled
INVALID Transaction may not have been found.
true Request was successful.
false Request failed.

Payment Process Flow

This expected payment flow helps to give you a picture of how the payment process starts and finishes af integration completely

Dusupay Buttons

The Dusupay Provied the following payment buttons:

File name Button
dusupaybtn6.png DusuPay
dusupaybtn1.png DusuPay
dusupaybtn2.png DusuPay
dusupaybtn3.png DusuPay
dusupaybtn4.png DusuPay
dusupaybtn5.png DusuPay

Plugins And Libraries

Plugins

Platform Price Download Link
Woocommerce 5.99 GBP Download Now
Opencart 9.99 GBP Download Now