Hosted Payment Page

It's highly recommended to use this method to collect funds using mobile money.

Follow the steps below to collect funds using HPP.

1. Set Payment Method

MOBILE_MONEY is the value to be set for the parameter, method in the request collection body. For Hosted Payment Page payments, we expect you to provide a, redirect_url where we will redirect the customer when they complete or cancel the transaction once you have redirected them to the payment_url we will return.

Sample Request Body

{
  ...
  "method": "MOBILE_MONEY",
  "redirect_url": "https://my-domain.com/redirect_url"
  ...
}

2. Expect Payment Link

payment_url will be returned which you will redirect the customer to complete the payment

Sample Response Body

{
  ...
  "payment_url": "https://sandbox.dusupay.com/v1/completepayment",
  ...
}

3. Redirect customer

Whenever a payment_url is returned in any response body, you are expected to redirect the customer to it for them to be able to complete the transaction initiated.

Mobile Money Collection API

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

Headers

Name	Type	Description
Content-Type*	String	application/json

Request Body

Name	Type	Description
api_key*	String	Obtained from merchant account setting
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.
amount*	Int/Double	2 decimal places allowed for double.
method*	String	MOBILE_MONEY
provider_id*	String	e.g airtel_ug,mtn_ug. Get the list of providers from Payment OptionsAPI
account_number*	String	Provide an internationally formatted number if the payment method is MOBILE_MONEY e.g 256777111777
merchant_reference*	String	The UNIQUE reference for this transaction generated by your system. A unique string value should be sent for every attempt. 4 to 36 character
narration*	String	Use this to add a brief description or comment on the transaction. 4 to 64 character
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
redirect_url*	String	Url e.g https://yourdomain.com that we redirect to.
account_name	String	Helps to easily lookup customer transactions.
account_email	String	Used to email customer. Helps to easily lookup customer transactions.
voucher	String	extra data field required only for GhanaMobileMoney-Vodafone
user_id*	String	This uniquely identifies the client on your system. A client is expected to have the same identifier for every transaction made by them. This is to allow for fraud detection.

200: OK

{
    "code": 202,
    "status": "accepted",
    "message": "Transaction Initiated",
    "data": {
        "id": 615616,
        "request_amount": 7,
        "request_currency": "USD",
        "account_amount": 26632.8249,
        "account_currency": "UGX",
        "transaction_fee": 1038.6802,
        "total_credit": 25594.1447,
        "provider_id": "mtn_ug",
        "merchant_reference": "xxxxxxxx8",
        "internal_reference": "DUSUPAY5FNZFYCL9WKX47F",
        "payment_url": "https://sandbox.dusupay.com/v1/complete-payment/DUSUPAY5FNZFYCL9WKX47F/mobile_money",
        "transaction_status": "PENDING",
        "transaction_type": "collection",
        "message": "Transaction Initiated",
        "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": false
    }
}

401: Unauthorized

{
    "code": 401,
    "status": "error",
    "message": "Unauthorized API access. Merchant API Key {api_key} missing",
    "data": {}
}