Collect For Payment

GovBill supports MDAs that remit/settle to URA the ability to collect funds (using the available methods) and directly use said funds to do PRN payments.

The request takes the PRN to be paid for as a mandatory parameter. The requesting merchant account chooses which transaction method to work with; Mobile Money or Card as described in the respective sections and as part of the request payload, the prn parameter is added.

The GovBill platform will go ahead to process the funds collection and when successful, it will automatically proceed to make the PRN payment and execute a second webhook for the PRN payment confirmation. However, in the event the PRN is not eligible to payment (invalid, already paid, expired etc), the merchant account will be notified via callback even before the collection process happens. The merchant account account required to have profiled a service payments callback URL as this will be the URL notified for everything regarding PRN payment.

Step 1: Form the request payload

Majority of the parameters depend on the method one decides to use for the collection and in addition, the PRN parameter is included and described in the table below;

Parameter	Type	Required	Description
prn	String	true	The PRN to be paid for on completion of this transaction

After collecting the necessary collection information from your customer, prepare your request payload as demonstrated below. Two (mobile money and card) sample payloads are shared

Using Mobile Money

{
    "merchant_reference": "auto",
    "transaction_method": "MOBILE_MONEY",
    "currency": "UGX",
    "amount": 25000,
    "provider_code": "mtn_momo_ug",
    "msisdn": "256772000001",
    "customer_email": "[email protected]",
    "customer_name": "JOHN DOE",
    "description": "PRN Payment",
    "prn": "2250000001301"
}

Using Card

{
    "merchant_reference": "auto",
    "transaction_method": "CARD",
    "currency": "UGX",
    "amount": 25000,
    "provider_code": "card_ug",
    "customer_email": "[email protected]",
    "customer_name": "JOHN DOE",
    "description": "PRN Payment",
    "prn": "2250000001301",
    "require_confirmation": false
}

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

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.govbill.ug/v1/collections/collect-for-payment" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "transaction_method": "CARD",
        "currency": "UGX",
        "amount": 25000,
        "provider_code": "card_ug",
        "customer_email": "[email protected]",
        "customer_name": "JOHN DOE",
        "description": "PRN Payment",
        "prn": "2250000001301"
    }'

202: Accepted - Request acknowledged for processing

{
	"code": 202,
	"status": "accepted",
	"message": "Request Accepted",
	"data": {
		"internal_reference": "GOVBILBJQT2KHDM6FZMJMH",
		"merchant_reference": "MCTREFPFYRECCFQ6RDMAWQZXVE"
	}
}

400: Bad Request - 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 of this point in time, the collection leg of the process is the one underway and the merchant handles any response/callback just like they would based on the collection method selected. When the collection succeeds however, an extra step comes up and described below.

Step 2: Payment confirmation notification

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 service payment callback URL. The callback structure is as shared below. The paid PRN would be in the account_number parameter of the callback payload.

{
    "event": "payment.completed",
    "payload": {
        "merchant_reference": "MCTREFWZ6QBEBZT5BZ6N",
        "internal_reference": "GOVBILLW9HWCZ9FBEVW6",
        "transaction_type": "SERVICE_PAYMENT",
        "request_currency": "UGX",
        "request_amount": 25000,
        "transaction_status": "COMPLETED",
        "account_number": "2250000001301",
        "transaction_charge": 1000,
        "transaction_amount": 26000,
        "customer_name": "JOHN DOE",
        "service_name": "URA Payment",
        "status_message": "Transaction completed successfully",
        "additional_details": {}
    }
}