Mobile Money Collection

The API supports mobile money as described in the Supported Countries section. The section below will guide you through the process of accepting Mobile Money

Overview

The currently supported mobile money channels are listed here (to be updated from time to time). Test mobile money phone numbers are also described in this section. We equally recommend that you go through the Getting Started section to have a high-level understanding of the funds collection process.

Step 1: Form the collection request payload

The table below describes the request parameters that are used for the collection request. Most will be collected from the paying customer and some are custom configurations based on your wishes (e.g. who bears the transaction charge).

Parameter
Type
Required
Description

merchant_reference

String

true

The unique reference for this request. Alternatively, the value auto can be passed, and a unique reference will be created for you by the API

transaction_method

String

true

The transaction method to be used. This will be MOBILE_MONEY for this request

currency

String

true

The 3-character ISO currency code for the request currency

amount

Number

true

The amount being requested

provider_code

String

true

The provider code as obtained from the payment options list

msisdn

String

true

The phone number from which the payment is being requested. This should be sent in international format e.g. 256777000001 for Ugandan numbers

customer_name

String

true

The name of the customer

customer_email

String

false

The email of the customer

description

String

false

The description/narration for the transaction

charge_customer

Boolean

false

Whether or not the customer should bear the charge for the transaction. By default, this is false to mean that the merchant bears the charge

After collecting the necessary mobile money payment information from your customer, prepare your request payload as demonstrated below.

{
    "merchant_reference": "auto",
    "transaction_method": "MOBILE_MONEY",
    "currency": "UGX",
    "amount": 10000,
    "provider_code": "mtn_momo_ug",
    "msisdn": "256777000001",
    "customer_email": "[email protected]",
    "customer_name": "JOHN DOE",
    "description": "Test Collection",
    "charge_customer": false
}

POST https://gwapisdbx.ellypayapp.com/collections/initialize

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (acknowledgement and failure) are also shared.

curl -X POST "https://gwapisdbx.ellypayapp.com/collections/initialize" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "transaction_method": "MOBILE_MONEY",
        "currency": "UGX",
        "amount": 10000,
        "provider_code": "mtn_momo_ug",
        "msisdn": "256777000001",
        "customer_email": "[email protected]",
        "customer_name": "JOHN DOE",
        "description": "Test Collection",
        "charge_customer": false,
    }'
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "merchant_reference": "MCTREFNGKLP5VQCQSBH2"
    }
}

Step 2: Handle intermediate notifications - Optional

You can optionally handle/listen to the intermediate callbacks that are sent, as some form of tracking the transaction progress. These callbacks/notifications are described in this section of the getting-started manual.

Step 3: Handle final status notification

Every merchant account is expected to have configured a callback/webhook URL for collections. For all collections that transition to the final state (COMPLETED, FAILED or CANCELLED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

{
    "event": "transaction.completed",
    "payload": {
        "id": 11832,
        "merchant_reference": "MCTREFNGKLP5VQCQSBH2",
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 100000,
        "transaction_currency": "UGX",
        "transaction_charge": 4000,
        "transaction_account": "256777000001",
        "charge_customer": false,
        "total_credit": 96000,
        "provider_code": "mtn_momo_ug",
        "request_amount": 100000,
        "institution_name": "MTN Mobile Money Uganda",
        "customer_name": "JOHN DOE",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Last updated