Introduction

Welcome to the VTStack API Reference. Our platform provides enterprise-grade infrastructure for Virtual Account Management, specifically optimized for small businesses and digital top-up platforms.

With VTStack, you can programmatically create dedicated virtual bank accounts through our partner PalmPay, enabling instant wallet funding and real-time transaction notifications.

The Integration Path

Follow these 5 steps to go from zero to live transactions on VTStack. Each step is designed to ensure maximum security and reliability.

// Header for all requests
x-api-key: sk_live_xxxxxxxxxxxx

curl -X POST https://api.vtstack.ng/api/virtual-accounts \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
        "firstName": "Hassan",
        "lastName": "Ibrahim",
        "email": "hassan@example.com",
        "phone": "08012345678",
        "bvn": "22123456789",
        "reference": "user_102_fund_acc"
    }'

// Example Webhook Response (POST)
{
  "event": "transaction.deposit",
  "data": {
    "accountNumber": "8102345678",
    "amount": 5000,
    "reference": "VT-DEP-721",
    "status": "success"
  }
}

// Returns verified account name
{
  "success": true,
  "data": { "accountName": "HASSAN IBRAHIM" }
}

Authentication

All API requests require a secret key to be included in the header of your request. Your secret keys allow access to your account sensitive operations, so keep them secure.

// Use the x-api-key header for all requests
x-api-key: YOUR_SECRET_KEY

Base URL

All API requests should be made to the following base URL:

https://api.vtstack.ng/api

Endpoints

{
  "firstName": "Hassan",
  "lastName": "Ibrahim",
  "email": "hassan@example.com",
  "phone": "08012345678",
  "bvn": "22123456789",
  "reference": "user_id_102"
}

{
  "success": true,
  "data": [
    {
      "accountNumber": "8102345678",
      "accountName": "Hassan Ibrahim",
      "bankName": "PalmPay",
      "status": "active"
    }
  ]
}

Bank Verification

Use VTStack's Bank Verification API to resolve and verify bank account details before initiating payouts. This helps prevent failed transfers by confirming the account holder's name and validating the account number against the bank.

curl -X GET https://api.vtstack.ng/api/banks \
  -H "x-api-key: YOUR_SECRET_KEY"

{
  "success": true,
  "data": [
    { "code": "100033", "name": "PalmPay" },
    { "code": "044", "name": "Access Bank" },
    { "code": "058", "name": "Guaranty Trust Bank" },
    { "code": "033", "name": "United Bank for Africa" },
    { "code": "057", "name": "Zenith Bank" }
  ]
}

curl -X GET "https://api.vtstack.ng/api/banks/verify?bankCode=044&accountNumber=0123456789" \
  -H "x-api-key: YOUR_SECRET_KEY"

{
  "success": true,
  "data": {
    "accountName": "HASSAN IBRAHIM",
    "accountNumber": "0123456789",
    "bankCode": "044"
  }
}

// 400 — Missing parameters
{
  "success": false,
  "message": "bankCode and accountNumber are required"
}

// 400 — Invalid account
{
  "success": false,
  "message": "Bank resolution failed"
}

Webhooks

Webhooks are used to notify your server of events. We send a POST request to your configured URL when a deposit is received.

{
  "event": "transaction.deposit",
  "data": {
    "reference": "TXN_7726182",
    "amount": 5000,
    "currency": "NGN",
    "customer": { "name": "Hassan Ibrahim" },
    "timestamp": "2026-03-20T14:30:00Z"
  }
}

Errors & Handling

Our API returns standard HTTP status codes. Errors are always returned in a JSON format for easy parsing.

Best Practices