{
  "openapi": "3.0.3",
  "info": {
    "title": "CBI Digital VAS & Telecom Developer API",
    "description": "Developer and Merchant API specification for integrating Bulk SMS, VTU Airtime & Data, Utility Bills, Electricity, Cable TV, Wallet Operations, and USSD Gateway with CBI Digital Platform.",
    "version": "1.0.0",
    "contact": {
      "name": "CBI Developer Support",
      "email": "info@cbidigitalmedia.com",
      "url": "https://cbivas.com"
    }
  },
  "servers": [
    {
      "url": "https://backend.cbivas.com/api/v1",
      "description": "Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Provide your JWT access token (Bearer <token>)"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Provide your live or test merchant API key"
      }
    },
    "schemas": {
      "MessageOut": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "code": { "type": "string" }
        },
        "required": ["message"]
      },
      "UserOut": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "email": { "type": "string" },
          "first_name": { "type": "string" },
          "last_name": { "type": "string" },
          "phone": { "type": "string" },
          "account_type": { "type": "string", "enum": ["individual", "business"] }
        }
      },
      "WalletOut": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "balance": { "type": "number", "format": "decimal", "example": 15450.00 },
          "ledger_balance": { "type": "number", "format": "decimal", "example": 15450.00 },
          "currency": { "type": "string", "example": "NGN" }
        }
      },
      "SendSMSIn": {
        "type": "object",
        "required": ["phones", "message"],
        "properties": {
          "phones": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["+2348012345678", "+2348098765432"]
          },
          "message": {
            "type": "string",
            "example": "Your transaction OTP is 584912. Valid for 10 minutes."
          },
          "sender_id": {
            "type": "string",
            "example": "CBISMS"
          },
          "campaign_name": {
            "type": "string",
            "example": "August Broadcast"
          },
          "scheduled_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SendSMSOut": {
        "type": "object",
        "properties": {
          "message_id": { "type": "string" },
          "campaign_id": { "type": "string" },
          "recipients_count": { "type": "integer" },
          "units_charged": { "type": "number" },
          "status": { "type": "string", "example": "SUBMITTED" }
        }
      },
      "CategoryOut": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string", "example": "Mobile Data" },
          "slug": { "type": "string", "example": "data" },
          "description": { "type": "string" }
        }
      },
      "BillerOut": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string", "example": "MTN Nigeria" },
          "slug": { "type": "string", "example": "mtn-data" },
          "category_id": { "type": "string" }
        }
      },
      "PackageOut": {
        "type": "object",
        "properties": {
          "plan_code": { "type": "string", "example": "MTN-1GB-MONTHLY" },
          "name": { "type": "string", "example": "MTN 1GB (30 Days)" },
          "amount": { "type": "string", "example": "1000.00" },
          "validity": { "type": "string", "example": "30 days" }
        }
      },
      "VerifyCustomerIn": {
        "type": "object",
        "required": ["service_type", "customer_id"],
        "properties": {
          "service_type": { "type": "string", "example": "electricity" },
          "customer_id": { "type": "string", "example": "10293847561" },
          "biller_slug": { "type": "string", "example": "ikedc-prepaid" }
        }
      },
      "VerifyCustomerOut": {
        "type": "object",
        "properties": {
          "customer_name": { "type": "string", "example": "KOLAWOLE ADEMOLA" },
          "customer_id": { "type": "string", "example": "10293847561" },
          "status": { "type": "string", "example": "valid" }
        }
      },
      "BillPurchaseIn": {
        "type": "object",
        "required": ["category_slug", "customer_id", "amount"],
        "properties": {
          "category_slug": { "type": "string", "example": "data" },
          "biller_slug": { "type": "string", "example": "mtn-data" },
          "plan_code": { "type": "string", "example": "MTN-1GB-MONTHLY" },
          "customer_id": { "type": "string", "example": "08031234567" },
          "amount": { "type": "number", "format": "decimal", "example": 1000.00 }
        }
      },
      "BillPaymentOut": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "reference": { "type": "string", "example": "BILL-938481023" },
          "category": { "type": "string" },
          "biller": { "type": "string" },
          "customer_id": { "type": "string" },
          "amount": { "type": "number", "format": "decimal" },
          "status": { "type": "string", "example": "SUCCESS" },
          "token": { "type": "string", "example": "4920-1928-3920-1928" },
          "created_at": { "type": "string" }
        }
      }
    }
  },
  "security": [
    { "BearerAuth": [] },
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/auth/me": {
      "get": {
        "tags": ["Authentication"],
        "summary": "Get authenticated user profile and company membership",
        "responses": {
          "200": {
            "description": "User profile",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UserOut" }
              }
            }
          }
        }
      }
    },
    "/wallet/me": {
      "get": {
        "tags": ["Wallet"],
        "summary": "Get current wallet balances",
        "responses": {
          "200": {
            "description": "Wallet balance object",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WalletOut" }
              }
            }
          }
        }
      }
    },
    "/sms/send": {
      "post": {
        "tags": ["SMS"],
        "summary": "Send single or bulk SMS messages",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SendSMSIn" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMS dispatch confirmation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SendSMSOut" }
              }
            }
          }
        }
      }
    },
    "/bill-payment/categories": {
      "get": {
        "tags": ["Bill Payment"],
        "summary": "List all active utility & biller categories",
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/CategoryOut" }
                }
              }
            }
          }
        }
      }
    },
    "/bill-payment/billers": {
      "get": {
        "tags": ["Bill Payment"],
        "summary": "List billers / providers under a category",
        "parameters": [
          {
            "name": "category_slug",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of billers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/BillerOut" }
                }
              }
            }
          }
        }
      }
    },
    "/bill-payment/packages": {
      "get": {
        "tags": ["Bill Payment"],
        "summary": "List plans / packages for a provider",
        "parameters": [
          {
            "name": "biller_slug",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Available packages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PackageOut" }
                }
              }
            }
          }
        }
      }
    },
    "/bill-payment/verify-customer": {
      "post": {
        "tags": ["Bill Payment"],
        "summary": "Verify meter number or smartcard customer ID",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VerifyCustomerIn" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Customer verification result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VerifyCustomerOut" }
              }
            }
          }
        }
      }
    },
    "/bill-payment/purchase": {
      "post": {
        "tags": ["Bill Payment"],
        "summary": "Execute Airtime, Data, Electricity, or Cable purchase",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BillPurchaseIn" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction confirmation and receipt/token",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BillPaymentOut" }
              }
            }
          }
        }
      }
    }
  }
}