BILLS PAYMENT

Verify Customer Biller

Verify a meter number (electricity) or smartcard/IUC number (cable) before charging, and get back the customer's name for display/confirmation.

Optional but strongly recommended for cable and electricity purchases — it helps you catch a mistyped meter or smartcard number before money leaves the wallet.

POST /v1/bills/verify

Use this endpoint to

Confirm that a meter or smartcard number belongs to a real, active account
Retrieve the customer's name to show for confirmation before charging
Check whether an account can currently be vended (can_vend)

Request

Body parameters

Field	Type	Required	Description
`biller_slug`	string	Yes	Biller `slug` from Get Billers (e.g. `IKEDC`, `DSTV`)
`product_name`	string	Yes	Product/meter type, e.g. `PREPAID` or `POSTPAID` for electricity
`customer_id`	string	Yes	Meter number (electricity) or smartcard/IUC number (cable)

Code Samples

const response = await fetch("https://sandbox.hitchpay.ng/v1/bills/verify", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    biller_slug: "IKEDC",
    product_name: "PREPAID",
    customer_id: "45700123456"
  })
});

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

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/bills/verify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "biller_slug" => "IKEDC",
    "product_name" => "PREPAID",
    "customer_id" => "45700123456"
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/bills/verify"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "biller_slug": "IKEDC",
    "product_name": "PREPAID",
    "customer_id": "45700123456"
}

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

Response

{
  "status": "success",
  "message": "Customer verified",
  "data": {
    "customer_name": "JOHN DOE",
    "account_number": "45700123456",
    "min_amount": 1000,
    "can_vend": true,
    "customer_type": "PREPAID",
    "address": "…",
    "biller_name": "Ikeja Electric"
  }
}

Fields

Field	Type	Description
`customer_name`	string	Name on the account. show this to your user to confirm before charging
`account_number`	string	Echoes the verified meter/smartcard number
`min_amount`	number	Minimum amount that can be vended (electricity)
`can_vend`	boolean	Whether this account can currently be charged
`customer_type`	string	e.g. `PREPAID` / `POSTPAID`
`address`	string	Customer address, if available
`biller_name`	string	Human-readable biller name

Errors

Code	Meaning
`INVALID_REQUEST`	Missing/invalid fields
`UNAUTHORIZED`	Business not found or inactive
`PRODUCT_UNAVAILABLE`	No matching product/network configured
`VERIFY_FAILED`	Provider could not verify this customer/meter/smartcard
`PROVIDER_ERROR`	Provider call failed

Questions? Email [email protected]. Also on GitBook.