Vtyield REST API Reference
Integrate wholesale telecommunication, data bundles, electricity vending, cable TV subscriptions, and exam result PINs into your applications.
Overview & Base URL
All API requests must be made over secure HTTPS. All request and response bodies use standard UTF-8 JSON.
Authentication
Authenticate requests by including your secret API key in the X-API-Key request header.
X-API-Key: vtk_live_9a8b7c6d5e4f... Content-Type: application/json
/api/v1/account/balance
Retrieve your current API wallet balance and dedicated virtual bank accounts for automated programmatic wallet funding.
curl https://vtyield.com/api/v1/account/balance \
-H "X-API-Key: YOUR_API_KEY"{
"status": "success",
"data": {
"balance": 150000.50,
"currency": "NGN",
"site_name": "SwiftPay Portal",
"funding_accounts": [
{
"bank_name": "PalmPay",
"account_number": "9081234567",
"account_name": "Vtyield / SwiftPay"
}
]
}
}/api/v1/airtime/purchase
Purchase airtime for MTN, GLO, AIRTEL, or 9MOBILE with instant fulfillment.
curl -X POST https://vtyield.com/api/v1/airtime/purchase \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"network": "MTN",
"phone": "08012345678",
"amount": 1000,
"reference": "tx-unique-airtime-1234"
}'{
"status": "success",
"message": "Airtime purchased successfully",
"data": {
"reference": "tx-unique-airtime-1234",
"transaction_id": "tx_a1b2c3d4e5",
"amount": 1000,
"discount": 20,
"amount_charged": 980,
"network": "MTN",
"phone": "08012345678",
"status": "completed"
}
}/api/v1/data/purchase
Purchase data bundles (SME, Gifting, Corporate) by providing the plan ID. Use GET /api/v1/data/plans to fetch live plans.
curl -X POST https://vtyield.com/api/v1/data/purchase \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"plan_id": "prod_mtn_1gb_sme",
"phone": "08012345678",
"reference": "tx-unique-data-5678"
}'/api/v1/electricity/purchase
Pay electricity bills and receive prepaid meter tokens. Discos supported: ikeja-electric, eko-electric, abuja-electric, kano-electric, portharcourt-electric, ibadan-electric, jos-electric, kaduna-electric, enugu-electric, benin-electric, aba-electric, yola-electric.
POST /api/v1/electricity/verify
{
"disco": "ikeja-electric",
"meter_number": "12345678901",
"meter_type": "prepaid"
}curl -X POST https://vtyield.com/api/v1/electricity/purchase \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"disco": "ikeja-electric",
"meter_number": "12345678901",
"meter_type": "prepaid",
"amount": 3000,
"phone": "08012345678",
"reference": "tx-elec-9988"
}'{
"status": "success",
"message": "Electricity bill paid successfully",
"data": {
"reference": "tx-elec-9988",
"token": "4810-9281-7491-0291-8472",
"units": "45.2 kWh",
"amount": 3000,
"status": "completed"
}
}/api/v1/tv/purchase
Subscribe to DSTV, GOTV, Startimes, and Showmax. Verify smartcard/IUC using POST /api/v1/tv/verify.
curl -X POST https://vtyield.com/api/v1/tv/purchase \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service_id": "dstv",
"smartcard_number": "1234567890",
"variation_code": "dstv-padi",
"phone": "08012345678",
"reference": "tx-tv-subscription-1122"
}'/api/v1/exam-pins/purchase
Purchase result checker tokens for WAEC, NECO, NABTEB, and JAMB UTME PINs with instant digital PIN/serial delivery.
curl -X POST https://vtyield.com/api/v1/exam-pins/purchase \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"exam_type": "WAEC",
"quantity": 1,
"phone": "08012345678",
"reference": "tx-waec-pin-99"
}'{
"status": "success",
"data": {
"reference": "tx-waec-pin-99",
"exam_type": "WAEC",
"quantity": 1,
"pins": [
{
"pin": "9812-3849-1029",
"serial": "WR2026-98102"
}
],
"status": "completed"
}
}/api/v1/transactions/status
Requery the status of any transaction using your original unique reference or the system transaction_id.
curl "https://vtyield.com/api/v1/transactions/status?reference=tx-unique-airtime-1234" \
-H "X-API-Key: YOUR_API_KEY"Webhook Integration & HMAC-SHA512
Receive real-time notifications for transaction events. Each webhook HTTP request includes a header X-Vtyield-Signature containing the HMAC-SHA512 hex digest of the raw request payload.
const crypto = require('crypto');
function verifyWebhook(rawPayloadString, signatureHeader, webhookSecret) {
const computed = crypto
.createHmac('sha512', webhookSecret)
.update(rawPayloadString)
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(signatureHeader));
}import hmac
import hashlib
def verify_webhook(raw_payload_bytes, signature_header, webhook_secret):
computed = hmac.new(
webhook_secret.encode('utf-8'),
raw_payload_bytes,
hashlib.sha512
).hexdigest()
return hmac.compare_digest(computed, signature_header)function verify_vtyield_webhook(string $rawPayload, string $signatureHeader, string $secret): bool {
if (empty($signatureHeader) || empty($secret)) {
return false;
}
$expected = hash_hmac('sha512', $rawPayload, $secret);
return hash_equals($expected, $signatureHeader);
}HTTP Status Codes & Error Responses
| Status | Meaning | Description |
|---|---|---|
| 200 OK | Success | Request processed and transaction fulfilled. |
| 400 Bad Request | Invalid Payload | Missing required parameters or insufficient wallet balance. |
| 401 Unauthorized | Invalid Key | API key missing, revoked, or invalid. |
| 409 Conflict | Duplicate Ref | Idempotency check: reference already used for a completed transaction. |
| 429 Too Many Requests | Rate Limit | Hourly request limit exceeded. |
Ready to Start Integrating?
Apply for instant developer access or generate your live API credentials.