RanoSub RanoSub developers
Vend external API · v1

A simple API for your app

Choose a service, use only its required fields, and see the response here before adding it to your own app.

Getting started

Base URL: https://YOUR_VEND_DOMAIN/api/v1. Amounts are in naira. Vend creates a transaction reference for every purchase.

Public endpoints

Health GET /api/v1/health

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/health"
Response example
{
  "status": "ok",
  "version": "v1",
  "enabled": true
}

Services GET /api/v1/services

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/services"
Response example
{
  "status": "success",
  "data": [
    "airtime",
    "data",
    "electricity",
    "cable",
    "exam_pin",
    "bulk_sms",
    "data_card",
    "recharge_card",
    "identity_slips"
  ]
}

Data plans by network GET /api/v1/products?service=data&network=mtn

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/products?service=data&network=mtn"
Response example
{
  "status": "success",
  "data": [
    {
      "code": 1,
      "name": "1GB Monthly",
      "plan_size": "1 GB",
      "network": "mtn",
      "service_code": "mtn-data",
      "service_name": "MTN Data",
      "price": 500,
      "validity": "30 days"
    }
  ]
}

Use your API key

Generate a key in your developer dashboard. Send it as Authorization: Bearer YOUR_VEND_API_KEY. Save it in this browser to keep it after refreshing.

Airtime

Top up a Nigerian phone number.

POST /api/v1/airtime

Get current products and codes: GET /api/v1/products?service=airtime. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields
networkNetworkRequired
phonePhoneRequired
amountAmount (₦)Required
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Data

Choose a network, select a data plan, then enter the phone number.

POST /api/v1/data

Get current products and codes: GET /api/v1/products?service=data. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Networks: mtn, airtel, glo, 9mobile. Get plans for one network with GET /api/v1/products?service=data&network=mtn, then send its code as plan with the same network.

Required fields
networkNetworkRequired
planData planRequired
phonePhoneRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Electricity

Pay a prepaid or postpaid electricity meter.

POST /api/v1/electricity

Get current products and codes: GET /api/v1/products?service=electricity. Use the numeric code for a plan or slip template, or service_code for disco.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields

Check the account before paying: POST /api/v1/verify/electricity

discoElectricity companyRequired
meterMeter numberRequired
meter_typeMeter typeRequired
amountAmount (₦)Required
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Cable TV

Renew a cable TV subscription.

POST /api/v1/cable

Get current products and codes: GET /api/v1/products?service=cable. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields

Check the account before paying: POST /api/v1/verify/cable

planTV packageRequired
smartcardSmartcard or IUCRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Exam PIN

Buy exam PINs. Optional quantity: 1–10, default 1. Delivery uses your account phone.

POST /api/v1/exam-pins

Get current products and codes: GET /api/v1/products?service=exam_pin. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields
planExam productRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Bulk SMS

Send one message to up to 1,000 unique numbers.

POST /api/v1/sms

Get current products and codes: GET /api/v1/products?service=bulk_sms. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields
senderSenderRequired
recipientsRecipientsRequired
messageMessageRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Data card

Buy data cards. Optional quantity: 1–10 and card_name. Delivery uses your account phone.

POST /api/v1/data-cards

Get current products and codes: GET /api/v1/products?service=data_card. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields
planData cardRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Recharge card

Buy recharge cards. Optional quantity: 1–10 and card_name. Delivery uses your account phone.

POST /api/v1/recharge-cards

Get current products and codes: GET /api/v1/products?service=recharge_card. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields
planRecharge cardRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

NIN / BVN slips

Generate a protected identity slip PDF.

POST /api/v1/identity-slips

Get current products and codes: GET /api/v1/products?service=identity_slips. Use the numeric code for a plan or slip template.

Product codes are permanent numbers. Send the returned code as a JSON number in plan or template, for example 1. Codes stay the same when products are sorted or filtered.

Required fields
templateSlip typeRequired
number11-digit NIN or BVNRequired
referenceYour own transaction reference. Reuse it to retry safely.Optional

This sends a real request and may charge your Vend wallet.

Wallet and transaction status

Use your key to check your available wallet balance or a purchase result. For identity slips, GET /api/v1/identity-slips/REFERENCE/download returns a short-lived PDF link.

Wallet balance GET /api/v1/wallet

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/wallet" -H "Authorization: Bearer YOUR_VEND_API_KEY"
Response example
{
  "status": "success",
  "data": {
    "balance": 2500,
    "held": 0,
    "currency": "NGN"
  }
}

Transaction history GET /api/v1/transactions?limit=50

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/transactions?limit=50" -H "Authorization: Bearer YOUR_VEND_API_KEY"
Response example
{
  "status": "success",
  "data": [
    {
      "status": "pending",
      "reference": "vtu_...",
      "customer_reference": "my-order-001",
      "service": "data",
      "network": "MTN",
      "phone_number": "08012345678",
      "product": "Example data product",
      "amount": 500,
      "total": 500,
      "balance_before": 15000,
      "balance_after": 14500,
      "currency": "NGN",
      "source": "api",
      "message": "Transaction is processing."
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "OPAQUE_CURSOR"
  }
}

Transaction status GET /api/v1/transactions/vtu_...

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/transactions/vtu_..." -H "Authorization: Bearer YOUR_VEND_API_KEY"
Response example
{
  "status": "success",
  "data": {
    "status": "pending",
    "reference": "vtu_...",
    "customer_reference": "my-order-001",
    "service": "data",
    "network": "MTN",
    "phone_number": "08012345678",
    "product": "Example data product",
    "amount": 500,
    "total": 500,
    "balance_before": 15000,
    "balance_after": 14500,
    "currency": "NGN",
    "source": "api",
    "message": "Transaction is processing."
  }
}

Identity slip download GET /api/v1/identity-slips/vend_slip_.../download

Request example
curl "https://YOUR_VEND_DOMAIN/api/v1/identity-slips/vend_slip_.../download" -H "Authorization: Bearer YOUR_VEND_API_KEY"
Response example
{
  "status": "success",
  "reference": "vend_slip_...",
  "service": "identity_slips",
  "product": "NIN basic slip",
  "amount": 2000,
  "total": 2000,
  "balance_before": 5000,
  "balance_after": 3000,
  "currency": "NGN",
  "source": "api",
  "download_url": "https://example.com/short-lived-file-link",
  "expires_in_minutes": 10
}

Webhooks

Add an HTTPS callback URL in your developer dashboard. Vend sends a small JSON notification when an API transaction changes status. No webhook secret is needed; confirm the reference with the authenticated transaction endpoint before updating your app.

Request example
POST https://YOUR_APP_DOMAIN/webhook
Content-Type: application/json

{
  "event": "transaction.succeeded",
  "reference": "vtu_...",
  "customer_reference": "my-order-001",
  "status": "succeeded",
  "service": "data",
  "amount": 500,
  "total": 500,
  "balance_before": 3000,
  "balance_after": 2500,
  "currency": "NGN"
}
Response example
{
  "received": true
}

Return HTTP 200 after receiving the notification. Confirm the reference through the authenticated transaction endpoint.

Test your saved webhook

Each saved URL has Test webhook and View history. A test sends the event below without creating a purchase or changing the wallet. HTTP 2xx confirms your endpoint accepted it; check your server logs to verify your handler processed it. Never credit a wallet or fulfil an order for a test event. Tests are limited to five per minute.

Request example
POST https://YOUR_APP_DOMAIN/webhook
Content-Type: application/json

{
  "event": "webhook.test",
  "test": true,
  "reference": "test_...",
  "created_at": "2026-10-07T12:00:00Z",
  "data": {
    "message": "Webhook connection test. No transaction or wallet change."
  }
}
Response example
{
  "received": true
}

Saved webhook URLs and delivery results remain in your developer dashboard history.