ECG
The ECG APIs let you look up customer meters and top them up programmatically. ECG Direct is the recommended flow for newly integrated meter topups, and the still-routed prepaid/postpaid endpoints are listed near the end of this page.
meter_category, which is required when adding a meter.
Overview
ECG Direct exposes four endpoints:
- Meter Detail — look up meters belonging to a phone number or account number.
- Service Status — check whether the ECG service is currently online before transacting.
- Add Meter — register a meter against a phone number so it can be reused for future payments.
- Pay Bill — top up a registered meter. The result is delivered to your
callback_url.
A typical flow is: Service Status → Meter Detail → (optionally Add Meter) → Pay Bill. A transaction is only confirmed once you receive the callback or perform a status check — never trust the synchronous response alone.
Meter Detail
Look up the meter(s) registered to a customer using either their phone number or their account number. Use the returned meterCategory when registering a meter via Add Meter.
https://xchange.korba365.com/api/v1.0/ecg_direct_meter_detail/
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_id | integer | Yes | Your Client ID, found in the dashboard under API / Website Credentials. |
| phone_number | string | Optional | Customer's phone number in international format. Eg. 233208795528. Provide either this or account_number. |
| account_number | string | Optional | Customer's ECG account number. Eg. 700252531. Provide either this or phone_number. |
curl -X POST https://xchange.korba365.com/api/v1.0/ecg_direct_meter_detail/ \ -H "Content-Type: application/json" \ -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \ -d '{ "client_id": 2, "phone_number": "233208795528" }'
{ "success": true, "results": { "success": true, "data": [ { "id": "f26688edb1b540bbb8aae0ab048901a2", "customerName": "MENSA FREDUA", "nameOnMeter": "MENSA FREDUA", "meterNumber": "G13304130", "accountNumber": "737458440", "address": "|0020-H/NOABURASO", "meterType": "SMART G", "balance": null, "meterCategory": "PREPAID", "alias": "MENSA FREDUA", "region": "ASHANTI WEST", "district": "Ahenema Kokoben District", "spn": "203810210", "regionId": "E11", "districtId": "6120", "createSource": "oltpv" } ] } }
{ "success": false, "error_code": 400, "error_message": "Please provide a phone_number value" }
Error Codes
| Code | Description |
|---|---|
| 101 | Phone number was not provided. |
Service Status
Check whether the ECG service is currently online for a given meter before initiating a payment. If isOnline is false, do not attempt to top up the meter — wait until the service is restored.
https://xchange.korba365.com/api/v1.0/ecg_direct_service_status/
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_id | integer | Yes | Your Client ID, found in the dashboard under API / Website Credentials. |
| meter_id | string | Yes | The internal Korba meter identifier returned as id in a previous Meter Detail or Add Meter response (e.g. a2c363ec6545486eaeb299bc7a64cefb). This is not the same as the physical meter number. |
curl -X POST https://xchange.korba365.com/api/v1.0/ecg_direct_service_status/ \ -H "Content-Type: application/json" \ -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \ -d '{ "client_id": 2, "meter_id": "a2c363ec6545486eaeb299bc7a64cefb" }'
{ "success": true, "results": { "success": true, "data": { "isOnline": false } } }
{ "success": false, "error_code": 400, "error_message": "Please provide a meter_id value" }
Error Codes
| Code | Description |
|---|---|
| 101 | Meter ID was not provided. |
Add Meter
Register an ECG meter against a phone number so that it can be reused for future payments. The meter_category value must come from a successful Meter Detail response.
https://xchange.korba365.com/api/v1.0/ecg_direct_add_meter/
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_id | integer | Yes | Your Client ID, found in the dashboard under API / Website Credentials. |
| alias | string | Yes | A friendly name for the meter — typically the customer's name (e.g. MENSA FREDUA) or a label like my home meter. |
| meter_number | string | Yes | The ECG meter number to register. Eg. P191177631. |
| phone_number | string | Yes | Customer's phone number in international format. Eg. 233208795528. |
| meter_category | string | Yes | The ECG meter category as returned by the Meter Detail API. Eg. PREPAID. |
| account_number | string | Optional | The ECG account number associated with the meter. Eg. 737458440. |
curl -X POST https://xchange.korba365.com/api/v1.0/ecg_direct_add_meter/ \ -H "Content-Type: application/json" \ -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \ -d '{ "client_id": 2, "alias": "MENSA FREDUA", "meter_number": "P191177631", "phone_number": "233208795528", "meter_category": "PREPAID", "account_number": "737458440" }'
{ "success": true, "results": { "message": "Meter added Successfully", "code": "201", "data": { "unsupported": false, "id": "a2c363ec6545486eaeb299bc7a64cefb", "customerName": "PROSPER TETTEH", "nameOnMeter": "PROSPER TETTEH", "meterNumber": "P191177631", "accountNumber": "733342761", "address": "5240-, St1 - Achimota - KWASHIEMAN, KWASHIEMAN, ACHIMOTA", "meterType": "NURI", "balance": null, "meterCategory": "PREPAID", "alias": "my home meter", "region": "Accra West Region", "district": "Achimota District", "spn": "203508274", "regionId": "", "districtId": "", "createSource": "oltpv" } } }
{ "success": false, "error_code": 400, "error_message": "Please provide a phone_number value" }
Error Codes
| Code | Description |
|---|---|
| 101 | Please provide a phone_number value. |
| 102 | Please provide the alias value. |
| 103 | Please provide the meter_number value. |
| 104 | Please provide the meter_category value. |
Pay Bill
Top up an ECG meter. Until you receive a callback or perform a status check, the transaction is not confirmed — never rely on the synchronous response alone to fulfil the customer.
https://xchange.korba365.com/api/v1.0/ecg_direct_pay_bill/
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_id | integer | Yes | Your Client ID, found in the dashboard under API / Website Credentials. |
| transaction_id | string | Yes | A unique identifier from your system for this transaction. Duplicates are rejected. |
| amount | number | Yes | Amount to recharge in GHS. Decimal values only. |
| meter_id | string | Yes | The internal Korba meter identifier returned as id in a previous Meter Detail or Add Meter response (e.g. a2c363ec6545486eaeb299bc7a64cefb). This is not the same as the physical meter number. |
| meter_number | string | Yes | The physical ECG meter number printed on the customer's meter (e.g. P191177631), returned as meterNumber in a Meter Detail or Add Meter response. |
| callback_url | string | Yes | A publicly accessible URL that receives the final transaction result. The transaction is only complete once this callback fires. |
| description | string | Optional | A free-text description of the transaction for your own records. |
curl -X POST https://xchange.korba365.com/api/v1.0/ecg_direct_pay_bill/ \ -H "Content-Type: application/json" \ -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \ -d '{ "client_id": 2, "transaction_id": "8937982379872398", "amount": 50.00, "meter_id": "a2c363ec6545486eaeb299bc7a64cefb", "meter_number": "P191177631", "callback_url": "https://webhook.site/fdd1d807-0147-4015-ab47-8ec7118ea595", "description": "awesome description" }'
{ "success": true, "results": { "success": true, "data": { "id": "f26688edb1b540bbb8aae0ab048901a2", "customerName": "MENSA FREDUA", "nameOnMeter": "MENSA FREDUA", "meterNumber": "G13304130", "accountNumber": "737458440", "address": "|0020-H/NOABURASO", "meterType": "SMART G", "balance": null, "meterCategory": "PREPAID", "alias": "MENSA FREDUA", "region": "ASHANTI WEST", "district": "Ahenema Kokoben District", "spn": "203810210", "regionId": "E11", "districtId": "6120", "createSource": "oltpv" } } }
{ "success": false, "error_code": 101, "error_message": "Please provide a amount value" }
Callback Parameters
When the transaction reaches a terminal state, Korba sends an HTTP GET request to your callback_url with the result appended as query parameters. A transaction is only considered complete after this callback is received (or confirmed via a status check).
| Parameter | Description |
|---|---|
| transaction_id | The unique transaction ID you initially provided in the request. |
| status | Returns the string SUCCESS or FAILED. |
| message | Details about how the transaction went. On failure, the reason will be in this field. |
| korba_trans_id | A unique ID generated by Korba for this transaction. |
| amount | The transaction amount. |
The callback URL is invoked like so:
https://webhook.site/1c4d4a5d?transaction_id=UNIQUE_ID&status=SUCCESS&message=MESSAGE&korba_trans_id=KORBA_ID&amount=50.00
Error Codes
| Code | Description |
|---|---|
| 101 | Please provide a transaction_id value. |
| 102 | Duplicate Transaction ID. |
| 103 | Please provide the meter_id value. |
| 104 | Please provide the amount value. |
| 105 | Please provide the callback_url value. |
| 106 | Please provide the meter_number value. |
| 107 | Please provide only decimal values for amount. |
| 108 | Invalid Callback URL. |
Other ECG Endpoints
The following ECG endpoints were available in the legacy docs and are still routed. Use these only when your account has been enabled for the corresponding ECG service.
ECG Postpaid Pay Bill
POST https://testxchange.korba365.com/api/v1.0/ecg_pay_bill/ { "client_id": 2, "customer_number": "700252531", "amount": "50.00", "transaction_id": "ECG-POST-20260626-001", "callback_url": "https://yourapp.com/callbacks/ecg/", "description": "ECG postpaid payment" }
ECG Prepaid Meter Lookup and Initiate Request
POST https://testxchange.korba365.com/api/v1.0/ecg_meter_lookup/ { "client_id": 2, "meter_code": "1234567" } POST https://testxchange.korba365.com/api/v1.0/ecg_prepaid_initiate_request/ { "client_id": 2, "meter_code": "1234567", "meter_owner": "Jane Doe", "amount": "50.00", "transaction_id": "ECG-PRE-20260626-001", "callback_url": "https://yourapp.com/callbacks/ecg/" }
ECG Prepaid/Postpaid Account Inquiry and Topup
POST https://testxchange.korba365.com/api/v1.0/ecg_prepaid_postpaid_account_inquiry/ { "client_id": 2, "power_app_number": "233208795528" } POST https://testxchange.korba365.com/api/v1.0/ecg_prepaid_postpaid_topup_account/ { "client_id": 2, "destination": "233208795528", "amount": "50.00", "bundle": "ECG", "transaction_id": "ECG-HUB-20260626-001", "callback_url": "https://yourapp.com/callbacks/ecg/" }