GWCL

Look up Ghana Water Company Limited (GWCL) customer accounts and settle water bills seamlessly through your application.

Customer Lookup

Validate a GWCL account number and retrieve the customer's name and outstanding balance before initiating payment. Always perform a lookup first to confirm the account details and display them to the customer.

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

Parameter	Type	Required	Description
client_id	integer	Yes	Your Client ID, found in the dashboard under API / Website Credentials.
account_number	string	Yes	The customer's GWCL account number as printed on their water bill.

curl -X POST https://testxchange.korba365.com/api/v1.0/gwcl_customer_lookup/ \
  -H "Content-Type: application/json" \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -d '{
    "client_id": 2,
    "account_number": "WA-000123456"
  }'

import requests, hmac, hashlib

client_key = "YOUR_CLIENT_KEY"
secret_key = "YOUR_SECRET_KEY"

payload = {
    "client_id": 2,
    "account_number": "WA-000123456",
}

message = "&".join(
    f"{k}={v}" for k, v in sorted(payload.items())
)
signature = hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()

url = "https://testxchange.korba365.com/api/v1.0/gwcl_customer_lookup/"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"HMAC {client_key}:{signature}",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const crypto = require("crypto");

const clientKey = "YOUR_CLIENT_KEY";
const secretKey = "YOUR_SECRET_KEY";

const payload = {
  client_id: 2,
  account_number: "WA-000123456",
};

const message = Object.keys(payload)
  .sort()
  .map(k => `${k}=${payload[k]}`)
  .join("&");
const signature = crypto.createHmac("sha256", secretKey).update(message).digest("hex");

const response = await fetch("https://testxchange.korba365.com/api/v1.0/gwcl_customer_lookup/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `HMAC ${clientKey}:${signature}`,
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);

<?php

$clientKey = 'YOUR_CLIENT_KEY';
$secretKey = 'YOUR_SECRET_KEY';

$payload = [
    'account_number' => 'WA-000123456',
    'client_id'      => 2,
];

ksort($payload);
$parts = [];
foreach ($payload as $k => $v) {
    $parts[] = "$k=$v";
}
$message   = implode('&', $parts);
$signature = hash_hmac('sha256', $message, $secretKey);

$ch = curl_init('https://testxchange.korba365.com/api/v1.0/gwcl_customer_lookup/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "Authorization: HMAC $clientKey:$signature",
    ],
]);

$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

200 OK Customer found

{
  "success": true,
  "customer_name": "Abena Asante",
  "account_number": "WA-000123456",
  "balance": "85.00"
}

4xx Error Lookup failed

{
  "success": false,
  "error_code": 702,
  "error_message": "Account number not found"
}

Pay Bill

Settle an outstanding GWCL water bill after confirming the account via customer lookup. The customer receives an SMS confirmation to the customer_number upon successful payment.

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

Parameter	Type	Required	Description
client_id	integer	Yes	Your Client ID, found in the dashboard under API / Website Credentials.
account_number	string	Yes	The customer's GWCL account number as returned by the customer lookup.
amount	number	Yes	Amount to pay in GHS. Must be a positive number.
transaction_id	string	Yes	A unique identifier from your system for this transaction. Duplicate IDs are rejected.
callback_url	string	Yes	A publicly accessible URL on your server that will receive the final transaction status via HTTP POST.
customer_number	string	Yes	Customer's mobile phone number for SMS payment confirmation delivery.

curl -X POST https://testxchange.korba365.com/api/v1.0/gwcl_pay_bill/ \
  -H "Content-Type: application/json" \
  -H "Authorization: HMAC YOUR_CLIENT_KEY:YOUR_SIGNATURE" \
  -d '{
    "client_id": 2,
    "account_number": "WA-000123456",
    "amount": 85.00,
    "transaction_id": "GWCL-TXN-001",
    "callback_url": "https://www.myapp.com/gwcl/callback",
    "customer_number": "0244000000"
  }'

import requests, hmac, hashlib

client_key = "YOUR_CLIENT_KEY"
secret_key = "YOUR_SECRET_KEY"

payload = {
    "client_id": 2,
    "account_number": "WA-000123456",
    "amount": 85.00,
    "transaction_id": "GWCL-TXN-001",
    "callback_url": "https://www.myapp.com/gwcl/callback",
    "customer_number": "0244000000",
}

message = "&".join(
    f"{k}={v}" for k, v in sorted(payload.items())
)
signature = hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()

url = "https://testxchange.korba365.com/api/v1.0/gwcl_pay_bill/"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"HMAC {client_key}:{signature}",
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const crypto = require("crypto");

const clientKey = "YOUR_CLIENT_KEY";
const secretKey = "YOUR_SECRET_KEY";

const payload = {
  client_id: 2,
  account_number: "WA-000123456",
  amount: 85.00,
  transaction_id: "GWCL-TXN-001",
  callback_url: "https://www.myapp.com/gwcl/callback",
  customer_number: "0244000000",
};

const message = Object.keys(payload)
  .sort()
  .map(k => `${k}=${payload[k]}`)
  .join("&");
const signature = crypto.createHmac("sha256", secretKey).update(message).digest("hex");

const response = await fetch("https://testxchange.korba365.com/api/v1.0/gwcl_pay_bill/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `HMAC ${clientKey}:${signature}`,
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);

<?php

$clientKey = 'YOUR_CLIENT_KEY';
$secretKey = 'YOUR_SECRET_KEY';

$payload = [
    'account_number'  => 'WA-000123456',
    'amount'          => 85.00,
    'callback_url'    => 'https://www.myapp.com/gwcl/callback',
    'client_id'       => 2,
    'customer_number' => '0244000000',
    'transaction_id'  => 'GWCL-TXN-001',
];

ksort($payload);
$parts = [];
foreach ($payload as $k => $v) {
    $parts[] = "$k=$v";
}
$message   = implode('&', $parts);
$signature = hash_hmac('sha256', $message, $secretKey);

$ch = curl_init('https://testxchange.korba365.com/api/v1.0/gwcl_pay_bill/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "Authorization: HMAC $clientKey:$signature",
    ],
]);

$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

200 OK Payment initiated

{
  "success": true,
  "transaction_id": "GWCL-TXN-001",
  "message": "Water bill payment initiated successfully."
}

4xx Error Payment failed

{
  "success": false,
  "error_code": 705,
  "error_message": "Duplicate transaction ID"
}

Error Codes

GWCL errors use the 700–720 range.

Code	Description
700	Missing or invalid `client_id`.
701	Missing or invalid `account_number`.
702	Account number not found. Verify the GWCL account number and try again.
703	Missing or invalid `amount`. Must be a positive number.
704	Missing or invalid `callback_url`. Must be a valid, publicly accessible HTTP/HTTPS URL.
705	Duplicate `transaction_id`. This ID has already been processed.
706	Missing or invalid `customer_number`. A valid mobile number is required for payment confirmation.
710	General GWCL payment error. Review the `error_message` field for further detail.

Previous ECG Next Utilities