{ "openapi": "3.0.0", "info": { "title": "NXT Banking API", "version": "1.0.0", "description": "Comprehensive Fintech API for Payouts, DMT, and UPI Collection with military-grade security and AI-powered fraud detection.", "contact": { "name": "NXT Banking Support", "email": "hello@getlaraware.com", "url": "https://nxtbanking.ai/support" }, "license": { "name": "Proprietary", "url": "https://nxtbanking.ai/terms" }, "termsOfService": "https://nxtbanking.ai/terms", "x-unified-contract": { "single_contract": true, "provider_switch_transparent": true, "virtual_endpoint_mode": true, "not_implemented_error_code": "FEATURE_NOT_AVAILABLE" } }, "servers": [ { "url": "https://nxtbanking.ai/api/v1", "description": "Production Server" }, { "url": "https://nxtbanking.ai/api/sandbox", "description": "Sandbox Server (Test Mode)" } ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "tags": [ { "name": "Authentication", "description": "API authentication and authorization" }, { "name": "Payout", "description": "Payout and fund transfer operations" }, { "name": "DMT", "description": "Domestic Money Transfer operations" }, { "name": "AEPS", "description": "Aadhaar Enabled Payment System operations" }, { "name": "BBPS", "description": "Bharat Bill Payment System operations" }, { "name": "UPI Collection", "description": "UPI payment collection operations" }, { "name": "Webhooks", "description": "Webhook management and callbacks" }, { "name": "collection", "description": "Operations related to collection" }, { "name": "payout", "description": "Operations related to payout" }, { "name": "verification", "description": "Operations related to verification" }, { "name": "dmt", "description": "Operations related to dmt" }, { "name": "Virtual Account", "description": "Operations related to Virtual Account" }, { "name": "bbps", "description": "Operations related to bbps" }, { "name": "aeps", "description": "Operations related to aeps" }, { "name": "recharge", "description": "Operations related to recharge" }, { "name": "reports", "description": "Operations related to reports" }, { "name": "onboarding-activation", "description": "Operations related to onboarding-activation" }, { "name": "payout/connected-banking", "description": "Operations related to payout/connected-banking" }, { "name": "payout/xpress-payout", "description": "Operations related to payout/xpress-payout" } ], "paths": { "/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" } } } }, "/bbps/capabilities": { "get": { "summary": "BBPS Capabilities", "description": "**Response envelope (all BBPS endpoints).** Success: `{success: true, status: SUCCESS|PENDING, code: OK|PENDING, message, data, meta}`. Error: `{success: false, status: FAILED, code, message, data, error: {code, message, details?}, meta}`. `meta.request_id` echoes your X-Request-ID. Branch on `code`, never on `message`.\n\n| code | HTTP | meaning |\n| --- | --- | --- |\n| `VALIDATION_FAILED` | 422 | One or more request fields are invalid. |\n| `BILLER_NOT_FOUND` | 404 | Biller not found or not active. |\n| `BILLER_UNAVAILABLE` | 503 | The biller is not reachable right now. Please try again later. |\n| `INVALID_CUSTOMER_PARAMS` | 422 | The customer details were not accepted for this biller. |\n| `NO_BILL_DUE` | 422 | There is no bill due for these customer details. |\n| `BILL_FETCH_NOT_SUPPORTED` | 400 | This biller does not support bill fetch. Pay without a fetch_id. |\n| `BILL_FETCH_REQUIRED` | 400 | This biller requires a bill fetch before payment. Pass the fetch_id. |\n| `BILL_FETCH_FAILED` | 422 | The bill could not be fetched for these customer details. |\n| `INVALID_FETCH_ID` | 404 | The fetch_id is unknown, belongs to another biller, or was already used. |\n| `AMOUNT_NOT_ALLOWED` | 422 | The amount is not allowed for this bill. |\n| `REMITTER_DETAILS_REQUIRED` | 422 | Remitter details are required for this payment amount. |\n| `DUPLICATE_REQUEST` | 409 | A payment with the same details is already in progress. |\n| `CLIENT_REF_ID_REUSED` | 409 | This client_ref_id was already used for a different payment. |\n| `INSUFFICIENT_BALANCE` | 402 | Wallet balance is not enough for this payment. |\n| `ACCOUNT_RESTRICTED` | 403 | Your account cannot make payments right now. Please contact support. |\n| `SERVICE_NOT_ENABLED` | 403 | Bill payment is not enabled for your account. Please contact support. |\n| `TRANSACTION_BLOCKED` | 403 | This payment was blocked by risk controls. |\n| `PAYMENT_FAILED` | 400 | The bill payment failed. Check the transaction status for details. |\n| `TRANSACTION_NOT_FOUND` | 404 | Transaction not found. |\n| `COMPLAINT_NOT_FOUND` | 404 | Complaint not found. |\n| `COMPLAINT_NOT_ALLOWED` | 409 | A complaint cannot be raised for this transaction. |\n| `COMPLAINT_NOT_ALLOWED_YET` | 409 | A complaint for this transaction can be raised after the waiting period. |\n| `COMPLAINT_FAILED` | 502 | The complaint could not be registered. Please try again later. |\n| `FEATURE_NOT_AVAILABLE` | 501 | This operation is not available for this biller right now. |\n| `RATE_LIMITED` | 429 | Too many requests. Please slow down and retry. |\n| `SERVICE_UNAVAILABLE` | 503 | Bill payment is temporarily unavailable. Please try again shortly. |\n\nReturns which BBPS operations are available right now. Check it at start-up instead of hard-coding features; a feature can be switched off without any change on your side.", "operationId": "get_api_v1_bbps_capabilities", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": { "features": { "bill_fetch": true, "bill_payment": true, "bill_validation": true, "plans": true, "complaints": true, "complaint_tracking": true, "categories": true, "billers": true, "regions": true, "transaction_status": true } }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/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. Poll POST /api/v1/collection/status for terminal state. Failed and expired responses add failure_reason and error_code without changing existing keys.", "operationId": "post_api_v1_collection_generate_dynamic_qr", "tags": [ "collection" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Amount to be collected in INR (Min: \u20b91)", "example": 100 }, "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": 500, "reference_id": "ORD-1775243072", "customer_name": "Ishaan Verma", "customer_mobile": "9810045671", "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": 486021, "order_id": "ECO261004141532071", "reference_id": "ORD-1775243072", "qr_code": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMDAiIGhlaWdodD0iMzAwIj4uLi48L3N2Zz4=", "qr_string": "upi://pay?pa=brightmart.col@icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712", "upi_intent": "upi://pay?pa=brightmart.col%40icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712", "upi_deep_link": "upi://pay?pa=brightmart.col%40icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712", "upi_intent_raw": "upi://pay?pa=brightmart.col@icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712", "phonepe_link": "intent://pay?pa=brightmart.col%40icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712#Intent;scheme=upi;package=com.phonepe.app;end", "paytm_link": "intent://pay?pa=brightmart.col%40icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712#Intent;scheme=upi;package=net.one97.paytm;end", "googlepay_link": "intent://pay?pa=brightmart.col%40icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712#Intent;scheme=upi;package=com.google.android.apps.nbu.paisa.user;end", "bhim_link": "upi://pay?pa=brightmart.col%40icici&pn=BrightMart&tr=ECO261004141532071&am=500.00&cu=INR&mc=5712", "gross_amount": "500.00", "credit_amount": "500.00", "settlement_charge": "5.00", "settlement_gst": "0.90", "tds": "0.00", "customer_name": "Ishaan Verma", "customer_mobile": "XXXXXX5671", "purpose": "Product Purchase", "status": "pending", "expires_at": "2026-10-04 14:45:32", "expires_at_iso": "2026-10-04T14:45:32+05:30", "expires_in_seconds": 1800, "short_expiry": false, "generated_at": "2026-10-04 14:15:32", "timestamp": "2026-10-04T14:15:32+05:30", "expiry_hint": 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" } } } }, "/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" } } } }, "/payout/modes": { "get": { "summary": "Get Transfer Modes", "description": "List the IMPS / NEFT / RTGS modes this rail accepts, with amount bands and live availability. Use `available_now` to decide whether to show the payout form. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_payout_modes", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "as_of": "2026-10-04T08:00:00+05:30", "timezone": "Asia/Kolkata", "modes": [ { "code": "IMPS", "name": "Immediate Payment Service", "available_now": true, "min_amount": 1, "max_amount": 500000, "typical_time": "30 seconds", "note": "24x7 real-time settlement" }, { "code": "NEFT", "name": "National Electronic Funds Transfer", "available_now": true, "min_amount": 1, "max_amount": 99999999, "typical_time": "2 hours (batch)", "note": "Processed in half-hourly RBI settlement batches" }, { "code": "RTGS", "name": "Real Time Gross Settlement", "available_now": true, "min_amount": 200000, "max_amount": 99999999, "typical_time": "Real-time", "note": "High-value real-time gross settlement (min \u20b92,00,000)" } ] }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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" } } } }, "/xpress-payout/modes": { "get": { "summary": "Get Transfer Modes", "description": "List the IMPS / NEFT / RTGS modes this rail accepts, with amount bands and live availability. Use `available_now` to decide whether to show the payout form. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_xpress_payout_modes", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "as_of": "2026-10-04T08:00:00+05:30", "timezone": "Asia/Kolkata", "modes": [ { "code": "IMPS", "name": "Immediate Payment Service", "available_now": true, "min_amount": 1, "max_amount": 500000, "typical_time": "30 seconds", "note": "24x7 real-time settlement" }, { "code": "NEFT", "name": "National Electronic Funds Transfer", "available_now": true, "min_amount": 1, "max_amount": 99999999, "typical_time": "2 hours (batch)", "note": "Processed in half-hourly RBI settlement batches" }, { "code": "RTGS", "name": "Real Time Gross Settlement", "available_now": true, "min_amount": 200000, "max_amount": 99999999, "typical_time": "Real-time", "note": "High-value real-time gross settlement (min \u20b92,00,000)" } ] }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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, 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" } } } }, "/aeps/onboard": { "post": { "summary": "Merchant Onboarding", "description": "STEP 1 of 11 \u2014 Register a merchant (once per merchant)\n\nWhat it does: creates an AEPS merchant under your API account using name, mobile, PAN, Aadhaar, shop address and settlement bank account.\nUnlimited merchants: you can onboard as many merchants as you want. Each merchant needs its own mobile, PAN, Aadhaar and bank account.\n\nBefore this: nothing. AEPS must be active on your account (no overdue payment).\nNext step: Step 2 \u2014 `POST /api/v1/aeps/ekyc/send-otp`\n\nSAVE from the response: `merchantLoginId` and `merchantLoginPin`. Send them as `merchantLoginId` + `merchantPin` in every later call for this merchant.\n\nGood to know:\n\u2022 Calling again with the SAME mobile is safe: you get `ALREADY_ONBOARDED` with the same merchantLoginId.\n\u2022 A new mobile = a new merchant.\n\u2022 See all your merchants: `GET /api/v1/aeps/merchants`\n\nCommon errors:\n\u2022 `VALIDATION_ERROR` \u2192 a field is missing or in the wrong format; see `errors`.\n\u2022 `ONBOARDING_VALIDATION_FAILED` \u2192 the bank rejected some fields; fix the ones in `error.fields`.\n\u2022 `PAYMENT_OVERDUE` / `SERVICE_SUSPENDED` \u2192 clear dues or contact your account manager.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_onboard", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of merchant (3-100 chars)", "example": "Rajesh Kumar Singh" }, "merchantPhoneNumber": { "type": "string", "description": "10-digit mobile number", "example": "9876543210" }, "address1": { "type": "string", "description": "Primary address line (max 200)", "example": "Shop No 5, Main Market" }, "address2": { "type": "string", "description": "Secondary address line (max 200)", "example": "Near Bus Stand" }, "state": { "type": "string", "description": "State name (max 50)", "example": "Rajasthan" }, "city": { "type": "string", "description": "City name (max 50)", "example": "Jaipur" }, "district": { "type": "string", "description": "District name (max 50)", "example": "Jaipur" }, "pincode": { "type": "string", "description": "6-digit PIN code", "example": "302001" }, "userPan": { "type": "string", "description": "Merchant PAN card number (format: XXXXX9999X)", "example": "ABCDE1234F" }, "aadhaarNumber": { "type": "string", "description": "12-digit Aadhaar number (UIDAI format; cannot start with 0/1)", "example": "234567890123" }, "gstin": { "type": "string", "description": "15-character GSTIN (format: NNAAAAANNNN A1Z A)", "example": "08ABCDE1234F1Z5" }, "companyOrShopPan": { "type": "string", "description": "Shop/company PAN if different from merchant (XXXXX9999X)", "example": "AAACS1234C" }, "bankAccountNumber": { "type": "string", "description": "Settlement bank account number (max 20)", "example": "12345678901234" }, "bankIfscCode": { "type": "string", "description": "Bank IFSC code (11 chars, format: AAAA0XXXXXX)", "example": "SBIN0001234" }, "bankName": { "type": "string", "description": "Bank name (max 100)", "example": "State Bank of India" }, "bankAccountName": { "type": "string", "description": "Account holder name as per bank record (max 100)", "example": "Rajesh Kumar Singh" }, "latitude": { "type": "number", "description": "GPS latitude (-90 to 90)", "example": 26.9124 }, "longitude": { "type": "number", "description": "GPS longitude (-180 to 180)", "example": 75.7873 }, "deviceIMEI": { "type": "string", "description": "Capture device IMEI / serial (max 50). Defaults to \"WEB-FORM\" if omitted.", "example": "358240051111110" } }, "required": [ "name", "merchantPhoneNumber", "address1", "state", "city", "district", "pincode", "userPan", "bankAccountNumber", "bankIfscCode" ], "example": { "name": "Rajesh Kumar Singh", "merchantPhoneNumber": "9876543210", "address1": "Shop No 5, Main Market", "address2": "Near Bus Stand", "state": "Rajasthan", "city": "Jaipur", "district": "Jaipur", "pincode": "302001", "userPan": "ABCDE1234F", "aadhaarNumber": "234567890123", "gstin": "08ABCDE1234F1Z5", "companyOrShopPan": "AAACS1234C", "bankAccountNumber": "12345678901234", "bankIfscCode": "SBIN0001234", "bankName": "State Bank of India", "bankAccountName": "Rajesh Kumar Singh", "latitude": 26.9124, "longitude": 75.7873, "deviceIMEI": "358240051111110" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "code": "ONBOARDED", "message": "Merchant onboarded successfully", "data": { "merchantLoginId": "MER48210375", "merchantLoginPin": "Q7M2K9", "merchantId": "MER48210375", "next_action": "ekyc", "alreadyOnboarded": false }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/aeps/ekyc/send-otp": { "post": { "summary": "eKYC Send OTP", "description": "STEP 2 of 11 \u2014 Start merchant eKYC (sends OTP to the merchant)\n\nWhat it does: sends an Aadhaar-linked OTP to the merchant's mobile and opens an eKYC session.\n\nBefore this: Step 1 (onboard).\nNext step: Step 3 \u2014 `POST /api/v1/aeps/ekyc/validate-otp`\n\nRequired: merchantLoginId + merchantPin (from Step 1), `mobileNumber` (the SAME mobile used in Step 1), `aadhaarNumber`, `latitude`, `longitude`.\nSAVE from the response: `primaryKeyId` and `encodeFPTxnId` \u2014 needed in Steps 3, 4 and 5.\n\nAlso use this step for Bank eKYC: if any call returns `BANK_EKYC_PENDING` (next_action `bank_ekyc`) or the merchant was inactive for 90+ days, run Steps 2 \u2192 3 \u2192 5 again, then Step 6.\n\nCommon errors:\n\u2022 `MERCHANT_MOBILE_ALREADY_REGISTERED` \u2192 this mobile already belongs to another merchant. Use that merchant's merchantLoginId (see `GET /api/v1/aeps/merchants`) or onboard with a different mobile.\n\u2022 `EKYC_IDENTITY_MISMATCH` \u2192 name / PAN / Aadhaar do not match the onboarding data.\n\u2022 `EKYC_AADHAAR_REJECTED` \u2192 Aadhaar could not be verified.\n\u2022 Do NOT call send-otp in a loop. If the OTP did not arrive, use Step 4 (resend-otp).\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_ekyc_send_otp", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "mobileNumber": { "type": "string", "description": "10-digit mobile \u2014 must be the same mobile used in onboard.", "example": "9876543210" }, "aadhaarNumber": { "type": "string", "description": "12-digit merchant Aadhaar.", "example": "234567890123" }, "latitude": { "type": "number", "description": "Merchant GPS latitude (-90 to 90).", "example": 26.9124 }, "longitude": { "type": "number", "description": "Merchant GPS longitude (-180 to 180).", "example": 75.7873 }, "panNumber": { "type": "string", "description": "Merchant PAN (10 chars).", "example": "ABCDE1234F" }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin", "mobileNumber", "aadhaarNumber", "latitude", "longitude" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "mobileNumber": "9876543210", "aadhaarNumber": "234567890123", "latitude": 26.9124, "longitude": 75.7873, "deviceIMEI": "358240051111110" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "OTP sent successfully", "data": { "primaryKeyId": 5172093, "encodeFPTxnId": "EKYC7Q2M9K4X8C1V6B3N5Z0LA", "encodedTxnId": "EKYC7Q2M9K4X8C1V6B3N5Z0LA" }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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-payment-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. Poll POST /api/v1/collection/status for terminal state. Failed and expired responses add failure_reason and error_code without changing existing keys. Canonical path. Alias POST /api/v1/collection/generate-link is also accepted.", "operationId": "post_api_v1_collection_generate_payment_link", "tags": [ "collection" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Payment amount in INR (\u20b950 minimum)", "example": 1000 }, "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": "Meera Nair", "customer_mobile": "9845012367", "customer_email": "meera.nair@example.com", "reference_id": "INV-2026-0417", "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": 486034, "order_id": "ECO261004141806554", "reference_id": "INV-2026-0417", "payment_link": "https://nxtbanking.ai/payment/upi/Wq7LmZc2VbN8xRtYk4HdFgJs9PaUe3Oi", "short_link": "https://nxtbanking.ai/payment/upi/Wq7LmZc2VbN8xRtYk4HdFgJs9PaUe3Oi", "amount": "1000.00", "customer_name": "Meera Nair", "customer_mobile": "XXXXXX2367", "customer_email": "meera.nair@example.com", "description": "Monthly Subscription Payment", "status": "pending", "expires_at": "05 Oct 2026, 02:18 PM", "generated_at": "04 Oct 2026, 02:18 PM", "notifications_sent": { "whatsapp": false, "sms": false, "email": false }, "expiry_hint": 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" } } } }, "/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" } } } }, "/payout/purpose-codes": { "get": { "summary": "Get Purpose Codes", "description": "List the purpose-of-payment codes accepted by `initiate`, so you can build the dropdown from our catalog instead of hardcoding it. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_payout_purpose_codes", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "purpose_codes": [ { "code": "VENDOR_PAYMENT", "name": "Vendor / Supplier Payment", "description": "Payments made to suppliers, contractors, or commercial vendors.", "requires_note": false }, { "code": "SALARY_WAGES", "name": "Salary / Employee Wages", "description": "Disbursements for payroll, employee stipends, or consultant wages.", "requires_note": false }, { "code": "CUSTOMER_REFUND", "name": "Customer Refund / Chargeback", "description": "Return of funds for cancelled orders, services, or warranty claims.", "requires_note": false }, { "code": "REIMBURSEMENT", "name": "Expense Reimbursement", "description": "Reimbursement of business expenses incurred by staff.", "requires_note": false }, { "code": "OTHER", "name": "Other Business Purpose", "description": "Other legitimate business transfer. Requires purpose_note (min 8 chars).", "requires_note": true } ] }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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" } } } }, "/xpress-payout/purpose-codes": { "get": { "summary": "Get Purpose Codes", "description": "List the purpose-of-payment codes accepted by `initiate`, so you can build the dropdown from our catalog instead of hardcoding it. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_xpress_payout_purpose_codes", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "purpose_codes": [ { "code": "VENDOR_PAYMENT", "name": "Vendor / Supplier Payment", "description": "Payments made to suppliers, contractors, or commercial vendors.", "requires_note": false }, { "code": "SALARY_WAGES", "name": "Salary / Employee Wages", "description": "Disbursements for payroll, employee stipends, or consultant wages.", "requires_note": false }, { "code": "CUSTOMER_REFUND", "name": "Customer Refund / Chargeback", "description": "Return of funds for cancelled orders, services, or warranty claims.", "requires_note": false }, { "code": "REIMBURSEMENT", "name": "Expense Reimbursement", "description": "Reimbursement of business expenses incurred by staff.", "requires_note": false }, { "code": "OTHER", "name": "Other Business Purpose", "description": "Other legitimate business transfer. Requires purpose_note (min 8 chars).", "requires_note": true } ] }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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/categories": { "get": { "summary": "List Bill Categories", "description": "All bill categories that can be paid. Use `code` or `name` as the `category` filter on List Billers.", "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, "status": "SUCCESS", "code": "OK", "message": "OK", "data": [ { "code": "ELECTRICITY", "name": "Electricity", "icon": "bolt", "biller_count": 120 }, { "code": "MOBILE_POSTPAID", "name": "Mobile Postpaid", "icon": "phone", "biller_count": 9 } ], "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/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" } } } }, "/aeps/ekyc/validate-otp": { "post": { "summary": "eKYC Validate OTP", "description": "STEP 3 of 11 \u2014 Verify the OTP\n\nWhat it does: verifies the 6-digit OTP the merchant received in Step 2.\n\nBefore this: Step 2 (send-otp).\nNext step: Step 5 \u2014 `POST /api/v1/aeps/ekyc/biometric`\n\nRequired: merchantLoginId + merchantPin (from Step 1), `otp`, `primaryKeyId` and `encodeFPTxnId` (both from Step 2, copied exactly).\n\nCommon errors:\n\u2022 `EKYC_OTP_INVALID` \u2192 wrong or expired OTP; call Step 4 (resend-otp).\n\u2022 `OTP_ATTEMPTS_EXCEEDED` \u2192 too many wrong tries; call Step 4 (resend-otp).\n\u2022 `EKYC_SESSION_EXPIRED` \u2192 session used or expired; start again from Step 2.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_ekyc_validate_otp", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "otp": { "type": "string", "description": "6-digit OTP received by the merchant.", "example": "123456" }, "primaryKeyId": { "type": "string", "description": "Value returned by Step 2 (send-otp). Copy as is.", "example": "PK_ABC123" }, "encodeFPTxnId": { "type": "string", "description": "Opaque session token returned by Step 2 (send-otp). Copy as is, do not decode.", "example": "ENC_TXN_456" }, "mobileNumber": { "type": "string", "description": "Mobile the OTP was sent to.", "example": "9876543210" }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin", "otp", "primaryKeyId", "encodeFPTxnId" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "otp": "123456", "primaryKeyId": "PK_ABC123", "encodeFPTxnId": "ENC_TXN_456" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "OTP validated successfully", "data": { "primaryKeyId": 5172093, "encodeFPTxnId": "EKYC7Q2M9K4X8C1V6B3N5Z0LA", "encodedTxnId": "EKYC7Q2M9K4X8C1V6B3N5Z0LA" }, "next_action": "ekyc_biometric", "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/recharge/plans": { "post": { "summary": "Get Recharge Plans", "description": "Fetch available recharge plans for a specific operator and circle. Returns cached plans when available for faster response.", "operationId": "post_api_v1_recharge_plans", "tags": [ "recharge" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operator": { "type": "string", "description": "Operator name", "example": "Airtel" }, "circle": { "type": "string", "description": "Telecom circle", "example": "Delhi NCR" } }, "required": [ "operator", "circle" ], "example": { "operator": "Airtel", "circle": "Delhi NCR" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": [ { "plan_id": "PLN001", "plan_name": "Unlimited Pack", "amount": 299, "talktime": "Unlimited", "validity": "28 days", "description": "Unlimited calls + 1.5GB/day data", "category_type": "Unlimited" }, { "plan_id": "PLN002", "plan_name": "Data Pack", "amount": 199, "talktime": "0", "validity": "24 days", "description": "1GB/day data", "category_type": "Data" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/reports/custom/{reportId}/data": { "post": { "summary": "Get Report Data", "description": "Fetch the actual data for a custom report with optional date range, status, and amount filters. Returns formatted data with summary statistics and performance metrics.", "operationId": "post_api_v1_reports_custom_reportId_data", "tags": [ "reports" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "ReportId", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_date": { "type": "string", "description": "Start date (YYYY-MM-DD)", "example": "2026-02-01" }, "to_date": { "type": "string", "description": "End date (YYYY-MM-DD)", "example": "2026-02-27" }, "status": { "type": "string", "description": "Filter by status (success, pending, failed)", "example": "success" }, "amount_min": { "type": "number", "description": "Minimum amount filter", "example": 100 }, "amount_max": { "type": "number", "description": "Maximum amount filter", "example": 50000 } }, "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" } } } }, "/payout/balance": { "get": { "summary": "Get Wallet Balance", "description": "Get the payout wallet balance available to spend and the amount currently held. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "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": { "balance": 250000.5, "available_balance": 250000.5, "locked_balance": 0, "currency": "INR", "status": "active", "updated_at": "2026-10-04T08:00:00+05:30" }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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" } } } }, "/xpress-payout/balance": { "get": { "summary": "Get Wallet Balance", "description": "Get the payout wallet balance available to spend and the amount currently held. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_xpress_payout_balance", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "balance": 250000.5, "available_balance": 250000.5, "locked_balance": 0, "currency": "INR", "status": "active", "updated_at": "2026-10-04T08:00:00+05:30" }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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": "Paginated list of billers that can be paid.\n\n- `fetch_mode`: `MANDATORY` (fetch the bill first and pay with `fetch_id`), `OPTIONAL`, or `NOT_SUPPORTED` (pay directly).\n- `validation_mode` / `plan_mode`: whether Validate Bill / Biller Plans apply.\n- `amount_exactness`: `EXACT`, `EXACT_OR_ABOVE`, `EXACT_OR_BELOW` or `ANY` against the fetched bill amount.", "operationId": "get_api_v1_bbps_billers", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category code or name from List Bill Categories", "schema": { "type": "string" }, "example": "ELECTRICITY" }, { "name": "search", "in": "query", "required": false, "description": "Biller name search (min 2 characters)", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Region code from List Regions. National billers are always included.", "schema": { "type": "string" }, "example": "IND-MAH" }, { "name": "fetch_supported", "in": "query", "required": false, "description": "Only billers that support bill fetch", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size, 1 to 200 (default 50)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": [ { "biller_id": "MAHA00000NAT01", "name": "State Electricity Board", "category": "Electricity", "coverage": "IND-MAH", "fetch_mode": "MANDATORY", "validation_mode": "NOT_SUPPORTED", "plan_mode": "NOT_SUPPORTED", "amount_exactness": "EXACT_OR_ABOVE", "accepts_adhoc_amount": false, "status": "ACTIVE" } ], "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10:00:00+05:30", "pagination": { "page": 1, "per_page": 50, "total": 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/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" } } } }, "/collection/send-collect-request": { "post": { "summary": "Send UPI Collect Request", "description": "Send a UPI collect request to a customer VPA. The customer receives a payment notification on their UPI app. If seamless mode is unavailable, automatically falls back to a payment link.", "operationId": "post_api_v1_collection_send_collect_request", "tags": [ "collection" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_vpa": { "type": "string", "description": "Customer UPI VPA", "example": "customer@upi" }, "amount": { "type": "number", "description": "Amount (\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": "kabir.malhotra@okaxis", "amount": 100, "customer_name": "Kabir Malhotra", "customer_mobile": "9910023345", "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": "ECO261004142210388", "reference_id": "TXN17910294410", "collection_id": 486047, "gross_amount": "100.00", "credit_amount": "100.00", "settlement_charge": "5.00", "settlement_gst": "0.90", "customer_vpa": "kabir.malhotra@okaxis", "status": "pending", "collection_type": "collect_request", "info": "Customer will pay \u20b9100. Full amount credited to wallet. Settlement charge (\u20b95.00 + GST \u20b90.90) 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" } } } }, "/bbps/biller/{biller_id}": { "get": { "summary": "Biller Details", "description": "One biller with the customer parameters to collect. Send them in `customer_params` keyed by `name`, exactly as listed.", "operationId": "get_api_v1_bbps_biller_biller_id", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "biller_id", "in": "path", "required": true, "description": "Biller id", "schema": { "type": "string" } }, { "name": "biller_id", "in": "query", "required": true, "description": "Biller id (path)", "schema": { "type": "string" }, "example": "MAHA00000NAT01" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": { "biller_id": "MAHA00000NAT01", "name": "State Electricity Board", "category": "Electricity", "coverage": "IND-MAH", "fetch_mode": "MANDATORY", "validation_mode": "NOT_SUPPORTED", "plan_mode": "NOT_SUPPORTED", "amount_exactness": "EXACT_OR_ABOVE", "accepts_adhoc_amount": false, "status": "ACTIVE", "description": null, "customer_params": [ { "name": "Consumer Number", "data_type": "NUMERIC", "required": true, "min_length": 9, "max_length": 12, "regex": "^[0-9]{9,12}$" } ], "amount_limits": { "min": 1, "max": 200000 } }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/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. When status is failed or expired, data includes failure_reason and error_code. retry_after_minutes is present for COLLECTION_DECLINED_SECURITY. Existing keys are unchanged.", "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": "ORD-1775243072" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Payment status retrieved successfully", "data": { "collection_id": "ECO261004141532071", "order_id": "ECO261004141532071", "reference_id": "ORD-1775243072", "status": "success", "status_label": "SUCCESS", "is_paid": true, "is_pending": false, "amount": 500, "payment_details": { "customer_name": null, "customer_mobile": null, "payment_mode": "UPI", "utr_number": "627184290315" }, "transaction_info": { "paid_at": "2026-10-04T14:16:49+05:30", "upi_id": null, "bank_reference": "627184290315" }, "net_amount": 500, "charge": 5, "gst": 0.9, "paid_at": "2026-10-04T14:16:49+05:30", "expired_at": "2026-10-04T14:20:32+05:30", "created_at": "2026-10-04T14:15:32+05:30", "updated_at": "2026-10-04T14:16:50+05:30", "tax_invoice": null }, "execution_time_ms": 6.4 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/virtual-account/{id}/close": { "post": { "summary": "Close Virtual Account", "description": "Close an active virtual account. Once closed, no further payments can be received and the account cannot be reopened.", "operationId": "post_api_v1_virtual_account_id_close", "tags": [ "Virtual Account" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Virtual account closed successfully", "data": { "id": 101, "status": "closed", "closed_at": "2025-11-30T18:30:00+05:30" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/aeps/ekyc/resend-otp": { "post": { "summary": "eKYC Resend OTP", "description": "STEP 4 of 11 \u2014 Resend the OTP (only if needed)\n\nWhen to use: the OTP from Step 2 did not arrive, expired, or was entered wrong too many times.\n\nBefore this: Step 2 (send-otp).\nNext step: Step 3 (validate-otp) with the new OTP.\n\nRequired: merchantLoginId + merchantPin (from Step 1), `primaryKeyId` and `encodeFPTxnId` from Step 2.\nIf the response returns new `primaryKeyId` / `encodeFPTxnId`, use the new values from now on.\n\nCommon errors:\n\u2022 `EKYC_SESSION_EXPIRED` \u2192 start again from Step 2.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_ekyc_resend_otp", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "primaryKeyId": { "type": "string", "description": "Value returned by Step 2 (send-otp). Copy as is.", "example": "PK_ABC123" }, "encodeFPTxnId": { "type": "string", "description": "Opaque session token returned by Step 2 (send-otp). Copy as is, do not decode.", "example": "ENC_TXN_456" }, "mobileNumber": { "type": "string", "description": "Mobile to resend the OTP to.", "example": "9876543210" }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin", "primaryKeyId", "encodeFPTxnId" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "primaryKeyId": "PK_ABC123", "encodeFPTxnId": "ENC_TXN_456" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "OTP resent successfully", "data": { "primaryKeyId": 5172093, "encodeFPTxnId": "EKYC7Q2M9K4X8C1V6B3N5Z0LA", "encodedTxnId": "EKYC7Q2M9K4X8C1V6B3N5Z0LA" }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/statements/{serviceType}": { "get": { "summary": "Get Service Statements", "description": "Fetch paginated transaction statements for any service type. Supports search, date range, amount filters, and sorting. Role-based data access is enforced automatically. Service types: payout, recharge, aeps, dmt, bbps, upi_collection, fund, wallet.", "operationId": "get_api_v1_statements_serviceType", "tags": [ "reports" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "serviceType", "in": "path", "required": true, "description": "ServiceType", "schema": { "type": "string" } }, { "name": "serviceType", "in": "query", "required": true, "description": "Service type (path): payout, recharge, aeps, dmt, bbps, upi_collection, fund, wallet", "schema": { "type": "string" }, "example": "payout" }, { "name": "from_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" }, "example": "2026-02-01" }, { "name": "to_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" }, "example": "2026-02-27" }, { "name": "status", "in": "query", "required": false, "description": "Transaction status filter", "schema": { "type": "string" }, "example": "success" }, { "name": "search", "in": "query", "required": false, "description": "Search by transaction ID, reference number, etc.", "schema": { "type": "string" } }, { "name": "length", "in": "query", "required": false, "description": "Records per page (default: 50)", "schema": { "type": "number" }, "example": 50 }, { "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" } } } }, "/xpress-payout/initiate": { "post": { "summary": "Initiate Payout", "description": "Send an IMPS / NEFT / RTGS transfer straight to a bank account. Put the account number, IFSC and account holder name in the request \u2014 no beneficiary verification or `bene_token` step. Xpress Payout must be activated on your account (403 `XPRESS_PAYOUT_NOT_ASSIGNED` otherwise). `remarks` is optional; if sent it must be exactly one purpose name (`label`) from GET /api/v1/xpress-payout/purpose-codes, otherwise 422. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "post_api_v1_xpress_payout_initiate", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Your unique transaction reference. Max 40 characters. Must be unique (checked against reports.txnid).", "example": "MYAPP1699523456789" }, "account_holder_name": { "type": "string", "description": "Beneficiary name as per bank records. Letters and spaces only. Alias: beneficiary_name.", "example": "Rahul Sharma" }, "account_number": { "type": "string", "description": "Beneficiary bank account number. Digits only.", "example": "9448272727" }, "ifsc_code": { "type": "string", "description": "IFSC of the beneficiary branch. Format: 4 letters + 0 + 6 alphanumeric.", "example": "KKBK0005333" }, "amount": { "type": "number", "description": "Transfer amount in INR. Minimum \u20b9100. Mode rules: IMPS/NEFT up to \u20b92,00,000; RTGS only above \u20b92,00,000.", "example": 100 }, "mode": { "type": "string", "description": "Transfer mode. Optional \u2014 defaults to IMPS when omitted. Case-insensitive.", "example": "IMPS" }, "mobile": { "type": "string", "description": "Beneficiary mobile number (10 digits).", "example": "9876543210" }, "remarks": { "type": "string", "description": "Optional. If sent, must be exactly one of the purpose names (`label`) from GET /api/v1/xpress-payout/purpose-codes. Free text is rejected with 422.", "example": "Vendor / Supplier Payment" }, "latitude": { "type": "number", "description": "GPS latitude.", "example": 28.7041 }, "longitude": { "type": "number", "description": "GPS longitude.", "example": 77.1025 }, "purpose": { "type": "string", "description": "Free-text purpose. Prefer purpose_code + purpose_note \u2014 those feed compliance review.", "example": "Payment for services" }, "purpose_code": { "type": "string", "description": "Declared reason for the transfer. Use one of the catalog codes (SALARY_WAGES, VENDOR_PAYMENT, CUSTOMER_REFUND, \u2026). OTHER requires purpose_note. Strongly recommended \u2014 missing or junk purpose increases review risk.", "example": "VENDOR_PAYMENT" }, "purpose_note": { "type": "string", "description": "Short reason in your own words. Required when purpose_code=OTHER. Minimum 8 characters when sent.", "example": "Invoice INV-2041 for September supply" } }, "required": [ "transaction_id", "account_holder_name", "account_number", "ifsc_code", "amount" ], "example": { "transaction_id": "YOUR-UNIQUE-TXN-REFERENCE", "account_holder_name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "amount": 100, "mode": "IMPS", "mobile": "9876543210", "remarks": "Vendor / Supplier Payment", "latitude": 28.7041, "longitude": 77.1025, "purpose": "Payment for services", "purpose_code": "VENDOR_PAYMENT", "purpose_note": "Invoice INV-2041 for September supply" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "success", "message": "Payout transfer processed successfully", "data": { "transaction_id": "MYAPP17899650546285908", "reference_id": "MYAPP17899650546285908", "status": "success", "amount": 100, "charge": 7, "gst": 1.26, "total_deducted": 108.26, "mode": "IMPS", "utr_number": "625110238639", "bank_ref_num": "625110238639", "beneficiary": { "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank" }, "created_at": "2026-10-04T10:03:49+05:30", "completed_at": "2026-10-04T10:04:12+05:30" }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/recharge/process": { "post": { "summary": "Process Recharge", "description": "Process a mobile or DTH recharge. Validates wallet balance, deducts amount with charges and GST, and processes through the recharge provider. Auto-refunds on failure.", "operationId": "post_api_v1_recharge_process", "tags": [ "recharge" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mobile_number": { "type": "string", "description": "10-digit mobile number starting with 6-9", "example": "9876543210" }, "operator": { "type": "string", "description": "Operator name", "example": "Airtel" }, "circle": { "type": "string", "description": "Telecom circle", "example": "Delhi NCR" }, "amount": { "type": "number", "description": "Recharge amount in INR (10-10000)", "example": 299 }, "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" } } } }, "/payout/verify-account": { "post": { "summary": "Verify Bank Account", "description": "Verify a bank account and get the registered holder name before paying it. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "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": "Beneficiary bank account number (9 to 18 digits).", "example": "9448272727" }, "ifsc_code": { "type": "string", "description": "11-character IFSC code of the beneficiary branch.", "example": "KKBK0005333" }, "account_holder_name": { "type": "string", "description": "Expected beneficiary name (used for verification hint).", "example": "Rahul Sharma" }, "mobile": { "type": "string", "description": "Optional 10-digit mobile number.", "example": "9876543210" } }, "required": [ "account_number", "ifsc_code", "account_holder_name" ], "example": { "account_number": "9448272727", "ifsc_code": "KKBK0005333", "account_holder_name": "Rahul Sharma" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "status": "valid", "verification_status": "verified", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "account_holder_name": "Rahul Sharma", "bank_name": "Kotak Mahindra Bank", "charged": 2.36, "txn_id": "VRF991823719" }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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": { "format": { "type": "string", "description": "Export format: excel, csv, pdf (default: excel)", "example": "csv" }, "from_date": { "type": "string", "description": "Start date (YYYY-MM-DD)", "example": "2026-02-01" }, "to_date": { "type": "string", "description": "End date (YYYY-MM-DD)", "example": "2026-02-27" }, "status": { "type": "string", "description": "Filter by status" } }, "example": { "format": "csv", "from_date": "2026-02-01", "to_date": "2026-02-27" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Export is being processed", "data": { "export_id": "export_65f3a1b2c_1698765432", "status": "queued", "download_url": "/downloads/reports/export_65f3a1b2c_1698765432", "estimated_records": 5000 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/xpress-payout/status": { "post": { "summary": "Check Payout Status", "description": "Poll the outcome of a payout using its `transaction_id`. Retry until `data.status` is `success`, `failed`, or `refunded`. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "post_api_v1_xpress_payout_status", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "The unique transaction_id sent in Step 9.", "example": "MYAPP17899650546285908" } }, "required": [ "transaction_id" ], "example": { "transaction_id": "MYAPP17899650546285908" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "transaction_id": "MYAPP17899650546285908", "reference_id": "MYAPP17899650546285908", "status": "success", "amount": 100, "charge": 7, "gst": 1.26, "total_deducted": 108.26, "utr_number": "625110238639", "beneficiary": { "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank" }, "created_at": "2026-10-04T10:03:49+05:30", "completed_at": "2026-10-04T10:04:12+05:30", "changed": false, "message": "Transaction successful", "refunded": false, "refund_amount": null }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/aeps/ekyc/biometric": { "post": { "summary": "eKYC Biometric Verification", "description": "STEP 5 of 11 \u2014 Merchant fingerprint / face scan (completes eKYC)\n\nWhat it does: verifies the merchant's biometric with Aadhaar. When it succeeds, eKYC is complete.\n\nBefore this: Step 3 (validate-otp). Get the PidOptions for the device from Step 8 (capture-directive, operation `ekyc`).\nNext step: Step 6 \u2014 `POST /api/v1/aeps/two-fa`\n\nRequired: merchantLoginId + merchantPin (from Step 1), `captureResponse` (full RD device output). Send `primaryKeyId` + `encodeFPTxnId` from Step 2 as well.\nCheck the response: `stage` and `next_action` tell you what to do next.\n\nCommon errors:\n\u2022 `BIOMETRIC_MISMATCH` \u2192 clean the sensor, scan again (next_action `retry_capture`).\n\u2022 `EKYC_SESSION_EXPIRED` \u2192 this OTP session was already used; restart from Step 2. A scan cannot be reused.\n\u2022 `BANK_EKYC_PENDING` \u2192 bank verification is required: run Steps 2 \u2192 3 \u2192 5 once more.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_ekyc_biometric", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "primaryKeyId": { "type": "string", "description": "Value returned by Step 2 (send-otp). Copy as is.", "example": "PK_ABC123" }, "encodeFPTxnId": { "type": "string", "description": "Opaque session token returned by Step 2 (send-otp). Copy as is, do not decode.", "example": "ENC_TXN_456" }, "captureResponse": { "type": "object", "description": "Full RD-service capture (PID data) as returned by the device. Must include the PID payload and a timestamp (ts). Get PidOptions from Step 8 (capture-directive)." }, "aadhaarNumber": { "type": "string", "description": "12-digit merchant Aadhaar.", "example": "234567890123" }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin", "captureResponse" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "primaryKeyId": "PK_ABC123", "encodeFPTxnId": "ENC_TXN_456", "captureResponse": { "errCode": "0", "fCount": "1", "fType": "2", "dpID": "DEVICE.PROVIDER", "rdsID": "RDS.ID.001", "rdsVer": "1.0.8", "mi": "MODEL", "mc": "MIIEGDCCAwCg...", "sessionKey": "dGVz...", "hmac": "Ymlu...", "PidDatatype": "X", "Piddata": "BASE64_ENCODED_PID_DATA", "ts": "2026-10-03T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Biometric eKYC completed successfully", "data": { "status": "completed", "bank_activation": "pending", "completed_at": "2026-10-03T15:24:16+05:30", "stage": "daily_2fa", "bank_ekyc_required": false }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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/history": { "get": { "summary": "Get Collection History", "description": "Retrieve paginated list of collection transactions", "operationId": "get_api_v1_collection_history", "tags": [ "collection" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "required": false, "description": "Records per page (max 100)", "schema": { "type": "integer" }, "example": 25 }, { "name": "status", "in": "query", "required": false, "description": "Filter by status: pending, success, failed, expired", "schema": { "type": "string" }, "example": "success" }, { "name": "collection_type", "in": "query", "required": false, "description": "Filter by type: dynamic_qr, payment_link, collect_request", "schema": { "type": "string" }, "example": "dynamic_qr" }, { "name": "date_from", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD)", "schema": { "type": "string" }, "example": "2026-03-01" }, { "name": "date_to", "in": "query", "required": false, "description": "End date (YYYY-MM-DD)", "schema": { "type": "string" }, "example": "2026-03-16" }, { "name": "search", "in": "query", "required": false, "description": "Search by order_id, transaction_id, or purpose", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": [ { "id": 486021, "order_id": "ECO261004141532071", "reference_id": "ORD-1775243072", "amount": "500.00", "charge": "5.00", "gst": "0.90", "status": "success", "collection_type": "dynamic_qr", "customer_name": "Ishaan Verma", "utr_number": "627184290315", "paid_at": "2026-10-04T14:16:49+05:30", "created_at": "2026-10-04T14:15:32+05:30" }, { "id": 486034, "order_id": "ECO261004141806554", "reference_id": "INV-2026-0417", "amount": "1000.00", "charge": "5.00", "gst": "0.90", "status": "pending", "collection_type": "payment_link", "customer_name": "Meera Nair", "utr_number": null, "paid_at": null, "created_at": "2026-10-04T14:18:06+05:30" } ], "pagination": { "total": 2, "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" } } } }, "/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/regions": { "get": { "summary": "List Regions", "description": "Regions (Indian states and union territories) that have local billers. Use `region_code` as the `region` filter on List Billers.", "operationId": "get_api_v1_bbps_regions", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": [ { "region_code": "IND-KAR", "name": "Karnataka" }, { "region_code": "IND-MAH", "name": "Maharashtra" } ], "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/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" } } } }, "/payout/beneficiaries/verify": { "post": { "summary": "Verify Payout Beneficiary", "description": "Step 1 of adding a beneficiary: check a bank account and get a `verification_id` valid for 24 hours. Charges \u20b92.00 + 18% GST (\u20b92.36 total) per call (first 30 calls free). See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "post_api_v1_payout_beneficiaries_verify", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_number": { "type": "string", "description": "Beneficiary bank account number. Digits only.", "example": "9448272727" }, "ifsc_code": { "type": "string", "description": "IFSC of the beneficiary branch.", "example": "KKBK0005333" }, "account_name": { "type": "string", "description": "Optional name hint. The bank-returned name is stored, not this field.", "example": "Rahul Sharma" } }, "required": [ "account_number", "ifsc_code" ], "example": { "account_number": "9448272727", "ifsc_code": "KKBK0005333", "account_name": "Rahul Sharma" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Bank account verified successfully via Penny Drop", "data": { "verification_id": "9d9014ab-4228-4efc-8e4a-b51c14f3b7d1", "payout_token": "ptkn_8f3a9e1c2b4d5e6f7a8b9c0d1e2f3a4b", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "name": "Rahul Sharma", "bank_name": "Kotak Mahindra Bank", "status": "valid", "penny_drop_status": "SUCCESS", "charged": 2.36, "gst": 0.36, "expires_at": "2026-10-05T08:00:00+05:30", "payout_token_expires_at": "2026-10-04T12:00:00+05:30", "token_valid_for": "4 hours" }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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/beneficiaries": { "post": { "summary": "Add Payout Beneficiary", "description": "Step 2 of adding a beneficiary: save it using the `verification_id` from step 1. The account+IFSC is stored once per user. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "post_api_v1_payout_beneficiaries", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "verification_id": { "type": "string", "description": "UUID returned by POST /api/v1/payout/beneficiaries/verify. Valid for 24 hours, single use.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "nickname": { "type": "string", "description": "Your label for this beneficiary.", "example": "Vendor Kotak" }, "mobile": { "type": "string", "description": "Optional 10-digit mobile.", "example": "9876543210" } }, "required": [ "verification_id" ], "example": { "verification_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "nickname": "Vendor Kotak", "mobile": "9876543210" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Beneficiary saved.", "data": { "beneficiary_id": 101, "name": "RAHUL SHARMA", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "KOTAK MAHINDRA BANK LIMITED", "nickname": "Vendor Kotak", "mobile": "9876543210", "is_verified": true, "verified_at": "2026-09-11T10:04:12+05:30", "is_active": 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" } } }, "get": { "summary": "List Payout Beneficiaries", "description": "List every active, verified beneficiary saved by this API user, newest first. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_payout_beneficiaries", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "items": [ { "id": 14029, "beneficiary_id": "BEN14029", "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank", "nickname": "Vendor Kotak", "mobile": "9876543210", "status": "active", "created_at": "2026-10-04T08:00:00+05:30" } ], "total": 1, "page": 1, "per_page": 20 }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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/{biller_id}/plans": { "get": { "summary": "Biller Plans", "description": "Plans for billers whose `plan_mode` is `MANDATORY` or `OPTIONAL` (for example DTH or FASTag). Returns an empty list when the biller has no plans. Pay the plan by sending its `amount`.", "operationId": "get_api_v1_bbps_billers_biller_id_plans", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "biller_id", "in": "path", "required": true, "description": "Biller id", "schema": { "type": "string" } }, { "name": "biller_id", "in": "query", "required": true, "description": "Biller id (path)", "schema": { "type": "string" }, "example": "DISH00000NAT01" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": [ { "plan_id": "P1001", "name": "Monthly Pack", "amount": 299, "validity": "30 days", "description": "Base pack", "category": "Monthly" } ], "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/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/ekyc/status": { "post": { "summary": "eKYC Status Check", "description": "OPTIONAL check \u2014 Is eKYC complete for this merchant?\n\nWhen to use: after Step 5, or any time you are not sure whether eKYC is finished.\nRequired: merchantLoginId + merchantPin (from Step 1).\nRead `stage` / `next_action` in the response and follow it (see the stage table in the introduction).\n\nTip: for a full picture of a merchant (stage, bank eKYC, daily 2FA) use `GET /api/v1/aeps/merchant-status`.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_ekyc_status", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant login ID", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant login PIN", "example": "YOUR_MERCHANT_PIN" }, "deviceIMEI": { "type": "string", "description": "Capture device IMEI / serial (max 50)", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "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" }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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" } } } }, "/xpress-payout/history": { "get": { "summary": "Payout History", "description": "List past payouts for this API user with date-range, status, and pagination filters. Maximum 90-day window per request. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_xpress_payout_history", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "from_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "schema": { "type": "string" }, "example": "2026-08-12" }, { "name": "to_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD). Defaults to today. Max window: 90 days.", "schema": { "type": "string" }, "example": "2026-09-11" }, { "name": "status", "in": "query", "required": false, "description": "Filter by transaction status.", "schema": { "type": "string" }, "example": "success" }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page. Defaults to 20.", "schema": { "type": "integer" }, "example": 20 } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "items": [ { "id": 53101, "transaction_id": "MYAPP17899650546285908", "reference_id": "MYAPP17899650546285908", "status": "success", "amount": 100, "charge": 7, "gst": 1.26, "total_deducted": 108.26, "mode": "IMPS", "utr_number": "625110238639", "beneficiary": { "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank" }, "created_at": "2026-10-04T10:03:49+05:30", "completed_at": "2026-10-04T10:04:12+05:30" } ], "pagination": { "current_page": 1, "per_page": 20, "total_records": 1, "total_pages": 1 }, "filters": { "status": "success", "from_date": "2026-09-04", "to_date": "2026-10-04" } }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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" } } } }, "/developer/postman/upi-collection": { "get": { "summary": "UPI Collection Postman Collection Download", "description": "Download the complete, ready-to-run UPI Collection Postman collection for this portal.\n\nWhat is inside:\n\u2022 All 5 UPI Collection endpoints in flow order \u2014 Dynamic QR, Payment Link, UPI Collect Request, Payment Status and Collection History.\n\u2022 Ready-to-run example request data and saved responses for success (paid / pending / expired / failed) and every common error.\n\u2022 Automatic HMAC-SHA256 request signing \u2014 fill only client_id and client_secret in the Variables tab.\n\u2022 Automatic chaining \u2014 a unique reference_id is generated for every create call and the returned order id is reused by Check Payment Status.\n\nHow to use (2 minutes):\n1. Click Download below (or open URL): https://nxtbanking.ai/developer/postman/upi-collection\n2. In Postman: File \u2192 Import \u2192 select the downloaded file.\n3. Open the collection \u2192 Variables tab \u2192 enter your client_id and client_secret from Dashboard \u2192 API Credentials \u2192 Save.\n4. Run folder 1 (create a collection), then folder 2 (check status) and folder 3 (history).", "operationId": "get_developer_postman_upi_collection", "tags": [ "collection" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "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" } } } }, "/onboarding/activation/biometric/submit": { "post": { "summary": "Submit Biometric eKYC", "description": "STEP 3 (final) of activation: submit the encrypted PID block produced by your RD service (Mantra, Morpho, Startek, etc.) along with location coordinates. On success the outlet enters `biometric_submitted` and the partner bank typically approves within minutes (rare cases up to a few hours). Poll /status until `state=active`.", "operationId": "post_api_v1_onboarding_activation_biometric_submit", "tags": [ "onboarding-activation" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference_key": { "type": "string", "description": "Reference key from /biometric/status." }, "pid_data": { "type": "string", "description": "Encrypted PID block JSON from your RD service." }, "biometric_type": { "type": "string", "description": "`FINGERPRINT` or `FACE`.", "example": "FINGERPRINT" }, "latitude": { "type": "number", "description": "Decimal latitude of the merchant location.", "example": 28.6139 }, "longitude": { "type": "number", "description": "Decimal longitude of the merchant location.", "example": 77.209 } }, "required": [ "reference_key", "pid_data", "biometric_type", "latitude", "longitude" ], "example": { "reference_key": "bm_2f8ad...", "pid_data": "{\"pidData\": \"\", \"skey\": \"...\", \"hmac\": \"...\"}", "biometric_type": "FINGERPRINT", "latitude": 28.6139, "longitude": 77.209 } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "statuscode": "TXN", "status": "success", "message": "Biometric eKYC submitted. Awaiting partner bank approval.", "data": { "state": "biometric_submitted", "next_action": "biometric_approval" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/aeps/two-fa": { "post": { "summary": "Two-Factor Authentication", "description": "STEP 6 of 11 \u2014 Daily merchant authentication (once per day)\n\nWhat it does: the merchant scans their finger/face once every calendar day (India time). Without it, transactions are refused with `TWO_FA_REQUIRED`.\nDo it separately for each service: `serviceType` = `AEPS` (cash withdrawal / deposit / balance / statement) and `AP` (Aadhaar Pay).\n\nBefore this: eKYC completed (Steps 2\u20135).\nNext step: Step 7 (banks) \u2192 Step 8 (capture-directive) \u2192 Step 10 (transaction).\n\nRequired: merchantLoginId + merchantPin (from Step 1), `captureResponse`. Optional: `serviceType`, `latitude`, `longitude`.\n\nCommon errors:\n\u2022 `BANK_EKYC_PENDING` \u2192 the bank wants eKYC again (new merchant first time, or inactive 90+ days). Run Steps 2 \u2192 3 \u2192 5, then call this step again. Do not keep retrying 2FA.\n\u2022 `BIOMETRIC_MISMATCH` \u2192 scan again.\n\u2022 `EKYC_NOT_COMPLETED` \u2192 finish Steps 2\u20135 first.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_two_fa", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "captureResponse": { "type": "object", "description": "Full RD-service capture (PID data) as returned by the device. Must include the PID payload and a timestamp (ts). Get PidOptions from Step 8 (capture-directive)." }, "serviceType": { "type": "string", "description": "AEPS (default: CW / CD / BE / MS) or AP (Aadhaar Pay). Each needs its own daily 2FA.", "example": "AEPS" }, "latitude": { "type": "number", "description": "GPS latitude.", "example": 26.9124 }, "longitude": { "type": "number", "description": "GPS longitude.", "example": 75.7873 }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin", "captureResponse" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "serviceType": "AEPS", "captureResponse": { "errCode": "0", "fCount": "1", "fType": "2", "dpID": "DEVICE.PROVIDER", "rdsID": "RDS.ID.001", "rdsVer": "1.0.8", "mi": "MODEL", "mc": "MIIEGDCCAwCg...", "sessionKey": "dGVz...", "hmac": "Ymlu...", "PidDatatype": "X", "Piddata": "BASE64_ENCODED_PID_DATA", "ts": "2026-10-03T12:00:00.000Z" }, "latitude": 26.9124, "longitude": 75.7873 } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "2FA authentication successful", "next_action": "transact", "data": { "serviceType": "AEPS", "expires_at": "2026-10-03T23:59:59+05:30", "stage": "ready" }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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/bills/validate": { "post": { "summary": "Validate Bill", "description": "Checks the customer details with the biller before payment, for billers whose `validation_mode` is not `NOT_SUPPORTED`. No money moves. `valid: false` carries a `reason_code` from the error list.", "operationId": "post_api_v1_bbps_bills_validate", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "biller_id": { "type": "string", "description": "Biller id", "example": "MAHA00000NAT01" }, "customer_params": { "type": "object", "description": "Customer parameters keyed by name from Biller Details" }, "customer_mobile": { "type": "string", "description": "Customer 10-digit mobile number" }, "amount": { "type": "number", "description": "Amount in rupees, when the biller validates amounts" } }, "required": [ "biller_id", "customer_params" ], "example": { "biller_id": "MAHA00000NAT01", "customer_params": { "Consumer Number": "000000000000" }, "amount": 1250 } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": { "biller_id": "MAHA00000NAT01", "valid": true, "reason_code": null, "message": "The customer details are valid for this biller." }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/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" } } } }, "/developer/postman/xpress-payout": { "get": { "summary": "Xpress Payout Postman Collection Download", "description": "Download a ready-to-run Postman collection for every Xpress Payout endpoint. Requests are signed automatically; fill in only client_id and client_secret.", "operationId": "get_developer_postman_xpress_payout", "tags": [ "payout/xpress-payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "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/banks": { "get": { "summary": "AEPS Bank List", "description": "STEP 7 of 11 \u2014 Get the customer's bank list\n\nWhat it does: returns banks with their IIN. Show this list to the customer and send the chosen `iin` as `nationalBankIdentificationNumber` in Step 10.\n`face_auth: true` means the bank accepts face authentication.\n\nQuery: `type` = `aeps` (default) or `aadhaar_pay`.\nCache the list for a few hours; no need to call before every transaction.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "get_api_v1_aeps_banks", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "aeps (default) or aadhaar_pay", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Bank list", "data": { "type": "aeps", "count": 3, "banks": [ { "iin": "607152", "bank_name": "HDFC Bank", "face_auth": true }, { "iin": "607094", "bank_name": "State Bank of India", "face_auth": true }, { "iin": "508534", "bank_name": "ICICI Bank", "face_auth": false } ] }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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" } } } }, "/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/fetch": { "post": { "summary": "Fetch Bill", "description": "Fetches the outstanding bill. No money moves. Pay it with Pay Bill using the returned `fetch_id`; the same request within 10 minutes returns the same unpaid fetch.\n\nAlso available as `POST /api/v1/bbps/bills/fetch`.", "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": "Biller id", "example": "MAHA00000NAT01" }, "customer_params": { "type": "object", "description": "Customer parameters keyed by name from Biller Details" }, "customer_mobile": { "type": "string", "description": "Customer 10-digit mobile number" } }, "required": [ "biller_id", "customer_params", "customer_mobile" ], "example": { "biller_id": "MAHA00000NAT01", "customer_params": { "Consumer Number": "000000000000" }, "customer_mobile": "9000000000" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "Bill fetched successfully", "data": { "fetch_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "biller_id": "MAHA00000NAT01", "biller_name": "State Electricity Board", "customer_name": "A CUSTOMER", "bill": { "number": "BILL0001", "date": "2026-10-01", "due_date": "2026-10-20", "period": "MONTHLY", "amount": 1250 }, "amount_exactness": "EXACT_OR_ABOVE", "amount_options": [ { "name": "Early Payment Amount", "amount": 1230 } ], "additional_info": [ { "name": "Units Consumed", "value": "180" } ] }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/payout/beneficiaries/{id}": { "get": { "summary": "Get Payout Beneficiary", "description": "Fetch a single beneficiary owned by this API user. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_payout_beneficiaries_id", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": true, "description": "beneficiary_id from the add/list response.", "schema": { "type": "integer" }, "example": 101 } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Beneficiary saved.", "data": { "beneficiary_id": 101, "name": "RAHUL SHARMA", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "KOTAK MAHINDRA BANK LIMITED", "nickname": "Vendor Kotak", "mobile": "9876543210", "is_verified": true, "verified_at": "2026-09-11T10:04:12+05:30", "is_active": 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" } } } }, "/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" } } } }, "/aeps/capture-directive": { "post": { "summary": "AEPS Capture Directive", "description": "STEP 8 of 11 \u2014 Get the PidOptions for the biometric device\n\nWhat it does: returns `pid_options` JSON object to pass to the RD service before every scan (eKYC, daily 2FA and transactions). Never hardcode PidOptions \u2014 values differ per operation.\n\nRequired: `operation` = `CW` | `BE` | `MS` | `CD` | `M` | `two_fa` | `ekyc`. Optional: `auth_mode` = `FINGER` (default) or `FACE`, `nationalBankIdentificationNumber`, `transactionAmount`.\nNext step: scan with the RD device, then send the device output as `captureResponse`.\n\nCommon errors:\n\u2022 `FACE_AUTH_UNSUPPORTED_BANK` \u2192 that bank does not support face; use FINGER.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_capture_directive", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "description": "CW | BE | MS | CD | M | two_fa | ekyc", "example": "CW" }, "auth_mode": { "type": "string", "description": "FINGER (default) or FACE", "example": "FINGER" }, "nationalBankIdentificationNumber": { "type": "string", "description": "Customer bank IIN (from Step 7).", "example": "607152" }, "transactionAmount": { "type": "number", "description": "Amount, for CW / M.", "example": 1000 } }, "required": [ "operation" ], "example": { "operation": "CW", "auth_mode": "FINGER" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Capture directive issued", "data": { "operation": "CW", "auth_mode": "FINGER", "pid_options": { "wadh": "", "fType": "2", "pidVer": "2.0", "env": "P", "timeout": "10000", "posh": "UNKNOWN" }, "allowed_auth_modes": [ "FINGER", "FACE" ], "otp": { "required": false, "threshold": "5000" } }, "operation": "CW", "auth_mode": "FINGER", "pid_options": { "wadh": "", "fType": "2", "pidVer": "2.0", "env": "P", "timeout": "10000", "posh": "UNKNOWN" }, "allowed_auth_modes": [ "FINGER", "FACE" ], "otp": { "required": false, "threshold": "5000" }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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": "Send an IMPS / NEFT / RTGS transfer to a bank account. Requires a `bene_token` from POST /payout/beneficiaries/verify \u2014 verify the beneficiary first. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "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": "Your unique transaction reference. Max 40 characters. Must be unique (checked against reports.txnid).", "example": "MYAPP1699523456789" }, "account_holder_name": { "type": "string", "description": "Beneficiary name as per bank records. Letters and spaces only. Alias: beneficiary_name.", "example": "Rahul Sharma" }, "account_number": { "type": "string", "description": "Beneficiary bank account number. Digits only.", "example": "9448272727" }, "ifsc_code": { "type": "string", "description": "IFSC of the beneficiary branch. Format: 4 letters + 0 + 6 alphanumeric.", "example": "KKBK0005333" }, "amount": { "type": "number", "description": "Transfer amount in INR. Minimum \u20b9100. Mode rules: IMPS/NEFT up to \u20b92,00,000; RTGS only above \u20b92,00,000.", "example": 100 }, "mode": { "type": "string", "description": "Transfer mode. Optional \u2014 defaults to IMPS when omitted. Case-insensitive.", "example": "IMPS" }, "mobile": { "type": "string", "description": "Beneficiary mobile number (10 digits).", "example": "9876543210" }, "remarks": { "type": "string", "description": "Optional remarks.", "example": "Payment for services" }, "latitude": { "type": "number", "description": "GPS latitude.", "example": 28.7041 }, "longitude": { "type": "number", "description": "GPS longitude.", "example": 77.1025 }, "purpose": { "type": "string", "description": "Free-text purpose. Prefer purpose_code + purpose_note \u2014 those feed compliance review.", "example": "Payment for services" }, "purpose_code": { "type": "string", "description": "Declared reason for the transfer. Use one of the catalog codes (SALARY_WAGES, VENDOR_PAYMENT, CUSTOMER_REFUND, \u2026). OTHER requires purpose_note. Strongly recommended \u2014 missing or junk purpose increases review risk.", "example": "VENDOR_PAYMENT" }, "purpose_note": { "type": "string", "description": "Short reason in your own words. Required when purpose_code=OTHER. Minimum 8 characters when sent.", "example": "Invoice INV-2041 for September supply" }, "bene_token": { "type": "string", "description": "REQUIRED. The `payout_token` returned by POST /api/v1/payout/beneficiaries/verify. HMAC-signed, bound to this user + account + IFSC, valid 4 hours and single-use. The bank-verified name carried by the token replaces `account_holder_name`. Missing, expired, already-used, or wrong-account tokens are refused (BENE_TOKEN_*). Re-verify the account before each payout.", "example": "eyJ1aWQiOjEyMywiYWNjIjoiOTQ0ODI3MjcyNyJ9.9f2c..." } }, "required": [ "transaction_id", "account_holder_name", "account_number", "ifsc_code", "amount", "bene_token" ], "example": { "transaction_id": "YOUR-UNIQUE-TXN-REFERENCE", "account_holder_name": "Rahul Sharma", "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", "purpose_code": "VENDOR_PAYMENT", "purpose_note": "Invoice INV-2041 for September supply", "bene_token": "" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "success", "message": "Payout transfer processed successfully", "data": { "transaction_id": "MYAPP17899650546285908", "reference_id": "MYAPP17899650546285908", "status": "success", "amount": 100, "charge": 7, "gst": 1.26, "total_deducted": 108.26, "mode": "IMPS", "utr_number": "625110238639", "bank_ref_num": "625110238639", "beneficiary": { "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank" }, "created_at": "2026-10-04T10:03:49+05:30", "completed_at": "2026-10-04T10:04:12+05:30" }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "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": "Pays a bill from your wallet.\n\n- `client_ref_id` is your unique id for this payment. Retrying with the same `client_ref_id` never pays twice: it returns the original transaction (`meta.replayed: true`). Reusing it for a different biller or amount returns `CLIENT_REF_ID_REUSED`.\n- Billers with `fetch_mode: MANDATORY` need `fetch_id` from Fetch Bill; `customer_params` and `customer_mobile` are then taken from the fetch.\n- HTTP 200 + `status: SUCCESS` is final. HTTP 202 + `status: PENDING` means the bill network has not confirmed yet: poll Transaction Status; do not pay again.\n- `remitter` is required above Rs 50,000.\n\nAlso available as `POST /api/v1/bbps/bills/pay`.", "operationId": "post_api_v1_bbps_pay", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_ref_id": { "type": "string", "description": "Your unique payment id, 6 to 64 characters of A-Z a-z 0-9 . _ -", "example": "ORDER-000001" }, "biller_id": { "type": "string", "description": "Biller id", "example": "MAHA00000NAT01" }, "fetch_id": { "type": "string", "description": "fetch_id from Fetch Bill (required when fetch_mode is MANDATORY)" }, "customer_params": { "type": "object", "description": "Required when fetch_id is not sent" }, "customer_mobile": { "type": "string", "description": "Required when fetch_id is not sent" }, "amount": { "type": "number", "description": "Amount in rupees, up to 2 decimals, 1 to 200000" }, "remitter": { "type": "object", "description": "{name, pan or aadhaar_last4}; required above Rs 50,000" } }, "required": [ "client_ref_id", "biller_id", "amount" ], "example": { "client_ref_id": "ORDER-000001", "biller_id": "MAHA00000NAT01", "fetch_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "amount": 1250 } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "Bill payment successful", "data": { "transaction_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "client_ref_id": "ORDER-000001", "status": "SUCCESS", "biller_id": "MAHA00000NAT01", "biller_name": "State Electricity Board", "category": "Electricity", "amount": 1250, "charges": { "fee": 5, "gst": 0.9, "total": 1255.9 }, "bbps_reference_id": "BB0000000000000000", "biller_reference": "BR000000001", "closing_balance": 8744.1, "created_at": "2026-10-23T10:00:00+05:30", "updated_at": "2026-10-23T10:00:04+05:30" }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/aeps/transaction-otp": { "post": { "summary": "AEPS Transaction OTP", "description": "STEP 9 of 11 \u2014 Customer OTP for high-value transactions (only when needed)\n\nWhen to use: Cash Withdrawal (CW) or Aadhaar Pay (M) ABOVE \u20b95,000. Not needed for BE / MS / CD or smaller amounts.\nWhat it does: sends an OTP to the customer's Aadhaar-linked mobile and returns `otp_reference`.\n\nRequired: merchantLoginId + merchantPin (from Step 1), `operation` (or `transactionType`), `transactionAmount`, `adhaarNumber` (customer), `nationalBankIdentificationNumber`, `mobileNumber`. Optional: `latitude`, `longitude`.\nNext step: Step 10 (transaction) with `otp_reference`.\n\nCommon errors:\n\u2022 `OTP_REQUIRED` (from Step 10) \u2192 you skipped this step for an amount above \u20b95,000.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_transaction_otp", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "transactionType": { "type": "string", "description": "CW or M", "example": "CW" }, "transactionAmount": { "type": "number", "description": "Amount in INR (above 5000).", "example": 6000 }, "adhaarNumber": { "type": "string", "description": "Customer 12-digit Aadhaar.", "example": "234567890123" }, "nationalBankIdentificationNumber": { "type": "string", "description": "Customer bank IIN (Step 7).", "example": "607152" }, "mobileNumber": { "type": "string", "description": "Customer mobile.", "example": "9876543210" }, "latitude": { "type": "number", "description": "GPS latitude.", "example": 26.9124 }, "longitude": { "type": "number", "description": "GPS longitude.", "example": 75.7873 }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "merchantLoginId", "merchantPin", "transactionType", "transactionAmount", "adhaarNumber", "nationalBankIdentificationNumber", "mobileNumber" ], "example": { "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "transactionType": "CW", "transactionAmount": 6000, "adhaarNumber": "234567890123", "nationalBankIdentificationNumber": "607152", "mobileNumber": "9876543210", "latitude": 26.9124, "longitude": 75.7873 } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "OTP sent to customer", "canonical_code": "OTP_SENT", "otp_required": true, "otp_reference": "OTPREF8K2M4Q7X", "validity": "2026-10-03T18:17:44+05:30", "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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/{transaction_id}": { "get": { "summary": "BBPS Transaction Status", "description": "Current state of a payment, by `transaction_id` or your `client_ref_id`. Statuses: `FETCHED`, `PENDING`, `SUCCESS`, `FAILED`, `REFUNDED`, `UNDER_REVIEW`.\n\nAlso available as `GET /api/v1/bbps/transactions/{transaction_id}`.", "operationId": "get_api_v1_bbps_status_transaction_id", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Transaction id", "schema": { "type": "string" } }, { "name": "transaction_id", "in": "query", "required": true, "description": "transaction_id from Pay Bill, or your client_ref_id (path)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": { "transaction_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "client_ref_id": "ORDER-000001", "status": "SUCCESS", "biller_id": "MAHA00000NAT01", "biller_name": "State Electricity Board", "category": "Electricity", "amount": 1250, "charges": { "fee": 5, "gst": 0.9, "total": 1255.9 }, "bbps_reference_id": "BB0000000000000000", "biller_reference": "BR000000001", "closing_balance": 8744.1, "created_at": "2026-10-23T10:00:00+05:30", "updated_at": "2026-10-23T10:00:04+05:30" }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/payout/status": { "post": { "summary": "Check Payout Status", "description": "Poll the outcome of a payout using its `transaction_id`. Retry until `data.status` is `success`, `failed`, or `refunded`. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "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": "The unique transaction_id sent in Step 9.", "example": "MYAPP17899650546285908" } }, "required": [ "transaction_id" ], "example": { "transaction_id": "MYAPP17899650546285908" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "transaction_id": "MYAPP17899650546285908", "reference_id": "MYAPP17899650546285908", "status": "success", "amount": 100, "charge": 7, "gst": 1.26, "total_deducted": 108.26, "utr_number": "625110238639", "beneficiary": { "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank" }, "created_at": "2026-10-04T10:03:49+05:30", "completed_at": "2026-10-04T10:04:12+05:30", "changed": false, "message": "Transaction successful", "refunded": false, "refund_amount": null }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/aeps/transaction": { "post": { "summary": "AEPS Unified Transaction", "description": "STEP 10 of 11 \u2014 Do the AEPS transaction\n\n`transactionType`: `CW` Cash Withdrawal \u00b7 `BE` Balance Enquiry \u00b7 `MS` Mini Statement \u00b7 `CD` Cash Deposit \u00b7 `M` Aadhaar Pay.\n\nBefore this: today's daily 2FA (Step 6) for this merchant, bank IIN (Step 7), customer scan using PidOptions (Step 8). For CW / M above \u20b95,000 also Step 9.\n\nRequired: merchantLoginId + merchantPin (from Step 1), `transactionType`, `adhaarNumber` (customer, 12 digits), `indicatorforUID` (0 = Aadhaar), `nationalBankIdentificationNumber`, `captureResponse`.\n`transactionAmount` is required for CW / CD / M (\u20b9100 \u2013 \u20b910,000).\nSend your own unique `transaction_id` (max 50) \u2014 you need it for Step 11.\n\nRead `status` in the response:\n\u2022 `success` \u2192 done. \u2022 `failed` \u2192 no money moved; a new attempt needs a NEW transaction_id. \u2022 `pending` \u2192 call Step 11 with the SAME transaction_id. Never re-send a pending one.\nSet your HTTP timeout to at least 200 seconds. On timeout, call Step 11 \u2014 do not retry.\n\nCommon errors:\n\u2022 `TWO_FA_REQUIRED` \u2192 run Step 6 for today, then retry.\n\u2022 `BANK_EKYC_PENDING` \u2192 run Steps 2 \u2192 3 \u2192 5, then Step 6.\n\u2022 `OTP_REQUIRED` \u2192 amount above \u20b95,000; run Step 9 first.\n\u2022 `BIOMETRIC_MISMATCH` \u2192 customer scans again (new transaction_id).\n\u2022 Bank decline codes (51 insufficient funds, 52/53 no account, 91/08 bank down\u2026) \u2192 see the bank code table in #guide/aeps-error-codes\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_transaction", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionType": { "type": "string", "description": "CW | BE | MS | CD | M", "example": "CW" }, "merchantLoginId": { "type": "string", "description": "Merchant id returned by Step 1 (onboard). Send it unchanged.", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant PIN returned by Step 1 (onboard).", "example": "YOUR_MERCHANT_PIN" }, "adhaarNumber": { "type": "string", "description": "Customer 12-digit Aadhaar (alias: aadhaarNumber).", "example": "234567890123" }, "indicatorforUID": { "type": "string", "description": "0 = Aadhaar number, 2 = Virtual ID.", "example": "0" }, "nationalBankIdentificationNumber": { "type": "string", "description": "Customer bank IIN from Step 7.", "example": "607152" }, "captureResponse": { "type": "object", "description": "Full RD-service capture (PID data) as returned by the device. Must include the PID payload and a timestamp (ts). Get PidOptions from Step 8 (capture-directive)." }, "transactionAmount": { "type": "number", "description": "Required for CW / CD / M. 100 \u2013 10000.", "example": 1000 }, "transaction_id": { "type": "string", "description": "Your unique id (max 50). Recommended \u2014 used for status checks.", "example": "PARTNER-TXN-0001" }, "otp_reference": { "type": "string", "description": "From Step 9. Required for CW / M above 5000.", "example": "OTPREF_123456" }, "mobileNumber": { "type": "string", "description": "Customer mobile.", "example": "9876543210" }, "latitude": { "type": "number", "description": "GPS latitude.", "example": 26.9124 }, "longitude": { "type": "number", "description": "GPS longitude.", "example": 75.7873 }, "virtualId": { "type": "string", "description": "Customer Virtual ID (when indicatorforUID = 2)." }, "remarks": { "type": "string", "description": "Free text (max 200)." }, "deviceIMEI": { "type": "string", "description": "Device IMEI / serial (max 50).", "example": "358240051111110" } }, "required": [ "transactionType", "merchantLoginId", "merchantPin", "adhaarNumber", "indicatorforUID", "nationalBankIdentificationNumber", "captureResponse" ], "example": { "transactionType": "CW", "merchantLoginId": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "transaction_id": "PARTNER-TXN-0001", "transactionAmount": 1000, "adhaarNumber": "234567890123", "indicatorforUID": "0", "nationalBankIdentificationNumber": "607152", "mobileNumber": "9876543210", "latitude": 26.9124, "longitude": 75.7873, "captureResponse": { "errCode": "0", "fCount": "1", "fType": "2", "dpID": "DEVICE.PROVIDER", "rdsID": "RDS.ID.001", "rdsVer": "1.0.8", "mi": "MODEL", "mc": "MIIEGDCCAwCg...", "sessionKey": "dGVz...", "hmac": "Ymlu...", "PidDatatype": "X", "Piddata": "BASE64_ENCODED_PID_DATA", "ts": "2026-10-03T12:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Transaction successful", "data": { "transaction_id": "TXN1791041234567123", "status": "success", "rrn": "627618856357", "amount": 1000, "charge": 0, "gst": 0, "tds": 0, "balance_info": { "available_balance": 15240.5, "account_number": null }, "statement": null }, "status": "success", "merchant_tran_id": "TXN1791041234567123", "rrn": "627618856357", "amount": "1000", "balance": "15240.50", "statement": null, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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/reasons": { "get": { "summary": "Complaint Reasons", "description": "The reasons a complaint can be raised for. Send `reason_code` when raising a complaint.", "operationId": "get_api_v1_bbps_complaints_reasons", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": [ { "reason_code": "TXN_SUCCESS_NO_SERVICE", "description": "Transaction Successful, Amount Debited but services not received" }, { "reason_code": "TXN_SUCCESS_SERVICE_STOPPED", "description": "Transaction Successful, Amount Debited but Service Disconnected or Service Stopped" } ], "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/payout/history": { "get": { "summary": "Payout History", "description": "List past payouts for this API user with date-range, status, and pagination filters. Maximum 90-day window per request. See [#guide/status-codes](#guide/status-codes) for status meanings and [#errors](#errors) for every error code, precaution, and retry rule.", "operationId": "get_api_v1_payout_history", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "from_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD). Defaults to 30 days ago.", "schema": { "type": "string" }, "example": "2026-08-12" }, { "name": "to_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD). Defaults to today. Max window: 90 days.", "schema": { "type": "string" }, "example": "2026-09-11" }, { "name": "status", "in": "query", "required": false, "description": "Filter by transaction status.", "schema": { "type": "string" }, "example": "success" }, { "name": "per_page", "in": "query", "required": false, "description": "Items per page. Defaults to 20.", "schema": { "type": "integer" }, "example": 20 } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "items": [ { "id": 53101, "transaction_id": "MYAPP17899650546285908", "reference_id": "MYAPP17899650546285908", "status": "success", "amount": 100, "charge": 7, "gst": 1.26, "total_deducted": 108.26, "mode": "IMPS", "utr_number": "625110238639", "beneficiary": { "name": "Rahul Sharma", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "bank_name": "Kotak Mahindra Bank" }, "created_at": "2026-10-04T10:03:49+05:30", "completed_at": "2026-10-04T10:04:12+05:30" } ], "pagination": { "current_page": 1, "per_page": 20, "total_records": 1, "total_pages": 1 }, "filters": { "status": "success", "from_date": "2026-09-04", "to_date": "2026-10-04" } }, "meta": { "trace_id": "pay_k9v2x4m7q1w8e5r3t0y6" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/aeps/status": { "post": { "summary": "AEPS Transaction Status", "description": "STEP 11 of 11 \u2014 Check a transaction (only when pending or timed out)\n\nWhen to use: Step 10 returned `pending`, or your call timed out. Use the SAME `transaction_id`.\nPolling: every 30\u201360 seconds, up to about 15 minutes. Most pending transactions settle within minutes; a few are settled by the bank by the next working day.\n\nRequired: `transaction_id`, merchantLoginId + merchantPin (from Step 1).\nFinal statuses: `success`, `failed`, `reversed`. Stop polling once you get one.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "post_api_v1_aeps_status", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Transaction ID to look up (alias: `txnId`, `transactionId`)", "example": "AEPS-CW-20260227143022-1234" }, "merchantLoginId": { "type": "string", "description": "Merchant login ID", "example": "YOUR_MERCHANT_LOGIN_ID" }, "merchantPin": { "type": "string", "description": "Merchant login PIN", "example": "YOUR_MERCHANT_PIN" }, "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": "YOUR_MERCHANT_LOGIN_ID", "merchantPin": "YOUR_MERCHANT_PIN", "deviceIMEI": "358240051111110" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Transaction status fetched successfully", "data": { "transaction_id": "TXN1791041234567123", "status": "success", "rrn": "627618856357", "amount": 1000, "response_code": "00", "response_message": "Transaction successful" }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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" } } } }, "/developer/postman/payout": { "get": { "summary": "Payout Postman Collection Download", "description": "Download the complete, ready-to-run Payout Postman collection for this portal.\n\nWhat is inside:\n\u2022 All 11 Payout endpoints ordered sequentially \u2014 discovery (modes, purpose codes, balance), beneficiary verification & management, payout initiate, status polling, and transaction history.\n\u2022 Ready-to-run example request data on every endpoint and saved success / error responses for all scenarios (validation errors, duplicate transaction ID, insufficient funds, expired tokens, cooling period, hold).\n\u2022 Automatic HMAC-SHA256 request signing via Pre-request script (calculates X-Client-ID, X-Timestamp, X-Request-ID, and X-Signature). Only client_id and client_secret need to be filled in.\n\u2022 Automatic token and ID chaining \u2014 verification_id, bene_token (payout_token), beneficiary_id, and transaction_id are auto-extracted from responses and injected into subsequent requests.\n\u2022 Dynamic transaction_id generation for initiate calls, preventing 409 collisions on repeated test runs.\n\nHow to use (2 minutes):\n1. Click Download below (or open URL): https://nxtbanking.ai/developer/postman/payout\n2. In Postman: File \u2192 Import \u2192 select the downloaded file.\n3. Open the collection \u2192 Variables tab \u2192 enter your client_id and client_secret from Dashboard \u2192 API Credentials \u2192 Save.\n4. Execute requests from top to bottom (Folder 1 \u2192 2 \u2192 3 \u2192 4).", "operationId": "get_developer_postman_payout", "tags": [ "payout" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "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": "Raises a complaint on a `SUCCESS` or `FAILED` payment. One open complaint per transaction. Most categories need 24 hours after payment first (`COMPLAINT_NOT_ALLOWED_YET` returns `data.allowed_from`).\n\nAlso available as `POST /api/v1/bbps/complaints`.", "operationId": "post_api_v1_bbps_complaints_raise", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "transaction_id of the payment" }, "reason_code": { "type": "string", "description": "Code from Complaint Reasons", "example": "TXN_SUCCESS_NO_SERVICE" }, "description": { "type": "string", "description": "Free text, up to 500 characters" } }, "required": [ "transaction_id", "reason_code" ], "example": { "transaction_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "reason_code": "TXN_SUCCESS_NO_SERVICE", "description": "Paid but bill still shows due" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "Complaint registered", "data": { "complaint_id": "BANKCMPLQ7W2E9R4T1Y6U3I8O5P0A2S7D4F", "transaction_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "network_complaint_id": "BB0000000000000001", "reason_code": "TXN_SUCCESS_NO_SERVICE", "status": "REGISTERED", "created_at": "2026-10-24T11:00:00+05:30", "resolved_at": null, "history": [ { "at": "2026-10-24T11:00:00+05:30", "status": "REGISTERED" } ] }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/aeps/merchant-status": { "get": { "summary": "AEPS Merchant Status", "description": "MERCHANT TOOL \u2014 Where is this merchant in the flow?\n\nReturns `stage`, `next_action`, `bank_ekyc_required`, `dormant`, `txn_ready` and a step list showing what is done and what is pending.\nUse it whenever you are not sure what to call next \u2014 before raising a ticket.\n\nQuery: `merchantLoginId` (recommended; defaults to your latest merchant). Unknown id \u2192 `MERCHANT_NOT_FOUND`.\nStages: `onboard` \u2192 `ekyc` \u2192 `bank_ekyc` \u2192 `daily_2fa` \u2192 `ready`.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "get_api_v1_aeps_merchant_status", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "merchantLoginId", "in": "query", "required": false, "description": "Merchant to inspect (defaults to latest onboarded).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "merchantLoginId": "MER48210375", "stage": "ready", "next_action": "transact", "bank_ekyc_required": false, "dormant": false, "last_activity_at": "2026-10-03T18:12:44+05:30", "txn_ready": true, "notes": [ "Error BANK_EKYC_PENDING (or next_action \"bank_ekyc\") on ANY call means: run ekyc/send-otp, ekyc/validate-otp, ekyc/biometric again (Bank eKYC), then two-fa.", "A merchant inactive for more than 90 days must repeat Bank eKYC before AEPS works again." ] }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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": "Your complaints, newest first.", "operationId": "get_api_v1_bbps_complaints", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size, 1 to 100 (default 20)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": [ { "complaint_id": "BANKCMPLQ7W2E9R4T1Y6U3I8O5P0A2S7D4F", "transaction_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "network_complaint_id": "BB0000000000000001", "reason_code": "TXN_SUCCESS_NO_SERVICE", "status": "REGISTERED", "created_at": "2026-10-24T11:00:00+05:30", "resolved_at": null, "history": [ { "at": "2026-10-24T11:00:00+05:30", "status": "REGISTERED" } ] } ], "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10:00:00+05:30", "pagination": { "page": 1, "per_page": 20, "total": 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" } } } }, "/aeps/merchants": { "get": { "summary": "AEPS Merchant List", "description": "MERCHANT TOOL \u2014 All merchants under your API account\n\nReturns each merchant's merchantLoginId, name, mobile, stage, next_action, KYC status and last transaction, plus a `summary` count per stage and `pagination`.\n\nQuery: `status` (onboard | ekyc | bank_ekyc | daily_2fa | ready), `q` (search id / name / mobile), `page`, `per_page` (max 100).\nUse it to find the merchantLoginId of an existing mobile (e.g. after `MERCHANT_MOBILE_ALREADY_REGISTERED`).\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "get_api_v1_aeps_merchants", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "onboard | ekyc | bank_ekyc | daily_2fa | ready", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search merchantLoginId, name or mobile", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default 1)", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size, max 100 (default 25)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "merchants": [ { "merchantLoginId": "MER48210375", "name": "RAJESH KUMAR", "mobile": "9876543210", "stage": "ready", "next_action": "transact", "onboarding_status": "completed", "kyc_status": "verified", "bank_ekyc_required": false, "dormant": false, "txn_ready": true, "is_active": true, "last_transaction_at": "2026-10-03T18:12:44+05:30", "onboarded_at": "2026-10-01T18:30:10+05:30" }, { "merchantLoginId": "MER73019264", "name": "SUNITA DEVI", "mobile": "9123456780", "stage": "bank_ekyc", "next_action": "bank_ekyc", "onboarding_status": "completed", "kyc_status": "pending", "bank_ekyc_required": true, "dormant": false, "txn_ready": false, "is_active": true, "last_transaction_at": null, "onboarded_at": "2026-10-03T16:40:00+05:30" } ], "summary": { "total": 2, "ready": 1, "bank_ekyc": 1 }, "pagination": { "page": 1, "per_page": 25, "total": 2, "last_page": 1 } }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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/{complaint_id}/status": { "get": { "summary": "BBPS Complaint Status", "description": "Latest status of one of your complaints, refreshed from the bill network while it is open (`meta.status_refreshed`). Statuses: `REGISTERED`, `ASSIGNED`, `IN_PROGRESS`, `RESOLVED`, `REJECTED`.\n\nAlso available as `GET /api/v1/bbps/complaints/{complaint_id}`.", "operationId": "get_api_v1_bbps_complaints_complaint_id_status", "tags": [ "bbps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "complaint_id", "in": "path", "required": true, "description": "Complaint id", "schema": { "type": "string" } }, { "name": "complaint_id", "in": "query", "required": true, "description": "complaint_id from Raise BBPS Complaint (path)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "status": "SUCCESS", "code": "OK", "message": "OK", "data": { "complaint_id": "BANKCMPLQ7W2E9R4T1Y6U3I8O5P0A2S7D4F", "transaction_id": "B4K9Q2M7X1C8V5N3Z6L0P2R7T9W4Y1H8J3F", "network_complaint_id": "BB0000000000000001", "reason_code": "TXN_SUCCESS_NO_SERVICE", "status": "REGISTERED", "created_at": "2026-10-24T11:00:00+05:30", "resolved_at": null, "history": [ { "at": "2026-10-24T11:00:00+05:30", "status": "REGISTERED" } ] }, "meta": { "request_id": "req-000000000001", "timestamp": "2026-10-23T10: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" } } } }, "/aeps/merchants/{merchantLoginId}": { "get": { "summary": "AEPS Merchant Detail", "description": "MERCHANT TOOL \u2014 One merchant in detail\n\nReturns profile (PAN and bank account masked), current stage / next_action, bank eKYC and dormant flags, and the last 10 transactions.\nPath: `merchantLoginId`. Not yours or unknown \u2192 404 `MERCHANT_NOT_FOUND`.\n\nFull flow: #guide/aeps-introduction\nAll codes: #guide/aeps-error-codes", "operationId": "get_api_v1_aeps_merchants_merchantLoginId", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "merchantLoginId", "in": "path", "required": true, "description": "MerchantLoginId", "schema": { "type": "string" } }, { "name": "merchantLoginId", "in": "path", "required": true, "description": "Merchant id returned by onboard", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "merchantLoginId": "MER48210375", "name": "RAJESH KUMAR", "mobile": "9876543210", "stage": "ready", "next_action": "transact", "txn_ready": true, "profile": { "pan_masked": "AB******4F", "bank_account_masked": "******1234", "bank_ifsc": "SBIN0001234" }, "status_detail": { "stage": "ready", "bank_ekyc_required": false, "dormant": false, "steps": [] }, "recent_transactions": [ { "transaction_id": "TXN1791041234567123", "type": "CW", "amount": 1000, "status": "success", "created_at": "2026-10-03T18:12:44+05:30" } ] }, "meta": { "trace_id": "aeps_k3m9x2p7q1w8e5r4t6y0" } } } } } }, "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" } } } }, "/developer/postman/aeps": { "get": { "summary": "AEPS Postman Collection Download", "description": "Download the complete, ready-to-run AEPS Postman collection for this portal.\n\nWhat is inside:\n\u2022 Every AEPS step in the right order \u2014 merchant setup (onboard, eKYC OTP, biometric), daily 2FA, bank list, capture directive, transaction OTP, transaction, status, merchant list / detail.\n\u2022 Example request data on every call and saved example responses for success AND each common error (validation, bank eKYC pending, OTP invalid, session expired, pending transaction, merchant not found, \u2026).\n\u2022 Automatic request signing \u2014 fill only client_id and client_secret in the collection Variables tab.\n\u2022 Automatic chaining \u2014 merchantLoginId, merchantPin, primaryKeyId, encodeFPTxnId, otp_reference and transaction_id are saved from one response into the next request.\n\nHow to use:\n1. Click Download below (or open this URL): https://nxtbanking.ai/developer/postman/aeps\n2. Postman \u2192 Import \u2192 select the downloaded file.\n3. Collection \u2192 Variables \u2192 set client_id and client_secret \u2192 Save.\n4. Run the folders top to bottom. Replace captureResponse with the real RD-service capture from the merchant device before biometric / 2FA / transaction calls.", "operationId": "get_developer_postman_aeps", "tags": [ "aeps" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "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 a bank account and return the registered holder name. Scheme charge for slug=account-verification is mandatory \u2014 the call is refused with SCHEME_NOT_CONFIGURED / NO_SCHEME_ASSIGNED until admin sets it. Wallet is debited, then refunded if the bank rejects the account.", "operationId": "post_api_v1_verification_account", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_number": { "type": "string", "description": "Account number, 9-18 digits.", "example": "9448272727" }, "ifsc_code": { "type": "string", "description": "11-character IFSC. Uppercased before validation.", "example": "KKBK0005333" }, "account_name": { "type": "string", "description": "Expected holder name. Alias: account_holder_name.", "example": "Rahul Sharma" } }, "required": [ "account_number", "ifsc_code" ], "example": { "account_number": "9448272727", "ifsc_code": "KKBK0005333", "account_name": "Rahul Sharma" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Account verified successfully", "data": { "verification_status": "verified", "account_number": "9448272727", "ifsc_code": "KKBK0005333", "account_name": "RAHUL SHARMA", "charged": 4.72, "verification": { "registered_name": "RAHUL SHARMA", "validation_id": "625110238639", "account_type": "SAVINGS", "validation_status": "A" }, "statuscode": "TXN", "txn_id": "ACV202609081020001234", "pricing_audit_id": 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" } } } }, "/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" } } } }, "/verification/corporate-cin": { "post": { "summary": "Corporate CIN Verification", "description": "Fetch company registration details from a Corporate Identification Number.", "operationId": "post_api_v1_verification_corporate_cin", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "cin": "U72900DL2019PTC349962" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Verification completed.", "data": { "cin": "U72900DL2019PTC349962", "company_name": "EXAMPLE PRIVATE LIMITED", "company_status": "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" } } } }, "/dmt/transfer": { "post": { "summary": "DMT Transfer", "description": "Initiate a money transfer (two-step OTP flow). STEP 1: submit txn detail without `otp`; provider issues OTP + `reference_key`. STEP 2: re-submit with `otp` + `reference_key` to settle. Modes supported: IMPS, NEFT, RTGS. Active rail is selected automatically; per-txn limits depend on the active rail (bank-2 supports higher caps).", "operationId": "post_api_v1_dmt_transfer", "tags": [ "dmt" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mobile": { "type": "string", "description": "Remitter mobile (10 digits)", "example": "9876543210" }, "beneaccount": { "type": "string", "description": "Beneficiary account", "example": "1234567890123" }, "beneifsc": { "type": "string", "description": "IFSC code (11 chars)", "example": "HDFC0001234" }, "amount": { "type": "number", "description": "Amount in INR", "example": 1000 }, "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" } } } }, "/verification/rc": { "post": { "summary": "Vehicle RC Verification", "description": "Fetch vehicle registration details from an RC number.", "operationId": "post_api_v1_verification_rc", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "rc_number": "MH12AB1234" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Verification completed.", "data": { "rc_number": "MH12AB1234", "owner_name": "EXAMPLE OWNER", "fuel_type": "PETROL" } } } } } }, "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/pan-name": { "post": { "summary": "PAN Name Verification", "description": "Fetch the name registered against a PAN.", "operationId": "post_api_v1_verification_pan_name", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "pan": "ABCDE1234F" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Verification completed.", "data": { "pan": "ABCDE1234F", "full_name": "EXAMPLE NAME", "category": "person" } } } } } }, "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/digilocker/create-link": { "post": { "summary": "DigiLocker Link", "description": "Create a DigiLocker link. This call is charged once. Status and Aadhaar download for the same link are not charged again.", "operationId": "post_api_v1_verification_digilocker_create_link", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "redirect_url": "https://example.com/kyc/done" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Verification link created.", "data": { "reference_id": "00000000-0000-4000-8000-000000000000", "link": "https://example.com/digilocker", "expires_in": 600 } } } } } }, "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/digilocker/status": { "post": { "summary": "DigiLocker Status", "description": "Read the status of a DigiLocker link you created. Not charged.", "operationId": "post_api_v1_verification_digilocker_status", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "reference_id": "00000000-0000-4000-8000-000000000000" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Link status fetched.", "data": { "reference_id": "00000000-0000-4000-8000-000000000000", "status": "pending", "completed": 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" } } } }, "/verification/digilocker/aadhaar": { "post": { "summary": "DigiLocker Aadhaar", "description": "Download Aadhaar details after the holder completes the DigiLocker link. Not charged.", "operationId": "post_api_v1_verification_digilocker_aadhaar", "tags": [ "verification" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "reference_id": "00000000-0000-4000-8000-000000000000" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "message": "Aadhaar details fetched.", "data": { "reference_id": "00000000-0000-4000-8000-000000000000", "name": "EXAMPLE NAME", "masked_aadhaar": "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" } } } }, "/connected-banking/accounts": { "get": { "summary": "cb_list_accounts", "description": "Returns all 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_accounts", "tags": [ "payout/connected-banking" ], "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", "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/verify-account": { "post": { "summary": "cb_verify_account", "description": "Runs a penny-drop verification against the bank 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_verify_account", "tags": [ "payout/connected-banking" ], "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/balance": { "get": { "summary": "cb_get_balance", "description": "Fetches the current available balance for a connected 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_balance", "tags": [ "payout/connected-banking" ], "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" } } } }, "/connected-banking/statement": { "post": { "summary": "cb_get_statement", "description": "Fetches a paginated bank statement from the bank 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_statement", "tags": [ "payout/connected-banking" ], "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/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_verify_beneficiary", "tags": [ "payout/connected-banking" ], "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/payout/initiate": { "post": { "summary": "cb_initiate_payout", "description": "Initiates a fund transfer from a connected 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 the connected account), `fee_wallet` (fee from CB wallet).", "operationId": "post_api_v1_connected_banking_payout_initiate", "tags": [ "payout/connected-banking" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connected_account_uuid": { "type": "string", "description": "Source connected account UUID" }, "transaction_id": { "type": "string", "description": "Your unique transaction ID (idempotency key, max 40 chars)", "example": "TXN-2026-001" }, "amount": { "type": "number", "description": "Transfer amount in INR (0.01 \u2013 2,000,000)", "example": 10000 }, "mode": { "type": "string", "description": "Transfer mode: IMPS, NEFT, or RTGS", "example": "IMPS" }, "beneficiary_account": { "type": "string", "description": "Beneficiary bank account number" }, "beneficiary_ifsc": { "type": "string", "description": "Beneficiary IFSC code" }, "beneficiary_name": { "type": "string", "description": "Beneficiary account holder name" }, "remarks": { "type": "string", "description": "Payment narration (max 200 chars)" }, "beneficiary_mobile": { "type": "string", "description": "10-digit mobile number for SMS notification" }, "beneficiary_email": { "type": "string", "description": "Email for payment advice" } }, "required": [ "connected_account_uuid", "transaction_id", "amount", "mode", "beneficiary_account", "beneficiary_ifsc", "beneficiary_name" ], "example": { "connected_account_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "transaction_id": "TXN-2026-001", "amount": 10000, "mode": "IMPS", "beneficiary_account": "1234567890", "beneficiary_ifsc": "SBIN0001234", "beneficiary_name": "John Doe", "remarks": "Invoice #INV-001 settlement" } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "transaction_id": "TXN-2026-001", "reference_id": "CB20260501IMPS001", "status": "pending", "amount": 10000, "charge": 5, "gst": 0.9, "utr_number": null, "billing_mode": "wallet_charge", "report_id": 98765, "initiated_at": "2026-05-01T10:00:00+05:30" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/connected-banking/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 bank 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_payout_status_txn_id", "tags": [ "payout/connected-banking" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "txn_id", "in": "path", "required": true, "description": "Txn id", "schema": { "type": "string" } }, { "name": "txn_id", "in": "query", "required": true, "description": "Your original transaction_id (path parameter, max 40 chars)", "schema": { "type": "string" }, "example": "TXN-2026-001" }, { "name": "refresh", "in": "query", "required": false, "description": "Set to true to poll the bank for a fresh status (only when status=pending)", "schema": { "type": "string" }, "example": "true" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "transaction_id": "TXN-2026-001", "reference_id": "CB20260501IMPS001", "status": "success", "amount": 10000, "charge": 5, "gst": 0.9, "utr_number": "426045678901234", "beneficiary_name": "John Doe", "beneficiary_account": "****7890", "beneficiary_ifsc": "SBIN0001234", "mode": "IMPS", "billing_mode": "wallet_charge", "initiated_at": "2026-05-01T10:00:00+05:30", "last_status_check": "2026-05-01T10:05:00+05:30" } } } } } }, "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/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_payout_history", "tags": [ "payout/connected-banking" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "connected_account_uuid", "in": "query", "required": false, "description": "Filter to a specific connected account", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "description": "Start date (YYYY-MM-DD). Default: 30 days ago", "schema": { "type": "string" } }, { "name": "to_date", "in": "query", "required": false, "description": "End date (YYYY-MM-DD). Default: today", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status: success, pending, failed", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size (1\u2013100, default: 20)", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number (default: 1)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "items": [ { "report_id": 98765, "transaction_id": "TXN-2026-001", "reference_id": "CB20260501IMPS001", "status": "success", "amount": 10000, "charge": 5, "gst": 0.9, "utr_number": "426045678901234", "beneficiary_name": "John Doe", "beneficiary_account": "****7890", "beneficiary_ifsc": "SBIN0001234", "mode": "IMPS", "billing_mode": "wallet_charge", "initiated_at": "2026-05-01T10:00:00+05:30" } ], "pagination": { "total": 42, "per_page": 20, "current_page": 1, "last_page": 3, "from": 1, "to": 20 }, "window": { "from_date": "2026-04-01", "to_date": "2026-04-30" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/connected-banking/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 bank connectivity test.", "operationId": "get_api_v1_connected_banking_health", "tags": [ "payout/connected-banking" ], "security": [ { "HmacAuth": [], "ClientIdAuth": [], "TimestampAuth": [], "RequestIdAuth": [] } ], "parameters": [ { "name": "probe", "in": "query", "required": false, "description": "Set to true to run a live bank connectivity probe", "schema": { "type": "boolean" } }, { "name": "connected_account_uuid", "in": "query", "required": false, "description": "Required when probe=true", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "status": "ok", "pending_payouts": 0, "oldest_pending": null, "active_accounts": 2, "probe": null, "checked_at": "2026-05-01T10:00:00+05:30" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "HmacAuth": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "Lowercase hex HMAC-SHA256 of the canonical string `METHOD|PATH|TIMESTAMP|BODY`, keyed with the secret issued for your X-Client-ID. PATH excludes the query string. BODY is the raw request body with line endings normalised to \\n (empty string for GET)." }, "ClientIdAuth": { "type": "apiKey", "in": "header", "name": "X-Client-ID", "description": "Tenant client identifier (issued via the dashboard). Required alongside X-Signature, X-Timestamp, X-Request-ID." }, "TimestampAuth": { "type": "apiKey", "in": "header", "name": "X-Timestamp", "description": "Unix epoch seconds (UTC). Requests outside the \u00b1300s window are rejected with AUTH_TIMESTAMP_INVALID." }, "RequestIdAuth": { "type": "apiKey", "in": "header", "name": "X-Request-ID", "description": "Per-request UUID v4 used for replay protection. A reused value within 10 minutes is rejected with HTTP 409." }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Sandbox-only API key (not accepted in production). Use HMAC quartet for prod." } }, "schemas": { "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully" }, "data": { "type": "object" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "ERROR_CODE" }, "message": { "type": "string", "example": "Error description" } } }, "PayoutRequest": { "type": "object", "required": [ "amount", "account_number", "ifsc_code", "beneficiary_name", "mode" ], "properties": { "amount": { "type": "number", "format": "double", "minimum": 10, "maximum": 200000, "example": 1000, "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" } } } } } } } } } } }