{
  "openapi": "3.1.0",
  "info": {
    "title": "NDAPI — Nolubz Dedicated API Payment Infrastructure",
    "description": "NDAPI enables businesses to collect NGN payments via virtual accounts, initiate bank transfers, verify account details, and track transactions in real time. Built on Nolubz's licensed payment rails.",
    "version": "1.0.0",
    "contact": {
      "name": "NDAPI Support",
      "email": "ndapi.admin@nolubz.com",
      "url": "https://ndapi.nolubz.com"
    },
    "termsOfService": "https://nolubz.com/terms",
    "x-logo": {
      "url": "https://ndapi.nolubz.com/NIcon.png"
    }
  },
  "servers": [
    {
      "url": "https://ndapi.nolubz.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your NDAPI key. Use NDAPI-TEST- prefix for test mode, NDAPI-LIVE- for production."
      }
    },
    "schemas": {
      "VirtualAccount": {
        "type": "object",
        "properties": {
          "account_number": { "type": "string", "example": "9646780657" },
          "account_name": { "type": "string", "example": "NOLUBZ/John Doe" },
          "bank": { "type": "string", "example": "Nolubz Infrastructure Tech" },
          "reference": { "type": "string", "example": "ORDER-2026-001" },
          "status": { "type": "string", "enum": ["active", "used", "expired"] },
          "expires_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "operator_name": { "type": "string" },
          "balance": {
            "type": "object",
            "properties": {
              "available_ngn": { "type": "number" },
              "total_deposits_ngn": { "type": "number" },
              "total_withdrawals_ngn": { "type": "number" }
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "total_deposits": { "type": "integer" },
              "total_withdrawals": { "type": "integer" }
            }
          }
        }
      },
      "Transfer": {
        "type": "object",
        "properties": {
          "reference": { "type": "string" },
          "amount_ngn": { "type": "number" },
          "fee_ngn": { "type": "number" },
          "net_amount_ngn": { "type": "number" },
          "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] },
          "transaction_id": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/virtual-accounts": {
      "post": {
        "summary": "Create a Virtual Account",
        "description": "Create a unique virtual bank account for receiving NGN payments. Can be permanent or dynamic (with expiry).",
        "operationId": "createVirtualAccount",
        "tags": ["Virtual Accounts"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["account_name"],
                "properties": {
                  "account_name": { "type": "string", "description": "Name to display on the virtual account", "example": "John Doe" },
                  "merchant_tx_ref": { "type": "string", "description": "Your internal order/transaction ID", "example": "ORDER-2026-001" },
                  "expected_amount_ngn": { "type": "number", "description": "Expected deposit amount. Leave blank to accept any amount.", "example": 50000 },
                  "expires_at": { "type": "string", "format": "date-time", "description": "Expiry date/time. Leave blank for permanent account.", "example": "2026-12-31T23:59:59Z" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Virtual account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "$ref": "#/components/schemas/VirtualAccount" }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/virtual-accounts/verify": {
      "post": {
        "summary": "Verify Bank Account",
        "description": "Confirm a bank account name before initiating a transfer. Always verify before sending funds.",
        "operationId": "verifyBankAccount",
        "tags": ["Virtual Accounts"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["account_number", "bank_code"],
                "properties": {
                  "account_number": { "type": "string", "example": "0123456789" },
                  "bank_code": { "type": "string", "example": "058" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account verified",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "account_name": { "type": "string", "example": "JANE SMITH" },
                    "account_number": { "type": "string" },
                    "bank_code": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/balance": {
      "get": {
        "summary": "Get Operator Balance",
        "description": "Check your operator balance, total deposits, withdrawals, and transaction statistics.",
        "operationId": "getBalance",
        "tags": ["Balance"],
        "responses": {
          "200": {
            "description": "Balance data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "$ref": "#/components/schemas/Balance" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/transfers": {
      "post": {
        "summary": "Initiate a Bank Transfer",
        "description": "Send NGN to any Nigerian bank account. Always verify the account name before initiating. Uses idempotency via the reference field.",
        "operationId": "createTransfer",
        "tags": ["Transfers"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount_ngn", "bank_code", "account_number", "account_name", "reference"],
                "properties": {
                  "amount_ngn": { "type": "number", "description": "Amount to transfer in NGN", "example": 50000 },
                  "bank_code": { "type": "string", "description": "CBN bank code", "example": "058" },
                  "account_number": { "type": "string", "description": "10-digit recipient account number", "example": "0123456789" },
                  "account_name": { "type": "string", "description": "Recipient account name", "example": "Jane Smith" },
                  "reference": { "type": "string", "description": "Your unique reference for idempotency", "example": "PAYOUT-2026-001" },
                  "narration": { "type": "string", "description": "Transfer description", "example": "Payment for order #1234" },
                  "bank_name": { "type": "string", "description": "Recipient bank name for your records", "example": "Guaranty Trust Bank" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer initiated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "mode": { "type": "string", "enum": ["test", "live"] },
                    "data": { "$ref": "#/components/schemas/Transfer" }
                  }
                }
              }
            }
          },
          "400": { "description": "Insufficient balance or missing parameters" },
          "401": { "description": "Invalid API key" },
          "409": { "description": "Duplicate reference" }
        }
      }
    },
    "/transactions": {
      "get": {
        "summary": "List Transactions",
        "description": "Retrieve your transaction history with filtering and pagination.",
        "operationId": "getTransactions",
        "tags": ["Transactions"],
        "parameters": [
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["day", "week", "month", "all"], "default": "day" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["deposit", "withdrawal", "all"], "default": "all" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Transaction list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transfer" } },
                    "total": { "type": "integer" },
                    "page": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Virtual Accounts", "description": "Create and manage virtual bank accounts for receiving payments" },
    { "name": "Balance", "description": "Check operator balance and statistics" },
    { "name": "Transfers", "description": "Initiate NGN bank transfers" },
    { "name": "Transactions", "description": "View transaction history" }
  ]
}