BILLS PAYMENT

Buy Databundle

Purchase a data bundle for a phone number, using a package_id from Get Data Plans.

POST /v1/bills/data

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

Purchase a data bundle for any phone number on a supported network
Charge the business NGN wallet the exact price of the selected plan
Safely retry a purchase without double-charging, using reference

Body parameters

Field	Type	Required	Description
`network`	string	Yes	Data biller `slug` from Get Billers (e.g. `MTN_NIGERIA`)
`phone`	string	Yes	Recipient phone number
`package_id`	string	Yes	Plan id from Get Data Plans
`reference`	string	Yes	Your unique idempotency key for this purchase

Code Samples

const response = await fetch("https://sandbox.hitchpay.ng/v1/bills/data", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    network: "MTN_NIGERIA",
    phone: "08012345678",
    package_id: "12345",
    reference: "order-data-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/data",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "network" => "MTN_NIGERIA",
    "phone" => "08012345678",
    "package_id" => "12345",
    "reference" => "order-data-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/data"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "network": "MTN_NIGERIA",
    "phone": "08012345678",
    "package_id": "12345",
    "reference": "order-data-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-data-001",
    "product": "databundle",
    "provider": "MTN_NIGERIA",
    "amount": 500,
    "fee": 0,
    "amount_charged": 500,
    "recipient": "08012345678",
    "currency": "NGN",
    "balance": 11950.75,
    "paid_at": "2026-07-02T10:20: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	`databundle`
`provider`	string	Network slug
`amount`	number	Price taken from the plan's `amount`
`fee`	number	Fee charged, if any
`amount_charged`	number	Total debited from your wallet
`recipient`	string	Phone number credited
`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 network/package configured
`INSUFFICIENT_BALANCE`	Wallet balance too low
`BILL_FAILED`	Provider declined the purchase — wallet is auto-refunded
`PROVIDER_ERROR`	Provider call failed

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