VtyieldAPI v1
Direct B2B API Suite

Vtyield REST API Reference

Integrate wholesale telecommunication, data bundles, electricity vending, cable TV subscriptions, and exam result PINs into your applications.

Format: JSON
HTTPS Only
Atomic Balance Locks
Idempotent Requests
Language Examples:

Overview & Base URL

All API requests must be made over secure HTTPS. All request and response bodies use standard UTF-8 JSON.

https://vtyield.com/api/v1

Authentication

Authenticate requests by including your secret API key in the X-API-Key request header.

Required Headers
X-API-Key: vtk_live_9a8b7c6d5e4f...
Content-Type: application/json
GET

/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"
Response Example (200 OK)
{
  "status": "success",
  "data": {
    "balance": 150000.50,
    "currency": "NGN",
    "site_name": "SwiftPay Portal",
    "funding_accounts": [
      {
        "bank_name": "PalmPay",
        "account_number": "9081234567",
        "account_name": "Vtyield / SwiftPay"
      }
    ]
  }
}
POST

/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" }'
Response Example (200 OK)
{
  "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"
  }
}
POST

/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" }'
POST

/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.

Verify Meter First (Recommended):
POST /api/v1/electricity/verify
{
  "disco": "ikeja-electric",
  "meter_number": "12345678901",
  "meter_type": "prepaid"
}
Purchase Token:
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"
  }'
Purchase Response:
{
  "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"
  }
}
POST

/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" }'
POST

/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" }'
Response:
{
  "status": "success",
  "data": {
    "reference": "tx-waec-pin-99",
    "exam_type": "WAEC",
    "quantity": 1,
    "pins": [
      {
        "pin": "9812-3849-1029",
        "serial": "WR2026-98102"
      }
    ],
    "status": "completed"
  }
}
GET

/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.

Node.js Signature Verification:
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));
}
Python Signature Verification:
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)
PHP Signature Verification:
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

StatusMeaningDescription
200 OKSuccessRequest processed and transaction fulfilled.
400 Bad RequestInvalid PayloadMissing required parameters or insufficient wallet balance.
401 UnauthorizedInvalid KeyAPI key missing, revoked, or invalid.
409 ConflictDuplicate RefIdempotency check: reference already used for a completed transaction.
429 Too Many RequestsRate LimitHourly request limit exceeded.

Ready to Start Integrating?

Apply for instant developer access or generate your live API credentials.