Developer Docs

HasrinPay Developer API

Integrate airtime, data, bills, and more into your application with one API.

Base URLhttps://api.hasrinpay.com/api/developer/v1

Overview

All API requests are made over HTTPS to https://api.hasrinpay.com/api/developer/v1. Requests and responses use JSON. Every response includes a status field (success or error). Purchase endpoints also return a meta block with a timestamp and request_id for support.

All Endpoints

Account & Wallet

GET

/me

App info, status, approved services, API key

GET

/wallet/balance

Current API wallet balance

GET

/wallet/transactions

All wallet transactions (paginated)

GET

/transactions/{reference}

Look up any transaction by reference

Data

GET

/data/plans

List active data plans

POST

/data/purchase

Purchase a data bundle

GET

/data/transactions

Data purchase history

GET

/data/transactions/{reference}

Single data transaction

Airtime

POST

/airtime/purchase

Top up airtime

GET

/airtime/transactions

Airtime purchase history

GET

/airtime/transactions/{reference}

Single airtime transaction

Bills

GET

/bills/electricity/discos

List electricity providers (DISCOs)

POST

/bills/electricity/validate

Validate a meter number

POST

/bills/electricity/purchase

Pay an electricity bill

GET

/bills/cable/plans

List cable TV plans

POST

/bills/cable/validate

Validate an IUC/smart card number

POST

/bills/cable/subscribe

Subscribe cable TV

GET

/bills/transactions

Bills payment history

GET

/bills/transactions/{reference}

Single bills transaction

Authentication

Every request must include your API secret key as a Bearer token in the Authorization header. Never share your secret key or commit it to source control.

Sandbox Keys

hpk_test_…

Safe for development. Responses are mocked. Deducts from your test balance.

Live Keys

hpk_live_…

Real transactions. Requires approved live access and funded wallet.

curl https://api.hasrinpay.com/api/developer/v1/me \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY" \
  -H "Accept: application/json"

Response

{
  "status": "success",
  "data": {
    "id": 3,
    "name": "My App",
    "company": "My Company Ltd",
    "email": "[email protected]",
    "status": "sandbox_active",
    "api_key": {
      "public_key": "hpk_test_fD8poWbgg...",
      "mode": "sandbox",
      "is_active": true,
      "permissions": ["airtime", "data", "bills"]
    },
    "service_requests": [
      { "service": "airtime", "status": "approved" },
      { "service": "data",    "status": "approved" }
    ]
  }
}

Sandbox Mode

All hpk_test_ keys operate in sandbox mode automatically. No real VTU calls are made — responses are realistic mocks and your sandbox wallet is debited so you can test balance handling.

Sandbox behaviour

New sandbox accounts start with ₦100,000 test balance
Purchases deduct from this balance — test your INSUFFICIENT_BALANCE handling
Electricity purchases return a fake token: 1234-5678-9012-3456-7890
Meter and IUC validation returns a mock customer: SANDBOX CUSTOMER
All sandbox responses include mode: "sandbox"
Messages are prefixed with [SANDBOX]

// Example sandbox airtime response
{
  "status": "success",
  "message": "[SANDBOX] Airtime purchase simulated successfully.",
  "data": {
    "reference": "DEV-AIR-1IOJRA3C49",
    "network": "MTN",
    "phone": "08012345678",
    "amount": 500,
    "mode": "sandbox"
  },
  "meta": {
    "timestamp": "2026-09-07T01:09:30.000000Z",
    "request_id": "6a9e13aba26fb"
  }
}

Errors

Failed requests return a non-2xx HTTP status with status: "error", a human-readable message, and ancode for programmatic handling.

HTTP	Code	Meaning
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Key lacks permission for this service
402	INSUFFICIENT_BALANCE	Wallet balance too low
422	VALIDATION_ERROR	Request body failed validation
400	TRANSACTION_FAILED	VTU transaction failed (live mode)
404		Transaction reference not found
500	SYSTEM_ERROR	Internal error — use request_id when contacting support

{
  "status": "error",
  "message": "Insufficient wallet balance.",
  "code": "INSUFFICIENT_BALANCE"
}

Wallet

Every developer app has its own API wallet. Fund it by transferring to your dedicated virtual bank account (visible in your dashboard). All purchases — airtime, data, bills — deduct from this wallet.

GET/wallet/balance

Returns your current API wallet balance.

curl https://api.hasrinpay.com/api/developer/v1/wallet/balance \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY"

Response

{
  "status": "success",
  "data": {
    "balance": 8750000,
    "balance_naira": 87500.0,
    "currency": "NGN",
    "mode": "sandbox"
  }
}

Note: balance is in kobo (multiply by 100). balance_naira is pre-converted.

GET/wallet/transactions

Paginated list of all wallet transactions across all services.

{
  "status": "success",
  "data": [
    {
      "reference": "MWT-BFEXLIORJ9JA",
      "type": "debit",
      "service": "airtime",
      "amount": 500,
      "balance_before": 100000,
      "balance_after": 99500,
      "description": "Sandbox airtime purchase — MTN 08012345678",
      "status": "completed",
      "created_at": "2026-09-07T01:09:30.000000Z"
    }
  ],
  "meta": { "total": 5, "per_page": 20, "current_page": 1, "last_page": 1 }
}

Data

Purchase mobile data bundles for MTN, Airtel, Glo, and 9Mobile. Requires the data permission on your API key.

GET/data/plans

List all active data plans. Filter by network or plan type.

Query Parameters

Parameter	Type	Required	Description
network	string	No	MTN, AIRTEL, GLO, or 9MOBILE
plan_type	string	No	e.g. SME, Stable, Gifting, Corporate

curl "https://api.hasrinpay.com/api/developer/v1/data/plans?network=MTN" \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY"

Response

{
  "status": "success",
  "data": [
    {
      "id": 1795,
      "network": "MTN",
      "plan_type": "Stable",
      "name": "MTN 2.5 GB GIFTING Stable (2days)",
      "size": "2.5 GB",
      "amount": "1000.00",
      "validity": 2
    }
  ]
}

POST/data/purchase

Purchase a data bundle. Deducts from your API wallet.

Request Body

Parameter	Type	Required	Description
network	string	Yes	MTN, AIRTEL, GLO, or 9MOBILE
plan_id	integer	Yes	Plan ID from GET /data/plans
phone	string	Yes	Nigerian number e.g. 08012345678

curl -X POST https://api.hasrinpay.com/api/developer/v1/data/purchase \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"MTN","plan_id":1795,"phone":"08012345678"}'

Response

{
  "status": "success",
  "message": "[SANDBOX] Data purchase simulated successfully.",
  "data": {
    "reference": "DEV-DATA-Y0K3IJZCTI",
    "network": "MTN",
    "phone": "08012345678",
    "plan": "MTN 2.5 GB GIFTING Stable (2days)",
    "amount": "1000.00",
    "mode": "sandbox"
  },
  "meta": { "timestamp": "2026-09-07T01:30:04.000000Z", "request_id": "6a9e139ca01cd" }
}

Airtime

Top up airtime for any Nigerian network. Requires the airtime permission.

POST/airtime/purchase

Purchase airtime. Minimum ₦50, maximum ₦50,000. Deducts from your API wallet.

Request Body

Parameter	Type	Required	Description
network	string	Yes	MTN, AIRTEL, GLO, or 9MOBILE
amount	number	Yes	Amount in Naira (50 – 50,000)
phone	string	Yes	Nigerian number e.g. 08012345678

curl -X POST https://api.hasrinpay.com/api/developer/v1/airtime/purchase \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network":"AIRTEL","amount":500,"phone":"08098765432"}'

Response

{
  "status": "success",
  "message": "[SANDBOX] Airtime purchase simulated successfully.",
  "data": {
    "reference": "DEV-AIR-1IOJRA3C49",
    "network": "AIRTEL",
    "phone": "08098765432",
    "amount": 500,
    "mode": "sandbox"
  },
  "meta": { "timestamp": "2026-09-07T01:09:30.000000Z", "request_id": "6a9e13aba26fb" }
}

Bills

Pay electricity bills and subscribe cable TV. Requires the bills permission. Always validate a meter/IUC before purchasing.

Electricity

POST/bills/electricity/validate

Validate a meter number. Always call this before purchasing electricity.

Request Body

Parameter	Type	Required	Description
disco	string	Yes	e.g. IKEDC, EKEDC, AEDC, IBEDC, PHEDC, BEDC, KEDC, JEDC, KAEDCO, YEDC
meter_number	string	Yes	Meter number
meter_type	string	Yes	prepaid or postpaid

Response

{
  "status": "success",
  "data": {
    "name": "SANDBOX CUSTOMER",
    "address": "1 Test Street, Lagos",
    "meter_number": "12345678901",
    "meter_type": "prepaid",
    "mode": "sandbox"
  }
}

POST/bills/electricity/purchase

Pay an electricity bill. Returns a token for prepaid meters.

Request Body

Parameter	Type	Required	Description
disco	string	Yes	DISCO code (e.g. IKEDC, EKEDC, AEDC)
meter_number	string	Yes	Meter number
meter_type	string	Yes	prepaid or postpaid
amount	number	Yes	Amount in Naira (min 1,000)
phone	string	Yes	Customer phone number

curl -X POST https://api.hasrinpay.com/api/developer/v1/bills/electricity/purchase \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "disco": "IKEDC",
    "meter_number": "45012345678",
    "meter_type": "prepaid",
    "amount": 5000,
    "phone": "08012345678"
  }'

Response

{
  "status": "success",
  "message": "[SANDBOX] Electricity purchase simulated successfully.",
  "data": {
    "reference": "DEV-ELEC-TBK5K3B0YX",
    "token": "1234-5678-9012-3456-7890",
    "meter_number": "45012345678",
    "amount": 5000,
    "units": "76.9 kWh",
    "mode": "sandbox"
  },
  "meta": { "timestamp": "2026-09-07T01:30:19.000000Z", "request_id": "6a9e13aba26fb" }
}

Cable TV

POST/bills/cable/validate

Validate an IUC/smart card number before subscribing.

Request Body

Parameter	Type	Required	Description
provider	string	Yes	DSTV, GOTV, or STARTIMES
iuc_number	string	Yes	Smart card / IUC number

POST/bills/cable/subscribe

Subscribe a cable TV plan. Deducts from your API wallet.

Request Body

Parameter	Type	Required	Description
provider	string	Yes	DSTV, GOTV, or STARTIMES
iuc_number	string	Yes	Smart card / IUC number
plan_id	string	Yes	Plan ID from GET /bills/cable/plans
amount	number	Yes	Subscription amount in Naira (min 500)

curl -X POST https://api.hasrinpay.com/api/developer/v1/bills/cable/subscribe \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "DSTV",
    "iuc_number": "7042892701",
    "plan_id": "COMPACT",
    "amount": 9000
  }'

Transactions

Look up any transaction by its reference, or list transactions per service. Use these for reconciliation, retry logic, and support queries.

GET/transactions/{reference}

Look up any transaction across all services by its reference.

curl https://api.hasrinpay.com/api/developer/v1/transactions/DEV-AIR-1IOJRA3C49 \
  -H "Authorization: Bearer hpk_test_YOUR_SECRET_KEY"

Response

{
  "status": "success",
  "data": {
    "reference": "MWT-BFEXLIORJ9JA",
    "type": "debit",
    "service": "airtime",
    "amount": 500,
    "balance_before": 100000,
    "balance_after": 99500,
    "description": "Sandbox airtime purchase — MTN 08012345678",
    "status": "completed",
    "created_at": "2026-09-07T01:09:30.000000Z"
  }
}

GET/airtime/transactions

Per-service transaction lists. Replace 'airtime' with 'data' or 'bills'.

Available endpoints

GET /airtime/transactions

GET /airtime/transactions/{reference}

GET /data/transactions

GET /data/transactions/{reference}

GET /bills/transactions

GET /bills/transactions/{reference}

All list endpoints are paginated (20 per page, newest first).

Migration Guide

Migrating from GongozConcept (or a similar provider)? We offer a compatibility API that accepts the exact same request format — only your base URL and token value change.

2-step migration

Step 1 — Change base URL

# Before
https://www.gongozconcept.com

# After
https://api.hasrinpay.com/api/compat/gongoz/v1

Step 2 — Swap your token

# Before
Authorization: Token 66f2e5c39ac8640f13cd888f

# After
Authorization: Token hpk_test_YOUR_HASRINPAY_KEY

Compat API supports

GET /api/user/

POST /api/data/

GET /api/data/

GET /api/data/{id}

POST /api/topup/

GET /api/topup/

GET /api/topup/{id}

POST /api/billpayment/

GET /api/billpayment/{id}

POST /api/cablesub/

GET /api/cablesub/{id}

GET /api/validatemeter

GET /api/validateiuc

One-time change needed

Data plan IDs are different — call GET /api/developer/v1/data/plans once to get our plan IDs and update your mapping. Everything else is identical.

Network ID mapping (compat API)

ID	Network	ID	DISCO
1	MTN	1	IKEDC
2	GLO	2	EKEDC
3	9MOBILE	3	IBEDC
4	AIRTEL	4	AEDC
		5	PHEDC
		6	BEDC
		7	KEDC
		8	JEDC
		9	KAEDCO
		10	YEDC

Cable: 1 = DSTV, 2 = GOTV, 3 = STARTIMES · Meter type: 1 = prepaid, 2 = postpaid

Need help?

Questions about the API, your application, or billing? Reach out.

[email protected]