Dusupay
Search…
Post Collection Request
This function is used to initiate a collection request after the customer has provided information about the product or service they wish to acquire.

Sandbox Collection API

1
POST https://sandbox.dusupay.com/v1/collections
Copied!
Headers
Request
Response
Sample Request
Sample Response
Sample IPN

Request Headers

Header
Value
Required
Content-Type
application/json
YES

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, CARD, BANK, CRYPTO
YES
provider_id
string
e.g airtel_ug, mtn_ug. Get the list of providers from the Payment Options API
YES
account_number
string
Provide an internationally formatted number if the payment method is MOBILE_MONEY e.g 256777111777 It is not required for CARD, BANK and CRYPTO payment methods unless specified in the Exceptional Parameters that follow merchant_reference
Only for MOBILE_MONEY
merchant_reference
string
The UNIQUE reference for this transaction, generated by your system. A unique string value should be sent for every attempt
YES,
4 to 36 character
narration
string
Use this to add a brief description or comment on the transaction.
required, 4 to 64 characters
mobile_money_hpp
boolean
Applies to mobile money transactions when you wish for the transaction to be processed over a hosted payment page.
When sent with the value true, the redirect_url parameter becomes mandatory AND the response will include a payment_url where the customer can be redirected to complete the payment
NO
redirect_url
string
Required for BANK, CARD and CRYPTO collections. Used to redirect the client after 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.
YES but Optional for MOBILE_MONEY
account_name
string
Helps to easily lookup customer transactions.
NO
account_email
string
Used to email customer. Helps to easily lookup customer transactions.
NO

Special Parameters

Some networks or providers require extra data from the customer for the transaction to get processed.
Network
Fields
Description
GhanaMobileMoney - Vodafone
voucher
String. Customer should dial *110# to generate a transaction voucher and provide it prior to the request

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 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
double
This is the amount less the transaction_fee deposited in 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
customer_charged
boolean
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
string
Optional This is a URL where the customer should be redirected to complete the payment. It's not mandatory for us to return a value for this field. It's only returned if the payment has to be completed from a web browser. Therefore always redirect the user to it whenever it contains a URL value otherwise tell the customer to approve the payment from their phone number if it's mobile money or informs them that their transaction is being processed. Once we send you an IPN or webhook data to your webhook/callback url, you can then inform the customer that the payment has completed or failed. This is common for online banking.
instructions
string
Optional This is only returned where we see fit. This means it could be empty in the response. Whenever it's returned, Please ensure to show the instructions returned such that the customer is aware of what to do next. This is mainly used for mobile money payments or requests that return an empty payment_url. We recommend that you display the instructions to the customer as a pop-up modal or new screen with a button that leads them to another screen where they can view the current state of their transaction. This will initially be Pending/Processing and once we notify you that the transaction has completed or failed, you can show it to the customer with the appropriate message returned from our API data.
1
{
2
"api_key": "pk_eridsdsde23e23e2. Get this from your merchant account settings",
3
"currency": "USD",
4
"amount": 0.2,
5
"method": "MOBILE_MONEY/CARD/BANK/CRYPTO",
6
"provider_id": "e.g airtel_ug, mtn_ug. Get list of providers from the Providers API",
7
"account_number": "256777111000",
8
"merchant_reference": "Your payment reference",
9
"narration": "Short Payment reason",
10
"redirect_url": "optional. used for payments completed via payment_url returned ",
11
"account_name": "optional",
12
"account_email": "optional",
13
"voucher": "optional. Required for Ghana vodafone mobile money"
14
}
Copied!
Below is a sample request for Mobile money via the hosted payment page
1
{
2
"api_key": "pk_eridsdsde23e23e2. Get this from your merchant account settings",
3
"currency": "USD",
4
"amount": 0.2,
5
"method": "MOBILE_MONEY",
6
"provider_id": "e.g airtel_ug, mtn_ug. Get list of providers from the Providers API",
7
"account_number": "256777111000",
8
"merchant_reference": "Your payment reference",
9
"narration": "Short Payment reason",
10
"mobile_money_hpp": true,
11
"redirect_url": "https://redirect-url.com",
12
"account_name": "optional",
13
"account_email": "optional",
14
"voucher": "optional. Required for Ghana vodafone mobile money"
15
}
Copied!
1
{
2
"code": 202,
3
"status": "accepted",
4
"message": "Transaction Initiated",
5
"data": {
6
"id": 226,
7
"request_amount": 0.2,
8
"request_currency": "USD",
9
"account_amount": 737.9934,
10
"account_currency": "UGX",
11
"transaction_fee": 21.4018,
12
"total_credit": 716.5916,
13
"provider_id": "mtn_ug",
14
"merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
15
"internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
16
"transaction_status": "PENDING",
17
"transaction_type": "collection",
18
"message": "Transaction Initiated",
19
"customer_charged": false,
20
"payment_url": "This only exists if the payment needs to be completed from a web browser.",
21
"instructions": [
22
{
23
"step_no": "1",
24
"description": "Ensure that you have sufficient balance on your MTN Mobile Money account"
25
},
26
{
27
"step_no": "2",
28
"description": "Approve the payment request sent to your phone"
29
}
30
],
31
"customer_charged": true
32
}
33
}
Copied!
Below is a sample response for the mobile money hosted page version
1
{
2
"code": 202,
3
"status": "accepted",
4
"message": "Transaction Initiated",
5
"data": {
6
"id": 226,
7
"request_amount": 0.2,
8
"request_currency": "USD",
9
"account_amount": 737.9934,
10
"account_currency": "UGX",
11
"transaction_fee": 21.4018,
12
"total_credit": 716.5916,
13
"provider_id": "mtn_ug",
14
"merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
15
"internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
16
"transaction_status": "PENDING",
17
"transaction_type": "collection",
18
"message": "Transaction Initiated",
19
"customer_charged": false,
20
"payment_url": "https://sandbox.dusupay.com/v1/complete-payment/DUSUPAY405GZM1G5JXGA71IK/mobile_money",
21
"instructions": [],
22
"customer_charged": true
23
}
24
}
Copied!
1
{
2
"id": 226,
3
"request_amount": 0.2,
4
"request_currency": "USD",
5
"account_amount": 737.9934,
6
"account_currency": "UGX",
7
"transaction_fee": 21.4018,
8
"total_credit": 716.5916,
9
"customer_charged": false,
10
"provider_id": "mtn_ug",
11
"merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
12
"internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
13
"transaction_status": "COMPLETED",
14
"transaction_type": "collection",
15
"message": "Transaction Completed Successfully",
16
"account_number": "256777111786 - Optional",
17
"account_name": "- Optional",
18
"institution_name": "MTN Mobile Money - Optional"
19
}
Copied!

Last modified 1mo ago
Copy link