Getting Started

Collections are payments that the merchant/MDA receives into their account. The sections here will highlight how the GovBill platform supports these.

The GovBill API currently supports funds collection via Mobile Money and Card. This is to allow for the flexibility of customer payments, such that customers can make payments in the ways that are most convenient. The funds collection section will describe the process flows for every available payment method.

The API currently enforces a 2-step collection process where step 1 initializes the collection then step 2 confirms the request to be escalated to the telecom/bank so that the customer approves the payment. If however you wish a straight-forward collection process, add the boolean parameter require_confirmation to your request payload and assign the value false. In this scenario, the API will combine the processes and give you a seamless experience.

Every collection will generally follow the steps described below, in the order of occurrence.

Pre-requisites

Before the merchant account can start transacting,

1. The merchant account would need to be approved by the admins and the payment options configured accordingly. This approval happens when the go-live requirements are met (being on sandbox and clearing the UAT tests)

2. Additionally, the merchant account needs to have added a collection callback URL on their profile. This is critical because along the timeline of any transaction, notifications are done to this configured URL.

Collection API Request

The merchant will form the collection request payload (based on the selected payment method) and send it to the API for processing. If there are any errors with the parameters, these would be communicated immediately in the response otherwise the API would respond with an acknowledgement. Take the following the mobile money request and a sample acknowledgement.

{
    "merchant_reference": "auto",
    "transaction_method": "MOBILE_MONEY",
    "currency": "UGX",
    "amount": 1000,
    "provider_code": "mtn_momo_ug",
    "msisdn": "256777000001",
    "customer_name": "JOHN DOE",
    "description": "Test Collection"
}

/*sample acknowledgement would be something like the following*/
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GOVBILPHEZBZJEEJMLGH",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
    }
}

However, should this process fail in any way even after the acknowledgement e.g. the initialization process doesn't not happen as expected throws an error, the following failure callback will be sent to the collection callback URL.

{
    "event": "request.failed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "GOVBILPHEZBZJEEJMLGH",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "request_amount": 1000,
        "transaction_status": "FAILED",
        "status_message": "Failed to initialize the transaction. System exception!"
    }
} 

Transaction charges notification - Optional

In special circumstances e.g. when the merchant opts for the 2-step workflow (doesn't use the require_confirmation parameter as described above), this notification is sent. The callback payload holds transaction details and allows you a chance to display the charge and final transaction amount to the end user. The transaction_amount is the actual amount to be debited/deducted from the customer's account. Below is a sample payload.

{
    "event": "transaction.charges",
    "payload": {
        "id": 266,
        "merchant_reference": "MCTREF4DRQGLN9RZVCYH",
        "internal_reference": "GOVBILBAFMBGCHBZARVQFY",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 40000,
        "transaction_currency": "UGX",
        "transaction_charge": 1200,
        "transaction_account": "256752000001",
        "charge_customer": false,
        "total_credit": 38800,
        "provider_code": "airtel_money_ug",
        "request_amount": 40000,
        "institution_name": "Airtel Money Uganda",
        "customer_name": "JOHN DOE",
        "transaction_status": "PENDING",
        "status_message": "Collection initialized successfully. Confirm charges"
    }
}

In the 2-step workflow, receiving this callback is what the merchant should base on to trigger the next step (confirmation). In this workflow, it is assumed that the details shared in the payload are displayed and the customer could click a button to proceed, in which case the merchant would execute the confirmation process as described below.

Request confirmation - Optional

When the merchant chooses the 2-step workflow, this would be step 2 of that workflow. This is usually executed after receiving the transaction.charges callback. This is a simple JSON POST request. Below is a sample request and sample responses.

{
    "internal_reference": "GOVBILMCANP2HRBSVNZR"
}

/*sample acknowledgement would be something like the following - MobileMoney*/
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GOVBILMCANP2HRBSVNZR",
        "merchant_reference": "MCTREF33DGRQU55JWAEJ"
    }
}

/*sample acknowledgement would be something like the following - Card*/
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GOVBILMCANP2HRBSVNZR",
        "merchant_reference": "MCTREF33DGRQU55JWAEJ",
        "payment_url": "https://devapi.govbill.ug/complete-payment/GOVBILMCANP2HRBSVNZR"
    }
}

Redirect to payment URL - Optional

In special circumstances e.g. card collections, the initial/confirmation response would have the payment URL to which the customer needs to be redirected to complete the transaction. A sample of this response payload is shared below.

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GOVBILMCANP2HRBSVNZR",
        "merchant_reference": "MCTREF33DGRQU55JWAEJ",
        "payment_url": "https://devapi.govbill.ug/complete-payment/GOVBILMCANP2HRBSVNZR"
    }
}

When the payment_url is part of the response, be sure to redirect the customer to that URL as that will be the only way for the customer to complete the transaction.

Final status notification

This is the notification that communicates the very final status of the transaction, and this would mark the close of the transaction process. Samples of completed and failed transaction callbacks/notifications shared below.

/*sample completed transaction callback*/
{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "GOVBILMCANP2HRBSVNZR",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 2000000,
        "transaction_currency": "UGX",
        "transaction_charge": 60000,
        "transaction_account": "256787008803",
        "charge_customer": false,
        "total_credit": 1940000,
        "provider_code": "mtn_momo_ug",
        "request_amount": 2000000,
        "customer_name": "JOHN DOE",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

/*sample failed transaction callback*/
{
      "event": "transaction.failed",
      "payload": {
        "id": 26609,
        "merchant_reference": "MCTREFNRFRTQA6SCWT5X",
        "internal_reference": "GOVBILMCANP2HRBSVNZR",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 2000000,
        "transaction_currency": "UGX",
        "transaction_charge": 0,
        "transaction_account": "256777000002",
        "charge_customer": false,
        "total_credit": 0,
        "provider_code": "mtn_momo_ug",
        "request_amount": 2000000,
        "customer_name": "JOHN DOE",
        "transaction_status": "FAILED",
        "status_message": "Balance Insufficient for the transaction"
      }
    }