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

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

Live Collection API

POST https://api.dusupay.com/v1/collections
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, 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

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

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.

Sample Request
{
"api_key": "pk_eridsdsde23e23e2. Get this from your merchant account settings",
"currency": "USD",
"amount": 0.2,
"method": "MOBILE_MONEY/CARD/BANK/CRYPTO",
"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": "Short Payment reason",
"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"
}
Sample Response
{
"code": 202,
"status": "accepted",
"message": "Transaction Initiated",
"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",
"transaction_type": "collection",
"message": "Transaction Initiated",
"customer_charged": false,
"payment_url": "This only exists if the payment needs to be completed from a web browser.",
"instructions": [
{
"step_no": "1",
"description": "Ensure that you have sufficient balance on your MTN Mobile Money account"
},
{
"step_no": "2",
"description": "Approve the payment request sent to your phone"
}
],
"customer_charged": true
}
}
Sample IPN
{
"id": 226,
"request_amount": 0.2,
"request_currency": "USD",
"account_amount": 737.9934,
"account_currency": "UGX",
"transaction_fee": 21.4018,
"total_credit": 716.5916,
"customer_charged": false,
"provider_id": "mtn_ug",
"merchant_reference": "76859aae-f148-48c5-9901-2e474cf19b71",
"internal_reference": "DUSUPAY405GZM1G5JXGA71IK",
"transaction_status": "COMPLETED",
"transaction_type": "collection",
"message": "Transaction Completed Successfully",
"account_number": "256777111786 - Optional",
"account_name": "- Optional",
"institution_name": "MTN Mobile Money - Optional"
}