Y3Data Developer REST API Documentation (v1)

1. Introduction & Base URL

The Y3Data Developer API gives software applications direct programmatic access to Nigerian digital services. All endpoints communicate over HTTPS using standard JSON payloads, HTTP verbs, and RFC-compliant status codes.

Production Base URL

              https://y3data.com/api/v1
            

2. Authentication

Every request must be authenticated with your Y3Data production API key passed via the standard HTTP Authorization header as a Bearer token.

# Standard Bearer Authorization (Recommended)
Authorization: Bearer y3_live_1a2b3c4d5e6f7g8h9i0j...
# Alternative Header (Supported)
X-API-Key: y3_live_1a2b3c4d5e6f7g8h9i0j...

Security Rule: Passing API keys via URL query parameters (e.g. ?api_key=...) or request body parameters is strictly rejected with HTTP 401 INVALID_AUTHENTICATION_METHOD to prevent accidental token exposure in web server access logs.

3. Request Idempotency (`request_id`)

To ensure money safety and eliminate double-charging during network drops, socket timeouts, or automatic retry loops, all purchase endpoints require a client-generated unique string: request_id.

Zero Double-Charge Guarantee: If the gateway receives a purchase request with an already processed request_id, it safely intercepts the request, skips re-charging your wallet, and immediately returns the cached transaction response.

4. Rate Limits

Rate limits are applied on a per-developer basis. The standard default allocation is 60 requests per minute. High-volume merchants may request elevated throughput limits through Developer Support.

Every response includes real-time telemetry headers:

X-RateLimit-Limit: Maximum allowed requests per 60-second window.
X-RateLimit-Remaining: Remaining requests available in the current window.
X-RateLimit-Reset: Epoch timestamp when the rate limit quota resets.

5. Standard Error Responses

All API errors return consistent JSON structures accompanied by standard HTTP 4xx or 5xx status codes:

{
  "status": "error",
  "code": "INSUFFICIENT_BALANCE",
  "message": "Insufficient API wallet balance.",
  "request_id": "ORDER-98234-XYZ",
  "balance": 150.00,
  "required_amount": 270.00,
  "shortfall": 120.00
}
          

HTTP Code	Error Code	Description
`401`	`UNAUTHORIZED`	Missing or malformed Authorization header.
`401`	`INVALID_API_KEY`	Key hash not found or key revoked.
`403`	`ACCOUNT_SUSPENDED`	Developer account is suspended.
`403`	`IP_NOT_WHITELISTED`	Client IP address is not on your allowed whitelist.
`400`	`INSUFFICIENT_BALANCE`	Wallet balance is lower than transaction cost.
`400`	`INVALID_REQUEST`	Missing required parameter or malformed request payload.
`429`	`RATE_LIMIT_EXCEEDED`	Exceeded per-minute quota. Back off and retry.
`502`	`SERVICE_UNAVAILABLE`	Upstream provider temporary outage. Wallet is not debited.

GET

/api/v1/account/balance

Query your available live API wallet balance. Your balance is debited in real-time as transactions are dispatched.

Response (200 OK)

{
  "status": "success",
  "balance": 25450.00,
  "currency": "NGN"
}
          

Mobile Data Bundles

Retrieve available data packages with wholesale pricing and dispatch automated top-ups across Nigerian mobile networks.

GET

/api/v1/data/plans

Query parameters: ?network=MTN (optional filter: MTN, AIRTEL, GLO, 9MOBILE).

POST

/api/v1/data/purchase

Request Body (JSON)

Field	Type	Required	Description
`network`	String	Yes	`MTN`, `AIRTEL`, `GLO`, or `9MOBILE`.
`plan_id`	String	Yes	Plan identifier from catalog (e.g. `mtn_1gb_sme`).
`phone`	String	Yes	11-digit recipient phone number (e.g. `08012345678`).
`request_id`	String	Yes	Unique client transaction reference for idempotency.

Response (200 OK)

{
  "status": "success",
  "message": "Data purchase successful",
  "transaction_id": "Y3API-ABCDEF12345",
  "request_id": "ORDER-98234-XYZ",
  "service": "data",
  "network": "MTN",
  "plan": "1.0GB SME",
  "phone": "08012345678",
  "amount": 270.00,
  "balance_after": 14730.00,
  "created_at": "2026-09-16T21:00:00+01:00"
}
          

Airtime VTU Top-up

Instant automated airtime recharge with server-calculated volume discounts.

GET

/api/v1/airtime/plans

Returns supported networks, minimum/maximum values, and active discount percentages for your account.

POST

/api/v1/airtime/purchase

Request Body (JSON)

Field	Type	Required	Description
`network`	String	Yes	`MTN`, `AIRTEL`, `GLO`, or `9MOBILE`.
`amount`	Numeric	Yes	Face value to recharge (₦50 – ₦50,000).
`phone`	String	Yes	11-digit recipient phone number.
`request_id`	String	Yes	Unique client request reference.

Response (200 OK)

{
  "status": "success",
  "message": "Airtime top-up successful",
  "transaction_id": "Y3AIR-ABCDEF12345",
  "request_id": "REQ-AIR-001",
  "service": "airtime",
  "network": "MTN",
  "phone": "08012345678",
  "face_value": 1000.00,
  "amount": 980.00,
  "discount": 20.00,
  "balance_after": 14020.00
}
          

Electricity Bills & Tokens

Validate prepaid & postpaid meter numbers and generate recharge tokens across all major Nigerian DisCos.

GET

/api/v1/electricity/providers

Supported DisCos: IKEDC, EKEDC, AEDC, IBEDC, KEDCO, PHED, EEDC, BEDC, YEDC, JED.

POST

/api/v1/electricity/validate

Validates meter number and returns verified customer name and address before purchase. Parameters: biller, meter_number, meter_type (prepaid/postpaid).

POST

/api/v1/electricity/purchase

Request Body (JSON)

Field	Type	Required	Description
`biller`	String	Yes	DisCo code (e.g. `IKEDC`).
`meter_number`	String	Yes	Meter number (minimum 8 digits).
`amount`	Numeric	Yes	Token value in Naira (₦500 – ₦100,000).
`meter_type`	String	No	`prepaid` (default) or `postpaid`.
`phone`	String	No	Customer phone number for SMS token delivery.
`request_id`	String	Yes	Unique client transaction reference.

Response (200 OK)

{
  "status": "success",
  "message": "Electricity token generated successfully",
  "transaction_id": "Y3ELEC-ABCDEF12345",
  "request_id": "REQ-ELEC-001",
  "service": "electricity",
  "biller": "IKEDC",
  "meter_number": "01234567890",
  "amount": 5000.00,
  "token": "1234-5678-9012-3456",
  "units": "76.3 kWh",
  "balance_after": 9730.00
}
          

Cable TV Subscriptions

Validate SmartCard / IUC numbers and activate bouquets across DStv, GOtv, StarTimes, and Showmax.

GET

/api/v1/cable/plans?provider=GOTV

POST

/api/v1/cable/validate

Parameters: provider, smartcard_number. Returns verified subscriber name.

POST

/api/v1/cable/subscribe

Request Body (JSON)

Field	Type	Required	Description
`provider`	String	Yes	`GOTV`, `DSTV`, `STARTIMES`, or `SHOWMAX`.
`plan_id`	String	Yes	Bouquet plan identifier (e.g. `gotv_smallie`).
`smartcard_number`	String	Yes	SmartCard / IUC number (min 8 digits).
`request_id`	String	Yes	Unique client transaction reference.

Response (200 OK)

{
  "status": "success",
  "message": "Cable TV subscription renewed successfully",
  "transaction_id": "Y3CAB-ABCDEF12345",
  "request_id": "REQ-CAB-001",
  "service": "cable",
  "provider": "GOTV",
  "package": "GOtv Smallie",
  "smartcard": "1234567890",
  "amount": 1575.00,
  "balance_after": 8155.00
}
          

Educational Exam PINs

Generate electronic scratch card result checker tokens for WAEC, NECO, NABTEB, and JAMB UTME.

GET

/api/v1/exams/products

POST

/api/v1/exams/purchase

Request Body (JSON)

Field	Type	Required	Description
`exam_type`	String	Yes	`waec`, `neco`, `nabteb`, or `jamb`.
`quantity`	Integer	Yes	Number of PINs (1 to 10).
`request_id`	String	Yes	Unique client transaction reference.

Response (200 OK)

{
  "status": "success",
  "message": "Exam PIN(s) generated successfully",
  "transaction_id": "Y3EXAM-ABCDEF12345",
  "request_id": "REQ-EXAM-001",
  "service": "exam_pin",
  "exam_type": "WAEC",
  "quantity": 1,
  "unit_price": 3850.00,
  "amount": 3850.00,
  "pins": [
    "Y3-WAEC-12345678 (Pin: 987654)"
  ],
  "balance_after": 4305.00
}
          

GET

/api/v1/transactions/{id}

Inquire about the real-time status of any transaction using either your original client request_id or the Y3Data reference. Returns only transactions belonging to your authenticated account.

Response (200 OK)

{
  "status": "success",
  "data": {
    "transaction_id": "Y3API-ABCDEF12345",
    "request_id": "ORDER-98234-XYZ",
    "service": "data",
    "network": "MTN",
    "plan_id": "mtn_1gb_sme",
    "phone": "08012345678",
    "amount": 270.00,
    "status": "SUCCESS",
    "message": "Data purchase successful",
    "created_at": "2026-09-16 21:00:00"
  }
}
          

Outbound Webhooks

When enabled in your dashboard, Y3Data dispatches asynchronous HTTP POST notifications to your server upon transaction resolution.

Supported Events

transaction.completed: Triggered when a purchase resolves with status SUCCESS.
transaction.failed: Triggered when a purchase fails and refund is credited to your balance.

Sample Webhook Payload

{
  "event": "transaction.completed",
  "timestamp": "2026-09-16T21:05:00+01:00",
  "data": {
    "transaction_reference": "Y3API-ABCDEF12345",
    "request_id": "ORDER-98234-XYZ",
    "service": "data",
    "amount": 270.00,
    "status": "SUCCESS"
  }
}
          

HMAC Signature Verification

Every delivery includes a header X-Y3Data-Signature. Compute the HMAC-SHA256 signature of the raw request payload using your secret:

// PHP Webhook Receiver Example
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_Y3DATA_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $myWebhookSecret);

if (hash_equals($expected, $signature)) {
    // Verified authentic from Y3Data
    $event = json_decode($payload, true);
    http_response_code(200);
} else {
    http_response_code(401);
}
          

IP Whitelist Security

You can configure allowed production IP addresses in the IP Whitelist tab of your Developer Console. When at least one active IP address is registered, all incoming API requests originating from unlisted addresses are strictly rejected with HTTP 403 IP_NOT_WHITELISTED. If no IP addresses are registered, requests are accepted from any origin.

Code Examples

Node.js / JavaScript (Fetch)

const response = await fetch('https://y3data.com/api/v1/data/purchase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + process.env.Y3DATA_API_KEY
  },
  body: JSON.stringify({
    network: 'MTN',
    plan_id: 'mtn_1gb_sme',
    phone: '08012345678',
    request_id: 'ORDER-' + Date.now()
  })
});
const result = await response.json();
console.log(result);
          

PHP (cURL)

$ch = curl_init('https://y3data.com/api/v1/account/balance');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Accept: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
          

Y3Data Developer API Documentation

1. Introduction & Base URL

2. Authentication

3. Request Idempotency (`request_id`)

4. Rate Limits

5. Standard Error Responses

/api/v1/account/balance

Response (200 OK)

Mobile Data Bundles

/api/v1/data/plans

/api/v1/data/purchase

Request Body (JSON)

Response (200 OK)

Airtime VTU Top-up

/api/v1/airtime/plans

/api/v1/airtime/purchase

Request Body (JSON)

Response (200 OK)

Electricity Bills & Tokens

/api/v1/electricity/providers

/api/v1/electricity/validate

/api/v1/electricity/purchase

Request Body (JSON)

Response (200 OK)

Cable TV Subscriptions

/api/v1/cable/plans?provider=GOTV

/api/v1/cable/validate

/api/v1/cable/subscribe

Request Body (JSON)

Response (200 OK)

Educational Exam PINs

/api/v1/exams/products

/api/v1/exams/purchase

Request Body (JSON)

Response (200 OK)

/api/v1/transactions/{id}

Response (200 OK)

Outbound Webhooks

Supported Events

Sample Webhook Payload

HMAC Signature Verification

IP Whitelist Security

Code Examples

Node.js / JavaScript (Fetch)

PHP (cURL)

Insufficient Wallet Balance

Select Your State