openapi: 3.0.0
info:
  title: 'NXT Banking API'
  version: 1.0.0
  description: 'Comprehensive Fintech API for Payouts, DMT, and UPI Collection with military-grade security and AI-powered fraud detection.'
  contact:
    name: 'NXT Banking Support'
    email: support@nxtbanking.com
    url: 'https://dev.nxtbanking.com/support'
  license:
    name: Proprietary
    url: 'https://dev.nxtbanking.com/terms'
  termsOfService: 'https://dev.nxtbanking.com/terms'
servers:
  -
    url: 'https://dev.nxtbanking.com/api/v1'
    description: 'Production Server'
  -
    url: 'https://dev.nxtbanking.com/api/sandbox'
    description: 'Sandbox Server (Test Mode)'
security:
  -
    ApiKeyAuth: {  }
tags:
  -
    name: Authentication
    description: 'API authentication and authorization'
  -
    name: Payout
    description: 'Payout and fund transfer operations'
  -
    name: DMT
    description: 'Domestic Money Transfer operations'
  -
    name: 'UPI Collection'
    description: 'UPI payment collection operations'
  -
    name: Webhooks
    description: 'Webhook management and callbacks'
  -
    name: collection
    description: 'Operations related to collection'
  -
    name: payout
    description: 'Operations related to payout'
  -
    name: verification
    description: 'Operations related to verification'
  -
    name: dmt
    description: 'Operations related to dmt'
  -
    name: 'Virtual Account'
    description: 'Operations related to Virtual Account'
paths:
  /collection/history:
    get:
      summary: 'Get Collection History'
      description: 'Retrieve paginated list of collection transactions'
      operationId: get_api_v1_collection_history
      tags:
        - collection
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: {  }
                  pagination: {  }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /virtual-account/create:
    post:
      summary: 'Create Virtual Account'
      description: 'Create a new virtual account with dedicated bank account number and optional UPI VPA for receiving payments. Each virtual account provides a unique collection point.'
      operationId: post_api_v1_virtual_account_create
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: name
          in: query
          required: true
          description: 'Display name for the virtual account'
          schema:
            type: string
          example: 'Primary Collection Account'
        -
          name: customer_identifier
          in: query
          required: true
          description: 'Your internal customer identifier (must be unique)'
          schema:
            type: string
          example: CUST_1001
        -
          name: description
          in: query
          required: false
          description: 'Optional description for this virtual account'
          schema:
            type: string
          example: 'Virtual account for order payments'
        -
          name: enable_upi
          in: query
          required: false
          description: 'If true, enables UPI VPA along with bank account (default: false)'
          schema:
            type: boolean
          example: true
        -
          name: close_by
          in: query
          required: false
          description: 'Auto-close datetime in YYYY-MM-DD HH:MM:SS format'
          schema:
            type: string
          example: '2025-12-31 23:59:59'
        -
          name: notes
          in: query
          required: false
          description: 'Additional metadata to store with the virtual account (key-value pairs)'
          schema:
            type: object
          example:
            order_id: ORD_98765
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                name: 'Primary Collection Account'
                customer_identifier: CUST_1001
                description: 'Virtual account for order payments'
                enable_upi: true
                close_by: '2025-12-31 23:59:59'
                notes:
                  order_id: ORD_98765
                  source: api
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Virtual account created successfully'
                  data: { id: 101, customer_identifier: CUST_1001, va_id: va_NxT1234567890abc, status: active, bank_account: { account_number: '1112220034567890', ifsc_code: RATN0VAAPIS, bank_name: 'NXT Virtual Account', beneficiary_name: 'Primary Collection Account' }, upi: { vpa: cust1001@nxtpay }, created_at: '2025-11-29T04:00:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /collection/generate-dynamic-qr:
    post:
      summary: 'Generate Dynamic QR Code'
      description: 'Generate a dynamic UPI QR code for payment collection. Uses military-grade HMAC-SHA256 authentication with 10-layer security validation.'
      operationId: post_api_v1_collection_generate_dynamic_qr
      tags:
        - collection
      security:
        -
          ApiKeyAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                amount: 100
                reference_id: ORD-1763429644
                customer_name: 'John Doe'
                customer_mobile: '9876543210'
                purpose: 'Product Purchase'
                expiry_minutes: 30
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Dynamic QR code generated successfully'
                  data: { collection_id: 1, order_id: ORD-1234567890, qr_code: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...', qr_string: 'upi://pay?pa=merchant.yourMid@digikhata&pn=Laraware Private Limited&mc=4900&am=100.00&cu=INR&tr=ORD-1234567890&tn=Payment', upi_intent: 'upi://pay?pa=merchant.yourMid@digikhata&pn=Laraware Private Limited&mc=4900&am=100.00&cu=INR&tr=ORD-1234567890&tn=Payment', upi_deep_link: 'upi://pay?pa=merchant.yourMid@digikhata&pn=Laraware Private Limited&mc=4900&am=100.00&cu=INR&tr=ORD-1234567890&tn=Payment', phonepe_link: 'phonepe://pay?pa=merchant.yourMid@digikhata&pn=Laraware Private Limited&mc=4900&am=100.00&cu=INR&tr=ORD-1234567890&tn=Payment', paytm_link: 'paytmmp://pay?pa=merchant.yourMid@digikhata&pn=Laraware Private Limited&mc=4900&am=100.00&cu=INR&tr=ORD-1234567890&tn=Payment', googlepay_link: 'gpay://pay?pa=merchant.yourMid@digikhata&pn=Laraware Private Limited&mc=4900&am=100.00&cu=INR&tr=ORD-1234567890&tn=Payment', gross_amount: '100.00', charge: '15.00', gst: '2.70', tds: '0.00', net_amount: '82.30', customer_name: 'John Doe', customer_mobile: '9876543210', purpose: 'Product Purchase', status: pending, expires_at: '2025-11-17 12:00:00', generated_at: '2025-11-17 11:30:00', timestamp: '2025-11-17T11:30:00+05:30', info: 'Customer will pay ₹100. After charges (₹15 + GST ₹2.70), you will receive ₹82.30 in your wallet.' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /payout/initiate:
    post:
      summary: 'Initiate Payout'
      description: 'Initiate secure money transfers to bank accounts with real-time processing, multi-scheme pricing, and comprehensive validation.'
      operationId: post_api_v1_payout_initiate
      tags:
        - payout
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: transaction_id
          in: query
          required: true
          description: 'Unique transaction ID (max 20 characters)'
          schema:
            type: string
          example: MYAPP1699523456789
        -
          name: account_holder_name
          in: query
          required: true
          description: 'Full name of the beneficiary as per bank records'
          schema:
            type: string
          example: 'John Doe'
        -
          name: account_number
          in: query
          required: true
          description: 'Bank account number of the beneficiary'
          schema:
            type: string
          example: '1234567890123456'
        -
          name: ifsc_code
          in: query
          required: true
          description: 'IFSC code of the beneficiary bank branch'
          schema:
            type: string
          example: SBIN0001234
        -
          name: amount
          in: query
          required: true
          description: 'Transfer amount in Indian Rupees (₹100 - ₹2,00,000)'
          schema:
            type: numeric
          example: 10000
        -
          name: mode
          in: query
          required: false
          description: 'Transfer mode (defaults to IMPS)'
          schema:
            type: string
          example: IMPS
        -
          name: mobile
          in: query
          required: false
          description: 'Beneficiary mobile number (10 digits)'
          schema:
            type: string
          example: '9876543210'
        -
          name: remarks
          in: query
          required: false
          description: 'Transaction remarks or purpose'
          schema:
            type: string
          example: 'Payment for services'
        -
          name: latitude
          in: query
          required: false
          description: 'GPS latitude for transaction tracking (-90 to 90)'
          schema:
            type: numeric
          example: 28.7041
        -
          name: longitude
          in: query
          required: false
          description: 'GPS longitude for transaction tracking (-180 to 180)'
          schema:
            type: numeric
          example: 77.1025
        -
          name: purpose
          in: query
          required: false
          description: 'Transaction purpose (max 200 characters)'
          schema:
            type: string
          example: 'Payment for services'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                transaction_id: MYAPP17633115096022
                account_holder_name: Anvesh
                account_number: '9448272727'
                ifsc_code: KKBK0005333
                amount: 100
                mode: IMPS
                mobile: '9876543210'
                remarks: 'Test transaction'
                latitude: 28.7041
                longitude: 77.1025
                purpose: 'Payment for services'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Payout initiated successfully'
                  data: { transaction_id: TXN1764164926, reference_id: TXN1764164926, utr_number: '24810935', status: success, amount: '100.00', charge: '7.00', gst: '1.26', tds: '0.00', total_deducted: '108.26', balance: { opening: '3612.74', closing: '3504.48' }, beneficiary: { name: 'Test User', account_number: '10205736840', ifsc_code: IDFB0022011, bank_name: 'IDFC Bank' }, tax_invoice: { invoice_number: INV/202511/00720, download_url: 'https://nxtbanking.ai/api/tax/invoice/943/download' }, timestamp: '2025-11-26T19:19:13+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/beneficiaries:
    get:
      summary: 'List Beneficiaries'
      description: 'Get list of saved beneficiaries for DMT transfers'
      operationId: get_api_v1_dmt_beneficiaries
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  data: {  }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/beneficiaries/add:
    post:
      summary: 'Add Beneficiary'
      description: 'Add a new beneficiary for DMT transfers'
      operationId: post_api_v1_dmt_beneficiaries_add
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter mobile (10 digits)'
          schema:
            type: string
          example: null
        -
          name: benename
          in: query
          required: true
          description: 'Beneficiary name'
          schema:
            type: string
          example: null
        -
          name: beneaccount
          in: query
          required: true
          description: 'Bank account number'
          schema:
            type: string
          example: null
        -
          name: beneifsc
          in: query
          required: true
          description: 'IFSC code'
          schema:
            type: string
          example: null
        -
          name: benemobile
          in: query
          required: true
          description: 'Beneficiary mobile'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                mobile: '9876543210'
                benename: 'John Doe'
                beneaccount: '1234567890'
                beneifsc: SBIN0001234
                benemobile: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'Beneficiary added'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /payout/status:
    post:
      summary: 'Check Payout Status'
      description: 'Check the current status of a payout transaction using transaction ID or reference ID.'
      operationId: post_api_v1_payout_status
      tags:
        - payout
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: transaction_id
          in: query
          required: true
          description: 'Your transaction ID from initiate response'
          schema:
            type: string
          example: TXN1732619845123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                transaction_id: TXN1732619845123
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { transaction_id: TXN1732619845123, status: success, amount: '100.00', utr_number: '24810935', created_at: '2025-11-26T19:19:12+05:30', completed_at: '2025-11-26T19:19:13+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /virtual-account/list:
    get:
      summary: 'List Virtual Accounts'
      description: 'Fetch paginated list of all virtual accounts for the authenticated user with optional status filtering.'
      operationId: get_api_v1_virtual_account_list
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: status
          in: query
          required: false
          description: 'Filter by virtual account status'
          schema:
            type: string
          example: active
        -
          name: per_page
          in: query
          required: false
          description: 'Number of results per page (default: 20)'
          schema:
            type: integer
          example: 25
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { virtual_accounts: [{ id: 101, customer_identifier: CUST_1001, name: 'Primary Collection Account', status: active, account_number: '1112220034567890', ifsc_code: RATN0VAAPIS, vpa: cust1001@nxtpay, total_received: 250000, total_credited: 243000, payment_count: 32, created_at: '2025-11-01T09:15:00+05:30' }], pagination: { total: 1, per_page: 20, current_page: 1, last_page: 1 } }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/transfer:
    post:
      summary: 'DMT Transfer'
      description: 'Transfer money via DMT (₹100-₹25,000 per transaction, ₹1,00,000 daily limit)'
      operationId: post_api_v1_dmt_transfer
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter mobile'
          schema:
            type: string
          example: null
        -
          name: beneid
          in: query
          required: false
          description: 'Beneficiary ID (if saved)'
          schema:
            type: integer
          example: null
        -
          name: beneaccount
          in: query
          required: true
          description: 'Account number'
          schema:
            type: string
          example: null
        -
          name: beneifsc
          in: query
          required: true
          description: 'IFSC code'
          schema:
            type: string
          example: null
        -
          name: amount
          in: query
          required: true
          description: 'Amount (₹100-₹25,000)'
          schema:
            type: numeric
          example: null
        -
          name: mode
          in: query
          required: false
          description: '5=IMPS, 4=NEFT, 13=RTGS'
          schema:
            type: integer
          example: null
        -
          name: mpin
          in: query
          required: true
          description: 'User MPIN'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                mobile: '9876543210'
                beneid: 123
                beneaccount: '1234567890'
                beneifsc: SBIN0001234
                amount: 5000
                mode: 5
                mpin: '1234'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'Fund Transfer Successful'
                  data: { txnStatus: 0, amount: 5000, bank_ref_no: UTR123456, balance: 45000 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /collection/generate-link:
    post:
      summary: 'Generate Payment Link'
      description: 'Generate a shareable payment link that can be sent via SMS, Email, or WhatsApp. Customer can pay using UPI or other methods. Perfect for invoices and remote payments.'
      operationId: post_api_v1_collection_generate_link
      tags:
        - collection
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: amount
          in: query
          required: true
          description: 'Payment amount in INR (₹50 minimum)'
          schema:
            type: numeric
          example: '1000.00'
        -
          name: customer_name
          in: query
          required: true
          description: 'Customer name'
          schema:
            type: string
          example: 'Jane Smith'
        -
          name: customer_mobile
          in: query
          required: true
          description: 'Customer mobile'
          schema:
            type: string
          example: '9123456789'
        -
          name: customer_email
          in: query
          required: false
          description: 'Customer email'
          schema:
            type: string
          example: jane@example.com
        -
          name: reference_id
          in: query
          required: true
          description: 'Unique invoice ID'
          schema:
            type: string
          example: INV2025001
        -
          name: description
          in: query
          required: true
          description: 'Payment description'
          schema:
            type: string
          example: 'Monthly Subscription'
        -
          name: expiry_hours
          in: query
          required: false
          description: 'Link expiry (default: 24)'
          schema:
            type: integer
          example: '24'
        -
          name: send_sms
          in: query
          required: false
          description: 'Send SMS notification'
          schema:
            type: boolean
          example: 'false'
        -
          name: send_email
          in: query
          required: false
          description: 'Send email notification'
          schema:
            type: boolean
          example: 'false'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                amount: 1000
                customer_name: 'Jane Smith'
                customer_mobile: '9123456789'
                customer_email: jane@example.com
                reference_id: INV2025001
                description: 'Monthly Subscription Payment'
                expiry_hours: 24
                send_sms: false
                send_email: false
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Payment link generated successfully'
                  data: { collection_id: INV2025001, reference_id: LINK1731397800_67890, payment_link: 'https://pay.nxtbanking.com/payment/upi/LINK1731397800_67890', short_link: 'https://nxt.io/p/AbCd123', payment_details: { amount: 1000, customer_name: 'Jane Smith', customer_mobile: '9123456789', customer_email: jane@example.com, description: 'Monthly Subscription Payment' }, provider: PayPoint, status: pending, expires_at: '2025-11-13T10:30:00+00:00', notifications_sent: { sms: false, email: false } }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  '/virtual-account/{id}':
    get:
      summary: 'Get Virtual Account Details'
      description: 'Get detailed information about a specific virtual account including real-time balance, financial summary, and recent payments.'
      operationId: get_api_v1_virtual_account_id
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: id
          in: path
          required: true
          description: Id
          schema:
            type: string
        -
          name: id
          in: query
          required: true
          description: 'Internal virtual account ID'
          schema:
            type: integer
          example: 101
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { id: 101, customer_identifier: CUST_1001, name: 'Primary Collection Account', status: active, realtime_balance: 12500.5, bank_account: { account_number: '1112220034567890', ifsc_code: RATN0VAAPIS, bank_name: 'NXT Virtual Account', beneficiary_name: 'Primary Collection Account' }, upi: { vpa: cust1001@nxtpay }, financial: { total_received: 250000, total_charges: 5000, total_gst: 900, total_credited: 243000, payment_count: 32 }, recent_payments: [{ id: 501, amount: 5000, net_amount: 4850, status: captured, method: bank_transfer, utr_number: HDFC12345ABC, created_at: '2025-11-29T03:15:00+05:30' }], created_at: '2025-11-01T09:15:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /collection/status:
    post:
      summary: 'Check Payment Status'
      description: 'Check the real-time status of a payment collection using collection ID. Returns current status, amount, and transaction details.'
      operationId: post_api_v1_collection_status
      tags:
        - collection
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: collection_id
          in: query
          required: true
          description: 'Your reference ID'
          schema:
            type: string
          example: ORD123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                collection_id: ORD123456
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Payment status retrieved successfully'
                  data: { collection_id: ORD123456, reference_id: DQR1731397800_12345, status: success, amount: 500, payment_details: { customer_name: 'John Doe', customer_mobile: '9876543210', payment_mode: UPI, utr_number: UTR1234567890123 }, transaction_info: { paid_at: '2025-11-12T10:35:00+00:00', upi_id: customer@paytm, bank_reference: BNK987654321 }, provider: PayPoint }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  '/virtual-account/{id}/close':
    post:
      summary: 'Close Virtual Account'
      description: 'Close an active virtual account. Once closed, no further payments can be received and the account cannot be reopened.'
      operationId: post_api_v1_virtual_account_id_close
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: id
          in: path
          required: true
          description: Id
          schema:
            type: string
        -
          name: id
          in: query
          required: true
          description: 'Internal virtual account ID to close'
          schema:
            type: integer
          example: 101
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Virtual account closed successfully'
                  data: { id: 101, status: closed, closed_at: '2025-11-30T18:30:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /payout/balance:
    get:
      summary: 'Get Wallet Balance'
      description: 'Get current wallet balance. This is a GET request - no request body needed, only authentication headers.'
      operationId: get_api_v1_payout_balance
      tags:
        - payout
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { available_balance: '3504.48', locked_balance: '0.00', currency: INR }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  '/virtual-account/{id}/payments':
    get:
      summary: 'Get Virtual Account Payments'
      description: 'Fetch all payments received in a specific virtual account with complete transaction details.'
      operationId: get_api_v1_virtual_account_id_payments
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: id
          in: path
          required: true
          description: Id
          schema:
            type: string
        -
          name: id
          in: query
          required: true
          description: 'Internal virtual account ID'
          schema:
            type: integer
          example: 101
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { virtual_account_id: 101, payments: [{ id: pay_NxT1234567890abc, amount: 5000, currency: INR, status: captured, method: bank_transfer, utr: HDFC12345ABC, payer_name: 'John Doe', payer_account: XXXX1234, created_at: '2025-11-29T03:15:00+05:30' }], count: 1 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /virtual-account/balance:
    get:
      summary: 'Get Virtual Account Balance'
      description: 'Get consolidated real-time balance across all active virtual accounts.'
      operationId: get_api_v1_virtual_account_balance
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { total_balance: 12500.5, currency: INR, accounts: [{ id: 101, customer_identifier: CUST_1001, name: 'Primary Collection Account', balance: 7500.25, amount_paid: 7500.25 }, { id: 102, customer_identifier: CUST_1002, name: 'Secondary Account', balance: 5000.25, amount_paid: 5000.25 }], fetched_at: '2025-11-29T04:05:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /virtual-account/stats:
    get:
      summary: 'Get Virtual Account Stats'
      description: 'Get high-level statistics for all virtual account collections including total received, credited amounts, and charges.'
      operationId: get_api_v1_virtual_account_stats
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { total_virtual_accounts: 2, active_virtual_accounts: 2, total_payments: 32, successful_payments: 32, total_received: 250000, total_credited: 243000, total_charges_paid: 5000 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /virtual-account/payment/status:
    post:
      summary: 'Check Payment Status'
      description: 'Check the status of a specific payment received in virtual account by payment_id or UTR number.'
      operationId: post_api_v1_virtual_account_payment_status
      tags:
        - 'Virtual Account'
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: payment_id
          in: query
          required: false
          description: 'Payment ID returned during credit (required if utr not provided)'
          schema:
            type: string
          example: pay_NxT1234567890
        -
          name: utr
          in: query
          required: false
          description: 'Bank UTR/Reference number (required if payment_id not provided)'
          schema:
            type: string
          example: HDFC12345ABC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                payment_id: pay_NxT1234567890
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { payment_id: pay_NxT1234567890, internal_id: 501, virtual_account_id: 101, customer_identifier: CUST_1001, amount: 5000, charge: 25, gst: 4.5, tds: 0, net_amount: 4970.5, status: captured, utr: HDFC12345ABC, method: bank_transfer, payer: { name: 'John Doe', account_number: '1234567890', ifsc: HDFC0001234, bank_name: 'HDFC Bank', vpa: null }, opening_balance: 10000, closing_balance: 14970.5, created_at: '2025-11-29T03:10:00+05:30', captured_at: '2025-11-29T03:15:00+05:30', processed_at: '2025-11-29T03:15:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
  /verification/account:
    post:
      summary: 'Account Verification'
      description: 'Verify bank account details and account holder name. Returns verified account holder name and charge applied.'
      operationId: post_api_v1_verification_account
      tags:
        - verification
      security:
        -
          ApiKeyAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                account_number: '123456789012'
                ifsc_code: SBIN0001234
                account_name: 'John Doe'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Account verified successfully'
                  data: { verification_status: verified, account_number: '123456789012', ifsc_code: SBIN0001234, account_name: 'JOHN DOE', charged: 4.72, verification: { registered_name: 'JOHN DOE', utr: RZPXUTR123456, validation_id: val_ABC123456, fund_account_id: fa_1234567890 }, statuscode: TXN }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        429:
          $ref: '#/components/responses/TooManyRequests'
        500:
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API Key for authentication. Get yours from the dashboard.'
    HmacAuth:
      type: apiKey
      in: header
      name: X-HMAC-Signature
      description: 'HMAC-SHA256 signature for request integrity verification.'
  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: 'Operation completed successfully'
        data:
          type: object
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: ERROR_CODE
        message:
          type: string
          example: 'Error description'
    PayoutRequest:
      type: object
      required:
        - amount
        - account_number
        - ifsc_code
        - beneficiary_name
        - mode
      properties:
        amount:
          type: number
          format: double
          minimum: 10
          maximum: 200000
          example: 1000.0
          description: 'Amount to transfer (₹10 - ₹2,00,000)'
        account_number:
          type: string
          pattern: '^[0-9]{9,18}$'
          example: '1234567890'
          description: 'Beneficiary bank account number'
        ifsc_code:
          type: string
          pattern: '^[A-Z]{4}0[A-Z0-9]{6}$'
          example: SBIN0001234
          description: 'Bank IFSC code'
        beneficiary_name:
          type: string
          example: 'John Doe'
          description: 'Beneficiary name'
        mode:
          type: string
          enum:
            - IMPS
            - NEFT
            - RTGS
          example: IMPS
          description: 'Transfer mode'
        client_ref_id:
          type: string
          example: ORDER_XYZ_123
          description: 'Your unique reference ID'
  responses:
    BadRequest:
      description: 'Bad Request - Invalid input data'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: INVALID_INPUT
            message: 'The provided input data is invalid.'
    Unauthorized:
      description: 'Unauthorized - Authentication required'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: UNAUTHORIZED
            message: 'Invalid or missing API key.'
    Forbidden:
      description: 'Forbidden - Access denied'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: FORBIDDEN
            message: 'You do not have permission to access this resource.'
    TooManyRequests:
      description: 'Too Many Requests - Rate limit exceeded'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: RATE_LIMIT_EXCEEDED
            message: 'You have exceeded the rate limit. Please try again later.'
    ServerError:
      description: 'Internal Server Error'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: SERVER_ERROR
            message: 'An internal server error occurred. Please contact support.'
