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 send and receive funds 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

  1. Sign into your Dusupay account and create a new merchant account if you do not have one already.
  2. Your account can instantly receive payments as soon as it’s created.
    However, you will need your new merchant account approved to make payouts or get settled. You can contact us at info@dusupay.com regarding this.

Request/Response

Requests

Base Url

https://api.dusupay.com

Responses

General Response format

{
    "code": 202,
    "status": "accepted",
    "message": "Transaction in Progress",
    "data": ...
}
Parameter Description
code this is similar to the standard HTTP status codes
status simple meaning of the status code
message Any message for the data returned
data can contain an object or list.

Response Codes

Code Description
200 We will only respond with 200 when transactions complete. Especially for synchronous requests
202 We have received your request but it has not completed. It’s being processed
400 When required data or parameters are missing
401 When the request does not include the api_key and/or the secret-key in the header
404 When the resource requested is not found
422 When the request has been received but can not be processed. The reason for failure will always be availed in the message parameter
500 Request failure due to server error in our system

NB

Request Authorization

At Collection

At Payout

Note

Obtaining API keys

  1. api_key - Under your merchant account, Click settings from the side menu. Got to API Settings and you will see it.

  2. secret-key - Under the API settings tab, Click the edit(pencil) button. Then Generate the secret key.

Note

Receiving Money

Introduction

How it works

  1. Customers will pay you using multiple payment options in different countries that have different currencies per provider or network used.
  2. These funds collected are deposited to your merchant account that you created earlier.
  3. Funds can be recieved in multiple currencies and stored as received with no conversion Therefore you will not loose value
  4. Your merchant account is in position to store value in different currencies from different countries that we can later collectively settle to your bank accounts in any country we support.

Example

You can request a payment of 10 USD via mobile money airtel_ug.

Take Note

  1. You will have to implemement a webhook/callback url and add it to the merchant account settings

    We will post all payments made through your merchant account to that url whenever the transaction status changes.

  2. For some payments especially online banking, customers need to complete their payments from a web interface.

    Therefore, in the request response, we will return a field called payment_url that contains a url that you will need to redirect the client for them to complete/approve the payment.

    For payments that do not need to be completed from the web, the payment_url field will be empty

Collection

Sample Request

Request payments at the comfort of your home currency.

POST: https://api.dusupay.com/v1/collections
{ 
    "api_key": "pk_eridsdsde23e23e2. Get this from your merchant account settings", 
    "currency": "USD", 
    "amount": 0.2,
    "method": "MOBILE_MONEY/CARD/BANK", 
    "provider_id": "e.g airtel_ug, mtn_ug. Get list of providers from the Providers API", 
    "account_number": "256777111000",
    "merchant_reference": "Your payment reference", 
    "narration": "Payment for Hosting",
    "redirect_url": "optional. used for payments completed via payment_url returned ",
    "account_name": "optional",
    "account_email": "optional",
    "voucher": "optional. Required for Ghana vodafone mobile money"
}
Parameter Type Description
api_key string, required Obtained from merchant account settings
currency string, required You can use your home currency when making requests. e.g USD

You will receive your funds at market rate into your merchant sub-account account.
amount int/double, required 2 decimal places allowed for double.
method string, required MOBILE_MONEY, CARD, BANK
provider_id string, required e.g airtel_ug, mtn_ug. Get list of providers from the Payment Options API
account_number string, required for MOBILE_MONEY Provide an internationally formatted number if the payment method is MOBILE_MONEY e.g 256777111777

It is not required for CARD and BANK payment methods unless specified in the Exceptional Parameters that follow
merchant_reference string, required,
4 to 36 characters
This is a unique transaction reference generated by your system.

You can try using UUID version 4.
narration string, required,
4 to 64 characters
Use this to add a brief description or comment to the transaction.
redirect_url string, optional for MOBILE_MONEY Required for BANK and CARD collections.

Used to redirect the client after a payment has been completed or canceled via the payment_url if returned in the request’s response.

When a request is made, a payment link is returned in the response if the payment needs to be completed by the client via the payment_url returned.

Some of the payment methods that would return a payment link include, online banking methods, visa 3d, and any other the require input via a web interface.
account_name string, optional Helps to easily lookup customer transactions.
account_email string, optional Used to email customer. Helps to easily lookup customer transactions.

Special Parameters

Network Fields Description
GhanaMobileMoney
- Vodafone

voucher

String. Customer should dial *110# to generate a transaction voucher and provide it prior to the request

Sample Response

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted.",
    "data": {
        "id": 226,
        "request_amount": 0.2,
        "request_currency": "USD",
        "account_amount": 737.9934,
        "account_currency": "UGX",
        "transaction_fee": 21.4018,
        "total_credit": 716.5916,
        "provider_id": "mtn_ug",
        "merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
        "internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
        "transaction_status": "PENDING",
        "customer_charged": false,
        "payment_url": "This only exists if the payment needs to be completed from a web browser."
    }
}
Parameters Description
request_amount Amount requested for collection
request_currency Currency of the request amount
account_amount The converted amount from request_currency to account_currency at market rate.
account_currency The sub-account/wallet currency in your merchant account where the amount paid by the customer will be deposited.

The currency of the amount paid by the customer is determined by the provider_id used to pay.
transaction_fee This is the fee charged off the paid amount. Whether the merchant is charged or the customer, depending on your merchant setting, the fees will be included in this field.
total_credit This is the amount less the transaction_fee deposited in your account.
provider_id This is the provider the customer is expected to pay from
merchant_reference This is the reference passed earlier in the request
internal_reference This is our internal reference. Useful when dealing with transaction issues. Store it.
transaction_status The status of the transaction
customer_charged This indicates whether it’s the customer that was charged or not.

Under your merchant account settings, you can define whether we should charge you or the customer paying.
payment_url This is a url where the customer should be redirect to complete the payment.

This link is only returned if the payment has to be completed from a web browser. Therefore always redirect the user to it whenever it’s returned.

This is common for online banking.

Card Payments

Local Cards

provider_id description
local_ngn Local Mastercard/Verve Nigeria

International Cards

provider_id description
international_usd 3D card payments to collect USD
international_ugx 3D card payments to collect UGX
international_kes 3D card payments to collect KES

Redirect URL

Description

NB

Redirect Data

Parameter Description
reference This is your merchant transaction reference
status Transaction status
message Response message.

Sending Money

Introduction

How it works

  1. With dusupay, Money is sent to either a customer’s mobile money wallet or bank supported.
  2. We will debit the equivalent local currency amount supported by the provider at market rate.
  3. Funds received by the customer account depend on the provider rate so they will receive funds less than those at market rate.

Payout

Sample Request

Request payments at the comfort of your home currency.

POST: https://api.dusupay.com/v1/payouts
{
    "api_key": "PUBK-24b72aebb821aea177483039677df9d3",
    "currency": "USD",
    "amount": 0.2,
    "method": "MOBILE_MONEY",
    "provider_id": "mtn_ug",
    "account_number": "256777044237",
    "account_name": "Hillary Namanya",
    "account_email": "optional@email.com",
    "merchant_reference": "AdIVeSAdeLEsta",
    "narration": "Hospital Bill"
}

Request Headers

Parameter Examples Description
secret-key SECK3298j923 Use your merchant account secret key

Request Parameters

Parameter Type Description
api_key string, required Obtained from merchant account settings
currency string, required You can use your home currency when making requests. e.g USD

You will receive your funds at market rate into your merchant sub-account account.
amount int/double, required 2 decimal places allowed for double.
method string, required MOBILE_MONEY, BANK
provider_id string, required e.g airtel_ug, mtn_ug. Get list of providers from the Payment Options API
account_number string, required Internationally formatted number required if method is MOBILE_MONEY
account_name string, required The name of the customer’s account
account_email string, optional The email address of the customer
merchant_reference string, required,
4 to 36 characters
This is a unique transaction reference generated by your system.

You can try using UUID version 4.
narration string, required,
4 to 64 characters
Use this to add a brief description or comment to the transaction.
extra_params Object, optional This field is mainly used to pass data that applies to specific payout methods or providers that follow below

Extra parameters

Description

Different countries require different extra information to send money to customer’s accounts correctly.

Below are some of the fields per country that are required to be included in the extra_params field when making a payout request.

Sample Extra Parameters
    {
        ...
        "extra_params": {
            "bank_code": "6876132",
            "branch_code": ""
        },
        ...
    }
Method Extra fields Description
Uganda
-BANK
bank_code The Bank code of Ugandan Bank
Kenya
-BANK
bank_code The Bank code of Kenyan Bank
Tanzania
-BANK
bank_code The Bank code of Tanzanian Bank
Nigeria
-BANK
bank_code The Bank code of Nigeria Bank
Ghana
-BANK
bank_code The Bank code of Ghanaian Bank
branch_code The Branch code of Ghanaian Bank. Required for GHS

An api to get Branch Codes will soon be availed as they are still being collected. Until then, Consider Ghana unavailable.

Sample Response

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted.",
    "data": {
        "id": 231,
        "request_amount": 0.2,
        "request_currency": "USD",
        "account_amount": 738.6622,
        "account_currency": "UGX",
        "transaction_fee": 1000,
        "total_debit": 1738.6622,
        "provider_id": "mtn_ug",
        "internal_reference": "DUSUPAY405GZM1NRJXGHH2SM",
        "transaction_status": "PENDING"
    }
}

Miscellaneous

Transaction Statuses

Status Reason
PENDING When a payment is waiting for processing.
FAILED When a payment failed
COMPLETED When a payment completed
CANCELLED When a customer cancelled a payment

Webhooks/IPNS

  1. All collection and payout transaction callbacks will be sent to the url
    set as the webhook url under your merchant account settings.

  2. A POST request with json data will be sent to your webhook url

  3. We require that you provide a secure webhook url.
    Therefore only https urls can be set or called-back.

Setting webhook

  1. Click the edit button under Api Settings of the merchant account settings.
  2. Set the Webhook URL field with your webhook URL

Calling webhook

  1. We will call your webhook url whenever the transaction status changes.

  2. You will need to acknowledge receipt of the callback by responding with http status code 200.
    Otherwise we will keep calling your endpoint at an interval of 10 minutes for 3 days.

Accepting webhook

  1. To ensure that the callback data sent to your webhook URL comes from our servers, you need to set a callback hash under the Api Settings.

  2. We will include a header called webhook-hash in the request sent to the callback url.
    e.g “webhook-hash: myWebhookHashSetInTheMerchantAccount”

  3. You should check to make sure the webhook-hash we sent matches what was set under your merchant account before giving value to the customer.

Responding to webhooks

Code Description
200 - OK
400 - Bad Request
401 - Unauthorised
403 - Forbidden
422 - Unprocessable entity.

Rejecting webhook

  1. In a scenario where the transaction cannot be processed or you cannot give value, respond with http codes below;
Code Description
400 - Bad Request.
- e.g when there’s a missing parameter
422 - Unprocessable entity.
- e.g when the request is fine but you cannot complete it because the amount does not match what you expected.

Note

  1. Always verify the amount to make sure it matches what is meant to be paid.

Sample Collection IPN Data

{
    "id": 226,
    "request_amount": 0.2,
    "request_currency": "USD",
    "account_amount": 737.9934,
    "account_currency": "UGX",
    "transaction_fee": 21.4018,
    "total_credit": 716.5916,
    "provider_id": "mtn_ug",
    "merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
    "internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
    "transaction_status": "COMPLETED",
    "transaction_type": "collection",
    "customer_charged": false,
    "message": "Transaction Completed Successfully"
}

Note

Sample Payout IPN Data

{
    "id": 226,
    "request_amount": 0.2,
    "request_currency": "USD",
    "account_amount": 737.9934,
    "account_currency": "UGX",
    "transaction_fee": 21.4018,
    "total_debit": 716.5916,
    "provider_id": "mtn_ug",
    "merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
    "internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
    "transaction_status": "COMPLETED",
    "transaction_type": "payout",
    "message": "Transaction Completed Successfully"
}

Take note

Payment Options

GET: https://api.dusupay.com/v1/payment-options/collection/mobile_money/ug?api_key={{api_key}}
{
    "code": 200,
    "status": "success",
    "message": "Request completed successfully.",
    "data": [
        {
            "id": "mtn_ug",
            "name": "MTN Mobile Money"
        },
        {
            "id": "airtel_ug",
            "name": "Airtel Money"
        }
    ]
}

Request Headers

Parameter Examples Value Description
secret-key SECK3298j923… Use your merchant account secret key

Request Query Parameters

Parameter Examples Value Description
api_key PUBK3298j923… Get your public key from your merchant account settings

Request Url Parameters

Paramater Examples Description
type collection If you want collection options returned
payout If you want payout options returned
method MOBILE_MONEY, For Mobile Money
BANK, For Bank
CARD, For Card
country NG The ISO2 code of the countries supported
E.g. UG,KE,NG,ZM,..

Response Fields

field Description
id Use id where a provider_id is required
name The provider name

Supported countries

code name Method
UG Uganda - MOBILE_MONEY (Collection, Payout)
- CARD (Collection)
- BANK(Payout)
KE Kenya - MOBILE_MONEY (Collection, Payout)
- CARD (Collection)
- BANK(Payout)
RW Rwanda - MOBILE_MONEY (Collection, Payout)
GH Ghana - MOBILE_MONEY (Collection, Payout)
- CARD (Collection)
- BANK(Payout)
CM Cameroon - MOBILE_MONEY (Collection, Payout)
ZA South Africa - BANK (Collection, Payout)
NG Nigeria - CARD(Collection)
- BANK (Collection, Payout)
ZM Zambia - MOBILE_MONEY (Collection, Payout)
SL Sierra Leone - MOBILE_MONEY (Payout)
- CARD (Collection)
- Bank (Payout)
US U.S.A - CARD (Collection)

Comming soon

West African CFA franc - XOF

Central African CFA franc - XAF

Cash payments

Account Balance

GET: https://api.dusupay.com/v1/merchants/balance?api_key={{api_key}}
{
    "code": 200,
    "status": "success",
    "message": "Request completed successfully.",
    "data": [
        {
            "currency": "UGX",
            "balance": 5475.816
        },
        {
            "currency": "USD",
            "balance": 12
        }
    ]
}

Request Headers

Parameter Examples Description
secret-key SECK3298j923 Use your merchant account secret key

Query Parameters

Parameter Examples Description
api_key PUBK3298j923 Get your public key from your merchant account settings

Testing/Sandbox

Description

Base URL

https://dashboard.dusupay.com/api-sandbox

Test Credentials

credential value
api_key PUBK-119a612068d0ad31aa2dc2aeea346e35
secret-key SECK-119e1c847b50352ea1eb32ccba5ecd71
webhook-hash TEST-DP-fu394jn2o23odko2i3

Available Test Api Endpoints

Test Collections API

https://dashboard.dusupay.com/api-sandbox/v1/collections

Test Payouts API

https://dashboard.dusupay.com/api-sandbox/v1/payouts

FAQ - Frequently Asked Questions

1. Why provider_id is required even for mobile money api requests

Adopting the idea of letting the customer choose the provider at all times early enough gives you more control on what extra data to ask from the client for those exceptional operators like Vodafone in Ghana.

As we add more operators, extra data might be required to be picked from the customer depending on the operator. Therefore it’s necessary to be aware of the operator in action.

Therefore the checkout flow would look like below;

2. Are all funds collected via different operators/provider_id in the same country combine.

Yes.

When one customer pays 1,000 UGX via airtel_ug and another pays 2,000 UGX via mtn_ug, your balance will reflect 3,000 UGX in the UGX subaccount under your merchant account.

This holds true with the assumption that there were zero transaction fees or the customer paid the transaction fees.

3. Are payouts now instant.

Yes and no.

Most of the mobile_money payouts are instant, 90% of most of the time. The other lag is based on the speed of the service provider/operator enabling the payout.
However, our system releases them instantly to be processed and paid out.


For some countries like South Africa. Our partner could take 2-4 days for the transaction to complete or reflect as complete in our system.

But most of the partners will complete the bank payout between instant e.g Nigeria and one day.

4. Where are the old dusupay api doc.

https://dusupay.com/docs/build