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: hello@laraware.net
    url: 'https://nxtbanking.ai/support'
  license:
    name: Proprietary
    url: 'https://nxtbanking.ai/terms'
  termsOfService: 'https://nxtbanking.ai/terms'
  x-unified-contract:
    single_contract: true
    provider_switch_transparent: true
    virtual_endpoint_mode: true
    not_implemented_error_code: FEATURE_NOT_AVAILABLE
servers:
  -
    url: 'https://nxtbanking.ai/api/v1'
    description: 'Production Server'
  -
    url: 'https://nxtbanking.ai/api/sandbox'
    description: 'Sandbox Server (Test Mode)'
security:
  -
    HmacAuth: {  }
    ClientIdAuth: {  }
    TimestampAuth: {  }
    RequestIdAuth: {  }
tags:
  -
    name: Authentication
    description: 'API authentication and authorization'
  -
    name: Payout
    description: 'Payout and fund transfer operations'
  -
    name: DMT
    description: 'Domestic Money Transfer operations'
  -
    name: AEPS
    description: 'Aadhaar Enabled Payment System operations'
  -
    name: BBPS
    description: 'Bharat Bill Payment System 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'
  -
    name: aeps/bank-1
    description: 'Operations related to aeps/bank-1'
  -
    name: aeps/bank-2
    description: 'Operations related to aeps/bank-2'
  -
    name: onboarding-activation
    description: 'Operations related to onboarding-activation'
  -
    name: payout/idfc
    description: 'Operations related to payout/idfc'
paths:
  /collection/history:
    get:
      summary: 'Get Collection History'
      description: 'Retrieve paginated list of collection transactions'
      operationId: get_api_v1_collection_history
      tags:
        - collection
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ id: 1, order_id: TXN-1234567890, reference_id: ORD-1763429644, amount: '500.00', status: success, collection_type: dynamic_qr, gateway: upi, 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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. The active rail (selected by admin in /admin/api-manager) determines the underlying source — the response shape is identical across rails.'
      operationId: get_api_v1_dmt_banks
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Display name for the virtual account'
                  example: 'Primary Collection Account'
                customer_identifier:
                  type: string
                  description: 'Your internal customer identifier (must be unique)'
                  example: CUST_1001
                description:
                  type: string
                  description: 'Optional description for this virtual account'
                  example: 'Virtual account for order payments'
                enable_upi:
                  type: boolean
                  description: 'If true, enables UPI VPA along with bank account (default: false)'
                  example: true
                close_by:
                  type: string
                  description: 'Auto-close datetime in YYYY-MM-DD HH:MM:SS format'
                  example: '2025-12-31 23:59:59'
                notes:
                  type: object
                  description: 'Additional metadata to store with the virtual account (key-value pairs)'
                  example: { order_id: ORD_98765 }
              required:
                - name
                - customer_identifier
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /collection/generate-dynamic-qr:
    post:
      summary: 'Generate Dynamic QR'
      description: 'Generate a transaction-specific dynamic QR code with fixed amount. Returns a QR code image (base64 SVG) that customers can scan with any UPI app to complete payment.'
      operationId: post_api_v1_collection_generate_dynamic_qr
      tags:
        - collection
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: 'Amount to be collected in INR (Min: ₹1)'
                  example: 100.0
                reference_id:
                  type: string
                  description: 'Unique order/reference ID (max 50 characters)'
                  example: ORD-1775243072
                customer_name:
                  type: string
                  description: 'Customer name (optional, defaults to user name)'
                  example: 'John Doe'
                customer_mobile:
                  type: string
                  description: 'Customer mobile number (10 digits, optional)'
                  example: '9876543210'
                purpose:
                  type: string
                  description: 'Payment purpose (optional, defaults to "Payment")'
                  example: 'Product Purchase'
                expiry_minutes:
                  type: integer
                  description: 'QR code validity in minutes (Default: 30)'
                  example: 30
              required:
                - amount
                - reference_id
              example:
                amount: 100
                reference_id: ORD-1775243072
                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: TXN-1234567890, reference_id: ORD-1775243072, qr_code: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...(base64 SVG QR image)...', qr_string: not_enabled, payment_link: not_enabled, payment_url: not_enabled, upi_intent: not_enabled, upi_deep_link: not_enabled, phonepe_link: not_enabled, paytm_link: not_enabled, googlepay_link: not_enabled, 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-04-05 22:30:00', generated_at: '2026-04-05 22:00:00', timestamp: '2026-04-05T22:00:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/initiate:
    post:
      summary: 'Initiate Activation'
      description: "⚠️ One-time activation. Required ONCE per merchant before using any Bank 2 backed rail — DMT, AEPS, BBPS, or UPI ATM. Bank 1 rails do NOT require this step. Once completed, the SAME activation unlocks all Bank 2 rails simultaneously; per-rail product flags then gate individual transactions. STEP 1 of the wizard: submits the merchant's KYC payload (auto-pulled from profile) to the Bank 2 Min-KYC endpoint and triggers an Aadhaar OTP to the registered mobile."
      operationId: post_api_v1_onboarding_activation_initiate
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                consent:
                  type: boolean
                  description: 'Merchant consent flag — must be `true`. Records DPDP-grade consent for sharing KYC with the Bank 2 partner.'
                  example: true
              required:
                - consent
              example:
                consent: true
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: OTP
                  status: success
                  message: 'OTP sent to your registered mobile.'
                  data: { reference_key: mk_72b91f..., mobile_masked: XXXXXX3210, next_action: verify-otp }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: 'Unique transaction ID (max 20 characters)'
                  example: MYAPP1699523456789
                account_holder_name:
                  type: string
                  description: 'Full name of the beneficiary as per bank records'
                  example: 'John Doe'
                account_number:
                  type: string
                  description: 'Bank account number of the beneficiary'
                  example: '1234567890123456'
                ifsc_code:
                  type: string
                  description: 'IFSC code of the beneficiary bank branch'
                  example: SBIN0001234
                amount:
                  type: number
                  description: 'Transfer amount in Indian Rupees (₹100 - ₹2,00,000)'
                  example: 10000.0
                mode:
                  type: string
                  description: 'Transfer mode (defaults to IMPS)'
                  example: IMPS
                mobile:
                  type: string
                  description: 'Beneficiary mobile number (10 digits)'
                  example: '9876543210'
                remarks:
                  type: string
                  description: 'Transaction remarks or purpose'
                  example: 'Payment for services'
                latitude:
                  type: number
                  description: 'GPS latitude for transaction tracking (-90 to 90)'
                  example: 28.7041
                longitude:
                  type: number
                  description: 'GPS longitude for transaction tracking (-180 to 180)'
                  example: 77.1025
                purpose:
                  type: string
                  description: 'Transaction purpose (max 200 characters)'
                  example: 'Payment for services'
              required:
                - transaction_id
                - account_holder_name
                - account_number
                - ifsc_code
                - amount
              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: BANK10022011, bank_name: 'Bank 1 Bank' }, tax_invoice: { invoice_number: INV/202511/00720, download_url: 'https://Your Platform.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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Full name of merchant (3-100 chars)'
                  example: 'Rajesh Kumar Singh'
                merchantPhoneNumber:
                  type: string
                  description: '10-digit mobile number'
                  example: '9876543210'
                address1:
                  type: string
                  description: 'Primary address line (max 200)'
                  example: 'Shop No 5, Main Market'
                address2:
                  type: string
                  description: 'Secondary address line (max 200)'
                  example: 'Near Bus Stand'
                state:
                  type: string
                  description: 'State name (max 50)'
                  example: Rajasthan
                city:
                  type: string
                  description: 'City name (max 50)'
                  example: Jaipur
                district:
                  type: string
                  description: 'District name (max 50)'
                  example: Jaipur
                pincode:
                  type: string
                  description: '6-digit PIN code'
                  example: '302001'
                userPan:
                  type: string
                  description: 'Merchant PAN card number (format: XXXXX9999X)'
                  example: ABCDE1234F
                aadhaarNumber:
                  type: string
                  description: '12-digit Aadhaar number (UIDAI format; cannot start with 0/1)'
                  example: '234567890123'
                gstin:
                  type: string
                  description: '15-character GSTIN (format: NNAAAAANNNN A1Z A)'
                  example: 08ABCDE1234F1Z5
                companyOrShopPan:
                  type: string
                  description: 'Shop/company PAN if different from merchant (XXXXX9999X)'
                  example: AAACS1234C
                bankAccountNumber:
                  type: string
                  description: 'Settlement bank account number (max 20)'
                  example: '12345678901234'
                bankIfscCode:
                  type: string
                  description: 'Bank IFSC code (11 chars, format: AAAA0XXXXXX)'
                  example: SBIN0001234
                bankName:
                  type: string
                  description: 'Bank name (max 100)'
                  example: 'State Bank of India'
                bankAccountName:
                  type: string
                  description: 'Account holder name as per bank record (max 100)'
                  example: 'Rajesh Kumar Singh'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50). Defaults to "WEB-FORM" if omitted.'
                  example: '358240051111110'
              required:
                - name
                - merchantPhoneNumber
                - address1
                - state
                - city
                - district
                - pincode
                - userPan
                - bankAccountNumber
                - bankIfscCode
              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: '234567890123'
                gstin: 08ABCDE1234F1Z5
                companyOrShopPan: AAACS1234C
                bankAccountNumber: '12345678901234'
                bankIfscCode: SBIN0001234
                bankName: 'State Bank of India'
                bankAccountName: 'Rajesh Kumar Singh'
                latitude: 26.9124
                longitude: 75.7873
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/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_bank_1_onboard
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Full name of merchant (3-100 chars)'
                  example: 'Rajesh Kumar Singh'
                merchantPhoneNumber:
                  type: string
                  description: '10-digit mobile number'
                  example: '9876543210'
                address1:
                  type: string
                  description: 'Primary address line (max 200)'
                  example: 'Shop No 5, Main Market'
                address2:
                  type: string
                  description: 'Secondary address line (max 200)'
                  example: 'Near Bus Stand'
                state:
                  type: string
                  description: 'State name (max 50)'
                  example: Rajasthan
                city:
                  type: string
                  description: 'City name (max 50)'
                  example: Jaipur
                district:
                  type: string
                  description: 'District name (max 50)'
                  example: Jaipur
                pincode:
                  type: string
                  description: '6-digit PIN code'
                  example: '302001'
                userPan:
                  type: string
                  description: 'Merchant PAN card number (format: XXXXX9999X)'
                  example: ABCDE1234F
                aadhaarNumber:
                  type: string
                  description: '12-digit Aadhaar number (UIDAI format; cannot start with 0/1)'
                  example: '234567890123'
                gstin:
                  type: string
                  description: '15-character GSTIN (format: NNAAAAANNNN A1Z A)'
                  example: 08ABCDE1234F1Z5
                companyOrShopPan:
                  type: string
                  description: 'Shop/company PAN if different from merchant (XXXXX9999X)'
                  example: AAACS1234C
                bankAccountNumber:
                  type: string
                  description: 'Settlement bank account number (max 20)'
                  example: '12345678901234'
                bankIfscCode:
                  type: string
                  description: 'Bank IFSC code (11 chars, format: AAAA0XXXXXX)'
                  example: SBIN0001234
                bankName:
                  type: string
                  description: 'Bank name (max 100)'
                  example: 'State Bank of India'
                bankAccountName:
                  type: string
                  description: 'Account holder name as per bank record (max 100)'
                  example: 'Rajesh Kumar Singh'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50). Defaults to "WEB-FORM" if omitted.'
                  example: '358240051111110'
              required:
                - name
                - merchantPhoneNumber
                - address1
                - state
                - city
                - district
                - pincode
                - userPan
                - bankAccountNumber
                - bankIfscCode
              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: '234567890123'
                gstin: 08ABCDE1234F1Z5
                companyOrShopPan: AAACS1234C
                bankAccountNumber: '12345678901234'
                bankIfscCode: SBIN0001234
                bankName: 'State Bank of India'
                bankAccountName: 'Rajesh Kumar Singh'
                latitude: 26.9124
                longitude: 75.7873
                deviceIMEI: '358240051111110'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Merchant onboarded successfully'
                  data: { merchantLoginId: BANK1123456789, merchantLoginPin: PINBANK1123456, merchantId: BANK1-MER-00001 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: 'Your transaction ID from initiate response'
                  example: TXN1732619845123
              required:
                - transaction_id
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. Returns primaryKeyId and encodeFPTxnId — store both, you must echo them back when calling validate-otp / resend-otp."
      operationId: post_api_v1_aeps_ekyc_send_otp
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID from onboarding'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                mobileNumber:
                  type: string
                  description: '10-digit mobile number that will receive the OTP'
                  example: '9876543210'
                aadhaarNumber:
                  type: string
                  description: '12-digit merchant Aadhaar (UIDAI format)'
                  example: '234567890123'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - mobileNumber
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                mobileNumber: '9876543210'
                aadhaarNumber: '234567890123'
                deviceIMEI: '358240051111110'
      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', primaryKeyId: PK_ABC123, encodeFPTxnId: FPTXN_ENC456 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/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. Returns primaryKeyId and encodeFPTxnId — store both, you must echo them back when calling validate-otp / resend-otp."
      operationId: post_api_v1_aeps_bank_1_ekyc_send_otp
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID from onboarding'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                mobileNumber:
                  type: string
                  description: '10-digit mobile number that will receive the OTP'
                  example: '9876543210'
                aadhaarNumber:
                  type: string
                  description: '12-digit merchant Aadhaar (UIDAI format)'
                  example: '234567890123'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - mobileNumber
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                mobileNumber: '9876543210'
                aadhaarNumber: '234567890123'
                deviceIMEI: '358240051111110'
      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', primaryKeyId: PK_ABC123, encodeFPTxnId: FPTXN_ENC456 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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.0
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/verify-otp:
    post:
      summary: 'Verify Activation OTP'
      description: 'STEP 2 of the wizard: verify the OTP received via SMS. On success, the outlet is provisioned on the Bank 2 partner and the merchant proceeds to biometric eKYC.'
      operationId: post_api_v1_onboarding_activation_verify_otp
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                otp:
                  type: string
                  description: '6-digit OTP from SMS.'
                  example: '483921'
                reference_key:
                  type: string
                  description: 'Reference key returned by /initiate.'
              required:
                - otp
                - reference_key
              example:
                otp: '483921'
                reference_key: mk_72b91f...
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'OTP verified. Please complete biometric eKYC.'
                  data: { outlet_id: OL12345678, state: min_kyc_done, next_action: biometric_capture }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. primaryKeyId and encodeFPTxnId from the send-otp response are REQUIRED here.'
      operationId: post_api_v1_aeps_ekyc_validate_otp
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                otp:
                  type: string
                  description: '6-digit OTP received via SMS'
                  example: '123456'
                primaryKeyId:
                  type: string
                  description: 'primaryKeyId returned by /aeps/ekyc/send-otp'
                  example: PK_ABC123
                encodeFPTxnId:
                  type: string
                  description: 'encodeFPTxnId returned by /aeps/ekyc/send-otp'
                  example: FPTXN_ENC456
                mobileNumber:
                  type: string
                  description: '10-digit mobile number OTP was sent to (legacy alias)'
                  example: '9876543210'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - otp
                - primaryKeyId
                - encodeFPTxnId
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                otp: '123456'
                primaryKeyId: PK_ABC123
                encodeFPTxnId: FPTXN_ENC456
                mobileNumber: '9876543210'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/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. primaryKeyId and encodeFPTxnId from the send-otp response are REQUIRED here.'
      operationId: post_api_v1_aeps_bank_1_ekyc_validate_otp
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                otp:
                  type: string
                  description: '6-digit OTP received via SMS'
                  example: '123456'
                primaryKeyId:
                  type: string
                  description: 'primaryKeyId returned by /aeps/ekyc/send-otp'
                  example: PK_ABC123
                encodeFPTxnId:
                  type: string
                  description: 'encodeFPTxnId returned by /aeps/ekyc/send-otp'
                  example: FPTXN_ENC456
                mobileNumber:
                  type: string
                  description: '10-digit mobile number OTP was sent to (legacy alias)'
                  example: '9876543210'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - otp
                - primaryKeyId
                - encodeFPTxnId
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                otp: '123456'
                primaryKeyId: PK_ABC123
                encodeFPTxnId: FPTXN_ENC456
                mobileNumber: '9876543210'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: 'Payment amount in INR (₹50 minimum)'
                  example: 1000.0
                customer_name:
                  type: string
                  description: 'Customer name'
                  example: 'Jane Smith'
                customer_mobile:
                  type: string
                  description: 'Customer mobile'
                  example: '9123456789'
                customer_email:
                  type: string
                  description: 'Customer email'
                  example: jane@example.com
                reference_id:
                  type: string
                  description: 'Unique invoice ID'
                  example: INV2025001
                description:
                  type: string
                  description: 'Payment description'
                  example: 'Monthly Subscription'
                expiry_hours:
                  type: integer
                  description: 'Link expiry (default: 24)'
                  example: 24
                send_sms:
                  type: boolean
                  description: 'Send SMS notification'
                  example: false
                send_email:
                  type: boolean
                  description: 'Send email notification'
                  example: false
              required:
                - amount
                - customer_name
                - customer_mobile
                - reference_id
                - description
              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, reference_id: INV2025001, payment_link: 'https://Your Platform.ai/payment/upi/abc123xyz...', short_link: 'https://Your Platform.ai/p/abc123', amount: '1000.00', customer_name: 'Jane Smith', customer_mobile: '9123456789', customer_email: jane@example.com, description: 'Monthly Subscription Payment', 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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operator:
                  type: string
                  description: 'Operator name'
                  example: Airtel
                circle:
                  type: string
                  description: 'Telecom circle'
                  example: 'Delhi NCR'
              required:
                - operator
                - circle
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: reportId
          in: path
          required: true
          description: ReportId
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from_date:
                  type: string
                  description: 'Start date (YYYY-MM-DD)'
                  example: '2026-02-01'
                to_date:
                  type: string
                  description: 'End date (YYYY-MM-DD)'
                  example: '2026-02-27'
                status:
                  type: string
                  description: 'Filter by status (success, pending, failed)'
                  example: success
                amount_min:
                  type: number
                  description: 'Minimum amount filter'
                  example: 100.0
                amount_max:
                  type: number
                  description: 'Maximum amount filter'
                  example: 50000.0
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/resend-otp:
    post:
      summary: 'Resend Activation OTP'
      description: 'Re-trigger the Aadhaar OTP if the merchant did not receive the first SMS. Rate-limited by the underlying provider; subject to a cool-down window.'
      operationId: post_api_v1_onboarding_activation_resend_otp
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference_key:
                  type: string
                  description: 'Reference key returned by /initiate.'
              required:
                - reference_key
              example:
                reference_key: mk_72b91f...
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: OTP
                  status: success
                  message: 'OTP re-sent.'
                  data: { mobile_masked: XXXXXX3210 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_number:
                  type: string
                  description: 'Bank account number to verify'
                  example: '1234567890123456'
                ifsc_code:
                  type: string
                  description: 'IFSC code of the bank branch'
                  example: SBIN0001234
              required:
                - account_number
                - ifsc_code
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/mobile-change:
    post:
      summary: 'Change Mobile Number'
      description: "Resolves the PAN-mobile mismatch case: when /initiate fails because the merchant's PAN is registered against a different mobile in NSDL records, this flow lets the merchant verify both mobiles to update."
      operationId: post_api_v1_onboarding_activation_mobile_change
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                new_mobile:
                  type: string
                  description: 'New 10-digit mobile to register.'
                  example: '9876543210'
              required:
                - new_mobile
              example:
                new_mobile: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: OTP
                  status: success
                  message: 'OTPs sent to both mobiles. Verify both to continue.'
                  data: { reference_key: mc_8a31..., next_action: verify_both_otps }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                collection_id:
                  type: string
                  description: 'Your reference ID'
                  example: ORD123456
              required:
                - collection_id
              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 }, 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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: id
          in: path
          required: true
          description: Id
          schema:
            type: string
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/ekyc/resend-otp:
    post:
      summary: 'eKYC Resend OTP'
      description: 'Resend OTP for eKYC verification if the previous OTP expired or was not received. primaryKeyId and encodeFPTxnId from the original send-otp response are REQUIRED here (same session).'
      operationId: post_api_v1_aeps_bank_1_ekyc_resend_otp
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                primaryKeyId:
                  type: string
                  description: 'primaryKeyId returned by the original /aeps/ekyc/send-otp'
                  example: PK_ABC123
                encodeFPTxnId:
                  type: string
                  description: 'encodeFPTxnId returned by the original /aeps/ekyc/send-otp'
                  example: FPTXN_ENC456
                mobileNumber:
                  type: string
                  description: '10-digit mobile number to resend OTP'
                  example: '9876543210'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - primaryKeyId
                - encodeFPTxnId
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                primaryKeyId: PK_ABC123
                encodeFPTxnId: FPTXN_ENC456
                mobileNumber: '9876543210'
                deviceIMEI: '358240051111110'
      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', primaryKeyId: PK_ABC123, encodeFPTxnId: FPTXN_ENC456 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_id:
                  type: string
                  description: 'BBPS Biller ID'
                  example: MAHA00000NAT01
                customer_params:
                  type: object
                  description: 'Key-value pairs as per biller configuration'
                customer_mobile:
                  type: string
                  description: 'Customer 10-digit mobile number'
                  example: '9876543210'
                channel:
                  type: string
                  description: 'Channel: INT (Internet), MOB (Mobile), AGT (Agent). Default: INT'
                  example: INT
              required:
                - biller_id
                - customer_params
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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
        -
          name: length
          in: query
          required: false
          description: 'Records per page (default: 50)'
          schema:
            type: number
          example: 50.0
        -
          name: page
          in: query
          required: false
          description: 'Page number (default: 1)'
          schema:
            type: number
          example: 1.0
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile_number:
                  type: string
                  description: '10-digit mobile number starting with 6-9'
                  example: '9876543210'
                operator:
                  type: string
                  description: 'Operator name'
                  example: Airtel
                circle:
                  type: string
                  description: 'Telecom circle'
                  example: 'Delhi NCR'
                amount:
                  type: number
                  description: 'Recharge amount in INR (10-10000)'
                  example: 299.0
                biller_id:
                  type: string
                  description: 'Biller ID from operators list'
                  example: BILAVAIRTEL001
              required:
                - mobile_number
                - operator
                - circle
                - amount
                - biller_id
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. Backend automatically routes to the active rail.'
      operationId: post_api_v1_dmt_remitter_query
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: 'Remitter 10-digit mobile number'
                  example: '9876543210'
              required:
                - mobile
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_vpa:
                  type: string
                  description: 'Customer UPI VPA'
                  example: customer@upi
                amount:
                  type: number
                  description: 'Amount (₹50 minimum)'
                  example: 100.0
                customer_name:
                  type: string
                  description: 'Customer name'
                customer_mobile:
                  type: string
                  description: '10-digit mobile'
                purpose:
                  type: string
                  description: 'Payment purpose'
                expiry_minutes:
                  type: integer
                  description: 'Expiry in minutes (5,10,15,30)'
                  example: 5
              required:
                - customer_vpa
                - amount
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/status:
    get:
      summary: 'Activation Status'
      description: "Returns the merchant's current activation FSM state plus per-rail product flags. **Always call this BEFORE attempting a Bank 2 transaction** — let the response's `next_action` drive your UI. Possible states: `pending`, `otp_sent`, `mobile_change_otp`, `min_kyc_done`, `biometric_required`, `biometric_submitted`, `active`, `rejected`, `suspended`. Per-rail unlock is signalled via `products.upi_atm`, `products.aeps`, `products.dmt`."
      operationId: get_api_v1_onboarding_activation_status
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: OK
                  data: { state: active, outlet_id: OL12345678, next_action: none, biometric_submitted_at: '2026-04-28T10:30:00+05:30', products: { upi_atm: active, aeps: active, dmt: pending_bank_approval } }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: serviceType
          in: path
          required: true
          description: ServiceType
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  description: 'Export format: excel, csv, pdf (default: excel)'
                  example: csv
                from_date:
                  type: string
                  description: 'Start date (YYYY-MM-DD)'
                  example: '2026-02-01'
                to_date:
                  type: string
                  description: 'End date (YYYY-MM-DD)'
                  example: '2026-02-27'
                status:
                  type: string
                  description: 'Filter by status'
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/ekyc/biometric:
    post:
      summary: 'eKYC Biometric Verification'
      description: 'Complete eKYC using biometric fingerprint verification via UIDAI-certified RD service device. Alternative to OTP-based eKYC. Pass primaryKeyId / encodeFPTxnId from a prior send-otp call when continuing the same session.'
      operationId: post_api_v1_aeps_ekyc_biometric
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                primaryKeyId:
                  type: string
                  description: 'primaryKeyId from a prior /aeps/ekyc/send-otp (when chaining with OTP eKYC)'
                  example: PK_ABC123
                encodeFPTxnId:
                  type: string
                  description: 'encodeFPTxnId from a prior /aeps/ekyc/send-otp (when chaining with OTP eKYC)'
                  example: FPTXN_ENC456
                captureResponse:
                  type: object
                  description: 'Biometric capture data from RD service device (UIDAI PidData format). Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - captureResponse
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                primaryKeyId: PK_ABC123
                encodeFPTxnId: FPTXN_ENC456
                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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/ekyc/biometric:
    post:
      summary: 'eKYC Biometric Verification'
      description: 'Complete eKYC using biometric fingerprint verification via UIDAI-certified RD service device. Alternative to OTP-based eKYC. Pass primaryKeyId / encodeFPTxnId from a prior send-otp call when continuing the same session.'
      operationId: post_api_v1_aeps_bank_1_ekyc_biometric
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                primaryKeyId:
                  type: string
                  description: 'primaryKeyId from a prior /aeps/ekyc/send-otp (when chaining with OTP eKYC)'
                  example: PK_ABC123
                encodeFPTxnId:
                  type: string
                  description: 'encodeFPTxnId from a prior /aeps/ekyc/send-otp (when chaining with OTP eKYC)'
                  example: FPTXN_ENC456
                captureResponse:
                  type: object
                  description: 'Biometric capture data from RD service device (UIDAI PidData format). Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - captureResponse
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                primaryKeyId: PK_ABC123
                encodeFPTxnId: FPTXN_ENC456
                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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_id:
                  type: string
                  description: '14-character BBPS Biller ID'
                  example: MAHA00000NAT01
                customer_params:
                  type: object
                  description: 'Key-value pairs as per biller config'
                customer_mobile:
                  type: string
                  description: 'Customer 10-digit mobile number'
                amount:
                  type: number
                  description: 'Payment amount in INR (1-200000)'
                  example: 1250.0
                transaction_id:
                  type: number
                  description: 'Transaction ID from a prior fetch (skip for quick_pay)'
                payment_mode:
                  type: string
                  description: 'Payment mode: Cash, UPI, Internet Banking, etc. Default: Cash'
                quick_pay:
                  type: boolean
                  description: 'Skip fetch step for supported billers'
                remitter_name:
                  type: string
                  description: 'Required if amount > 50000 (NPCI compliance)'
                remitter_pan:
                  type: string
                  description: 'PAN card for high-value transactions'
              required:
                - biller_id
                - customer_params
                - customer_mobile
                - amount
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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 + reference_key to complete registration.'
      operationId: post_api_v1_dmt_remitter_register
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: 'Remitter 10-digit mobile number'
                  example: '9876543210'
                fname:
                  type: string
                  description: 'First name'
                  example: Rajesh
                lname:
                  type: string
                  description: 'Last name'
                  example: Kumar
                dob:
                  type: string
                  description: 'Date of birth (YYYY-MM-DD)'
                  example: '1990-05-15'
                pincode:
                  type: string
                  description: '6-digit area pincode'
                  example: '110001'
                address:
                  type: string
                  description: 'Remitter address'
                  example: '123 Main Street, New Delhi'
                otp:
                  type: string
                  description: '6-digit OTP received via SMS (Step 2 only)'
                  example: '483921'
                reference_key:
                  type: string
                  description: 'Reference key returned from Step 1 (Step 2 only)'
                stateresp:
                  type: string
                  description: 'State name. Only consumed by some upstream rails — safe to omit; backend defaults from pincode.'
                gst_state:
                  type: string
                  description: '2-digit GST state code. Only consumed by some upstream rails — safe to omit.'
              required:
                - mobile
                - fname
                - lname
                - dob
                - pincode
                - address
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/biometric/status:
    post:
      summary: 'Biometric eKYC Status'
      description: 'Pre-flight before /biometric/submit. Returns the Bank 2 issued `reference_key` + PID `wadh` token the RD service needs to encrypt the fingerprint payload, plus a flag telling whether biometric is currently mandatory and whether face-auth is available as an alternative.'
      operationId: post_api_v1_onboarding_activation_biometric_status
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                service:
                  type: string
                  description: 'Optional rail key (`upi_atm` / `aeps` / `dmt`). Different rails can have slightly different enrolment requirements; defaults to `upi_atm`.'
                  example: dmt
              example:
                service: dmt
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'Biometric capture required.'
                  data: { is_mandatory: true, is_face_auth_available: true, reference_key: bm_2f8ad..., pid_option_wadh: B+xxxxxxxxxxxxxxxx=, aadhaar_masked: XXXX-XXXX-1234 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: 'Remitter mobile number (10 digits)'
                  example: '9876543210'
                beneid:
                  type: number
                  description: 'Beneficiary ID to delete'
                  example: 42.0
              required:
                - mobile
                - beneid
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/ekyc/status:
    post:
      summary: 'eKYC Status Check'
      description: 'Check the current eKYC verification status of a merchant.'
      operationId: post_api_v1_aeps_bank_1_ekyc_status
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: per_page
          in: query
          required: false
          description: 'Results per page (default: 20)'
          schema:
            type: number
          example: 20.0
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/biometric/submit:
    post:
      summary: 'Submit Biometric eKYC'
      description: 'STEP 3 (final) of activation: submit the encrypted PID block produced by your RD service (Mantra, Morpho, Startek, etc.) along with location coordinates. On success the outlet enters `biometric_submitted` and the partner bank typically approves within minutes (rare cases up to a few hours). Poll /status until `state=active`.'
      operationId: post_api_v1_onboarding_activation_biometric_submit
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference_key:
                  type: string
                  description: 'Reference key from /biometric/status.'
                pid_data:
                  type: string
                  description: 'Encrypted PID block JSON from your RD service.'
                biometric_type:
                  type: string
                  description: '`FINGERPRINT` or `FACE`.'
                  example: FINGERPRINT
                latitude:
                  type: number
                  description: 'Decimal latitude of the merchant location.'
                  example: 28.6139
                longitude:
                  type: number
                  description: 'Decimal longitude of the merchant location.'
                  example: 77.209
              required:
                - reference_key
                - pid_data
                - biometric_type
                - latitude
                - longitude
              example:
                reference_key: bm_2f8ad...
                pid_data: '{"pidData": "<encrypted>", "skey": "...", "hmac": "..."}'
                biometric_type: FINGERPRINT
                latitude: 28.6139
                longitude: 77.209
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'Biometric eKYC submitted. Awaiting partner bank approval.'
                  data: { state: biometric_submitted, next_action: biometric_approval }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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 performed once per day before the first debit transaction.'
      operationId: post_api_v1_aeps_two_fa
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                captureResponse:
                  type: object
                  description: 'Biometric capture data from RD service device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - captureResponse
              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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/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 performed once per day before the first debit transaction.'
      operationId: post_api_v1_aeps_bank_1_two_fa
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                captureResponse:
                  type: object
                  description: 'Biometric capture data from RD service device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
                - captureResponse
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  rdsID: MANTRA.AND.001
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                beneaccount:
                  type: string
                  description: 'Beneficiary bank account number (6-20 digits)'
                  example: '1234567890123'
                beneifsc:
                  type: string
                  description: 'IFSC code (11 characters)'
                  example: HDFC0001234
                benename:
                  type: string
                  description: 'Expected beneficiary name (for matching)'
                  example: 'Suresh Sharma'
              required:
                - beneaccount
                - beneifsc
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_id:
                  type: string
                  description: 'Payment ID returned during credit (required if utr not provided)'
                  example: pay_NxT1234567890
                utr:
                  type: string
                  description: 'Bank UTR/Reference number (required if payment_id not provided)'
                  example: HDFC12345ABC
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/daily-kyc:
    post:
      summary: 'Daily KYC Check'
      description: 'CURRENTLY UNAVAILABLE — daily KYC via API is not supported by the underlying processor. The endpoint always responds with HTTP 503 and DAILY_KYC_UNAVAILABLE. Use Two-Factor Authentication (/api/v1/aeps/two-fa) for daily merchant re-authentication. This contract may change once provider support is enabled; the success envelope will then add a `data` block similar to two-fa.'
      operationId: post_api_v1_aeps_bank_1_daily_kyc
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - merchantLoginId
                - merchantPin
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                deviceIMEI: '358240051111110'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error: { code: DAILY_KYC_UNAVAILABLE, message: 'Daily KYC is not yet supported by the underlying processor. Please contact support if processor capabilities change.' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. Works for transactions initiated on any rail.'
      operationId: get_api_v1_dmt_status_txnid
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                txn_reference_id:
                  type: string
                  description: 'BBPS transaction reference ID'
                  example: BBPS202602271430ABCDEF
                disposition:
                  type: string
                  description: 'Complaint reason/disposition'
                  example: 'Amount debited but bill not paid'
                description:
                  type: string
                  description: 'Additional details (max 500 characters)'
                  example: 'Payment was debited but biller shows unpaid.'
              required:
                - txn_reference_id
                - disposition
              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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /onboarding/activation/biometric/refresh:
    post:
      summary: 'Refresh Biometric Status'
      description: "Force-refresh the per-rail product activation flags from the Bank 2 partner. Useful when a merchant's biometric was just approved by the bank and they need an immediate UI update without waiting for the 30-minute poll job. Rate-limited."
      operationId: post_api_v1_onboarding_activation_biometric_refresh
      tags:
        - onboarding-activation
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'Status refreshed.'
                  data: { state: active, products: { upi_atm: active, aeps: active, dmt: active } }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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.0
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. Internally normalises to transactionType=CW. Requires 2FA. Amount range: ₹100 - ₹10,000."
      operationId: post_api_v1_aeps_cash_withdrawal
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                  example: 1000.0
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
                - transactionAmount
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 1000
                mobileNumber: '9876543210'
                latitude: 26.9124
                longitude: 75.7873
                remarks: 'CW for daily cash'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
                transaction_id: EXTPARTNER-CW-20260421-001
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/cash-withdrawal:
    post:
      summary: 'Cash Withdrawal'
      description: "Process Aadhaar-based cash withdrawal from customer's bank account via biometric authentication. Internally normalises to transactionType=CW. Requires 2FA. Amount range: ₹100 - ₹10,000."
      operationId: post_api_v1_aeps_bank_1_cash_withdrawal
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                  example: 1000.0
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
                - transactionAmount
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 1000
                mobileNumber: '9876543210'
                latitude: 26.9124
                longitude: 75.7873
                remarks: 'CW for daily cash'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
                transaction_id: EXTPARTNER-CW-20260421-001
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/balance-enquiry:
    post:
      summary: 'Balance Enquiry'
      description: "Check customer's bank account balance using Aadhaar-based biometric authentication. Internally normalises to transactionType=BE. Returns the available balance in the customer's bank account. No 2FA required, but service charge is debited."
      operationId: post_api_v1_aeps_balance_enquiry
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/balance-enquiry:
    post:
      summary: 'Balance Enquiry'
      description: "Check customer's bank account balance using Aadhaar-based biometric authentication. Internally normalises to transactionType=BE. Returns the available balance in the customer's bank account. No 2FA required, but service charge is debited."
      operationId: post_api_v1_aeps_bank_1_balance_enquiry
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/banks:
    get:
      summary: 'List BBPS Bank Slots'
      description: 'Introspection. Returns the bank slots (bank-1, bank-2, bank-3, bank-4) available for BBPS, the addon operations each bank supports, and the bank slot currently serving traffic for the caller. Use the `supports` array on each bank to decide whether to call an addon endpoint.'
      operationId: get_api_v1_bbps_banks
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ slot: bank-1, display_name: 'Bank 1', supports: {  } }, { slot: bank-2, display_name: 'Bank 2', supports: [validate_bill, fetch_plans, track_complaint, enquire_deposit] }, { slot: bank-3, display_name: 'Bank 3', supports: [validate_bill, fetch_plans, list_regions, billers_by_region] }, { slot: bank-4, display_name: 'Bank 4', supports: [fetch_plans] }]
                  current_bank: bank-2
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/mini-statement:
    post:
      summary: 'Mini Statement'
      description: "Fetch recent bank account mini statement using Aadhaar-based biometric authentication. Internally normalises to transactionType=MS. Returns last few transactions from the customer's bank account. No 2FA required, but service charge is debited."
      operationId: post_api_v1_aeps_mini_statement
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/mini-statement:
    post:
      summary: 'Mini Statement'
      description: "Fetch recent bank account mini statement using Aadhaar-based biometric authentication. Internally normalises to transactionType=MS. Returns last few transactions from the customer's bank account. No 2FA required, but service charge is debited."
      operationId: post_api_v1_aeps_bank_1_mini_statement
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                mobileNumber: '9876543210'
                captureResponse:
                  errCode: '0'
                  fCount: '1'
                  fType: '2'
                  dpID: MANTRA.MSIPL
                  mi: MFS100
                  sessionKey: dGVz...
                  hmac: Ymlu...
                  PidDatatype: X
                  Pid: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/addons/validate:
    post:
      summary: 'Validate Bill'
      description: '**Applicable for: Bank 2, Bank 3 (optional).** Pre-payment bill validation. Confirms biller-side acceptance of the customer parameters before deducting wallet funds. If the active bank does not support this operation a `501 NOT_APPLICABLE_FOR_THIS_BANK` envelope is returned with `applicable_banks` listing the banks that DO support it.'
      operationId: post_api_v1_bbps_addons_validate
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_id:
                  type: string
                  description: 'BBPS biller id'
                  example: MAHA00000NAT01
                customer_params:
                  type: object
                  description: 'Key/value map per biller schema'
                amount:
                  type: number
                  description: 'Optional bill amount for validation'
              required:
                - biller_id
                - customer_params
              example:
                biller_id: MAHA00000NAT01
                customer_params:
                  'Consumer Number': '123456789'
                amount: 1250
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { valid: true, message: 'Customer parameters validated by the biller.' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. Internally normalises to transactionType=CD. Requires 2FA. Amount range: ₹100 - ₹10,000."
      operationId: post_api_v1_aeps_cash_deposit
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                  example: 5000.0
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
                - transactionAmount
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/cash-deposit:
    post:
      summary: 'Cash Deposit'
      description: "Deposit cash into customer's bank account using Aadhaar-based biometric authentication. Internally normalises to transactionType=CD. Requires 2FA. Amount range: ₹100 - ₹10,000."
      operationId: post_api_v1_aeps_bank_1_cash_deposit
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                  example: 5000.0
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
                - transactionAmount
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/addons/plans:
    get:
      summary: 'Fetch Plans'
      description: '**Applicable for: Bank 2, Bank 3, Bank 4 (optional).** Fetch plan / tariff catalogue for prepaid-style billers (DTH, broadband, gas-cylinder etc.) supported by the active bank. If the active bank does not support this operation a `501 NOT_APPLICABLE_FOR_THIS_BANK` envelope is returned.'
      operationId: get_api_v1_bbps_addons_plans
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: biller_id
          in: query
          required: true
          description: 'BBPS biller id'
          schema:
            type: string
          example: AIRT00000NAT01
        -
          name: circle
          in: query
          required: false
          description: 'Telecom / utility circle code'
          schema:
            type: string
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ plan_id: P-149, amount: 149, description: '1.5GB/day, 28 days', validity: '28 days' }]
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/aadhaar-pay:
    post:
      summary: 'Aadhaar Pay'
      description: 'Process Aadhaar-based merchant payment (AadhaarPay/MATM). Internally normalises to transactionType=M. Customer pays merchant via biometric authentication. Requires 2FA. Amount range: ₹100 - ₹10,000.'
      operationId: post_api_v1_aeps_aadhaar_pay
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                  example: 1000.0
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
                - transactionAmount
              example:
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/aadhaar-pay:
    post:
      summary: 'Aadhaar Pay'
      description: 'Process Aadhaar-based merchant payment (AadhaarPay/MATM). Internally normalises to transactionType=M. Customer pays merchant via biometric authentication. Requires 2FA. Amount range: ₹100 - ₹10,000.'
      operationId: post_api_v1_aeps_bank_1_aadhaar_pay
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                adhaarNumber:
                  type: string
                  description: 'Customer 12-digit Aadhaar number (note the historical spelling — `aadhaarNumber` is also accepted as an alias)'
                  example: '234567890123'
                indicatorforUID:
                  type: string
                  description: 'UID indicator: 0 = Aadhaar number, 2 = Virtual ID'
                  example: '0'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN/NBIN code (alias: `iin`)'
                  example: '607094'
                virtualId:
                  type: string
                  description: 'Virtual ID (alias: `vpa`); send when indicatorforUID = 2'
                  example: '1234567890123456'
                mobileNumber:
                  type: string
                  description: 'Customer 10-digit mobile'
                  example: '9876543210'
                captureResponse:
                  type: object
                  description: 'Biometric fingerprint capture data from RD device. Must contain a payload key (Pid / pidData / xml / etc.) AND a timestamp key (ts / timestamp / captureTime).'
                latitude:
                  type: number
                  description: 'GPS latitude (-90 to 90)'
                  example: 26.9124
                longitude:
                  type: number
                  description: 'GPS longitude (-180 to 180)'
                  example: 75.7873
                remarks:
                  type: string
                  description: 'Free-text remarks (max 200 chars). Alias: `note`.'
                  example: 'CW for daily cash'
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
                transaction_id:
                  type: string
                  description: 'Caller-supplied unique transaction ID for idempotency (max 50, must be unique across aepsreports). Server generates one if omitted.'
                  example: EXTPARTNER-CW-20260421-001
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                  example: 1000.0
              required:
                - merchantLoginId
                - merchantPin
                - adhaarNumber
                - indicatorforUID
                - nationalBankIdentificationNumber
                - captureResponse
                - transactionAmount
              example:
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                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: BASE64_ENCODED_PID_DATA
                  ts: '2026-04-21T12:00:00.000Z'
                deviceIMEI: '358240051111110'
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/addons/regions:
    get:
      summary: 'List Regions'
      description: '**Applicable for: Bank 3 (optional).** Fetch the list of coverage regions / state-circles supported by the active bank. Use the returned region codes with `/api/v1/bbps/addons/billers/by-region`.'
      operationId: get_api_v1_bbps_addons_regions
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ region_code: MH, region_name: Maharashtra }, { region_code: KA, region_name: Karnataka }]
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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. For non-final statuses (pending), the upstream provider is queried in-line and the local record is updated.'
      operationId: post_api_v1_aeps_status
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: 'Transaction ID to look up (alias: `txnId`, `transactionId`)'
                  example: AEPS-CW-20260227143022-1234
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: FING123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINFING123456
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - transaction_id
                - merchantLoginId
                - merchantPin
              example:
                transaction_id: AEPS-CW-20260227143022-1234
                merchantLoginId: FING123456789
                merchantPin: PINFING123456
                deviceIMEI: '358240051111110'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction status fetched successfully'
                  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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/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. For non-final statuses (pending), the upstream provider is queried in-line and the local record is updated.'
      operationId: post_api_v1_aeps_bank_1_status
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: 'Transaction ID to look up (alias: `txnId`, `transactionId`)'
                  example: AEPS-CW-20260227143022-1234
                merchantLoginId:
                  type: string
                  description: 'Merchant login ID'
                  example: BANK1123456789
                merchantPin:
                  type: string
                  description: 'Merchant login PIN'
                  example: PINBANK1123456
                deviceIMEI:
                  type: string
                  description: 'Capture device IMEI / serial (max 50)'
                  example: '358240051111110'
              required:
                - transaction_id
                - merchantLoginId
                - merchantPin
              example:
                transaction_id: AEPS-CW-20260227143022-1234
                merchantLoginId: BANK1123456789
                merchantPin: PINBANK1123456
                deviceIMEI: '358240051111110'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction status fetched successfully'
                  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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/addons/billers/by-region:
    get:
      summary: 'Billers By Region'
      description: '**Applicable for: Bank 3 (optional).** Fetch the billers that operate in a specific coverage region. Useful for state-utility billers where the canonical `/api/v1/bbps/billers` filter is not granular enough.'
      operationId: get_api_v1_bbps_addons_billers_by_region
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: region
          in: query
          required: true
          description: 'Region code from /addons/regions'
          schema:
            type: string
          example: MH
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: [{ biller_id: MAHA00000NAT01, biller_name: 'Maharashtra Electricity', category: Electricity }]
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/addons/complaint/track:
    post:
      summary: 'Track Complaint'
      description: '**Applicable for: Bank 2 (optional).** Detailed complaint tracking that returns the full assignment / disposition history for a complaint. The canonical `/api/v1/bbps/complaints/{id}/status` returns the current snapshot; this addon returns the full audit trail when the active bank supports it.'
      operationId: post_api_v1_bbps_addons_complaint_track
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                complaint_id:
                  type: string
                  description: 'Complaint id'
                  example: CMPL-001
              required:
                - complaint_id
              example:
                complaint_id: CMPL-001
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { complaint_id: CMPL-001, history: [{ at: '2026-02-27T15:00:00+05:30', status: RAISED, remarks: Created }, { at: '2026-02-27T16:30:00+05:30', status: ASSIGNED, remarks: 'Assigned to OU-Level-1' }] }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /bbps/addons/deposit/enquire:
    post:
      summary: 'Enquire Deposit'
      description: '**Applicable for: Bank 2 (optional).** Postpaid deposit enquiry — used to confirm a pending bill payment was received and credited at the biller. If the active bank does not support this operation a `501 NOT_APPLICABLE_FOR_THIS_BANK` envelope is returned.'
      operationId: post_api_v1_bbps_addons_deposit_enquire
      tags:
        - bbps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_id:
                  type: string
                  description: 'BBPS biller id'
                  example: MAHA00000NAT01
                customer_params:
                  type: object
                  description: 'Key/value map per biller schema'
              required:
                - biller_id
                - customer_params
              example:
                biller_id: MAHA00000NAT01
                customer_params:
                  'Consumer Number': '123456789'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { credited: true, message: 'Last payment confirmed at biller.' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/remitter/kyc:
    post:
      summary: 'Remitter biometric / face KYC'
      description: 'Submit biometric / face KYC payload for a remitter. NOTE: This endpoint is supported only on rails that offer biometric KYC (currently the Bank 2 rail). When the active rail does not support it, the response carries `statuscode=NOT_SUPPORTED`. Pin to the Bank 2 base path (/api/v1/dmt/bank-2/remitter/kyc) if you specifically need the Bank 2 flow.'
      operationId: post_api_v1_dmt_remitter_kyc
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: 'Remitter 10-digit mobile number'
                  example: '9876543210'
                pidData:
                  type: string
                  description: 'Encoded PID / biometric payload. Format depends on the active rail (Bank 2 PID block on bank-2).'
                biometricType:
                  type: string
                  description: 'FINGERPRINT or FACE. Only honoured on rails that support biometric KYC.'
              required:
                - mobile
              example:
                mobile: '9876543210'
                biometricType: FINGERPRINT
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: 'KYC accepted'
                  data: { kycStatus: VERIFIED }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/remitter/limit:
    get:
      summary: 'Remitter limit lookup'
      description: 'Returns the remaining monthly / per-txn DMT limits for a remitter mobile. Backend routes to the active rail; response shape is identical across rails.'
      operationId: get_api_v1_dmt_remitter_limit
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter mobile (10 digits)'
          schema:
            type: string
          example: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  statuscode: TXN
                  status: success
                  message: OK
                  data: { monthlyLimitAvailable: '18000.00' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        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:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      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'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/beneficiaries:
    get:
      summary: 'List Beneficiaries'
      description: 'List beneficiaries registered for a given remitter mobile. Pass `mobile` as a query string parameter. Active rail is selected by admin in /admin/api-manager.'
      operationId: get_api_v1_dmt_beneficiaries
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: mobile
          in: query
          required: true
          description: 'Remitter mobile (10 digits)'
          schema:
            type: string
          example: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { beneficiaries: [{ id: 42, benename: 'Suresh Sharma', beneaccount: '1234567890123', beneifsc: HDFC0001234, benemobile: '9988776655', verified: true }] }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/beneficiaries/add:
    post:
      summary: 'Add Beneficiary'
      description: 'Register a new beneficiary for a remitter (two-step OTP flow). STEP 1: submit beneficiary detail without `otp`. STEP 2: re-submit with `otp` + `reference_key` to confirm.'
      operationId: post_api_v1_dmt_beneficiaries_add
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: 'Remitter mobile (10 digits)'
                  example: '9876543210'
                benename:
                  type: string
                  description: 'Beneficiary name'
                  example: 'Suresh Sharma'
                beneaccount:
                  type: string
                  description: 'Beneficiary account number'
                  example: '1234567890123'
                beneifsc:
                  type: string
                  description: 'IFSC code (11 chars)'
                  example: HDFC0001234
                benemobile:
                  type: string
                  description: 'Beneficiary mobile (10 digits)'
                  example: '9988776655'
                bank_id:
                  type: string
                  description: 'Bank ID from /api/v1/dmt/banks. Required only on rails that demand a numeric bank id (e.g. bank-2). Safe to omit on bank-1.'
                otp:
                  type: string
                  description: '6-digit OTP (Step 2 only)'
                reference_key:
                  type: string
                  description: 'Reference key from Step 1'
              required:
                - mobile
                - benename
                - beneaccount
                - beneifsc
              example:
                mobile: '9876543210'
                benename: 'Suresh Sharma'
                beneaccount: '1234567890123'
                beneifsc: HDFC0001234
                benemobile: '9988776655'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'OTP sent for beneficiary verification'
                  data: { reference_key: BENE-REF-1730xxxx, validity: '2026-04-28 11:00:00' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /dmt/transfer:
    post:
      summary: 'DMT Transfer'
      description: 'Initiate a money transfer (two-step OTP flow). STEP 1: submit txn detail without `otp`; provider issues OTP + `reference_key`. STEP 2: re-submit with `otp` + `reference_key` to settle. Modes supported: IMPS, NEFT, RTGS. Active rail is selected automatically; per-txn limits depend on the active rail (bank-2 supports higher caps).'
      operationId: post_api_v1_dmt_transfer
      tags:
        - dmt
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobile:
                  type: string
                  description: 'Remitter mobile (10 digits)'
                  example: '9876543210'
                beneaccount:
                  type: string
                  description: 'Beneficiary account'
                  example: '1234567890123'
                beneifsc:
                  type: string
                  description: 'IFSC code (11 chars)'
                  example: HDFC0001234
                amount:
                  type: number
                  description: 'Amount in INR'
                  example: 1000.0
                mode:
                  type: string
                  description: 'Transfer mode (IMPS/NEFT/RTGS)'
                  example: IMPS
                otp:
                  type: string
                  description: 'OTP from Step 1 (Step 2 only)'
                reference_key:
                  type: string
                  description: 'Reference key from Step 1'
              required:
                - mobile
                - beneaccount
                - beneifsc
                - amount
                - mode
              example:
                mobile: '9876543210'
                beneaccount: '1234567890123'
                beneifsc: HDFC0001234
                amount: 1000
                mode: IMPS
                otp: '483921'
                reference_key: TXN-REF-1730xxxx
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction Successful'
                  data: { txn_id: DMT2026042811001, utr: '431013704887', amount: '1000.00', mode: IMPS, beneficiary_name: 'SURESH SHARMA' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/accounts:
    get:
      summary: cb_list_accounts
      description: 'Returns all IDFC connected bank accounts linked to the authenticated API caller. Includes account UUID, bank slug, masked debit account number, current status, billing mode, and last-verified timestamp. Accounts in any lifecycle state are returned; filter on `status` client-side.'
      operationId: get_api_v1_connected_banking_idfc_accounts
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { accounts: [{ uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890, bank_slug: idfc, nickname: 'Primary Collection Account', debit_account_masked: '****4321', status: active, billing_mode: wallet_charge, is_default: true, last_verified_at: '2026-05-01T10:00:00+05:30', created_at: '2026-04-01T08:00:00+05:30' }] }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/verify-account:
    post:
      summary: cb_verify_account
      description: 'Runs a penny-drop verification against IDFC to confirm the connected account is live and the credentials are correct. Call this after onboarding a new account or after a credential rotation. Returns the fetched account balance on success to confirm connectivity.'
      operationId: post_api_v1_connected_banking_idfc_verify_account
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connected_account_uuid:
                  type: string
                  description: 'UUID of the connected bank account to verify'
                  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              required:
                - connected_account_uuid
              example:
                connected_account_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { verified: true, balance: 142500, currency: INR, verified_at: '2026-05-01T10:00:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/balance:
    get:
      summary: cb_get_balance
      description: "Fetches the current available balance for a connected IDFC bank account. Results are cached for up to 60 seconds (configurable) to avoid hammering the bank API. Pass `?connected_account_uuid=` to target a specific account; omit to use the caller's default account."
      operationId: get_api_v1_connected_banking_idfc_balance
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: connected_account_uuid
          in: query
          required: false
          description: 'UUID of the connected account. Omit to use the default account.'
          schema:
            type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { balance: 142500, currency: INR, account_number: '****4321', fetched_at: '2026-05-01T10:00:00+05:30', cached: false }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/daily-login/status:
    get:
      summary: 'Daily Login Status'
      description: "Check whether today's biometric daily-login is completed for Bank 2 rail. One-time Bank 2 activation must be completed first via /api/v1/onboarding/activation/*."
      operationId: get_api_v1_aeps_bank_2_daily_login_status
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  provider: bank_2
                  logged_in: false
                  action_required: true
                  message: 'Daily biometric login required before AEPS transactions.'
                  outlet: { outlet_id: BANK2-OUT-1001, reference_key: REF-KEY-123 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/daily-login:
    post:
      summary: 'Daily Login Submit'
      description: 'Submit biometric payload to complete daily login for Bank 2 rail. Requires one-time Bank 2 activation to be in active state.'
      operationId: post_api_v1_aeps_bank_2_daily_login
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                captureResponse:
                  type: object
                  description: 'RD service biometric capture payload'
                latitude:
                  type: number
                  description: Latitude
                longitude:
                  type: number
                  description: Longitude
              required:
                - captureResponse
              example:
                captureResponse:
                  pidData: BASE64_PID_DATA
                  sessionKey: BASE64_SESSION_KEY
                  hmac: BASE64_HMAC
                  ts: '2026-04-28T10:30:00.000Z'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Daily login successful. You can now perform AEPS transactions.'
                  data: { actcode: LOGGEDIN, next_action: /api/v1/aeps/bank-2/cash-withdrawal }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/cash-withdrawal:
    post:
      summary: 'Cash Withdrawal'
      description: 'Aadhaar-based cash withdrawal on Bank 2 rail. If one-time activation is incomplete, returns ACTIVATION_REQUIRED (HTTP 409).'
      operationId: post_api_v1_aeps_bank_2_cash_withdrawal
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: 'Set CW'
                adhaarNumber:
                  type: string
                  description: 'Customer Aadhaar number'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN code'
                transactionAmount:
                  type: number
                  description: 'Amount in INR (100-10000)'
                captureResponse:
                  type: object
                  description: 'Biometric capture payload'
              required:
                - transactionType
                - adhaarNumber
                - nationalBankIdentificationNumber
                - transactionAmount
                - captureResponse
              example:
                transactionType: CW
                merchantLoginId: BANK2-OUT-1001
                merchantPin: '******'
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                transactionAmount: 1000
                captureResponse:
                  pidData: BASE64_PID_DATA
                  ts: '2026-04-28T10:30:00.000Z'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transactionStatusCode: '00', rrn: '202604281234', provider_name: bank_2 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/balance-enquiry:
    post:
      summary: 'Balance Enquiry'
      description: 'Balance Enquiry transaction on Bank 2 rail.'
      operationId: post_api_v1_aeps_bank_2_balance_enquiry
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: 'Set BE'
                adhaarNumber:
                  type: string
                  description: 'Customer Aadhaar number'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN code'
                captureResponse:
                  type: object
                  description: 'Biometric capture payload'
              required:
                - transactionType
                - adhaarNumber
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                transactionType: BE
                merchantLoginId: BANK2-OUT-1001
                merchantPin: '******'
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                captureResponse:
                  pidData: BASE64_PID_DATA
                  ts: '2026-04-28T10:30:00.000Z'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transactionStatusCode: '00', provider_name: bank_2 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/mini-statement:
    post:
      summary: 'Mini Statement'
      description: 'Mini Statement transaction on Bank 2 rail.'
      operationId: post_api_v1_aeps_bank_2_mini_statement
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: 'Set MS'
                adhaarNumber:
                  type: string
                  description: 'Customer Aadhaar number'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN code'
                captureResponse:
                  type: object
                  description: 'Biometric capture payload'
              required:
                - transactionType
                - adhaarNumber
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                transactionType: MS
                merchantLoginId: BANK2-OUT-1001
                merchantPin: '******'
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                captureResponse:
                  pidData: BASE64_PID_DATA
                  ts: '2026-04-28T10:30:00.000Z'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transactionStatusCode: '00', provider_name: bank_2 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/cash-deposit:
    post:
      summary: 'Cash Deposit'
      description: 'Cash Deposit transaction on Bank 2 rail.'
      operationId: post_api_v1_aeps_bank_2_cash_deposit
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: 'Set CD'
                adhaarNumber:
                  type: string
                  description: 'Customer Aadhaar number'
                nationalBankIdentificationNumber:
                  type: string
                  description: 'Bank IIN code'
                captureResponse:
                  type: object
                  description: 'Biometric capture payload'
              required:
                - transactionType
                - adhaarNumber
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                transactionType: CD
                merchantLoginId: BANK2-OUT-1001
                merchantPin: '******'
                adhaarNumber: '234567890123'
                indicatorforUID: '0'
                nationalBankIdentificationNumber: '607094'
                captureResponse:
                  pidData: BASE64_PID_DATA
                  ts: '2026-04-28T10:30:00.000Z'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Transaction successful'
                  data: { transactionStatusCode: '00', provider_name: bank_2 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/status:
    post:
      summary: 'AEPS Transaction Status'
      description: 'Check transaction status on Bank 2 rail by merchant transaction id.'
      operationId: post_api_v1_aeps_bank_2_status
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_id:
                  type: string
                  description: 'Merchant transaction id'
                merchantLoginId:
                  type: string
                  description: 'Outlet identifier'
                merchantPin:
                  type: string
                  description: 'Outlet PIN placeholder'
              required:
                - transaction_id
                - merchantLoginId
                - merchantPin
              example:
                transaction_id: AEPS-CW-202604281234
                merchantLoginId: BANK2-OUT-1001
                merchantPin: '******'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  message: 'Status fetched'
                  data: { transactionStatusCode: '00', rrn: '202604281234', provider_name: bank_2 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/statement:
    post:
      summary: cb_get_statement
      description: 'Fetches a paginated bank statement from IDFC for the specified date range. Maximum window: 90 days. Returns debit and credit transactions with amounts, UTR numbers, and narrations. Useful for reconciliation and audit workflows.'
      operationId: post_api_v1_connected_banking_idfc_statement
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connected_account_uuid:
                  type: string
                  description: 'UUID of the connected bank account'
                from_date:
                  type: string
                  description: 'Start date (YYYY-MM-DD)'
                  example: '2026-04-01'
                to_date:
                  type: string
                  description: 'End date (YYYY-MM-DD)'
                  example: '2026-04-30'
                page:
                  type: integer
                  description: 'Page number (default: 1)'
              required:
                - connected_account_uuid
                - from_date
                - to_date
              example:
                connected_account_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                from_date: '2026-04-01'
                to_date: '2026-04-30'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { transactions: [{ date: '2026-04-15', type: debit, amount: 5000, utr: '426045678901234', narration: 'NEFT/CB-TXN-001/John Doe', balance: 142500 }], from_date: '2026-04-01', to_date: '2026-04-30', total: 1 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/activate:
    post:
      summary: 'AEPS Activate'
      description: 'Rail-agnostic merchant activation / onboarding entrypoint for AePS.'
      operationId: post_api_v1_aeps_activate
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: ''
                merchantPhoneNumber:
                  type: string
                  description: ''
              required:
                - name
                - merchantPhoneNumber
              example:
                name: 'Ramesh Kumar'
                merchantPhoneNumber: '9876543210'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { state: pending, next_action: ekyc_or_otp }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/verify-beneficiary:
    post:
      summary: cb_verify_beneficiary
      description: 'Verifies a beneficiary bank account via IMPS penny-drop before initiating a payout. Returns the account holder name fetched from the bank, allowing you to confirm the account details match your records before committing funds.'
      operationId: post_api_v1_connected_banking_idfc_verify_beneficiary
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connected_account_uuid:
                  type: string
                  description: 'Source connected account UUID (debited for the penny-drop)'
                account_number:
                  type: string
                  description: 'Beneficiary bank account number'
                  example: '1234567890'
                ifsc_code:
                  type: string
                  description: 'Beneficiary IFSC code'
                  example: SBIN0001234
                beneficiary_name:
                  type: string
                  description: 'Expected beneficiary name (used for fuzzy match)'
              required:
                - connected_account_uuid
                - account_number
                - ifsc_code
              example:
                connected_account_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                account_number: '1234567890'
                ifsc_code: SBIN0001234
                beneficiary_name: 'John Doe'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { verified: true, account_name: 'JOHN DOE', account_number: '1234567890', ifsc_code: SBIN0001234, bank_name: 'State Bank of India' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/daily-session:
    post:
      summary: 'AEPS Daily Session'
      description: 'Complete daily biometric 2FA session for the active AePS rail (Asia/Kolkata day).'
      operationId: post_api_v1_aeps_daily_session
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                auth_mode:
                  type: string
                  description: ''
                captureResponse:
                  type: object
                  description: ''
              required:
                - captureResponse
              example:
                auth_mode: FINGER
                captureResponse:
                  PidData: ...
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { status: active, login_date: '2026-07-31' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/capture-directive:
    post:
      summary: 'AEPS Capture Directive'
      description: 'Return RD PidOptions for the active (or pinned) AePS rail and operation/auth_mode.'
      operationId: post_api_v1_aeps_capture_directive
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operation:
                  type: string
                  description: CW|BE|MS|CD|M|two_fa|ekyc|face_auth|…
                auth_mode:
                  type: string
                  description: 'FINGER or FACE'
              required:
                - operation
              example:
                operation: CW
                auth_mode: FINGER
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { auth_mode: FINGER, pid_options_xml: '<PidOptions>...</PidOptions>' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/transaction-otp:
    post:
      summary: 'AEPS Transaction OTP'
      description: 'Send / initiate OTP for high-value AePS transactions when the rail requires it.'
      operationId: post_api_v1_aeps_transaction_otp
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mobileNumber:
                  type: string
                  description: ''
                transactionAmount:
                  type: number
                  description: ''
                transactionType:
                  type: string
                  description: ''
              required:
                - mobileNumber
                - transactionAmount
              example:
                mobileNumber: '9876543210'
                transactionAmount: 6000
                transactionType: CW
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { otp_ref: OTP123, expires_in: 120 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/transaction:
    post:
      summary: 'AEPS Unified Transaction'
      description: 'Unified LIVE AePS transaction (CW|BE|MS|CD|M). Routed to active rail; OTP may be required above ₹5,000.'
      operationId: post_api_v1_aeps_transaction
      tags:
        - aeps
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: ''
                transactionAmount:
                  type: number
                  description: ''
                adhaarNumber:
                  type: string
                  description: ''
                nationalBankIdentificationNumber:
                  type: string
                  description: ''
                captureResponse:
                  type: object
                  description: ''
                otp_reference:
                  type: string
                  description: ''
              required:
                - transactionType
                - adhaarNumber
                - nationalBankIdentificationNumber
                - captureResponse
              example:
                transactionType: CW
                transactionAmount: 1000
                adhaarNumber: XXXXXXXX1234
                nationalBankIdentificationNumber: '607152'
                captureResponse:
                  PidData: ...
                latitude: '28.6139'
                longitude: '77.2090'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { transaction_id: AEPS-CW-…, status: success, rrn: '602312345678' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/capture-directive:
    post:
      summary: 'AEPS Bank Rail 1 Capture Directive'
      description: 'PidOptions pinned to Bank Rail 1 (LIVE env=P).'
      operationId: post_api_v1_aeps_bank_1_capture_directive
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operation:
                  type: string
                  description: ''
                auth_mode:
                  type: string
                  description: ''
              required:
                - operation
              example:
                operation: CW
                auth_mode: FINGER
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { rail_key: bank-1, auth_mode: FINGER, pid_options_xml: '<PidOptions env="P">…</PidOptions>' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-1/transaction:
    post:
      summary: 'AEPS Bank Rail 1 Transaction'
      description: 'Unified transaction forced onto Bank Rail 1. Bank 2 does not support Aadhaar Pay (M).'
      operationId: post_api_v1_aeps_bank_1_transaction
      tags:
        - aeps/bank-1
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: ''
                captureResponse:
                  type: object
                  description: ''
              required:
                - transactionType
                - captureResponse
              example:
                transactionType: CW
                transactionAmount: 1000
                captureResponse:
                  PidData: ...
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { status: success, rail_key: bank-1 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/capture-directive:
    post:
      summary: 'AEPS Bank Rail 2 Capture Directive'
      description: 'PidOptions pinned to Bank Rail 2 (LIVE env=P).'
      operationId: post_api_v1_aeps_bank_2_capture_directive
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operation:
                  type: string
                  description: ''
                auth_mode:
                  type: string
                  description: ''
              required:
                - operation
              example:
                operation: CW
                auth_mode: FINGER
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { rail_key: bank-2, auth_mode: FINGER, pid_options_xml: '<PidOptions env="P">…</PidOptions>' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /aeps/bank-2/transaction:
    post:
      summary: 'AEPS Bank Rail 2 Transaction'
      description: 'Unified transaction forced onto Bank Rail 2. Bank 2 does not support Aadhaar Pay (M).'
      operationId: post_api_v1_aeps_bank_2_transaction
      tags:
        - aeps/bank-2
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionType:
                  type: string
                  description: ''
                captureResponse:
                  type: object
                  description: ''
              required:
                - transactionType
                - captureResponse
              example:
                transactionType: CW
                transactionAmount: 1000
                captureResponse:
                  PidData: ...
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { status: success, rail_key: bank-2 }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/payout/initiate:
    post:
      summary: cb_initiate_payout
      description: 'Initiates a fund transfer from a connected IDFC bank account to any beneficiary account. Supports IMPS, NEFT, and RTGS modes. Supply a unique `transaction_id` per transfer — the endpoint is idempotent within the 7-day window so safe retries are possible. Billing modes: `wallet_charge` (fee from main wallet), `source_sweep` (fee swept from IDFC), `fee_wallet` (fee from CB wallet).'
      operationId: post_api_v1_connected_banking_idfc_payout_initiate
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                connected_account_uuid:
                  type: string
                  description: 'Source connected account UUID'
                transaction_id:
                  type: string
                  description: 'Your unique transaction ID (idempotency key, max 40 chars)'
                  example: TXN-2026-001
                amount:
                  type: number
                  description: 'Transfer amount in INR (0.01 – 2,000,000)'
                  example: 10000.0
                mode:
                  type: string
                  description: 'Transfer mode: IMPS, NEFT, or RTGS'
                  example: IMPS
                beneficiary_account:
                  type: string
                  description: 'Beneficiary bank account number'
                beneficiary_ifsc:
                  type: string
                  description: 'Beneficiary IFSC code'
                beneficiary_name:
                  type: string
                  description: 'Beneficiary account holder name'
                remarks:
                  type: string
                  description: 'Payment narration (max 200 chars)'
                beneficiary_mobile:
                  type: string
                  description: '10-digit mobile number for SMS notification'
                beneficiary_email:
                  type: string
                  description: 'Email for payment advice'
              required:
                - connected_account_uuid
                - transaction_id
                - amount
                - mode
                - beneficiary_account
                - beneficiary_ifsc
                - beneficiary_name
              example:
                connected_account_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                transaction_id: TXN-2026-001
                amount: 10000
                mode: IMPS
                beneficiary_account: '1234567890'
                beneficiary_ifsc: SBIN0001234
                beneficiary_name: 'John Doe'
                remarks: 'Invoice #INV-001 settlement'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { transaction_id: TXN-2026-001, reference_id: CB20260501IMPS001, status: pending, amount: 10000, charge: 5, gst: 0.9, utr_number: null, billing_mode: wallet_charge, report_id: 98765, initiated_at: '2026-05-01T10:00:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  '/connected-banking/idfc/payout/status/{txn_id}':
    get:
      summary: cb_payout_status
      description: 'Retrieves the current status of a Connected Banking payout by its `transaction_id`. Append `?refresh=true` to trigger a live IDFC status poll when the payout is still pending — the DB row is updated and the fresh status returned. Omitting `refresh` returns the cached DB state.'
      operationId: get_api_v1_connected_banking_idfc_payout_status_txn_id
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: txn_id
          in: path
          required: true
          description: 'Txn id'
          schema:
            type: string
        -
          name: txn_id
          in: query
          required: true
          description: 'Your original transaction_id (path parameter, max 40 chars)'
          schema:
            type: string
          example: TXN-2026-001
        -
          name: refresh
          in: query
          required: false
          description: 'Set to true to poll IDFC for a fresh status (only when status=pending)'
          schema:
            type: string
          example: 'true'
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { transaction_id: TXN-2026-001, reference_id: CB20260501IMPS001, status: success, amount: 10000, charge: 5, gst: 0.9, utr_number: '426045678901234', beneficiary_name: 'John Doe', beneficiary_account: '****7890', beneficiary_ifsc: SBIN0001234, mode: IMPS, billing_mode: wallet_charge, initiated_at: '2026-05-01T10:00:00+05:30', last_status_check: '2026-05-01T10:05:00+05:30', live_data: null }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/payout/history:
    get:
      summary: cb_payout_history
      description: 'Returns a paginated ledger of all Connected Banking payouts for the authenticated caller. Supports date-range filtering (max 90 days per call), status filtering, and per-account scoping. Use the `pagination` block in the response to iterate pages. Default window: last 30 days. Default page size: 20.'
      operationId: get_api_v1_connected_banking_idfc_payout_history
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: connected_account_uuid
          in: query
          required: false
          description: 'Filter to a specific connected account'
          schema:
            type: string
        -
          name: from_date
          in: query
          required: false
          description: 'Start date (YYYY-MM-DD). Default: 30 days ago'
          schema:
            type: string
        -
          name: to_date
          in: query
          required: false
          description: 'End date (YYYY-MM-DD). Default: today'
          schema:
            type: string
        -
          name: status
          in: query
          required: false
          description: 'Filter by status: success, pending, failed'
          schema:
            type: string
        -
          name: per_page
          in: query
          required: false
          description: 'Page size (1–100, default: 20)'
          schema:
            type: integer
        -
          name: page
          in: query
          required: false
          description: 'Page number (default: 1)'
          schema:
            type: integer
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { items: [{ report_id: 98765, transaction_id: TXN-2026-001, reference_id: CB20260501IMPS001, status: success, amount: 10000, charge: 5, gst: 0.9, utr_number: '426045678901234', beneficiary_name: 'John Doe', beneficiary_account: '****7890', beneficiary_ifsc: SBIN0001234, mode: IMPS, billing_mode: wallet_charge, initiated_at: '2026-05-01T10:00:00+05:30' }], pagination: { total: 42, per_page: 20, current_page: 1, last_page: 3, from: 1, to: 20 }, window: { from_date: '2026-04-01', to_date: '2026-04-30' } }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
  /connected-banking/idfc/health:
    get:
      summary: cb_health
      description: 'Returns a health snapshot for the Connected Banking module scoped to the authenticated caller: pending payout count, age of the oldest pending payout, number of active connected accounts, and overall status (`ok` or `degraded`). Optionally pass `?probe=true&connected_account_uuid=` to perform a live IDFC connectivity test.'
      operationId: get_api_v1_connected_banking_idfc_health
      tags:
        - payout/idfc
      security:
        -
          HmacAuth: {  }
          ClientIdAuth: {  }
          TimestampAuth: {  }
          RequestIdAuth: {  }
      parameters:
        -
          name: probe
          in: query
          required: false
          description: 'Set to true to run a live IDFC balance probe'
          schema:
            type: boolean
        -
          name: connected_account_uuid
          in: query
          required: false
          description: 'Required when probe=true'
          schema:
            type: string
      responses:
        200:
          description: 'Successful operation'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: { status: ok, pending_payouts: 0, oldest_pending: null, active_accounts: 2, probe: null, checked_at: '2026-05-01T10:00:00+05:30' }
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        422:
          $ref: '#/components/responses/ValidationError'
        429:
          $ref: '#/components/responses/TooManyRequests'
        501:
          $ref: '#/components/responses/NotImplemented'
        500:
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: X-Signature
      description: 'Lowercase hex HMAC-SHA256 of the canonical string `METHOD|PATH|TIMESTAMP|BODY`, keyed with the secret issued for your X-Client-ID. PATH excludes the query string. BODY is the raw request body with line endings normalised to \n (empty string for GET).'
    ClientIdAuth:
      type: apiKey
      in: header
      name: X-Client-ID
      description: 'Tenant client identifier (issued via the dashboard). Required alongside X-Signature, X-Timestamp, X-Request-ID.'
    TimestampAuth:
      type: apiKey
      in: header
      name: X-Timestamp
      description: 'Unix epoch seconds (UTC). Requests outside the ±300s window are rejected with AUTH_TIMESTAMP_INVALID.'
    RequestIdAuth:
      type: apiKey
      in: header
      name: X-Request-ID
      description: 'Per-request UUID v4 used for replay protection. A reused value within 10 minutes is rejected with HTTP 409.'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Sandbox-only API key (not accepted in production). Use HMAC quartet for prod.'
  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: ERR_UNAUTHENTICATED
            message: 'Invalid or missing API key.'
    ValidationError:
      description: 'Validation Error - Input constraints failed'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: ERR_VALIDATION
            message: 'Validation failed for one or more fields.'
    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.'
    NotImplemented:
      description: 'Feature not implemented by currently active providers'
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code: { type: string, example: FEATURE_NOT_AVAILABLE }
                  message: { type: string, example: 'This operation is currently not available for active providers.' }
                  httpStatus: { type: integer, example: 501 }
              meta:
                type: object
                properties:
                  traceId: { type: string }
                  provider: { type: string }
    UnsupportedApiVersion:
      description: 'Unsupported API version for unified endpoint'
      headers:
        X-API-Supported-Versions:
          description: 'Comma-separated list of supported versions for unified endpoints'
          schema:
            type: string
            example: v1
        X-Trace-ID:
          description: 'Request trace identifier'
          schema:
            type: string
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: object
                properties:
                  code: { type: string, example: ERR_API_VERSION_UNSUPPORTED }
                  message: { type: string, example: 'Unsupported API version. Supported versions: v1.' }
                  trace_id: { type: string }
              meta:
                type: object
                properties:
                  requested_version: { type: string, example: v2 }
                  supported_versions: { type: array, items: { type: string, example: v1 } }
                  default_version: { type: string, example: v1 }
