Billway Payment Services API

Welcome to the Billway Payment Services API. This API enables businesses to manage collections, disbursements, bill payments, and sub-user wallets programmatically.

Base URL: https://api.billway.ng/api/v1
Providers: Safe Haven MFB (Banking) • VTPass (Bills)

Authentication

Authenticate requests using your API headers.

X-API-Key
Required
Your public API key.
X-API-Secret
Required
Your secret API key.

Rate Limiting

100 requests per minute per key.

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

Create Sub-User

POST /subusers

Create a new sub-user with a dedicated wallet.

Body Parameters

external_id
Required String
Your unique identifier for this user.
name
Required String
Full name of the user.
email
Required String
Valid email address.

Get Balance

GET/wallet/balance

Initiate Collection

POST/collections/initiate

Initiate Transfer

POST/disbursements/initiate

Buy Airtime

POST/bills/airtime

Bill Payment Services (p1 & p2)

Unified bill payments split by provider prefixes:

  • p1 (SafeHaven): Value Added Services (VAS) like betting, specialized bills.
  • p2 (VTPass): Core utilities (Airtime, Data, Electricity, Cable).
  • p3 (VFD): Specific billers (under /p3/bills).

1. SafeHaven (p1) Endpoints

GET /bills/p1/services
GET /bills/p1/categories?service_id={id}
GET /bills/p1/items?service_id={id}&category_id={id}

Purchase (p1)

POST /bills/p1/purchase
sub_user_id
Required.
service_id
Required.
category_id
Required.
item_id
Optional (if item selection needed).
amount
Required.
beneficiary
Phone/Smartcard/Meter number.

2. VTPass (p2) Endpoints

GET /bills/p2/variations?service_id={id}

Verify Customer (p2)

POST /bills/p2/verify

Purchase Airtime (p2)

POST /bills/p2/airtime

Purchase Data (p2)

POST /bills/p2/data

Pay Electricity (p2)

POST /bills/p2/electricity

Pay Cable TV (p2)

POST /bills/p2/cable

3. Verify Transaction Status

GET /bills/p1/verify/{reference}

Note: Use the appropriate verification endpoint based on the provider used for purchase.

Request 
curl -X POST https://api.billway.ng/api/v1/subusers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "USER-123",
    "name": "John Doe",
    "email": "john@example.com"
  }'
Try It