Confirm Payment Request

This is the second step of the 2-step process of completing funds collection. It depends on the first one and only uses a valid reference returned from step 1.

Expand the following section to view how the request is setup to confirm the funds collection from the customer's mobile money or card account. When the request is valid, the API responds with an acknowledgement and in the background, proceeds to send the confirmation prompt to the customer (for cases of Mobile Money) OR returns the payment page URL as part of the response (for the case of Card).

On success/failure of the transaction, a callback/webhook request will be made to the registered callback URL.

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

The operation confirms the funds request from the customer's mobile money wallet or card account. 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
internal_reference*	String	The unique reference generated by the GovBill platform in step 1

202: Accepted When the request has been acknowledged for processing

{
	"code": 202,
	"status": "accepted",
	"message": "You will receive a prompt to pay UGX 81,000 on your mobile. Enter PIN to approve payment",
	"data": {}
}

OR

{
	"code": 202,
	"status": "accepted",
	"message": "Redirect to URL for the payment of UGX 25,000",
	"data": {
		"payment_url": "https://payment-page-url"
	}
}

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"
  }
}

As mentioned in the introduction section, the API is asynchronous. The 202 response is an acknowledgement of your request. The GovBill Platform will send a payment notification with the updated status of the transaction. The notification data has the same structure as the acknowledgement response in Step 1 with a few additional details. A sample is shared below

{
  "id": 266,
  "merchant_reference": "CSTREF2NZQQW53KJMQPE",
  "internal_reference": "GOVBIL7VFAXUTT4BF828RM",
  "transaction_type": "COLLECTION",
  "request_currency": "UGX",
  "request_amount": 80000,
  "transaction_currency": "UGX",
  "transaction_amount": 81000,
  "transaction_fee": 1000,
  "charge_customer": true,
  "total_credit": 80000,
  "provider_code": "airtel_money_ug",
  "transaction_status": "COMPLETED",
  "status_message": "Transaction Completed Successfully",
  "transaction_account": "256752000001",
  "customer_name": "SANDBOX CUSTOMER",
  "institution_name": "Airtel Money"
}

If the collection happened successfully, the GovBill platform automatically proceeds to make the PRN payment using the collected funds. When the PRN payment is successful, a confirmation webhook will be sent to the designated callback URL. The callback structure is similar to the one for collection confirmation but with an additional parameter prn as shown below;

{
  "id": 266,
  "merchant_reference": "CSTREF2NZQQW53KJMQPE",
  "internal_reference": "GOVBIL7VFAXUTT4BF828RM",
  "transaction_type": "COLLECTION",
  "request_currency": "UGX",
  "request_amount": 80000,
  "transaction_currency": "UGX",
  "transaction_amount": 81000,
  "transaction_fee": 1000,
  "charge_customer": true,
  "total_credit": 80000,
  "provider_code": "airtel_money_ug",
  "transaction_status": "COMPLETED",
  "status_message": "Transaction Completed Successfully",
  "transaction_account": "256752000001",
  "customer_name": "SANDBOX CUSTOMER",
  "institution_name": "Airtel Money",
  "prn": "2230000069722"
}