Post Payout Request

This function is used to initiate a payout request after the customer has provided information about where they want their funds sent as a withdraw or payment.

Sandbox Payout API

POST https://sandbox.dusupay.com/v1/payouts

Live Payout API

POST https://api.dusupay.com/v1/payouts
Headers
Request
Response
Sample Request
Sample Response
Sample IPN
Headers

Request Headers

Header

Value

Required

Content-Type

application/json

YES

Request

Request Body

Parameter

Type

Description

Required

api_key

string

Obtained from merchant account settings

YES

currency

string

You can use your home currency when making requests. e.g USD You will receive your funds at the market rate into your merchant sub-account account.

YES

amount

int/double

2 decimal places allowed for double.

YES

method

string

MOBILE_MONEY, BANK

YES

provider_id

string

e.g airtel_ug, mtn_ug. Get the list of providers from the Payment Providers API

YES

account_number

string

Internationally formatted number required if the method is MOBILE_MONEY For European, UK, Germany bank payouts, set account_number to contain the IBAN

YES

account_name

string

The name of the customer’s account

YES

account_email

string

The email address of the customer

NO

merchant_reference

string

This is a unique transaction reference generated by your system. You can try using UUID version 4.

YES,

4 to 36 character

narration

string

Use this to add a brief description or comment on the transaction.

YES, 4 to 64 characters

extra_params

Object

This field is mainly used to pass data that applies to specific payout methods or providers that follow below

NO

Extra Parameters

  • 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 the field when making a payout request.

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 can be found here.

USA - BANK

routing_number

Bank Routing number

swift_code

Bank Swift code

bank_name

Bank Name e.g (BANK OF AMERICA)

beneficiary_address

e.g San Francisco, 4 Newton

Europe - BANK

bank_code

Bank code provided by the payment options API e.g bank_fr (for France), bank_de (for Germany)

routing_number

The swift code can be used here

swift_code

Bank Swift code

postal_code

Beneficiary postal code e.g 80489

street_number

e.g 31

street_name

e.g Handelsbank Elsenheimer St

city

e.g Munchen

bank_name

Bank Name e.g (LLOYDS BANK)

U.K - BANK

routing_number

The swift code can be used here

swift_code

Bank Swift code

postal_code

Beneficiary postal code e.g 80489

street_number

e.g 31

street_name

e.g Handelsbank Elsenheimer St

city

e.g Munchen

bank_name

Bank Name e.g (LLOYDS BANK)

bank_code

Bank code provided by the payment options API e.g bank_at (for Australia), bank_be (for Belgium)

Response

Response body

Parameters

Type

Description

request_amount

double

Amount requested for collection

request_currency

string

The currency of the requested amount

account_amount

double

The converted amount from request_currency to account_currency at market rate.

account_currency

string

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

double

This is the fee charged from 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_debit

double

This is the amount including the transaction_fee withdrawn from your account.

provider_id

string

This is the provider the customer is expected to pay from

merchant_reference

string

This is the reference passed earlier in the request

internal_reference

string

This is our internal reference. Useful when dealing with transaction issues. Store it.

transaction_status

string

The status of the transaction

transaction_type

string

payout The type of transaction made

message

string

The reason or message based on the transaction status

Sample Request
{
"api_key": "PUBK-***",
"currency": "USD",
"amount": 0.2,
"method": "MOBILE_MONEY",
"provider_id": "mtn_ug",
"account_number": "256777044237",
"account_name": "John Doe",
"account_email": "[email protected]",
"merchant_reference": "AdIVeSAdeLEsta",
"narration": "Withdraw Payment"
}
// With extra parameters
{
"api_key": "PUBK-***",
"currency": "USD",
"amount": 0.2,
"method": "BANK",
"provider_id": "bank_gh",
"account_number": "1000909898989",
"account_name": "John Doe",
"account_email": "[email protected]",
"merchant_reference": "AdIVeSAdeLEsta",
"narration": "Hospital Bill",
"extra_params": {
"bank_code": "6876132",
"branch_code": "7898"
},
}
Sample Response
{
"code": 202,
"status": "accepted",
"message": "Transaction Initiated",
"data": {
"id": 124468,
"request_amount": 700,
"request_currency": "UGX",
"account_amount": 700,
"account_currency": "UGX",
"transaction_fee": 1500,
"total_debit": 2200,
"provider_id": "mtn_ug",
"merchant_reference": "payout-1005",
"internal_reference": "DUSUPAY405GZMDVTKASJL8UQ",
"transaction_status": "PENDING",
"transaction_type": "payout",
"message": "Transaction Initiated"
}
}
Sample IPN
{
"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",
"account_number": "256777111786 - Optional",
"account_name": "- Optional",
"institution_name": "MTN Mobile Money - Optional"
}