Yenllet API Documentation

Authentication

All API requests must include your secret API key in the Authorization header as a Bearer token. Keep your API key confidential — never expose it in client-side code that end users can inspect.

# Example: authenticate and fetch wallet balance
curl -X GET "https://yenllet.name.ng/api/v1/wallet/balance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Getting Your API Key

Generate your secret API key in three simple steps from the Yenllet dashboard:

1. Log into your Yenllet account at yenllet.name.ng/login and navigate to Dashboard → API Settings.
2. Click the "Generate API Key" button. Your key will be displayed only once — copy and store it securely in a vault or environment variable.
3. Use the key in the Authorization header of every request. You can rotate or revoke a key at any time from the same page.

How Transactions Work

Every Yenllet API transaction follows a predictable lifecycle. Understanding it will help you build robust error handling and reconciliation logic.

1. Client calls an endpoint (e.g. POST /airtime/buy) with the required parameters and your Authorization header.
2. Yenllet validates the request — checks API key, wallet balance, recipient number format, and provider availability.
3. Funds are deducted from your wallet and the transaction is queued for the upstream provider (Clubkonnect / direct aggregator).
4. Provider delivers the service (airtime, data, TV, electricity, betting) to the recipient — usually within 1–10 seconds.
5. Yenllet returns the final response with a status of success, pending, or failed, plus a unique transactionId.

Check Wallet Balance

Returns the current prepaid wallet balance associated with your API key. Useful for pre-flight balance checks before initiating transactions.

Response sample

{
  "success": true,
  "balance": 15423.50,
  "currency": "NGN",
  "walletId": "yw_8f3a9c2e1d",
  "lastUpdated": "2026-01-15T14:32:11Z"
}

Buy Airtime

Deliver instant airtime to any Nigerian phone number. Supports MTN, Airtel, Glo, and 9mobile.

Parameters

Success response

{
  "success": true,
  "status": "success",
  "transactionId": "yx_air_9f2a1c7e",
  "network": "MTN",
  "phone": "08012345678",
  "amount": 500,
  "previousBalance": 15423.50,
  "newBalance": 14923.50,
  "createdAt": "2026-01-15T14:33:02Z"
}

Error response

{
  "success": false,
  "status": "failed",
  "error": "INSUFFICIENT_BALANCE",
  "message": "Wallet balance is too low for this transaction."
}

Buy Data

Purchase a data bundle for any Nigerian number. Pass a valid planId from GET /plans/data.

Parameters

Success response

{
  "success": true,
  "status": "success",
  "transactionId": "yx_dat_4b8c2a1f",
  "network": "MTN",
  "phone": "08012345678",
  "plan": "1GB - 30 Days",
  "amount": 350,
  "newBalance": 14573.50,
  "createdAt": "2026-01-15T14:34:18Z"
}

Subscribe TV

Renew or activate a DStv, GOtv, Startimes, or Showmax subscription. Always call POST /tv/verify first to validate the smartcard / IUC number.

Parameters

Supported TV providers

Pay Electricity

Purchase prepaid electricity tokens for any of the 12 distribution companies (DisCos) in Nigeria. For prepaid meters, a token is returned in the response.

Parameters

Supported DisCos (12)

Get All Plans

Returns the full catalogue of available plans across all categories: data, TV, and betting. Cache this response for up to 1 hour.

Response sample

{
  "success": true,
  "data": {
    "data_plans": [
      { "id": "mtn_1gb_30d", "network": "MTN", "name": "1GB - 30 Days", "price": 350 },
      { "id": "airtel_2gb_30d", "network": "AIRTEL", "name": "2GB - 30 Days", "price": 750 }
    ],
    "tv_plans": [ ... ],
    "betting_providers": [ ... ]
  }
}

Domains API

Yenllet's Domains API lets you search, register, renew, transfer, and fully manage domain names through the WhoGoHost reseller platform — all from a single integrated wallet. Every domain operation is paid from the user's Yenllet wallet balance, so no separate billing is required.

1. List Available TLDs & Pricing

Returns all top-level domains you can register through Yenllet, along with wholesale cost, selling price, and markup. Public endpoint — no auth required.

{
  "success": true,
  "tlds": [
    {
      "tld": "com",
      "register_wholesale": 8200,
      "register_sell": 9200,
      "renew_sell": 9200,
      "transfer_sell": 9200,
      "is_active": true
    },
    { "tld": "com.ng", "register_sell": 5200, ... }
  ]
}

2. Check Domain Availability

Checks if a domain is available for registration and returns the selling price for the matching TLD. Public endpoint.

{
  "success": true,
  "domain": "mybrand.com",
  "available": true,
  "price_register": 9200,
  "price_renew": 9200
}

3. Register a New Domain

Registers a domain for the specified number of years. Deducts the total cost from the user's Yenllet wallet. Nameservers default to WhoGoHost's (ns1.whogohost.com, ns2.whogohost.com) if not provided.

{
  "success": true,
  "message": "Domain mybrand.com registered successfully for 1 year(s).",
  "domain": "mybrand.com",
  "regperiod": 1,
  "amount_charged": 9200
}

4. Renew a Domain

Extends the registration period of an existing domain. The domain must already be registered through Yenllet.

5. Transfer a Domain

Transfers a domain from another registrar to Yenllet. Requires the EPP code from the current registrar. The transfer process typically takes 5–7 days.

6. List Your Domains

Returns all domains registered through the authenticated user's account, including expiry dates and status.

{
  "success": true,
  "domains": [
    {
      "domain": "mybrand.com",
      "regdate": "2026-01-15",
      "expirydate": "2027-01-15",
      "status": "active",
      "id_protect": false
    }
  ]
}

7. Domain Management Endpoints

Each domain you register can be fully managed. All management endpoints follow the pattern /api/domains/:domain/<action> and require authentication.

8. Update DNS Records

Add, modify, or delete DNS records. DNS management only works if your domain's nameservers point to WhoGoHost (ns1.whogohost.com / ns2.whogohost.com). Otherwise, manage DNS at your nameserver provider.

{
  "dnsrecords": [
    { "hostname": "@", "type": "A", "address": "192.168.1.1" },
    { "hostname": "www", "type": "CNAME", "address": "mybrand.com" },
    { "hostname": "@", "type": "MX", "address": "mail.mybrand.com" }
  ]
}

9. Supported TLDs & Live Pricing

Yenllet supports all TLDs available through WhoGoHost. Pricing is set by the admin from the Domains tab — the table below fetches live prices from the API and updates automatically.

10. Domain Registration cURL Example

curl -X POST "https://yenllet.name.ng/api/domains/register" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mybrand.com",
    "regperiod": 1,
    "nameservers": ["ns1.whogohost.com", "ns2.whogohost.com"],
    "contacts": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "phonenumber": "08012345678",
      "address1": "123 Main St",
      "city": "Lagos",
      "state": "Lagos",
      "country": "NG",
      "postcode": "100001"
    },
    "addons": { "id_protect": true }
  }'

Code Examples

Copy-paste examples in your favourite language. All examples show how to buy ₦500 MTN airtime.

// npm install node-fetch (Node 18+ has fetch built-in)
const res = await fetch('https://yenllet.name.ng/api/v1/airtime/buy', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '08012345678',
    amount: 500,
    network: 'MTN',
    reference: 'my-order-001'
  })
});
const data = await res.json();
console.log(data.transactionId);

// app/api/airtime/route.ts
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { phone, amount, network } = await req.json();
  const res = await fetch('https://yenllet.name.ng/api/v1/airtime/buy', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.YENLLET_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ phone, amount, network })
  });
  return NextResponse.json(await res.json());
}

# pip install requests
import requests

url = "https://yenllet.name.ng/api/v1/airtime/buy"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "phone": "08012345678",
    "amount": 500,
    "network": "MTN",
    "reference": "my-order-001",
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data["transactionId"])

<?php
$ch = curl_init("https://yenllet.name.ng/api/v1/airtime/buy");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "phone"     => "08012345678",
    "amount"    => 500,
    "network"    => "MTN",
    "reference" => "my-order-001"
]));

$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["transactionId"];

curl -X POST "https://yenllet.name.ng/api/v1/airtime/buy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"08012345678","amount":500,"network":"MTN","reference":"my-order-001"}'

Reseller API

Yenllet's Reseller tier is designed for businesses reselling VTU services at volume. You get discounted pricing, a white-label dashboard, and dedicated endpoints.

Reseller-only endpoints

Pricing example (Reseller vs Retail)

{
  "mtn_1gb_30d": { "retail": 350, "reseller": 322, "discount_pct": 8 },
  "dstv_premium_1m": { "retail": 24500, "reseller": 22540, "discount_pct": 8 }
}

Reseller Domain API

Mirror what Yenllet does with WhoGoHost: your customer searches and buys a domain on your site, your site calls these endpoints with your x-api-key header, Yenllet charges your wallet, calls WhoGoHost, and the domain is registered in your Yenllet account. No manual login to Yenllet needed — full automation.

1. List TLDs & Prices

Returns all active TLDs with sell prices. Use this to build your domain search page. No request body needed — just the x-api-key header.

{
  "success": true,
  "tlds": [
    { "tld": "com", "register_sell": 15999, "renew_sell": 25000, "transfer_sell": 25000 },
    { "tld": "com.ng", "register_sell": 4000, "renew_sell": 8200, "transfer_sell": 8200 }
  ]
}

2. Check Domain Availability

Checks if a domain is available AND returns the price for that TLD. Use this on your search page — when the user types a domain, call this to show "Available — ₦15,999/year" or "Already taken."

{
  "success": true,
  "domain": "mybrand.com",
  "tld": "com",
  "available": true,
  "price_register": 15999,
  "price_renew": 25000,
  "price_transfer": 25000
}

3. Register a Domain

Registers a domain. Charges your reseller wallet, calls WhoGoHost, and the domain is owned by your Yenllet account. On failure, your wallet is auto-refunded.

curl -X POST "https://yenllet.name.ng/api/v1/domains/register" \
  -H "x-api-key: ylrsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mybrand.com",
    "regperiod": 1,
    "nameservers": ["ns1.cloudflare.com", "ns2.cloudflare.com"],
    "contacts": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "phonenumber": "08012345678",
      "address1": "123 Main St",
      "city": "Lagos",
      "state": "Lagos",
      "country": "NG",
      "postcode": "100001"
    }
  }'

4. Transfer a Domain

Transfer a domain from another registrar to your Yenllet account. Requires the EPP authorization code from the current registrar. Transfer takes 5–7 days to complete.

5. Renew a Domain

Extends the registration of a domain you already own. Body: { "domain": "mybrand.com", "regperiod": 1 }

6. List Your Domains

Returns all domains registered through your reseller API key. Use this to build a "My Domains" dashboard for your customers.

7. Domain Management — DNS, Nameservers, Lock & More

Once a domain is registered, your customers can fully manage it through your site. All management endpoints use the pattern /api/v1/domains/:domain/<action> and require the x-api-key header. A domain can only be managed by the reseller who owns it.

8. DNS Record Management — CNAME, A, MX, TXT & More

Your customers can manage DNS records directly from your site. DNS management only works if the domain's nameservers point to WhoGoHost (ns1.whogohost.com / ns2.whogohost.com). If the customer is using Cloudflare or another DNS provider, they need to manage DNS there.

{
  "dnsrecords": [
    { "hostname": "@", "type": "A", "address": "192.168.1.1" },
    { "hostname": "www", "type": "CNAME", "address": "mybrand.com" },
    { "hostname": "@", "type": "MX", "address": "mail.mybrand.com", "priority": 10 },
    { "hostname": "@", "type": "TXT", "address": "v=spf1 include:_spf.google.com ~all" },
    { "hostname": "_dmarc", "type": "TXT", "address": "v=DMARC1; p=none;" }
  ]
}

9. Complete Flow — How Your Customer Buys a Domain

1. Customer types mybrand.com in the search box on your site
2. Your site calls GET /api/v1/domains/check?domain=mybrand.com → shows "Available — ₦15,999/yr"
3. Customer fills in contact form + selects years, clicks "Buy"
4. Your site calls POST /api/v1/domains/register with contacts + nameservers
5. Yenllet charges your wallet, calls WhoGoHost, returns success + order_uid
6. Your site shows confirmation to the customer
7. Later, customer wants to point DNS to their hosting → your site calls POST /api/v1/domains/mybrand.com/dns
8. Customer wants WHOIS privacy → POST /api/v1/domains/mybrand.com/idprotect
9. Domain near expiry → POST /api/v1/domains/renew

Error Codes

Yenllet uses conventional HTTP response codes. Errors include a machine-readable error code and a human-readable message.

Webhooks

Yenllet fires webhooks for transaction status changes so you can update your own system in real time without polling. Configure your webhook URL in Dashboard → API Settings → Webhooks.

Payload sample

{
  "event": "transaction.completed",
  "transactionId": "yx_air_9f2a1c7e",
  "type": "airtime",
  "status": "success",
  "amount": 500,
  "recipient": "08012345678",
  "reference": "my-order-001",
  "timestamp": "2026-01-15T14:33:05Z",
  "signature": "sha256=ab12cd34ef56..."
}

Webhook fields

Supported Providers

Yenllet integrates with every major Nigerian network, TV provider, electricity DisCo, and betting platform.

Networks

TV providers

Betting providers

Rate Limits

API keys are subject to per-minute and per-day request limits. Limits reset on a rolling window.

Frequently Asked Questions