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: no-reply@laraware.org
    url: 'https://nxtbanking.ai/support'
  license:
    name: Proprietary
    url: 'https://nxtbanking.ai/terms'
  termsOfService: 'https://nxtbanking.ai/terms'
servers:
  -
    url: 'https://nxtbanking.ai/api/v1'
    description: 'Production Server'
  -
    url: 'https://nxtbanking.ai/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'
  -
    name: bbps
    description: 'Operations related to bbps'
  -
    name: aeps
    description: 'Operations related to aeps'
  -
    name: recharge
    description: 'Operations related to recharge'
  -
    name: reports
    description: 'Operations related to reports'
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: {  }
      parameters:
        -
          name: page
          in: query
          required: false
          description: 'Page number'
          schema:
            type: integer
          example: 1
        -
          name: per_page
          in: query
          required: false
          description: 'Records per page (max 100)'
          schema:
            type: integer
          example: 25
        -
          name: status
          in: query
          required: false
          description: 'Filter by status: pending, success, failed, expired'
          schema:
            type: string
          example: success
        -
          name: collection_type
          in: query
          required: false
          description: 'Filter by type: dynamic_qr, payment_link, collect_request'
          schema:
            type: string
          example: dynamic_qr
        -
          name: date_from
          in: query
          required: false
          description: 'Start date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-03-01'
        -
          name: date_to
          in: query
          required: false
          description: 'End date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-03-16'
        -
          name: search
          in: query
          required: false
          description: 'Search by order_id, transaction_id, or purpose'
          schema:
            type: string
          example: null
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ id: 1, order_id: ECO1710600000456, reference_id: ORD-1763429644, amount: '500.00', status: success, collection_type: dynamic_qr, gateway: easebuzz_pg, created_at: '2026-03-16T15:00:00+05:30' }]
                  pagination: { total: 25, per_page: 25, 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/banks:
    get:
      summary: 'List Supported Banks'
      description: 'Get the complete list of supported banks for DMT (Domestic Money Transfer). Use this to populate bank selection dropdowns in your application.'
      operationId: get_api_v1_dmt_banks
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ id: 1, name: 'State Bank of India', code: SBIN, ifsc_prefix: SBIN0 }, { id: 2, name: 'HDFC Bank', code: HDFC, ifsc_prefix: HDFC0 }, { id: 3, name: 'ICICI Bank', code: ICIC, ifsc_prefix: ICIC0 }, { id: 4, name: 'Axis Bank', code: UTIB, ifsc_prefix: UTIB0 }, { id: 5, name: 'Punjab National Bank', code: PUNB, ifsc_prefix: PUNB0 }]
        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. Customer scans the QR → opens payment checkout → pays via UPI/Cards/NetBanking. Uses HMAC-SHA256 authentication.'
      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: ECO1710600000456, reference_id: ORD-1763429644, qr_code: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...(base64 SVG)...', qr_string: 'https://pay.easebuzz.in/pay/{access_key}', upi_intent: 'https://pay.easebuzz.in/pay/{access_key}', upi_deep_link: 'https://pay.easebuzz.in/pay/{access_key}', phonepe_link: null, paytm_link: null, googlepay_link: null, gross_amount: '100.00', credit_amount: '100.00', settlement_charge: '2.00', settlement_gst: '0.36', tds: '0.00', customer_name: 'John Doe', customer_mobile: '9876543210', purpose: 'Product Purchase', status: pending, expires_at: '2026-03-16 21:30:00', generated_at: '2026-03-16 21:00:00', timestamp: '2026-03-16T21:00:00+05:30', info: 'Customer will pay ₹100. Full amount will be credited to your wallet. Settlement charge (₹2 + GST ₹0.36) will be deducted when you settle.' }
        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'
  /reports/available:
    get:
      summary: 'Get Available Reports'
      description: 'Get all custom reports available to the authenticated user based on their role permissions. Results are cached for 30 minutes.'
      operationId: get_api_v1_reports_available
      tags:
        - reports
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  reports: [{ id: report_65f3a1_1698765432, name: 'Daily Payout Summary', description: 'Payout transactions grouped by date', service_type: payout, report_type: table }, { id: report_75a4b2_1698765500, name: 'Recharge Report', description: 'All recharge transactions', service_type: recharge, report_type: table }]
        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'
  /recharge/operators:
    get:
      summary: 'Get Operators'
      description: 'Get the list of available mobile and DTH operators for recharge. Use this to populate operator selection in your application.'
      operationId: get_api_v1_recharge_operators
      tags:
        - recharge
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ name: Airtel, biller_id: BILAVAIRTEL001 }, { name: Jio, biller_id: BILAVJIO000001 }, { name: 'Vi (Vodafone Idea)', biller_id: BILAVVODA00001 }, { name: BSNL, biller_id: BILAVBSNL00001 }]
        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'
  /bbps/categories:
    get:
      summary: 'List Bill Categories'
      description: 'Get all available BBPS bill payment categories such as Electricity, Water, Gas, Broadband, DTH, Insurance, Loan EMI, and more.'
      operationId: get_api_v1_bbps_categories
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ id: 1, name: Electricity, code: ELECTRICITY, icon: bolt }, { id: 2, name: Water, code: WATER, icon: droplet }, { id: 3, name: Gas, code: GAS, icon: flame }, { id: 4, name: Broadband, code: BROADBAND, icon: wifi }, { id: 5, name: DTH, code: DTH, icon: tv }, { id: 6, name: 'Mobile Postpaid', code: POSTPAID, icon: phone }, { id: 7, name: Landline, code: LANDLINE, icon: phone }, { id: 8, name: Insurance, code: INSURANCE, icon: shield }, { id: 9, name: 'Loan EMI', code: EMI, icon: credit-card }, { id: 10, name: FASTag, code: FASTAG, icon: car }]
        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'
  /aeps/onboard:
    post:
      summary: 'Merchant Onboarding'
      description: 'Register a new AEPS merchant agent. Complete KYC onboarding with PAN, Aadhaar, and bank account details. Required before processing any AEPS transactions.'
      operationId: post_api_v1_aeps_onboard
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: name
          in: query
          required: true
          description: 'Full name of merchant'
          schema:
            type: string
          example: 'Rajesh Kumar Singh'
        -
          name: merchantPhoneNumber
          in: query
          required: true
          description: '10-digit mobile number'
          schema:
            type: string
          example: '9876543210'
        -
          name: address1
          in: query
          required: true
          description: 'Primary address line'
          schema:
            type: string
          example: 'Shop No 5, Main Market'
        -
          name: address2
          in: query
          required: false
          description: 'Secondary address line'
          schema:
            type: string
          example: 'Near Bus Stand'
        -
          name: state
          in: query
          required: true
          description: 'State name'
          schema:
            type: string
          example: Rajasthan
        -
          name: city
          in: query
          required: true
          description: 'City name'
          schema:
            type: string
          example: Jaipur
        -
          name: district
          in: query
          required: true
          description: 'District name'
          schema:
            type: string
          example: Jaipur
        -
          name: pincode
          in: query
          required: true
          description: '6-digit PIN code'
          schema:
            type: string
          example: '302001'
        -
          name: userPan
          in: query
          required: true
          description: 'PAN card number (format: XXXXX9999X)'
          schema:
            type: string
          example: ABCDE1234F
        -
          name: aadhaarNumber
          in: query
          required: false
          description: '12-digit Aadhaar number'
          schema:
            type: string
          example: '123456789012'
        -
          name: bankAccountNumber
          in: query
          required: true
          description: 'Settlement bank account number'
          schema:
            type: string
          example: '12345678901234'
        -
          name: bankIfscCode
          in: query
          required: true
          description: 'Bank IFSC code (11 characters)'
          schema:
            type: string
          example: SBIN0001234
        -
          name: bankName
          in: query
          required: false
          description: 'Bank name'
          schema:
            type: string
          example: 'State Bank of India'
        -
          name: latitude
          in: query
          required: false
          description: 'GPS latitude (-90 to 90)'
          schema:
            type: numeric
          example: 26.9124
        -
          name: longitude
          in: query
          required: false
          description: 'GPS longitude (-180 to 180)'
          schema:
            type: numeric
          example: 75.7873
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                name: 'Rajesh Kumar Singh'
                merchantPhoneNumber: '9876543210'
                address1: 'Shop No 5, Main Market'
                address2: 'Near Bus Stand'
                state: Rajasthan
                city: Jaipur
                district: Jaipur
                pincode: '302001'
                userPan: ABCDE1234F
                aadhaarNumber: '123456789012'
                bankAccountNumber: '12345678901234'
                bankIfscCode: SBIN0001234
                bankName: 'State Bank of India'
                latitude: 26.9124
                longitude: 75.7873
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Merchant onboarded successfully'
                  data: { merchantLoginId: FING123456789, merchantLoginPin: PINFING123456, merchantId: FP-MER-00001 }
        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'
  /aeps/ekyc/send-otp:
    post:
      summary: 'eKYC Send OTP'
      description: "Send OTP for eKYC verification to the merchant's registered mobile number. First step in the OTP-based eKYC flow."
      operationId: post_api_v1_aeps_ekyc_send_otp
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID from onboarding'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
        -
          name: mobileNumber
          in: query
          required: true
          description: '10-digit mobile number for OTP'
          schema:
            type: string
          example: '9876543210'
        -
          name: aadhaarNumber
          in: query
          required: false
          description: '12-digit Aadhaar number'
          schema:
            type: string
          example: '123456789012'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                mobileNumber: '9876543210'
                aadhaarNumber: '123456789012'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'OTP sent successfully'
                  data: { status: true, message: 'OTP sent to registered mobile number' }
        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'
  /recharge/circles:
    get:
      summary: 'Get Circles'
      description: 'Get the list of available telecom circles (regions) for recharge. Use along with operators to fetch plans.'
      operationId: get_api_v1_recharge_circles
      tags:
        - recharge
      security:
        -
          ApiKeyAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ name: 'Delhi NCR', value: 'Delhi NCR' }, { name: Maharashtra, value: Maharashtra }, { name: Karnataka, value: Karnataka }, { name: 'Tamil Nadu', value: 'Tamil Nadu' }, { name: 'UP East', value: 'UP East' }, { name: Rajasthan, value: Rajasthan }]
        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'
  '/reports/custom/{reportId}':
    get:
      summary: 'Get Report Details'
      description: 'Get the configuration and metadata for a specific custom report including field definitions, permissions, and report type.'
      operationId: get_api_v1_reports_custom_reportId
      tags:
        - reports
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: reportId
          in: path
          required: true
          description: ReportId
          schema:
            type: string
        -
          name: reportId
          in: query
          required: true
          description: 'Report ID (path parameter)'
          schema:
            type: string
          example: report_65f3a1_1698765432
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  report: { id: report_65f3a1_1698765432, name: 'Daily Payout Summary', description: 'All payout transactions with user and financial details', service_type: payout, report_type: table, fields: [{ id: txnid, name: 'Transaction ID', type: text }, { id: amount, name: Amount, type: currency }, { id: status, name: Status, type: badge }, { id: created_at, name: Date/Time, type: datetime }] }
        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'
  /bbps/billers:
    get:
      summary: 'List Billers'
      description: 'Get a paginated list of all available BBPS billers. Filter by category, search term, or region. Returns biller details including customer parameters and payment modes.'
      operationId: get_api_v1_bbps_billers
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: category
          in: query
          required: false
          description: 'Filter by category name (e.g., Electricity, Water)'
          schema:
            type: string
          example: Electricity
        -
          name: search
          in: query
          required: false
          description: 'Search by biller name or ID'
          schema:
            type: string
          example: Maharashtra
        -
          name: region
          in: query
          required: false
          description: 'Filter by coverage region'
          schema:
            type: string
          example: Maharashtra
        -
          name: per_page
          in: query
          required: false
          description: 'Results per page (default: 50)'
          schema:
            type: number
          example: 50
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ id: 1, biller_id: MAHA00000NAT01, biller_name: 'Maharashtra Electricity', category_name: Electricity, status: ACTIVE, customer_params: [{ paramName: 'Consumer Number', dataType: ALPHANUMERIC, isOptional: 'false' }], payment_modes: [Cash, UPI] }]
                  pagination: { current_page: 1, last_page: 5, total: 230 }
        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'
  '/bbps/biller/{billerId}':
    get:
      summary: 'Biller Details'
      description: 'Get detailed information about a specific BBPS biller including customer parameter configuration, supported payment modes, and fetch requirements.'
      operationId: get_api_v1_bbps_biller_billerId
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: billerId
          in: path
          required: true
          description: BillerId
          schema:
            type: string
        -
          name: billerId
          in: query
          required: true
          description: 'Biller ID (path parameter)'
          schema:
            type: string
          example: MAHA00000NAT01
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { biller_id: MAHA00000NAT01, biller_name: 'Maharashtra Electricity', category: Electricity, fetch_required: true, fetch_supported: true, customer_params: [{ paramName: 'Consumer Number', dataType: ALPHANUMERIC, isOptional: 'false', minLength: 5, maxLength: 20 }], payment_modes: [Cash, UPI, 'Internet Banking'] }
        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'
  /aeps/ekyc/validate-otp:
    post:
      summary: 'eKYC Validate OTP'
      description: 'Validate the OTP received for eKYC verification. On success, merchant KYC status is updated to verified.'
      operationId: post_api_v1_aeps_ekyc_validate_otp
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
        -
          name: mobileNumber
          in: query
          required: true
          description: 'Mobile number OTP was sent to'
          schema:
            type: string
          example: '9876543210'
        -
          name: otp
          in: query
          required: true
          description: '6-digit OTP received via SMS'
          schema:
            type: string
          example: '123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                mobileNumber: '9876543210'
                otp: '123456'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'OTP validated successfully'
                  data: { status: true, message: 'eKYC completed' }
        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: 2, order_id: ECO1710600000789, payment_link: 'https://nxtbanking.ai/payment/upi/abc123xyz...', short_link: 'https://nxtbanking.ai/p/abc123', amount: '1000.00', customer_name: 'Jane Smith', customer_mobile: '9123456789', customer_email: jane@example.com, description: 'Monthly Subscription', status: pending, expires_at: '17 Mar 2026, 09:00 PM', generated_at: '16 Mar 2026, 09:00 PM', notifications_sent: { whatsapp: false, 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'
  /recharge/plans:
    post:
      summary: 'Get Recharge Plans'
      description: 'Fetch available recharge plans for a specific operator and circle. Returns cached plans when available for faster response.'
      operationId: post_api_v1_recharge_plans
      tags:
        - recharge
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: operator
          in: query
          required: true
          description: 'Operator name'
          schema:
            type: string
          example: Airtel
        -
          name: circle
          in: query
          required: true
          description: 'Telecom circle'
          schema:
            type: string
          example: 'Delhi NCR'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                operator: Airtel
                circle: 'Delhi NCR'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ plan_id: PLN001, plan_name: 'Unlimited Pack', amount: 299, talktime: Unlimited, validity: '28 days', description: 'Unlimited calls + 1.5GB/day data', category_type: Unlimited }, { plan_id: PLN002, plan_name: 'Data Pack', amount: 199, talktime: '0', validity: '24 days', description: '1GB/day data', category_type: 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'
  '/reports/custom/{reportId}/data':
    post:
      summary: 'Get Report Data'
      description: 'Fetch the actual data for a custom report with optional date range, status, and amount filters. Returns formatted data with summary statistics and performance metrics.'
      operationId: post_api_v1_reports_custom_reportId_data
      tags:
        - reports
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: reportId
          in: path
          required: true
          description: ReportId
          schema:
            type: string
        -
          name: reportId
          in: query
          required: true
          description: 'Report ID (path parameter)'
          schema:
            type: string
          example: report_65f3a1_1698765432
        -
          name: from_date
          in: query
          required: false
          description: 'Start date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-02-01'
        -
          name: to_date
          in: query
          required: false
          description: 'End date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-02-27'
        -
          name: status
          in: query
          required: false
          description: 'Filter by status (success, pending, failed)'
          schema:
            type: string
          example: success
        -
          name: amount_min
          in: query
          required: false
          description: 'Minimum amount filter'
          schema:
            type: numeric
          example: 100
        -
          name: amount_max
          in: query
          required: false
          description: 'Maximum amount filter'
          schema:
            type: numeric
          example: 50000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                from_date: '2026-02-01'
                to_date: '2026-02-27'
                status: success
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ txnid: TXN20260227001, amount: '5,000.00', status: success, created_at: '27-02-2026 10:30:00' }]
                  summary: { total_records: 150, total_amount: 750000, success_rate: 94.4 }
                  performance: { execution_time_ms: 120, records_count: 150 }
        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'
  /payout/verify-account:
    post:
      summary: 'Verify Bank Account'
      description: 'Verify bank account details before initiating payout to ensure account validity.'
      operationId: post_api_v1_payout_verify_account
      tags:
        - payout
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: account_number
          in: query
          required: true
          description: 'Bank account number to verify'
          schema:
            type: string
          example: '1234567890123456'
        -
          name: ifsc_code
          in: query
          required: true
          description: 'IFSC code of the bank branch'
          schema:
            type: string
          example: SBIN0001234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                account_number: '1234567890123456'
                ifsc_code: SBIN0001234
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Account verification successful'
                  data: { account_number: '1234567890123456', ifsc_code: SBIN0001234, bank_name: 'State Bank of India', branch_name: 'New Delhi Main Branch', account_holder_name: 'Test Beneficiary', account_type: Savings, verification_status: verified, verification_id: VER123456789, timestamp: '2025-11-11T09:37:09+00:00' }
        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: ECO1710600000456, reference_id: ORD-1763429644, status: success, amount: 500, payment_details: { customer_name: 'John Doe', customer_mobile: '9876543210', payment_mode: UPI, utr_number: UTR1234567890123 }, transaction_info: { paid_at: '2026-03-16T15:30:00+05:30', upi_id: customer@upi, bank_reference: UTR1234567890123 }, provider: easebuzz_pg, net_amount: 498, charge: 1.77, gst: 0.32, created_at: '2026-03-16T15:00:00+05:30', updated_at: '2026-03-16T15:30:00+05:30', tax_invoice: null }
                  execution_time_ms: 12.5
        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'
  /aeps/ekyc/resend-otp:
    post:
      summary: 'eKYC Resend OTP'
      description: 'Resend OTP for eKYC verification if the previous OTP expired or was not received.'
      operationId: post_api_v1_aeps_ekyc_resend_otp
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
        -
          name: mobileNumber
          in: query
          required: true
          description: 'Mobile number to resend OTP'
          schema:
            type: string
          example: '9876543210'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                mobileNumber: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'OTP resent successfully'
                  data: { status: true, message: 'OTP resent to registered mobile number' }
        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'
  /bbps/fetch:
    post:
      summary: 'Fetch Bill'
      description: 'Fetch an outstanding bill from a BBPS biller. Customer parameters are validated dynamically based on biller configuration. Returns bill amount, due date, and bill details.'
      operationId: post_api_v1_bbps_fetch
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: biller_id
          in: query
          required: true
          description: 'BBPS Biller ID'
          schema:
            type: string
          example: MAHA00000NAT01
        -
          name: customer_params
          in: query
          required: true
          description: 'Key-value pairs as per biller configuration'
          schema:
            type: object
          example: null
        -
          name: customer_mobile
          in: query
          required: false
          description: 'Customer 10-digit mobile number'
          schema:
            type: string
          example: '9876543210'
        -
          name: channel
          in: query
          required: false
          description: 'Channel: INT (Internet), MOB (Mobile), AGT (Agent). Default: INT'
          schema:
            type: string
          example: INT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                biller_id: MAHA00000NAT01
                customer_params:
                  'Consumer Number': '123456789'
                customer_mobile: '9876543210'
                channel: INT
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Bill fetched successfully'
                  data: { ref_id: ABCDEFGHIJKLMNOPQRSTUVWXYZ06058-1430, transaction_id: 42, biller_name: 'Maharashtra Electricity', customer_name: 'John Doe', bill_amount: 1250, bill_date: '2026-01-15', due_date: '2026-02-28', bill_number: BILL-2026-001, bill_period: 'Jan 2026' }
        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'
  '/statements/{serviceType}':
    get:
      summary: 'Get Service Statements'
      description: 'Fetch paginated transaction statements for any service type. Supports search, date range, amount filters, and sorting. Role-based data access is enforced automatically. Service types: payout, recharge, aeps, dmt, bbps, upi_collection, fund, wallet.'
      operationId: get_api_v1_statements_serviceType
      tags:
        - reports
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: serviceType
          in: path
          required: true
          description: ServiceType
          schema:
            type: string
        -
          name: serviceType
          in: query
          required: true
          description: 'Service type (path): payout, recharge, aeps, dmt, bbps, upi_collection, fund, wallet'
          schema:
            type: string
          example: payout
        -
          name: from_date
          in: query
          required: false
          description: 'Start date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-02-01'
        -
          name: to_date
          in: query
          required: false
          description: 'End date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-02-27'
        -
          name: status
          in: query
          required: false
          description: 'Transaction status filter'
          schema:
            type: string
          example: success
        -
          name: search
          in: query
          required: false
          description: 'Search by transaction ID, reference number, etc.'
          schema:
            type: string
          example: null
        -
          name: length
          in: query
          required: false
          description: 'Records per page (default: 50)'
          schema:
            type: number
          example: 50
        -
          name: page
          in: query
          required: false
          description: 'Page number (default: 1)'
          schema:
            type: number
          example: 1
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ txnid: PAY20260227001, amount: '10,000.00', status: success, created_at: '27-02-2026 14:30:00', account_number: '1234****5678' }]
                  recordsTotal: 500
                  recordsFiltered: 500
                  config: { headers: [{ key: txnid, name: 'Transaction ID', type: text }, { key: amount, name: Amount, type: currency }, { key: status, name: Status, type: badge }], service_name: Payout }
        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'
  /recharge/process:
    post:
      summary: 'Process Recharge'
      description: 'Process a mobile or DTH recharge. Validates wallet balance, deducts amount with charges and GST, and processes through the recharge provider. Auto-refunds on failure.'
      operationId: post_api_v1_recharge_process
      tags:
        - recharge
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: mobile_number
          in: query
          required: true
          description: '10-digit mobile number starting with 6-9'
          schema:
            type: string
          example: '9876543210'
        -
          name: operator
          in: query
          required: true
          description: 'Operator name'
          schema:
            type: string
          example: Airtel
        -
          name: circle
          in: query
          required: true
          description: 'Telecom circle'
          schema:
            type: string
          example: 'Delhi NCR'
        -
          name: amount
          in: query
          required: true
          description: 'Recharge amount in INR (10-10000)'
          schema:
            type: numeric
          example: 299
        -
          name: biller_id
          in: query
          required: true
          description: 'Biller ID from operators list'
          schema:
            type: string
          example: BILAVAIRTEL001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                mobile_number: '9876543210'
                operator: Airtel
                circle: 'Delhi NCR'
                amount: 299
                biller_id: BILAVAIRTEL001
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Recharge successful'
                  data: { ref_id: RCH20260227A1B2C3, txn_ref_id: BAV123456789, mobile_number: '9876543210', operator: Airtel, amount: 299, status: success }
        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/remitter/query:
    post:
      summary: 'Query Remitter'
      description: 'Query a remitter (sender) by mobile number. Returns remitter details including name, monthly transfer limits, and registered beneficiaries. If remitter is not found, proceed to register.'
      operationId: post_api_v1_dmt_remitter_query
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter 10-digit mobile number'
          schema:
            type: string
          example: '9876543210'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                mobile: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Customer found'
                  data: { name: 'Rajesh Kumar', mobile: '9876543210', total_limit: 25000, used_limit: 5000, available_limit: 20000, beneficiaries: [{ id: 42, name: 'Suresh Sharma', bank: 'HDFC Bank', account_number: '1234567890123', ifsc: HDFC0001234, mobile: '9988776655' }] }
        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/send-collect-request:
    post:
      summary: 'Send UPI Collect Request'
      description: 'Send a UPI collect request to a customer VPA. The customer receives a payment notification on their UPI app. If seamless mode is unavailable, automatically falls back to a payment link.'
      operationId: post_api_v1_collection_send_collect_request
      tags:
        - collection
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: customer_vpa
          in: query
          required: true
          description: 'Customer UPI VPA'
          schema:
            type: string
          example: customer@upi
        -
          name: amount
          in: query
          required: true
          description: 'Amount (₹50 minimum)'
          schema:
            type: numeric
          example: 100
        -
          name: customer_name
          in: query
          required: false
          description: 'Customer name'
          schema:
            type: string
          example: null
        -
          name: customer_mobile
          in: query
          required: false
          description: '10-digit mobile'
          schema:
            type: string
          example: null
        -
          name: purpose
          in: query
          required: false
          description: 'Payment purpose'
          schema:
            type: string
          example: null
        -
          name: expiry_minutes
          in: query
          required: false
          description: 'Expiry in minutes (5,10,15,30)'
          schema:
            type: integer
          example: 5
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                customer_vpa: customer@upi
                amount: 100
                customer_name: 'John Doe'
                customer_mobile: '9876543210'
                purpose: 'Invoice Payment'
                expiry_minutes: 5
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Collect request sent successfully'
                  data: { order_id: ECO1710600000123, reference_id: TXN12345, collection_id: 100, gross_amount: '100.00', credit_amount: '100.00', settlement_charge: '2.00', settlement_gst: '0.36', customer_vpa: customer@upi, status: pending, collection_type: collect_request, info: 'Customer will pay ₹100. Full amount credited to wallet. Settlement charge (₹2.00 + GST ₹0.36) deducted when you settle.' }
        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'
  '/statements/{serviceType}/bulk-export':
    post:
      summary: 'Bulk Export Statements'
      description: 'Initiate a bulk export of statement data for a service type. Supports Excel, CSV, and PDF formats. Restricted to admin and whitelabel roles with export permissions.'
      operationId: post_api_v1_statements_serviceType_bulk_export
      tags:
        - reports
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: serviceType
          in: path
          required: true
          description: ServiceType
          schema:
            type: string
        -
          name: serviceType
          in: query
          required: true
          description: 'Service type (path): payout, recharge, aeps, dmt, bbps, etc.'
          schema:
            type: string
          example: payout
        -
          name: format
          in: query
          required: false
          description: 'Export format: excel, csv, pdf (default: excel)'
          schema:
            type: string
          example: csv
        -
          name: from_date
          in: query
          required: false
          description: 'Start date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-02-01'
        -
          name: to_date
          in: query
          required: false
          description: 'End date (YYYY-MM-DD)'
          schema:
            type: string
          example: '2026-02-27'
        -
          name: status
          in: query
          required: false
          description: 'Filter by status'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                format: csv
                from_date: '2026-02-01'
                to_date: '2026-02-27'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Export is being processed'
                  data: { export_id: export_65f3a1b2c_1698765432, status: queued, download_url: /downloads/reports/export_65f3a1b2c_1698765432, estimated_records: 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'
  /aeps/ekyc/biometric:
    post:
      summary: 'eKYC Biometric Verification'
      description: 'Complete eKYC using biometric fingerprint verification via RD service device. Alternative to OTP-based eKYC.'
      operationId: post_api_v1_aeps_ekyc_biometric
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric capture data from RD service device (UIDAI PidData format)'
          schema:
            type: object
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  rdsID: MANTRA.AND.001
                  rdsVer: 1.0.8
                  mi: MFS100
                  mc: MIIEGDCCAwCg...
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Biometric eKYC completed successfully'
                  data: { status: true, message: 'Biometric eKYC verified' }
        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'
  /bbps/pay:
    post:
      summary: 'Pay Bill'
      description: 'Process a BBPS bill payment. Supports fetch-then-pay and quick-pay flows. Validates wallet balance, deducts charges with GST, and processes payment through BBPS network. NPCI compliant with remitter details for transactions above ₹50,000.'
      operationId: post_api_v1_bbps_pay
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: biller_id
          in: query
          required: true
          description: '14-character BBPS Biller ID'
          schema:
            type: string
          example: MAHA00000NAT01
        -
          name: customer_params
          in: query
          required: true
          description: 'Key-value pairs as per biller config'
          schema:
            type: object
          example: null
        -
          name: customer_mobile
          in: query
          required: true
          description: 'Customer 10-digit mobile number'
          schema:
            type: string
          example: null
        -
          name: amount
          in: query
          required: true
          description: 'Payment amount in INR (1-200000)'
          schema:
            type: numeric
          example: 1250
        -
          name: transaction_id
          in: query
          required: false
          description: 'Transaction ID from a prior fetch (skip for quick_pay)'
          schema:
            type: number
          example: null
        -
          name: payment_mode
          in: query
          required: false
          description: 'Payment mode: Cash, UPI, Internet Banking, etc. Default: Cash'
          schema:
            type: string
          example: null
        -
          name: quick_pay
          in: query
          required: false
          description: 'Skip fetch step for supported billers'
          schema:
            type: boolean
          example: null
        -
          name: remitter_name
          in: query
          required: false
          description: 'Required if amount > 50000 (NPCI compliance)'
          schema:
            type: string
          example: null
        -
          name: remitter_pan
          in: query
          required: false
          description: 'PAN card for high-value transactions'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                biller_id: MAHA00000NAT01
                customer_params:
                  'Consumer Number': '123456789'
                customer_mobile: '9876543210'
                amount: 1250
                transaction_id: 42
                payment_mode: Cash
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Bill payment successful'
                  data: { ref_id: ABCDEFGHIJKLMNOPQRSTUVWXYZ06058-1430, txn_reference_id: BBPS202602271430ABCDEF, biller_reference: BR-2026-001, biller_name: 'Maharashtra Electricity', amount: 1250, charge: 10, gst: 1.8, total_deduction: 1261.8, closing_balance: 48738.2, transaction_date: '2026-02-27 14:30:00' }
        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'
  '/recharge/status/{ref_id}':
    get:
      summary: 'Recharge Status'
      description: 'Check the status of a recharge transaction. For pending transactions, queries the provider for live status and updates accordingly. Auto-refunds wallet on provider-confirmed failure.'
      operationId: get_api_v1_recharge_status_ref_id
      tags:
        - recharge
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: ref_id
          in: path
          required: true
          description: 'Ref id'
          schema:
            type: string
        -
          name: ref_id
          in: query
          required: true
          description: 'Reference ID from process response (path parameter)'
          schema:
            type: string
          example: RCH20260227A1B2C3
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { ref_id: RCH20260227A1B2C3, status: success, message: 'Recharge successful', txn_ref_id: BAV123456789, amount: 299 }
        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/remitter/register:
    post:
      summary: 'Register Remitter'
      description: 'Register a new remitter (sender) for DMT. Two-step OTP flow: Step 1 - Send request without OTP to trigger SMS. Step 2 - Resend with the received OTP to complete registration.'
      operationId: post_api_v1_dmt_remitter_register
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter 10-digit mobile number'
          schema:
            type: string
          example: '9876543210'
        -
          name: fname
          in: query
          required: true
          description: 'First name'
          schema:
            type: string
          example: Rajesh
        -
          name: lname
          in: query
          required: true
          description: 'Last name'
          schema:
            type: string
          example: Kumar
        -
          name: dob
          in: query
          required: true
          description: 'Date of birth (YYYY-MM-DD)'
          schema:
            type: string
          example: '1990-05-15'
        -
          name: pincode
          in: query
          required: true
          description: '6-digit area pincode'
          schema:
            type: string
          example: '110001'
        -
          name: address
          in: query
          required: true
          description: 'Remitter address'
          schema:
            type: string
          example: '123 Main Street, New Delhi'
        -
          name: otp
          in: query
          required: false
          description: '6-digit OTP received via SMS (Step 2 only)'
          schema:
            type: string
          example: '483921'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                mobile: '9876543210'
                fname: Rajesh
                lname: Kumar
                dob: '1990-05-15'
                pincode: '110001'
                address: '123 Main Street, New Delhi'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'OTP sent to mobile number'
                  data: { status: otp_sent }
        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'
  '/bbps/status/{refId}':
    get:
      summary: 'BBPS Transaction Status'
      description: 'Check the status of a BBPS transaction using the reference ID. Returns current status, biller reference, and transaction details.'
      operationId: get_api_v1_bbps_status_refId
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: refId
          in: path
          required: true
          description: RefId
          schema:
            type: string
        -
          name: refId
          in: query
          required: true
          description: 'Transaction reference ID (35 characters, path parameter)'
          schema:
            type: string
          example: ABCDEFGHIJKLMNOPQRSTUVWXYZ06058-1430
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { ref_id: ABCDEFGHIJKLMNOPQRSTUVWXYZ06058-1430, status: success, txn_reference_id: BBPS202602271430ABCDEF, biller_reference: BR-2026-001, amount: 1250, biller_name: 'Maharashtra Electricity', created_at: '2026-02-27T14: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'
  /dmt/beneficiaries/delete:
    post:
      summary: 'Delete Beneficiary'
      description: "Delete a registered beneficiary from a remitter's account. Only beneficiaries owned by the authenticated user can be deleted."
      operationId: post_api_v1_dmt_beneficiaries_delete
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter mobile number (10 digits)'
          schema:
            type: string
          example: '9876543210'
        -
          name: beneid
          in: query
          required: true
          description: 'Beneficiary ID to delete'
          schema:
            type: number
          example: 42
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                mobile: '9876543210'
                beneid: 42
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Beneficiary deleted successfully'
        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'
  /aeps/ekyc/status:
    post:
      summary: 'eKYC Status Check'
      description: 'Check the current eKYC verification status of a merchant.'
      operationId: post_api_v1_aeps_ekyc_status
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { status: true, ekycStatus: completed, message: 'eKYC is verified' }
        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'
  '/statements/{serviceType}/summary':
    get:
      summary: 'Get Service Summary'
      description: 'Get dashboard-style summary metrics for a specific service. Returns total transactions, amounts, success rates, commissions, and other key statistics.'
      operationId: get_api_v1_statements_serviceType_summary
      tags:
        - reports
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: serviceType
          in: path
          required: true
          description: ServiceType
          schema:
            type: string
        -
          name: serviceType
          in: query
          required: true
          description: 'Service type (path): payout, recharge, aeps, dmt, bbps, etc.'
          schema:
            type: string
          example: payout
        -
          name: period
          in: query
          required: false
          description: 'Time period: today, week, month (default: today)'
          schema:
            type: string
          example: today
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { total_transactions: 1250, total_amount: 6500000, success_count: 1180, failed_count: 45, pending_count: 25, success_rate: 94.4, total_commission: 32500, average_amount: 5200 }
                  service_type: payout
                  period: today
        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'
  /bbps/complaints:
    get:
      summary: 'List BBPS Complaints'
      description: 'Get a paginated list of all BBPS complaints raised by the authenticated user. Returns complaint status, disposition, and reference details.'
      operationId: get_api_v1_bbps_complaints
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: per_page
          in: query
          required: false
          description: 'Results per page (default: 20)'
          schema:
            type: number
          example: 20
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ id: 1, complaint_id: CMPL-001, txn_reference_id: BBPS202602271430ABCDEF, disposition: 'Amount debited but bill not paid', status: RAISED, created_at: '2026-02-27T15:00:00+05:30' }]
                  pagination: { current_page: 1, last_page: 1, total: 3 }
        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'
  /aeps/two-fa:
    post:
      summary: 'Two-Factor Authentication'
      description: 'Complete two-factor authentication using biometric fingerprint. Required before Cash Withdrawal, Cash Deposit, and Aadhaar Pay transactions. Must be done daily.'
      operationId: post_api_v1_aeps_two_fa
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric capture data from RD service device'
          schema:
            type: object
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  rdsID: MANTRA.AND.001
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: '2FA authentication successful'
                  data: { status: true, message: 'Two-factor authentication completed' }
        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/verify:
    post:
      summary: 'Verify Beneficiary Account'
      description: 'Verify a bank account via penny drop verification. Returns the account holder name for confirmation before adding as beneficiary. A small verification fee is charged from the wallet.'
      operationId: post_api_v1_dmt_beneficiaries_verify
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: beneaccount
          in: query
          required: true
          description: 'Beneficiary bank account number (6-20 digits)'
          schema:
            type: string
          example: '1234567890123'
        -
          name: beneifsc
          in: query
          required: true
          description: 'IFSC code (11 characters)'
          schema:
            type: string
          example: HDFC0001234
        -
          name: benename
          in: query
          required: false
          description: 'Expected beneficiary name (for matching)'
          schema:
            type: string
          example: 'Suresh Sharma'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                beneaccount: '1234567890123'
                beneifsc: HDFC0001234
                benename: 'Suresh Sharma'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Account verified successfully'
                  data: { account_holder: 'SURESH SHARMA', account_number: '1234567890123', ifsc: HDFC0001234, bank_name: 'HDFC Bank' }
        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'
  /aeps/daily-kyc:
    post:
      summary: 'Daily KYC Check'
      description: 'Perform daily KYC verification check for the merchant. Ensures compliance with daily operational requirements.'
      operationId: post_api_v1_aeps_daily_kyc
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: FING123456789
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: PINFING123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Daily KYC check completed'
        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/status/{txnid}':
    get:
      summary: 'DMT Transaction Status'
      description: 'Check the status of a DMT transaction using the transaction ID. Returns current status, UTR number, amount, charges, and beneficiary details.'
      operationId: get_api_v1_dmt_status_txnid
      tags:
        - dmt
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: txnid
          in: path
          required: true
          description: Txnid
          schema:
            type: string
        -
          name: txnid
          in: query
          required: true
          description: 'Transaction ID (path parameter)'
          schema:
            type: string
          example: DMT20260227abc123-def456
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { txnid: DMT20260227abc123-def456, status: success, amount: 5000, charge: 15, gst: 2.7, tds: 0.75, total_deducted: 5016.95, utr: '408612345678', beneficiary_name: 'Suresh Sharma', beneficiary_account: '1234567890123', ifsc: HDFC0001234, created_at: '2026-02-27 10:30:00' }
        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'
  /bbps/complaints/raise:
    post:
      summary: 'Raise BBPS Complaint'
      description: 'Raise a complaint for a BBPS transaction. Supported dispositions: Amount debited but bill not paid, Wrong amount debited, Bill paid but status showing failed, Duplicate transaction, Refund not received.'
      operationId: post_api_v1_bbps_complaints_raise
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: txn_reference_id
          in: query
          required: true
          description: 'BBPS transaction reference ID'
          schema:
            type: string
          example: BBPS202602271430ABCDEF
        -
          name: disposition
          in: query
          required: true
          description: 'Complaint reason/disposition'
          schema:
            type: string
          example: 'Amount debited but bill not paid'
        -
          name: description
          in: query
          required: false
          description: 'Additional details (max 500 characters)'
          schema:
            type: string
          example: 'Payment was debited but biller shows unpaid.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                txn_reference_id: BBPS202602271430ABCDEF
                disposition: 'Amount debited but bill not paid'
                description: 'Payment was debited from my wallet but biller shows unpaid.'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Complaint raised successfully'
                  data: { complaint_id: CMPL-001, status: RAISED, txn_reference_id: BBPS202602271430ABCDEF }
        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'
  '/bbps/complaints/{id}/status':
    get:
      summary: 'BBPS Complaint Status'
      description: 'Check the current status of a BBPS complaint. Possible statuses: RAISED, ASSIGNED, IN_PROGRESS, RE_ASSIGNED, RESOLVED, CLOSED, REJECTED.'
      operationId: get_api_v1_bbps_complaints_id_status
      tags:
        - bbps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: id
          in: path
          required: true
          description: Id
          schema:
            type: string
        -
          name: id
          in: query
          required: true
          description: 'Complaint record ID (path parameter)'
          schema:
            type: number
          example: 1
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { complaint_id: CMPL-001, status: IN_PROGRESS, disposition: 'Amount debited but bill not paid', assigned_to: OU-Level-1, remarks: 'Under investigation', created_at: '2026-02-27T15:00:00+05:30', resolved_at: null }
        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'
  /aeps/cash-withdrawal:
    post:
      summary: 'Cash Withdrawal'
      description: "Process Aadhaar-based cash withdrawal from customer's bank account via biometric authentication. Requires 2FA. Amount range: ₹100 - ₹10,000."
      operationId: post_api_v1_aeps_cash_withdrawal
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
        -
          name: adhaarNumber
          in: query
          required: true
          description: 'Customer 12-digit Aadhaar number'
          schema:
            type: string
          example: '123456789012'
        -
          name: nationalBankIdentificationNumber
          in: query
          required: true
          description: 'Bank IIN/NBIN code'
          schema:
            type: string
          example: '607094'
        -
          name: transactionAmount
          in: query
          required: true
          description: 'Amount in INR (100-10000)'
          schema:
            type: numeric
          example: 1000
        -
          name: mobileNumber
          in: query
          required: false
          description: 'Customer 10-digit mobile'
          schema:
            type: string
          example: '9876543210'
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric fingerprint capture data from RD device'
          schema:
            type: object
          example: null
        -
          name: latitude
          in: query
          required: false
          description: 'GPS latitude'
          schema:
            type: numeric
          example: 26.9124
        -
          name: longitude
          in: query
          required: false
          description: 'GPS longitude'
          schema:
            type: numeric
          example: 75.7873
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '123456789012'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 1000
                mobileNumber: '9876543210'
                latitude: 26.9124
                longitude: 75.7873
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transaction_id: AEPS-CW-20260227143022-1234, status: success, rrn: '602312345678', amount: 1000, charge: 5, gst: 0.9, tds: 0.25, total_deducted: 1005.65, balance: { opening: 50000, closing: 48994.35 } }
        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'
  /aeps/balance-enquiry:
    post:
      summary: 'Balance Enquiry'
      description: "Check customer's bank account balance using Aadhaar-based biometric authentication. Returns the available balance in the customer's bank account."
      operationId: post_api_v1_aeps_balance_enquiry
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
        -
          name: adhaarNumber
          in: query
          required: true
          description: 'Customer 12-digit Aadhaar number'
          schema:
            type: string
          example: '123456789012'
        -
          name: nationalBankIdentificationNumber
          in: query
          required: true
          description: 'Bank IIN/NBIN code'
          schema:
            type: string
          example: '607094'
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric fingerprint capture data from RD device'
          schema:
            type: object
          example: null
        -
          name: mobileNumber
          in: query
          required: false
          description: 'Customer 10-digit mobile'
          schema:
            type: string
          example: '9876543210'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '123456789012'
                nationalBankIdentificationNumber: '607094'
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transaction_id: AEPS-BE-20260227143022-1234, status: success, rrn: '602312345678', balance_info: '15230.50', charge: 2, gst: 0.36, balance: { opening: 50000, closing: 49997.64 } }
        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'
  /aeps/mini-statement:
    post:
      summary: 'Mini Statement'
      description: "Fetch recent bank account mini statement using Aadhaar-based biometric authentication. Returns last few transactions from the customer's bank account."
      operationId: post_api_v1_aeps_mini_statement
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
        -
          name: adhaarNumber
          in: query
          required: true
          description: 'Customer 12-digit Aadhaar number'
          schema:
            type: string
          example: '123456789012'
        -
          name: nationalBankIdentificationNumber
          in: query
          required: true
          description: 'Bank IIN/NBIN code'
          schema:
            type: string
          example: '607094'
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric fingerprint capture data from RD device'
          schema:
            type: object
          example: null
        -
          name: mobileNumber
          in: query
          required: false
          description: 'Customer 10-digit mobile'
          schema:
            type: string
          example: '9876543210'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '123456789012'
                nationalBankIdentificationNumber: '607094'
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transaction_id: AEPS-MS-20260227143022-1234, status: success, rrn: '602312345678', statement: [{ date: '2026-02-25', narration: UPI/CR/402612345678, type: CR, amount: 5000 }, { date: '2026-02-24', narration: ATM/WDL/602312345679, type: DR, amount: 2000 }, { date: '2026-02-23', narration: NEFT/CR/HDFC0001234, type: CR, amount: 15000 }], charge: 2, gst: 0.36, balance: { opening: 50000, closing: 49997.64 } }
        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'
  /aeps/cash-deposit:
    post:
      summary: 'Cash Deposit'
      description: "Deposit cash into customer's bank account using Aadhaar-based biometric authentication. Requires 2FA. Amount range: ₹100 - ₹10,000."
      operationId: post_api_v1_aeps_cash_deposit
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
        -
          name: adhaarNumber
          in: query
          required: true
          description: 'Customer 12-digit Aadhaar number'
          schema:
            type: string
          example: null
        -
          name: nationalBankIdentificationNumber
          in: query
          required: true
          description: 'Bank IIN/NBIN code'
          schema:
            type: string
          example: null
        -
          name: transactionAmount
          in: query
          required: true
          description: 'Amount in INR (100-10000)'
          schema:
            type: numeric
          example: 5000
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric fingerprint capture data from RD device'
          schema:
            type: object
          example: null
        -
          name: mobileNumber
          in: query
          required: false
          description: 'Customer 10-digit mobile'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '123456789012'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 5000
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transaction_id: AEPS-CD-20260227143022-1234, status: success, rrn: '602312345678', amount: 5000, charge: 10, gst: 1.8, net_credit: 4988.2, balance: { opening: 50000, closing: 54988.2 } }
        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'
  /aeps/aadhaar-pay:
    post:
      summary: 'Aadhaar Pay'
      description: 'Process Aadhaar-based merchant payment (AadhaarPay/MATM). Customer pays merchant via biometric authentication. Requires 2FA. Amount range: ₹100 - ₹10,000.'
      operationId: post_api_v1_aeps_aadhaar_pay
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
        -
          name: adhaarNumber
          in: query
          required: true
          description: 'Customer 12-digit Aadhaar number'
          schema:
            type: string
          example: null
        -
          name: nationalBankIdentificationNumber
          in: query
          required: true
          description: 'Bank IIN/NBIN code'
          schema:
            type: string
          example: null
        -
          name: transactionAmount
          in: query
          required: true
          description: 'Amount in INR (100-10000)'
          schema:
            type: numeric
          example: 1000
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric fingerprint capture data from RD device'
          schema:
            type: object
          example: null
        -
          name: mobileNumber
          in: query
          required: false
          description: 'Customer 10-digit mobile'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '123456789012'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 1000
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transaction_id: AEPS-M-20260227143022-1234, status: success, rrn: '602312345678', amount: 1000, charge: 5, gst: 0.9, total_deducted: 1005.9, balance: { opening: 50000, closing: 48994.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'
  /aeps/status:
    post:
      summary: 'AEPS Transaction Status'
      description: 'Check the status of an AEPS transaction using the transaction ID. Returns current status, RRN, and amount details.'
      operationId: post_api_v1_aeps_status
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: transaction_id
          in: query
          required: true
          description: 'Transaction ID to look up'
          schema:
            type: string
          example: AEPS-CW-20260227143022-1234
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                transaction_id: AEPS-CW-20260227143022-1234
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { transaction_id: AEPS-CW-20260227143022-1234, status: success, rrn: '602312345678', amount: 1000, response_code: '00', response_message: 'Transaction successful' }
        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'
  /aeps/transaction:
    post:
      summary: 'Unified AEPS Transaction'
      description: 'Unified AEPS transaction endpoint supporting all transaction types: Cash Withdrawal (CW), Balance Enquiry (BE), Mini Statement (MS), Cash Deposit (CD), and Aadhaar Pay (M). Use transactionType parameter to specify the operation.'
      operationId: post_api_v1_aeps_transaction
      tags:
        - aeps
      security:
        -
          ApiKeyAuth: {  }
      parameters:
        -
          name: transactionType
          in: query
          required: true
          description: 'Transaction type: CW (Cash Withdrawal), BE (Balance Enquiry), MS (Mini Statement), CD (Cash Deposit), M (Aadhaar Pay)'
          schema:
            type: string
          example: CW
        -
          name: merchantLoginId
          in: query
          required: true
          description: 'Merchant login ID'
          schema:
            type: string
          example: null
        -
          name: merchantPin
          in: query
          required: true
          description: 'Merchant login PIN'
          schema:
            type: string
          example: null
        -
          name: adhaarNumber
          in: query
          required: true
          description: 'Customer 12-digit Aadhaar number'
          schema:
            type: string
          example: null
        -
          name: indicatorforUID
          in: query
          required: true
          description: '0 = Aadhaar, 2 = Virtual ID'
          schema:
            type: string
          example: '0'
        -
          name: nationalBankIdentificationNumber
          in: query
          required: true
          description: 'Bank IIN/NBIN code'
          schema:
            type: string
          example: null
        -
          name: transactionAmount
          in: query
          required: false
          description: 'Amount in INR (required for CW, CD, M; 100-10000)'
          schema:
            type: numeric
          example: null
        -
          name: captureResponse
          in: query
          required: true
          description: 'Biometric fingerprint capture data from RD device'
          schema:
            type: object
          example: null
        -
          name: mobileNumber
          in: query
          required: false
          description: 'Customer 10-digit mobile'
          schema:
            type: string
          example: null
        -
          name: latitude
          in: query
          required: false
          description: 'GPS latitude'
          schema:
            type: numeric
          example: null
        -
          name: longitude
          in: query
          required: false
          description: 'GPS longitude'
          schema:
            type: numeric
          example: null
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              example:
                transactionType: CW
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '123456789012'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 1000
                mobileNumber: '9876543210'
                latitude: 26.9124
                longitude: 75.7873
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: encoded-pid-data
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transaction_id: AEPS-CW-20260227143022-1234, status: success, rrn: '602312345678', amount: 1000, charge: 5, gst: 0.9, tds: 0.25, total_deducted: 1005.65, balance: { opening: 50000, closing: 48994.35 } }
        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.'
