Developer API Documentation | 9jaBillz B2B VTU & Fintech Gateway

Overview & Architecture

The 9jaBillz Reseller API is a RESTful B2B gateway designed for high-concurrency automated bill delivery. All endpoints accept and return JSON-encoded payloads and enforce strict cryptographic signature validation to ensure message integrity and non-repudiation.

Production Base URL

https://app.9jabillz.com.ng

Data Format

JSON (application/json)

Sign Algorithm

HMAC SHA256

Idempotency & Replay Protection

All transaction dispatch requests require a unique request_ref string generated by your platform. Replaying a request with an existing reference will result in an immediate 409 Conflict status without double-charging your API wallet.

HMAC SHA256 Authentication

Authentication is handled securely via custom HTTP headers. Every request must be cryptographically signed using your secret key. Never expose your Secret Key in public client-side scripts, repositories, or mobile applications.

Canonical Signature String Construction

To construct the pre-hash signature payload, concatenate request variables using newline (\n) separators in the exact order specified below:

POST Signature Formula

CanonicalData = HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(RAW_JSON_BODY)
Signature = LOWERCASE_HEX( HMAC_SHA256(CanonicalData, YOUR_SECRET_KEY) )

GET Signature Formula (Empty Body)

CanonicalData = HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + ""
Signature = LOWERCASE_HEX( HMAC_SHA256(CanonicalData, YOUR_SECRET_KEY) )

Security Headers Reference

Ensure all 6 security headers are passed cleanly with every request payload.

Header Name	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`
`Accept`	string	Yes	Must be `application/json`
`X-API-KEY`	string	Yes	Your reseller Public Key (`9ja_live_pk_...`)
`X-API-TIMESTAMP`	integer	Yes	Current Unix timestamp in seconds. Max drift: 300s.
`X-API-NONCE`	string	Yes	Unique random string per request to prevent replay attacks.
`X-API-SIGNATURE`	string	Yes	Hex-encoded HMAC SHA256 signature string.

Global Error Codes & Responses

The 9jaBillz API uses standard HTTP status codes to communicate the success or failure of API operations.

HTTP Code	Status Reason	Description / Action
`200 OK`	Success	Request executed and fulfilled successfully.
`400 Bad Request`	Validation Error	Missing required body fields or invalid parameters.
`401 Unauthorized`	Auth Mismatch	Invalid Public Key, bad HMAC signature, or timestamp skew > 300s.
`404 Not Found`	Invalid Item	Plan variation code, smartcard, or provider code not found.
`409 Conflict`	Duplicate Ref	`request_ref` already exists in transaction history.
`502 Bad Gateway`	Upstream Error	Vendor dispatch failure; reseller wallet is automatically refunded.

Standard Error Payload Example

401 Unauthorized Response

{
    "status": false,
    "message": "Authentication required. Invalid or missing API key or HMAC signature.",
    "data": null
}

Build Automated VTU & Fintech Integrations Fast