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.

OVA balance is debited immediately. Ensure your Partner Wallet has sufficient funds before initiating an ECG payment. Always look up the meter first using Meter Detail to confirm the customer's information and capture the 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 StatusMeter 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.

POST 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"
  }'
200 OK Meter found
{
  "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"
      }
    ]
  }
}
4xx Error Lookup failed
{
  "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.

POST 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"
  }'
200 OK Status returned
{
  "success": true,
  "results": {
    "success": true,
    "data": {
      "isOnline": false
    }
  }
}
4xx Error Status check failed
{
  "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.

POST 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"
  }'
200 OK Meter registered
{
  "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"
    }
  }
}
4xx Error Add meter failed
{
  "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.

POST 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"
  }'
200 OK Payment initiated
{
  "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"
    }
  }
}
4xx Error Payment failed
{
  "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.

Flow Endpoint Required Fields
ECG Postpaid Pay Bill /api/v1.0/ecg_pay_bill/ customer_number, amount, transaction_id, client_id, callback_url
ECG Prepaid Meter Lookup /api/v1.0/ecg_meter_lookup/ meter_code, client_id
ECG Prepaid Initiate Request /api/v1.0/ecg_prepaid_initiate_request/ meter_code, meter_owner, amount, transaction_id, client_id, callback_url
ECG Prepaid Locations /api/v1.0/ecg_prepaid_get_locations/ client_id
ECG Prepaid/Postpaid Account Inquiry /api/v1.0/ecg_prepaid_postpaid_account_inquiry/ power_app_number, client_id
ECG Prepaid/Postpaid Topup /api/v1.0/ecg_prepaid_postpaid_topup_account/ destination, amount, bundle, transaction_id, client_id, callback_url

ECG Postpaid Pay Bill

Request
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

Requests
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

Requests
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/"
}