Request Card Payment

The GovBill API supports card payments as described in the Supported Countries section. The section below will guide you through the process of accepting Card (VISA/Mastercard)

Overview

Card is supported in a few countries as listed here (to be updated from time to time). Test card numbers are also described in this section. We equally recommend that you go through the Getting Started section to have a high-level understanding of the funds collection process.

Step 1: Form payload for collection request

The table below describes the request parameters that are used for the collection request. Most will be collected from the paying customer and some are custom configurations based on your wishes (e.g. who bears the transaction charge, whether or not you wish to trigger the confirmation process by yourself).

Parameter	Type	Required	Description
merchant_reference	String	true	The unique reference for this request. Alternatively, the value auto can be passed and a reference will be created for you by the platform
transaction_method	String	true	The transaction method to be used. This will be CARD for this request
provider_code	String	true	The provider code as obtained from the payment options list the previous section
currency	String	true	The 3 character ISO currency code for the request currency
amount	Number	true	The amount being requested
customer_name	String	true	The name of the customer
customer_email	String	false	The email of the customer
description	String	false	The description/narration for the transaction
charge_customer	Boolean	false	Whether or not the customer should bear the charge for the transaction. Defaults to false if the parameter is not set explicitly
require_confirmation	Boolean	false	Whether or not the requesting merchant account wishes to explicitly do the second step (confirmation). Currently defaults to true
redirect_url	String	true	The URL that GovBill will redirect to when the transaction is complete

After collecting the necessary card payment information from your customer, prepare your request payload as demonstrated below.

{
    "merchant_reference": "auto",
    "transaction_method": "CARD",
    "currency": "UGX",
    "amount": 10000,
    "provider_code": "card_ug",
    "customer_email": "[e-mail]",
    "customer_name": "JOHN DOE",
    "description": "Test Collection",
    "charge_customer": false
}

POST https://gwapisdbx.govbill.ug/collections/initialize

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/collections/initialize" \
   -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": 10000,
        "provider_code": "card_ug",
        "customer_email": "[e-mail]",
        "customer_name": "JOHN DOE",
        "description": "Test Collection",
        "charge_customer": false,
    }'

202: Accepted - Request acknowledged for processing

/*sample acknowledgement when require_confirmation=true*/
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GOVBILEPRRU9UVPDCDP3",
        "merchant_reference": "MCTREF5VE628T8SE95L9"
    }
}

/*sample acknowledgement when require_confirmation=false*/
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "GOVBILY9ETWQN72YRSUJ",
        "merchant_reference": "MCTREFXC5DUTCADAS3PF",
        "payment_url": "https://devapi.govbill.ug/complete-payment/GOVBILY9ETWQN72YRSUJ"
    }
}

400: Bad Request - Request is not formed as expected

{
    "code": 400,
    "status": "error",
    "message": "Amount is outside the allowed range for card collections",
    "data": {}
}

Step 2: Transaction confirmation - Optional

If in step 1 you chose that you wish to explictly handle the request confirmation, then it becomes mandatory that you send the transaction confirmation API request. If the request in step 1 is successful and responds with an acknowledgement (HTTP code 202), you should listen and handle the transaction charges webhook/callback. This will be sent to the collection callback URL that's configured on your merchant account. The callback is sent as a JSON POST request and we recommend that the confirmation request is done after the arrival of this callback. Below is a sample payload.

{
    "event": "transaction.charges",
    "payload": {
        "id": 266,
        "merchant_reference": "MCTREF4DRQGLN9RZVCYH",
        "internal_reference": "GOVBILEPRRU9UVPDCDP3",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 40000,
        "transaction_currency": "UGX",
        "transaction_charge": 1200,
        "transaction_account": "37897237921",
        "charge_customer": false,
        "total_credit": 38800,
        "provider_code": "card_ug",
        "request_amount": 40000,
        "institution_name": "Card Payment - UGX",
        "customer_name": "JOHN DOE",
        "transaction_status": "PENDING",
        "status_message": "Collection initialized successfully. Confirm charges"
    }
}

This payload 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 account. You can then execute the confirmation request as described below. The request takes a single parameter, internal_reference

POST https://gwapisdbx.govbill.ug/collections/confirm

curl -X POST "https://gwapisdbx.govbill.ug/collections/confirm" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "internal_reference": "GOVBILEPRRU9UVPDCDP3"
    }'

The confirmation request will respond with an acknowledgement just like in Step 1 above. The response will also have a payment_url to which the customer needs to be redirected to complete the transaction.

Step 3: Handle the final status notification

Every merchant account is expected to have configured a callback/webhook URL for collections. For all collections that transition to the final state (COMPLETED, FAILED or CANCELLED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

Successful Card Collection

{
    "event": "transaction.completed",
    "payload": {
        "id": 20760,
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "internal_reference": "GOVBILEPRRU9UVPDCDP3",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 2000000,
        "transaction_currency": "UGX",
        "transaction_charge": 60000,
        "transaction_account": "411111xxxxxx1111",
        "charge_customer": false,
        "total_credit": 1940000,
        "provider_code": "card_ug",
        "request_amount": 2000000,
        "customer_name": "JOHN DOE",
        "transaction_status": "COMPLETED",
        "status_message": "Transaction Completed Successfully"
    }
}

Failed Card Collection

{
      "event": "transaction.failed",
      "payload": {
        "id": 26609,
        "merchant_reference": "MCTREFNRFRTQA6SCWT5X",
        "internal_reference": "GOVBILEPRRU9UVPDCDP3",
        "transaction_type": "COLLECTION",
        "request_currency": "UGX",
        "transaction_amount": 2000000,
        "transaction_currency": "UGX",
        "transaction_charge": 0,
        "transaction_account": "462294xxxxxx3705",
        "charge_customer": false,
        "total_credit": 0,
        "provider_code": "card_ug",
        "request_amount": 2000000,
        "customer_name": "JOHN DOE",
        "transaction_status": "FAILED",
        "status_message": "Balance Insufficient for the transaction"
      }
    }