{ "openapi": "3.0.0", "info": { "title": "NXT Banking API", "version": "1.0.0", "description": "Comprehensive Fintech API for Payouts, DMT, and UPI Collection with military-grade security and AI-powered fraud detection.", "contact": { "name": "NXT Banking Support", "email": "no-reply@laraware.org", "url": "https://nxtbanking.ai/support" }, "license": { "name": "Proprietary", "url": "https://nxtbanking.ai/terms" }, "termsOfService": "https://nxtbanking.ai/terms", "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": "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" }, "example": null } ], "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 \u2014 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": "numeric", "description": "Amount to be collected in INR (Min: \u20b91)", "example": "100.00" }, "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": "\u26a0\ufe0f One-time activation. Required ONCE per merchant before using any Bank 2 backed rail \u2014 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 \u2014 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": "numeric", "description": "Transfer amount in Indian Rupees (\u20b9100 - \u20b92,00,000)", "example": 10000 }, "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": "numeric", "description": "GPS latitude for transaction tracking (-90 to 90)", "example": 28.7041 }, "longitude": { "type": "numeric", "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/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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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/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 \u2014 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 } ], "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/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": "numeric", "description": "Payment amount in INR (\u20b950 minimum)", "example": "1000.00" }, "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": { "reportId": { "type": "string", "description": "Report ID (path parameter)", "example": "report_65f3a1_1698765432" }, "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": "numeric", "description": "Minimum amount filter", "example": 100 }, "amount_max": { "type": "numeric", "description": "Maximum amount filter", "example": 50000 } }, "required": [ "reportId" ], "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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal virtual account ID to close", "example": 101 } }, "required": [ "id" ] } } } }, "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" }, "example": null }, { "name": "length", "in": "query", "required": false, "description": "Records per page (default: 50)", "schema": { "type": "number" }, "example": 50 }, { "name": "page", "in": "query", "required": false, "description": "Page number (default: 1)", "schema": { "type": "number" }, "example": 1 } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": [ { "txnid": "PAY20260227001", "amount": "10,000.00", "status": "success", "created_at": "27-02-2026 14:30:00", "account_number": "1234****5678" } ], "recordsTotal": 500, "recordsFiltered": 500, "config": { "headers": [ { "key": "txnid", "name": "Transaction ID", "type": "text" }, { "key": "amount", "name": "Amount", "type": "currency" }, { "key": "status", "name": "Status", "type": "badge" } ], "service_name": "Payout" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "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": "numeric", "description": "Recharge amount in INR (10-10000)", "example": 299 }, "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": "numeric", "description": "Amount (\u20b950 minimum)", "example": 100 }, "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 \u20b9100. Full amount credited to wallet. Settlement charge (\u20b92.00 + GST \u20b90.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** \u2014 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": { "serviceType": { "type": "string", "description": "Service type (path): payout, recharge, aeps, dmt, bbps, etc.", "example": "payout" }, "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" } }, "required": [ "serviceType" ], "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/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 \u20b950,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": "numeric", "description": "Payment amount in INR (1-200000)", "example": 1250 }, "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 \u2014 safe to omit; backend defaults from pincode." }, "gst_state": { "type": "string", "description": "2-digit GST state code. Only consumed by some upstream rails \u2014 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 } }, "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/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 } ], "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.2090" } }, "required": [ "reference_key", "pid_data", "biometric_type", "latitude", "longitude" ], "example": { "reference_key": "bm_2f8ad...", "pid_data": "{\"pidData\": \"\", \"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/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 \u2014 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 } ], "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/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: \u20b9100 - \u20b910,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 \u2014 `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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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": "numeric", "description": "Amount in INR (100-10000)", "example": 1000 } }, "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/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 \u2014 `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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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/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 \u2014 `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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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": "numeric", "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/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: \u20b9100 - \u20b910,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 \u2014 `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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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": "numeric", "description": "Amount in INR (100-10000)", "example": 5000 } }, "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" }, "example": null } ], "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/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: \u20b9100 - \u20b910,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 \u2014 `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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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": "numeric", "description": "Amount in INR (100-10000)", "example": 1000 } }, "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/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" } } } }, "/aeps/bank-1/transaction": { "post": { "summary": "Unified AEPS Transaction", "description": "Unified AEPS transaction endpoint supporting all transaction types: Cash Withdrawal (CW), Balance Enquiry (BE), Mini Statement (MS), Cash Deposit (CD), and Aadhaar Pay (M). Use transactionType parameter to specify the operation. The per-type endpoints (cash-withdrawal, balance-enquiry, etc.) are thin wrappers around this endpoint.", "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": "Transaction type: CW (Cash Withdrawal), BE (Balance Enquiry), MS (Mini Statement), CD (Cash Deposit), M (Aadhaar Pay). Alias: `txnType`.", "example": "CW" }, "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 \u2014 `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": "numeric", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "numeric", "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": "numeric", "description": "Amount in INR (REQUIRED for CW, CD, M; range 100-10000). Alias: `amount`.", "example": 1000 } }, "required": [ "transactionType", "merchantLoginId", "merchantPin", "adhaarNumber", "indicatorforUID", "nationalBankIdentificationNumber", "captureResponse" ], "example": { "transactionType": "CW", "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" } } } }, "/bbps/addons/deposit/enquire": { "post": { "summary": "Enquire Deposit", "description": "**Applicable for: Bank 2 (optional).** Postpaid deposit enquiry \u2014 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": "numeric", "description": "Amount in INR", "example": 1000 }, "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": "numeric", "description": "Latitude" }, "longitude": { "type": "numeric", "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": "numeric", "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/aadhaar-pay": { "post": { "summary": "Aadhaar Pay", "description": "Aadhaar Pay transaction on Bank 2 rail.", "operationId": "post_api_v1_aeps_bank_2_aadhaar_pay", "tags": [ "aeps/bank-2" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionType": { "type": "string", "description": "Set M" }, "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": "M", "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" } } } }, "/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" } } } }, "/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 \u2014 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": "decimal", "description": "Transfer amount in INR (0.01 \u2013 2,000,000)", "example": 10000 }, "mode": { "type": "enum", "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 \u2014 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": "path" }, "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": "query" }, "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" }, "example": null }, { "name": "from_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD). Default: 30 days ago", "schema": { "type": "string" }, "example": null }, { "name": "to_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD). Default: today", "schema": { "type": "string" }, "example": null }, { "name": "status", "in": "query", "required": false, "description": "Filter by status: success, pending, failed", "schema": { "type": "enum" }, "example": null }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (1\u2013100, default: 20)", "schema": { "type": "integer" }, "example": null }, { "name": "page", "in": "query", "required": false, "description": "Page number (default: 1)", "schema": { "type": "integer" }, "example": null } ], "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" }, "example": null }, { "name": "connected_account_uuid", "in": "query", "required": false, "description": "Required when probe=true", "schema": { "type": "string" }, "example": null } ], "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": "Hex-encoded HMAC-SHA256 of `clientId|method|path|timestamp|requestId|sha256(body)`. Use the secret issued for your X-Client-ID." }, "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 \u00b1300s window are rejected with AUTH_TIMESTAMP_INVALID." }, "RequestIdAuth": { "type": "apiKey", "in": "header", "name": "X-Request-ID", "description": "Per-request UUID v4. Replays within 5 minutes are rejected with AUTH_REPLAY_DETECTED." }, "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, "description": "Amount to transfer (\u20b910 - \u20b92,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" } } } } } } } } } } }