Skip to content
HitchPay API Docs

BILLS PAYMENT

Pay Cable TV

Pay a cable TV subscription (DStv, GOtv, etc.) using a package_id from Get Cable Plans.

POST /v1/bills/cable

Note: This endpoint does not take an amount. The price is fixed by the selected package_id; any amount sent in the body is ignored.

Use this endpoint to

  • Pay for a cable TV subscription for a smartcard/IUC number
  • Charge the business NGN wallet the exact price of the selected package
  • Safely retry a purchase without double-charging, using reference

Body parameters

Field Type Required Description
provider string Yes Cable biller slug from Get Billers (e.g. DSTV)
smartcard string Yes Smartcard / IUC number
package_id string Yes Plan id from Get Cable Plans
customer_name string No Name from Verify Customer — recommended, not required
reference string Yes Your unique idempotency key for this purchase

Code Samples

const response = await fetch("https://sandbox.hitchpay.ng/v1/bills/cable", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    provider: "DSTV",
    smartcard: "1234567890",
    package_id: "98765",
    customer_name: "JOHN DOE",
    reference: "order-cable-001"
  })
});

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

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/bills/cable",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "provider" => "DSTV",
    "smartcard" => "1234567890",
    "package_id" => "98765",
    "customer_name" => "JOHN DOE",
    "reference" => "order-cable-001"
  ]),
  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/cable"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "provider": "DSTV",
    "smartcard": "1234567890",
    "package_id": "98765",
    "customer_name": "JOHN DOE",
    "reference": "order-cable-001"
}

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

Response

{
  "status": "success",
  "message": "Bill payment successful.",
  "data": {
    "reference": "HTCHB…",
    "merchant_reference": "order-cable-001",
    "product": "cable",
    "provider": "DSTV",
    "amount": 19000,
    "fee": 0,
    "amount_charged": 19000,
    "recipient": "1234567890",
    "currency": "NGN",
    "balance": 93450.75,
    "paid_at": "2026-07-02T10:25:00.000Z"
  }
}

If the response is pending, resolve it via Get Transaction Status or the bill.success / bill.failed webhook.

Fields

Field Type Description
reference string Our transaction id — use this for status polling
merchant_reference string Echoes the reference you sent
product string cable
provider string Provider slug
amount number Price taken from the package's amount
fee number Fee charged, if any
amount_charged number Total debited from your wallet
recipient string Smartcard/IUC number charged
currency string NGN
balance number Your wallet balance after this transaction
paid_at string ISO 8601 timestamp

Errors

Code Meaning
INVALID_REQUEST Missing/invalid fields, or unknown package_id
UNAUTHORIZED Business not found or inactive
PRODUCT_UNAVAILABLE No matching provider/package configured
INSUFFICIENT_BALANCE Wallet balance too low
BILL_FAILED Provider declined the purchase — wallet is auto-refunded
PROVIDER_ERROR / VERIFY_FAILED Provider or verification call failed

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