Request Mobile Money Payment

This is the first of a two-step process; where the first step initializes (returning transaction details) THEN the second is a confirmation request for the process to continue.

Expand the following section to view how the mobile money request is set up to debit funds from the customer's mobile money account. When the request is valid, the API responds with an acknowledgement; details of the transaction e.g. the charges together with a unique reference from the platform, which will subsequently be used for the confirmation.

POST https://sandbox-api.govbill.ug/v1/collections/initialize

The operation initiates a funds request from the customer's mobile money wallet. The request is sent as a JSON body

Headers

Name	Type	Description
public-key*	String	The Public Key as obtained from the approval email
Content-Type*	String	application/json

Request Body

Name	Type	Description
merchant_reference*	String	The unique reference for this request. It should be unique for every single request. Alternatively, the value auto can be passed and a reference will be created for you by the platform
currency*	String	The 3 character ISO currency code for the request currency
amount*	float	The amount being requested
provider_code*	String	The provider code as obtained from the payment options list the previous section
msisdn*	String	The phone number from which the payment is being requested. This should be sent in international format e.g. 256777000001 for Ugandan numbers
description	String	The description/narration for the transaction
customer_name*	String	The name of the customer
transaction_method*	String	The transaction method to be used. Allowed values are those returned for the transaction_method parameter in the payment options response

202: Accepted When the request has been acknowledged for processing

{
	"code": 202,
	"status": "accepted",
	"message": "Transaction Initiated. Pending Customer Confirmation",
	"data": {
		"id": 5742,
		"merchant_reference": "CSTREFYSCJBGSCSSMN2N",
		"internal_reference": "GOVBILGBHCVVGFZ6VFRFYJ",
		"transaction_type": "COLLECTION",
		"request_currency": "UGX",
		"request_amount": 80000,
		"transaction_currency": "UGX",
		"transaction_amount": 80000,
		"transaction_fee": 2000,
		"charge_customer": false,
		"total_credit": 78000,
		"provider_code": "mtn_momo_ug",
		"transaction_status": "PENDING",
		"status_message": "Transaction Initiated"
	}
}

400: Bad Request When the request is not formed as expected

  {
  "code": 400,
  "status": "error",
  "message": "256752000001 is not a valid MTN Mobile Money Uganda (mtn_momo_ug) phone number",
  "data": {
    "internal_reference": "GOVNETQJ7CA7ESLZCRBXSX"
  }
}

On acknowledgement, the internal_reference returned as part of the data is crucial for the next step of the process. This 1st step 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 mobile money account.