Utilities

Validate a utility customer before payment, then initiate a bill payment using the values returned by the validation step.

Supported Bill Types

Pass the selected provider as bill_type. Values are case-sensitive.

bill_type	Description
DSTV	DStv bill payment.
KWESETV	Kwese TV bill payment.
GBCTV	GBC TV bill payment.
ECG	ECG utility payment.
GOTV	GOtv bill payment.
STARTIMES	StarTimes bill payment.

Validate User

Use this endpoint to confirm that the customer account exists before initiating payment.

POST https://testxchange.korba365.com/api/v1.0/utilities_validate_user/

Parameter	Type	Required	Description
customer_number	string	Mandatory	Utilities customer number.
bill_type	string	Mandatory	One of the supported bill types listed above.
transaction_id	string	Mandatory	Unique ID generated by your system.
client_id	integer	Mandatory	Your Client ID from the dashboard.

Validate request

curl -X POST https://testxchange.korba365.com/api/v1.0/utilities_validate_user/ \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "bill_type": "DSTV",
    "client_id": 8,
    "customer_number": "7020000004",
    "transaction_id": "085694478"
  }'

Validate Response

200 OK

{
  "results": {
    "message": "ANTHONY BASSAW-5.00"
  },
  "error_code": null
}

4xx Error

{
  "success": false,
  "error_code": 405,
  "error_message": "Duplicate transaction id"
}

Pay Bill

After validation, use the returned customer details to make a payment.

POST https://testxchange.korba365.com/api/v1.0/utilities_pay_bill/

Parameter	Type	Required	Description
customer_number	string	Mandatory	Utility customer number.
bill_type	string	Mandatory	One of the supported bill types listed above.
transaction_id	string	Mandatory	Unique ID generated by your system.
sender_name	string	Mandatory	Customer name from the validate user response.
address	string	Mandatory	Customer address.
client_id	integer	Mandatory	Your Client ID from the dashboard.
amount	number	Mandatory	Amount to pay.
callback_url	string	Mandatory	Callback URL for final transaction status.
customer_phone_number	string	Optional	Customer phone number used by the newer utility payment flow. Defaults internally if omitted.
description	string	Optional	Description of the transaction.
payer_name	string	Optional	Payer name for reporting.
extra_info	string	Optional	Additional metadata for reporting.

Pay bill request

curl -X POST https://testxchange.korba365.com/api/v1.0/utilities_pay_bill/ \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "bill_type": "DSTV",
    "client_id": 8,
    "customer_number": "7020000004",
    "sender_name": "ANTHONY BASSAW",
    "address": "Accra",
    "amount": "1.0",
    "transaction_id": "986887909",
    "callback_url": "https://myapp.com/utility_callback/"
  }'

Pay Bill Response

200 OK

{
  "results": "Transaction initiated successfully.",
  "error_code": null,
  "success": true
}

4xx Error

{
  "success": false,
  "error_code": 405,
  "error_message": "Duplicate transaction id"
}

Callback

The payment callback is called after processing and includes transaction_id, status (SUCCESS or FAILED), and message as query parameters.

Previous GWCL Next MTN Direct Debit