API reference
Bills
Airtime, data, electricity, cable TV and more, paid from your NGN wallet.
Pay a bill
Creates a bill order and pays it from your Lint NGN wallet in one call. The response may show the order as PENDING when the biller has not answered yet; Lint keeps retrying and posts the final outcome to your registered webhook endpoints as bill_order.completed or bill_order.failed, followed by bill_order.payment_refunded once the payment is returned to your wallet. Each event is sent once per order. Send an Idempotency-Key so a retry after a timeout cannot pay twice.
Headers
- Idempotency-Keystring
Optional, up to 255 characters. Retrying with the same key and the same body within 24 hours returns the original response (with header
Idempotent-Replayed: true) instead of moving money again. The same key with a different body is rejected withidempotency_key_reused; a key whose first request is still running returns 409idempotency_key_in_progress. A request that fails validation does not use up its key.Example:
"payout-2026-11-02-000123"
Body
- biller_product_idintegerrequired
Example:
256 - amount_enteredinteger
Amount in kobo. Required when the product has no fixed amount; must be at least the product's minimum payable amount.
Example: 100000₦1,000.00
- currencystring
Example:
"NGN" - customer_namestring
Example:
"Ada Obi" - product_field_entriesarray of object
One entry per field on the product; every required field must be present.
- field_idinteger
Example:
344 - valuestring
Example:
"08130695389"
Responses
- 201Order paid
- 401Missing, invalid or expired access token.
unauthenticated - 409An earlier request with this Idempotency-Key is still running.
idempotency_key_in_progressinsufficient_balance - 422Validation failed, the wallet cannot cover the order, the order cannot be priced, your wallet is not set up, or the Idempotency-Key was used with a different body.
validation_failedinsufficient_balanceinvalid_orderaccount_not_readyidempotency_key_reused - 502The biller rejected or failed the order (, the message carries the order id and the biller's reason) or could not be reached.
bill_order_failedprovider_errorinsufficient_balance
curl -X POST https://staging.lint.finance/api/partner/v1/vas/billers/create-order \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"biller_product_id": 256,
"amount_entered": 100000,
"currency": "NGN",
"customer_name": "Ada Obi",
"product_field_entries": [
{
"field_id": 344,
"value": "08130695389"
}
]
}'{
"data": {
"id": 88123,
"bill_price": 500000,
"service_fee": 10000,
"total": 510000,
"currency": "NGN",
"customer_id": "45071234567",
"customer_name": "Ada Obi",
"reference": "c41e2f0b9a7d4c1e88123",
"status": "SUCCESSFUL",
"message": "",
"response_pin": "1234-5678-9012-3456-7890",
"customer_entries": [
{
"id": 327,
"field_name": "Meter number",
"field_variable_name": "meter_number",
"customer_entry": "45071234567"
}
],
"product": {},
"product_img": "https://lint-assets-public.s3.amazonaws.com/billers/ikeja-electric.png",
"created_at": "2026-11-02T07:42:54+00:00",
"metadata": [
{}
]
},
"status": "success",
"message": "Bill order created"
}Validate a bill customer
Checks a customer identifier (meter number, smartcard number…) with the biller before you take payment, and returns the name and details the biller holds for it.
Body
- customer_idstringrequired
The identifier the biller expects for this product.
Example:
"45071234567" - product_idintegerrequired
Biller product id.
Example:
256
Responses
- 200The customer as the biller knows them
- 401Missing, invalid or expired access token.
unauthenticated - 422A field failed validation.
validation_failed - 502An upstream bank, biller or identity provider failed. Safe to retry; send the same Idempotency-Key where the endpoint supports one.
provider_error
curl -X POST https://staging.lint.finance/api/partner/v1/vas/billers/validate-customer \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "45071234567",
"product_id": 256
}'{}List billers
Billers you can pay through Lint (electricity, airtime, data, cable TV…). Payroll-only categories (Pension Fund Administrators, HMOs) are left out unless you filter for them explicitly.
Query parameters
- qstring
Search billers by name.
Example:
"ikeja" - biller_category_idinteger
Filter by category id. Wins over category_code when both are sent.
Example:
1 - category_codestring
Filter by category slug, a stable alternative to biller_category_id, e.g.
utilitiesorpension-fund-administrators.Example:
"utilities" - pageinteger
Example:
1 - per_pageinteger
1–100.
Example:
20
Responses
- 200A page of billers
- 401Missing, invalid or expired access token.
unauthenticated - 422A field failed validation.
validation_failed
curl -X GET https://staging.lint.finance/api/partner/v1/vas/billers \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": [
{
"id": 1,
"name": "Electricity Biller",
"short_name": "Electricity",
"popular": true,
"description": "Provides electricity bill payment services",
"logo_url": "https://example.com/logo.png",
"biller_category_id": 5,
"is_airtime_biller": false,
"is_mobile_data_biller": true
}
]
}Retrieve a biller with its products
Returns the biller's products, each with the fields a customer must fill in (meter number, phone number…) and its prices. Use a product id and its field ids to create an order.
Path parameters
- billerintegerrequired
Biller id.
Example:
12
Responses
- 200The biller
- 401Missing, invalid or expired access token.
unauthenticated - 404The resource does not exist or belongs to another partner. The two cases are indistinguishable by design.
not_found
curl -X GET https://staging.lint.finance/api/partner/v1/vas/billers/12 \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": {
"id": 1,
"name": "Electricity Biller",
"short_name": "Electricity",
"popular": true,
"description": "Provides electricity bill payment services",
"logo_url": "https://example.com/logo.png",
"biller_category_id": 5,
"is_airtime_biller": false,
"is_mobile_data_biller": true
},
"message": "Biller fetched successfully"
}Retrieve a bill order
Use this to check an order's final status, e.g. after a timeout or a missed webhook.
Path parameters
- billOrderintegerrequired
Bill order id returned by create-order.
Example:
88123
Responses
- 200The bill order
- 401Missing, invalid or expired access token.
unauthenticated - 404The resource does not exist or belongs to another partner. The two cases are indistinguishable by design.
not_found
curl -X GET https://staging.lint.finance/api/partner/v1/vas/billers/orders/88123 \
-H "Authorization: Bearer $LINT_ACCESS_TOKEN" \
-H "Accept: application/json"{
"data": {
"id": 88123,
"bill_price": 500000,
"service_fee": 10000,
"total": 510000,
"currency": "NGN",
"customer_id": "45071234567",
"customer_name": "Ada Obi",
"reference": "c41e2f0b9a7d4c1e88123",
"status": "SUCCESSFUL",
"message": "",
"response_pin": "1234-5678-9012-3456-7890",
"customer_entries": [
{
"id": 327,
"field_name": "Meter number",
"field_variable_name": "meter_number",
"customer_entry": "45071234567"
}
],
"product": {},
"product_img": "https://lint-assets-public.s3.amazonaws.com/billers/ikeja-electric.png",
"created_at": "2026-11-02T07:42:54+00:00",
"metadata": [
{}
]
},
"status": "success",
"message": "Bill order retrieved"
}