Request Card 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 card payment request is set up to debit funds from the customer's card account (VISA/Mastercard). 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 card (VISA/Mastercard). 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
description	String	The description/narration for the transaction
redirect_url*	String	The URL to which GovBill will redirect the customer on transaction completion. https URL recommended
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": 13848,
		"merchant_reference": "CSTREFKPKWWZBKE5WXPM",
		"internal_reference": "GOVBILDTRXU2SRHZ2ZTFKA",
		"transaction_type": "COLLECTION",
		"request_currency": "UGX",
		"request_amount": 25000,
		"transaction_currency": "UGX",
		"transaction_amount": 25000,
		"transaction_fee": 1000,
		"charge_customer": false,
		"total_credit": 24000,
		"provider_code": "visa_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 card.