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

SENDING MONEY - Previous

Payouts

Bank Codes

Last updated 2 months ago

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

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)

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

Post Payout Request

Sandbox Payout API

Live Payout API

Request Headers

Request Body

Extra Parameters

Response body

​