Getting Started

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

The API supports funds collection via Mobile Money for now and many other methods will be supported along the way. 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. However, every collection will follow the steps described below, in the order of occurrence.

Prerequisites

Before funds collection can start,

1. The merchant needs to have an approved merchant account on the live platform. This is only achieved after the go-live requirements are met (being on sandbox and clearing the UAT tests).

2. The payment channels/options required by the merchant need to be configured on the designated merchant account. The support teams will be available to assist with this.

3. The merchant 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": "GBPREFFFZNGLVH96GSKK",
        "merchant_reference": "MCTREFBNKWHXANJBYX2L"
    }
}

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": "GBPREFFFZNGLVH96GSKK",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "request_amount": 1000,
        "transaction_status": "FAILED",
        "status_message": "Multiple attempts in a short time"
    }
} 

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": "GBPREFFFZNGLVH96GSKK",
        "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": "GBPREFFFZNGLVH96GSKK",
        "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"
      }
    }

Handling Other Callbacks - Optional

Between the time of the collection API request and the final status notification, the platform will optionally send other notifications to communicate progress and the state of the transaction. These notifications are also sent to the configured collection callback URL and the merchant is listen to them if they so wish. Sample payloads and descriptions are shared below;

Transaction Charges Notification

Shortly after the collection request is acknowledged, if the request matches all the desired conditions, the platform will perform billing and share details with the merchant. The payload in this case therefore carries information about the transaction charges and the expected amount to be deposited to the merchant currency account in the event the transaction is successful. Sample payload below;

{
    "event": "transaction.charges",
    "payload": {
        "id": 266,
        "merchant_reference": "MCTREF4DRQGLN9RZVCYH",
        "internal_reference": "GBPREFFFZNGLVH96GSKK",
        "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"
    }
}

Payment Instructions Notification

This notification normally comes after the request has been escalated to the last mile processor (e.g. the telecom mobile money platform). Its purpose is to communicate what the customer might expect in order to approve the transaction e.g. mobile money customers should expect a PIN approval prompt. Below is a sample payload.

{
    "event": "transaction.processing",
    "payload": {
        "id": 27594,
        "merchant_reference": "MCTREF9WVCPGFRHYCWSK",
        "internal_reference": "GBPREFFFZNGLVH96GSKK",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 5000,
        "transaction_currency": "UGX",
        "transaction_charge": 150,
        "transaction_account": "256777000001",
        "charge_customer": false,
        "total_credit": 4850,
        "provider_code": "mtn_ug",
        "request_amount": 5000,
        "customer_name": "JOHN DOE",
        "transaction_status": "PROCESSING",
        "status_message": "Transaction Initiated successfully. Approve Payment by entering the PIN",
        "payment_instructions": "<p>You will receive a prompt on the mobile number <b>256777000001</b>.<br/> Enter your PIN to authorize your payment of <b>UGX 5,000</b></p>"
    }
}

All the callbacks/notifications sent for collections will come with signature headers as described in this section of the documentation. Verification of those signatures is also doumented there.

Cross-currency Collections

If the request currency is different e.g. USD from the payment provider currency (transaction currency) e.g. KES, the API will convert the USD to KES and at the end of the transaction, your KES balance will be credited with the converted amount. More details here.