BILLS PAYMENT

Get Transaction Status

Look up the current state of a bills payment transaction. Use this to resolve any purchase that came back pending.

GET /v1/bills/status/:reference

:reference in the URL is our transaction id — the reference value returned by the purchase call, not the reference you originally sent (which is returned to you as merchant_reference).

Use this endpoint to

Check the final state of a pending transaction
Retrieve the vend token for an electricity purchase, if it wasn't returned synchronously
Reconcile your records against transactions on our side

Path parameters

Parameter	Type	Required	Description
`reference`	string	Yes	Our transaction id, from a purchase response

Code Samples

const response = await fetch(
  "https://sandbox.hitchpay.ng/v1/bills/status/HTCHB123456",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN"
    }
  }
);

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

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/bills/status/HTCHB123456",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ]
]);

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

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/bills/status/HTCHB123456"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

Response

{
  "status": "success",
  "message": "Transaction status retrieved",
  "data": {
    "reference": "HTCHB…",
    "merchant_reference": "order-data-001",
    "product": "databundle",
    "provider": "MTN_NIGERIA",
    "amount": 500,
    "fee": 0,
    "amount_charged": 500,
    "recipient": "08012345678",
    "currency": "NGN",
    "status": "successful",
    "token": "…",
    "units": "…",
    "created_at": "1782947655"
  }
}

Fields

Field	Type	Description
`reference`	string	Our transaction id
`merchant_reference`	string	Your original `reference`
`product`	string	`airtime`, `databundle`, `cable`, or `electricity`
`provider`	string	Biller slug
`amount`	number	Amount charged
`fee`	number	Fee charged, if any
`amount_charged`	number	Total debited from your wallet
`recipient`	string	Phone / smartcard / meter number
`currency`	string	`NGN`
`status`	string	`successful` \| `failed` \| `pending`
`token`	string	Vend token — electricity only
`units`	string	Units purchased — electricity only
`created_at`	string	Unix timestamp

Errors

Code	Meaning
`INVALID_REQUEST`	`reference` missing or malformed
`UNAUTHORIZED`	Business not found or inactive, or reference belongs to another business

Best practice: don't poll aggressively. Subscribe to the bill.success / bill.failed webhook and use this endpoint as a fallback/reconciliation check.

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