Collect For 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 collection request is set up to debit funds from the customer's mobile money or card account. When the request is valid, the API responds with an acknowledgement. The request takes the PRN to be paid for and returns details of the transaction e.g. the charges together with a unique reference from the platform, which will subsequently be used for the confirmation.

When these two steps complete sucessfully, the GovBill platform will automatically proceed to make the PRN payment and execute a second webhook for the PRN payment confirmation.ok

POST https://sandbox-api.govbill.ug/v1/collections/collect-for-payment

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 of the customer requesting the PRN payment.
description	String	The description/narration for the transaction
prn*	String	The PRN to be paid for on completion of this 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
redirect_url	String	Required if transaction_method is CARD. The URL that GovBill will redirect to when the transaction is complete

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 or card.