{
  "info": {
    "_postman_id": "cbi-vas-api-collection-v1",
    "name": "CBI Digital VAS & Telecom API Collection",
    "description": "Comprehensive customer and developer collection for integrating CBI Digital Services: Bulk SMS, VTU Airtime & Data, Utility Bills, Electricity, Cable TV, Wallet Operations, and USSD Gateway.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "version": "1.0.0"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://backend.cbivas.com/api/v1",
      "type": "string"
    },
    {
      "key": "apiKey",
      "value": "YOUR_API_KEY",
      "type": "string"
    },
    {
      "key": "bearerToken",
      "value": "YOUR_JWT_ACCESS_TOKEN",
      "type": "string"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{bearerToken}}",
        "type": "string"
      }
    ]
  },
  "item": [
    {
      "name": "1. Authentication & Profile",
      "item": [
        {
          "name": "Get Auth Token (Login)",
          "request": {
            "auth": { "type": "noauth" },
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"developer@company.com\",\n  \"password\": \"YourSecurePassword123\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/auth/token/pair",
              "host": ["{{baseUrl}}"],
              "path": ["auth", "token", "pair"]
            },
            "description": "Authenticate user and retrieve access token and refresh token."
          }
        },
        {
          "name": "Get Current Profile & Balance Context",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/auth/me",
              "host": ["{{baseUrl}}"],
              "path": ["auth", "me"]
            },
            "description": "Fetch details of the authenticated user, company membership, and permissions."
          }
        },
        {
          "name": "Refresh Access Token",
          "request": {
            "auth": { "type": "noauth" },
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"refresh\": \"YOUR_REFRESH_TOKEN\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/auth/token/refresh",
              "host": ["{{baseUrl}}"],
              "path": ["auth", "token", "refresh"]
            },
            "description": "Obtain a fresh JWT access token using a valid refresh token."
          }
        }
      ]
    },
    {
      "name": "2. Wallet & Balance",
      "item": [
        {
          "name": "Get Wallet Balance",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/wallet/me",
              "host": ["{{baseUrl}}"],
              "path": ["wallet", "me"]
            },
            "description": "Retrieve current available balance, ledger balance, and currency for the account/company."
          }
        },
        {
          "name": "List Wallet Transactions",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/wallet/transactions?page=1&page_size=20",
              "host": ["{{baseUrl}}"],
              "path": ["wallet", "transactions"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "page_size", "value": "20" }
              ]
            },
            "description": "Paginated history of all debits, credits, and transaction references."
          }
        },
        {
          "name": "Initialize Wallet Funding",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amount\": 5000.00,\n  \"gateway\": \"paystack\",\n  \"callback_url\": \"https://yourwebsite.com/payment/callback\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/wallet/fund",
              "host": ["{{baseUrl}}"],
              "path": ["wallet", "fund"]
            },
            "description": "Initialize a payment checkout link to top up the wallet balance."
          }
        },
        {
          "name": "Request Dedicated Virtual Account",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"bvn\": \"22123456789\",\n  \"bank_code\": \"wema\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/wallet/virtual-account/request",
              "host": ["{{baseUrl}}"],
              "path": ["wallet", "virtual-account", "request"]
            },
            "description": "Generate an automated dedicated virtual bank account number for instant bank transfer wallet top-ups."
          }
        }
      ]
    },
    {
      "name": "3. SMS Messaging Service",
      "item": [
        {
          "name": "Send Single or Bulk SMS",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-API-Key", "value": "{{apiKey}}", "disabled": true }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phones\": [\"+2348012345678\", \"+2348098765432\"],\n  \"message\": \"Your verification code is 492810. Valid for 10 minutes.\",\n  \"sender_id\": \"CBISMS\",\n  \"campaign_name\": \"OTP Broadcast\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/sms/send",
              "host": ["{{baseUrl}}"],
              "path": ["sms", "send"]
            },
            "description": "Dispatch single or bulk SMS messages. If 1 phone is specified without campaign name, sent instantly in direct mode."
          }
        },
        {
          "name": "List SMS Campaigns",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/sms/campaigns?page=1&page_size=15",
              "host": ["{{baseUrl}}"],
              "path": ["sms", "campaigns"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "page_size", "value": "15" }
              ]
            },
            "description": "Fetch all previous SMS campaigns with sent counts, delivered metrics, and costs."
          }
        },
        {
          "name": "List Approved Sender IDs",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/sms/sender-ids",
              "host": ["{{baseUrl}}"],
              "path": ["sms", "sender-ids"]
            },
            "description": "Retrieve all registered alphanumeric sender IDs and their approval statuses."
          }
        },
        {
          "name": "Request New Sender ID",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sender_id\": \"MYBRAND\",\n  \"use_case\": \"Transactional alerts and authentication OTPs for our mobile application.\",\n  \"sample_message\": \"Your transaction of NGN 5,000 on MYBRAND was successful.\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/sms/sender-ids/request",
              "host": ["{{baseUrl}}"],
              "path": ["sms", "sender-ids", "request"]
            },
            "description": "Submit a custom alphanumeric sender ID for telco compliance approval."
          }
        }
      ]
    },
    {
      "name": "4. Bill Payment & VTU Services",
      "item": [
        {
          "name": "List Bill Payment Categories",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/bill-payment/categories",
              "host": ["{{baseUrl}}"],
              "path": ["bill-payment", "categories"]
            },
            "description": "List all active service categories (e.g. Airtime, Mobile Data, Electricity, Cable TV, Betting)."
          }
        },
        {
          "name": "List Billers by Category",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/bill-payment/billers?category_slug=data",
              "host": ["{{baseUrl}}"],
              "path": ["bill-payment", "billers"],
              "query": [
                { "key": "category_slug", "value": "data" }
              ]
            },
            "description": "Retrieve billers/telcos under a specific category (e.g. MTN, Airtel, Glo, 9mobile, IKEDC, DSTV)."
          }
        },
        {
          "name": "List Data / TV Plan Packages",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/bill-payment/packages?biller_slug=mtn-data",
              "host": ["{{baseUrl}}"],
              "path": ["bill-payment", "packages"],
              "query": [
                { "key": "biller_slug", "value": "mtn-data" }
              ]
            },
            "description": "Fetch real-time data plans or cable TV subscription bouquets with plan codes and prices."
          }
        },
        {
          "name": "Verify Customer / Meter / Smartcard",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"service_type\": \"electricity\",\n  \"customer_id\": \"10293847561\",\n  \"biller_slug\": \"ikedc-prepaid\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/bill-payment/verify-customer",
              "host": ["{{baseUrl}}"],
              "path": ["bill-payment", "verify-customer"]
            },
            "description": "Validate a customer meter number, smartcard number, or account name before executing payment."
          }
        },
        {
          "name": "Purchase Bill / Airtime / Data",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"category_slug\": \"data\",\n  \"biller_slug\": \"mtn-data\",\n  \"plan_code\": \"MTN-1GB-MONTHLY\",\n  \"customer_id\": \"08031234567\",\n  \"amount\": 1000.00\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/bill-payment/purchase",
              "host": ["{{baseUrl}}"],
              "path": ["bill-payment", "purchase"]
            },
            "description": "Execute instant purchase of VTU Airtime, Data, Electricity token, or Cable TV renewal."
          }
        }
      ]
    },
    {
      "name": "5. USSD Gateway Service",
      "item": [
        {
          "name": "List Active USSD Applications",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Accept", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/ussd/applications",
              "host": ["{{baseUrl}}"],
              "path": ["ussd", "applications"]
            },
            "description": "List configured USSD base codes and extension routes mapped to webhook endpoints."
          }
        },
        {
          "name": "Start Interactive USSD Simulation",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"service_code\": \"*384*100#\",\n  \"phone_number\": \"+2348012345678\",\n  \"network\": \"MTN\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/ussd/simulator/start",
              "host": ["{{baseUrl}}"],
              "path": ["ussd", "simulator", "start"]
            },
            "description": "Initialize a test USSD session against your configured webhook URL."
          }
        },
        {
          "name": "Send USSD Simulator Input",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"session_id\": \"ussd_test_session_12345\",\n  \"user_input\": \"1\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/ussd/simulator/input",
              "host": ["{{baseUrl}}"],
              "path": ["ussd", "simulator", "input"]
            },
            "description": "Submit menu selection for an active USSD simulation session."
          }
        }
      ]
    },
    {
      "name": "6. Webhook Events",
      "item": [
        {
          "name": "Sample Webhook Delivery (SMS DLR)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" },
              { "key": "X-CBI-Signature", "value": "sha256=abcdef123456..." }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"event\": \"sms.delivery_report\",\n  \"data\": {\n    \"message_id\": \"msg_9012481023\",\n    \"recipient\": \"+2348012345678\",\n    \"status\": \"DELIVERED\",\n    \"delivered_at\": \"2026-08-02T08:30:00Z\"\n  }\n}"
            },
            "url": {
              "raw": "https://your-server.com/api/webhooks/cbi",
              "host": ["https://your-server.com"],
              "path": ["api", "webhooks", "cbi"]
            },
            "description": "Format of webhook notifications dispatched from CBI to your configured callback endpoint."
          }
        }
      ]
    }
  ]
}