{ "openapi": "3.1.0", "info": { "title": "Eko Platform Services REST API", "version": "v3", "description": "Public reference for Eko's REST APIs.\n\n**Authentication.** Every request carries `developer_key`, a per-request\n`secret-key` (an HMAC-SHA256 signature), and `secret-key-timestamp`\nheaders. The `ekoHmac` security scheme identifies the partner key; the\ntwo signing headers are modeled as required header parameters because\nno OpenAPI security scheme type can express a per-request HMAC. A\ngenerated client therefore cannot sign on its own — use an EPS SDK or\nthe `x-eko-signing` recipe at the root of this document. See\n/docs/how-auth-works." }, "components": { "responses": { "Unauthorized": { "description": "Authentication failed. For known causes the body `status` (also in `response_type_id`) names the check that failed; see https://eps.eko.in/docs/error-codes#authentication-errors-http-401.", "content": { "application/json": { "examples": { "status_2483": { "summary": "2483 — The developer_key is wrong", "value": { "status": 2483, "response_type_id": 2483, "response_status_id": 1, "message": "Unauthorized" } }, "status_2484": { "summary": "2484 — The secret-key (signature) is wrong", "value": { "status": 2484, "response_type_id": 2484, "response_status_id": 1, "message": "Invalid secret-key or timestamp" } }, "status_2485": { "summary": "2485 — The secret-key-timestamp is more than 2 minutes older or newer than the server clock, or was reused from an earlier request", "value": { "status": 2485, "response_type_id": 2485, "response_status_id": 1, "message": "Expired security headers (secret-key-timestamp older than 2 minutes)" } }, "status_2486": { "summary": "2486 — The secret-key-timestamp is not in milliseconds (13 digits) — often seconds (10 digits)", "value": { "status": 2486, "response_type_id": 2486, "response_status_id": 1, "message": "Invalid secret-key-timestamp (expected milliseconds since the UNIX epoch)" } }, "status_2487": { "summary": "2487 — The secret-key or secret-key-timestamp header is missing", "value": { "status": 2487, "response_type_id": 2487, "response_status_id": 1, "message": "Missing security headers" } } } } } } }, "securitySchemes": { "ekoHmac": { "type": "apiKey", "in": "header", "name": "developer_key", "description": "Identifies the partner. NOT sufficient on its own: every request must also carry `secret-key` = base64(HMAC-SHA256(secret-key-timestamp, base64(access_key))) and `secret-key-timestamp` (ms since epoch), both sent as headers. Generated clients cannot compute this — use an EPS SDK or follow `x-eko-signing`. Known-answer test vector: timestamp 1700000000000 with access_key test-access-key-123 → secret-key 88lqTf9ew69XbVbeczjxVL8/B4vibfp1MvTi1mIj2Xo=. Docs: https://eps.eko.in/docs/how-auth-works" } } }, "security": [ { "ekoHmac": [] } ], "x-eko-signing": { "algorithm": "HMAC-SHA256", "key": "base64(access_key), used as the literal string bytes (do not decode)", "message": "secret-key-timestamp (current time in ms since epoch, as a string)", "output": "base64(signature) → `secret-key` header", "headers": [ "developer_key", "secret-key", "secret-key-timestamp" ], "steps": [ "Base64-encode the access_key.", "Generate the current timestamp in milliseconds (as a string).", "Compute HMAC-SHA256 of the timestamp using the base64-encoded key.", "Base64-encode the resulting signature — this is the secret-key." ], "testVector": { "accessKey": "test-access-key-123", "timestamp": "1700000000000", "secretKey": "88lqTf9ew69XbVbeczjxVL8/B4vibfp1MvTi1mIj2Xo=" }, "docsUrl": "https://eps.eko.in/docs/how-auth-works", "backendOnly": "access_key is a server-side secret; never sign in a browser or ship it to a client." }, "servers": [ { "url": "https://staging.eko.in/ekoapi/v3", "description": "UAT / Sandbox" }, { "url": "https://api.eko.in/ekoicici/v3", "description": "Production" } ], "tags": [ { "name": "Domestic Money Transfer (DMT)", "description": "Instant domestic money transfer via IMPS/NEFT" }, { "name": "AePS Cashout", "description": "Aadhaar-enabled biometric cash withdrawal & transfer" }, { "name": "Bharat Bill Payment System (BBPS)", "description": "Bill payments for 25+ biller categories via Bharat Connect" }, { "name": "PAN Verification", "description": "Full PAN identity fetch in <2 seconds" }, { "name": "DigiLocker Integration", "description": "Fetch notarised docs — Aadhaar, DL, marksheets, etc" }, { "name": "Bank Account Verification", "description": "Penny-drop bank account validation" }, { "name": "GST Verification", "description": "GSTIN lookup & filing status" }, { "name": "UPI ID (VPA) Verification", "description": "Validate UPI ID (VPA) in real time" }, { "name": "Driving Licence Verification", "description": "Driving licence validity & details" }, { "name": "Vehicle & RC Verification", "description": "Vehicle registration, ownership & insurance details" }, { "name": "Employee Verification", "description": "Employment & background check via EPFO" }, { "name": "Reverse Geocoding", "description": "Convert GPS coordinates to address" }, { "name": "Voter ID Verification", "description": "Validate voter ID (EPIC) details instantly" }, { "name": "Passport Application Validation", "description": "Validate Indian passport application details using file number and date of birth" }, { "name": "CIN Verification", "description": "Validate Company Identification Numbers via MCA" }, { "name": "IP Verification", "description": "Geo-locate and risk-score IP addresses" }, { "name": "Name Match", "description": "Fuzzy name matching across identity documents" }, { "name": "ITR Compliance Check", "description": "Check income tax return filing and compliance status" }, { "name": "DIN Verification", "description": "Verify Director Identification Numbers via MCA" }, { "name": "E-Challan Verification", "description": "Check pending traffic challans for vehicles" }, { "name": "Email Verification", "description": "Validate email address deliverability and risk" }, { "name": "FSSAI License Verification", "description": "Verify FSSAI food license details and status" }, { "name": "Mobile/OTP Verification", "description": "Send, verify & validate mobile OTPs with a signed proof token" }, { "name": "User & Agent Management", "description": "Onboard agents/retailers, manage their services, and check settlement balance" }, { "name": "Transactions & Refunds", "description": "Transaction status inquiry and OTP-based refunds" }, { "name": "Bank & IFSC", "description": "Bank/IFSC lookup" } ], "paths": { "/customer/payment/dmt-fino/sender/{customer_id}": { "get": { "operationId": "dmtGetSender", "summary": "Get Sender Profile", "description": "The first step in the DMT flow. Call this to check whether a customer is already registered as a DMT sender. If the sender exists, the response returns their profile and remaining transfer limits so you can skip registration.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 308 | Sender not found | [dmt-onboard-sender](https://eps.eko.in/docs/dmt-onboard-sender) |\n| 309 | Sender found | [dmt-get-recipients](https://eps.eko.in/docs/dmt-get-recipients) |\n| 2134 | Sender found, Biometric eKYC pending | [dmt-fino-sender-ekyc](https://eps.eko.in/docs/dmt-fino-sender-ekyc) |\n| 2129 | Sender found, Validate eKYC OTP pending | [dmt-fino-validate-ekyc-otp](https://eps.eko.in/docs/dmt-fino-validate-ekyc-otp) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-get-sender", "x-eko-trxn-type-id": 100, "x-eko-product-code": 96, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9123456789" } }, { "name": "user_code", "in": "query", "required": true, "description": "Agent user code (sent as a query parameter).", "schema": { "type": "string", "description": "Agent user code (sent as a query parameter).", "example": "20810200" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "is_registered": { "description": "Registration flag from the profile lookup. Read customer_profile.kyc_state to determine KYC completion.", "example": 0, "type": "number" }, "next_allowed_limit": { "description": "Remaining remittance limit currently available (INR).", "example": 25000, "type": "number" }, "kyc_state": { "description": "Top-level KYC flag for the lookup response.", "example": 0, "type": "number" }, "customer_profile": { "description": "Sender profile summary (present once KYC is complete).", "type": "object", "properties": { "name": { "description": "Sender name.", "example": "Rahul", "type": "string" }, "mobile": { "description": "Sender's mobile number.", "example": "9155927131", "type": "string" }, "balance": { "description": "Sender wallet balance (INR).", "example": "0.00", "type": "string" }, "total_monthly_limit": { "description": "Sender's monthly remittance limit (INR).", "example": "25000.0", "type": "string" }, "next_allowed_limit": { "description": "Remaining limit currently available (INR).", "example": "25000.0", "type": "string" }, "kyc_state": { "description": "Sender KYC state (1 = KYC complete on the profile).", "example": 1, "type": "number" }, "chart": { "description": "Per-period limit-usage breakdown.", "type": "array", "items": { "type": "object", "properties": { "data_type_id": { "description": "Identifier for the limit period/bucket.", "example": 10, "type": "number" }, "data": { "description": "Limit usage for the period.", "type": "object", "properties": { "unavailable": { "description": "Amount blocked/unavailable (INR).", "example": 0, "type": "number" }, "used": { "description": "Amount already used (INR).", "example": 0, "type": "number" }, "remaining": { "description": "Remaining limit for the period (INR).", "example": 25000, "type": "number" } } }, "label": { "description": "Display label for the period.", "example": "", "type": "string" } } } } } } } } } }, "examples": { "success": { "summary": "309 — Sender found", "value": { "status": 0, "response_status_id": -1, "response_type_id": 309, "message": "Success!", "data": { "is_registered": 0, "next_allowed_limit": 25000, "kyc_state": 0, "customer_profile": { "total_monthly_limit": "25000.0", "mobile": "9155927131", "balance": "0.00", "next_allowed_limit": "25000.0", "name": "Rahul", "kyc_state": 1, "chart": [ { "data_type_id": 10, "data": { "unavailable": 0, "used": 0, "remaining": 25000 }, "label": "" } ] } } } }, "sender_not_enrolled_proceed_to_onboard_sender": { "summary": "308 — Sender not found", "value": { "status": 308, "response_status_id": 1, "message": "Failure!Customer Not Enrolled", "response_type_id": 308, "data": { "ekyc_enabled": "" } } }, "enrolled_on_eko_kyc_pending_on_fino_proceed_to_sender_ekyc": { "summary": "2134 — Sender found, Biometric eKYC pending", "value": { "status": 0, "response_status_id": 0, "message": "Customer KYC Pending", "response_type_id": 2134, "data": { "otp_ref_id": "" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "dmtOnboardSender", "summary": "Onboard Sender", "description": "Registers a new customer in the DMT-Fino system. Provide the customer's name, date of birth, and residence address. On success the sender is opened on Eko but KYC on Fino is still pending — complete biometric eKYC (Sender eKYC → Validate eKYC OTP) next. If the sender was already onboarded on Fino externally, the response instead matches the KYC-complete profile from Get Sender Profile (response_type_id 309) and no eKYC is required. After onboarding, call Get Sender Profile to read the sender's current stage.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2134 | Onboarded, KYC pending — proceed to Sender eKYC | [dmt-fino-sender-ekyc](https://eps.eko.in/docs/dmt-fino-sender-ekyc) |\n| 300 | Already onboarded, KYC pending — re-check stage with Get Sender Profile | [dmt-get-sender](https://eps.eko.in/docs/dmt-get-sender) |\n| 309 | Already onboarded on Fino — KYC complete, proceed to Recipients | [dmt-get-recipients](https://eps.eko.in/docs/dmt-get-recipients) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-onboard-sender", "x-eko-trxn-type-id": 110, "x-eko-product-code": 106, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "creates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number (used as customer identifier).", "schema": { "type": "string", "description": "Sender's 10-digit mobile number (used as customer identifier).", "example": "9123456789" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "otp_ref_id": { "description": "OTP reference placeholder returned with the KYC-pending status. Empty until eKYC is initiated via Sender eKYC.", "example": "", "type": "string" } } } } }, "examples": { "success": { "summary": "2134 — Onboarded, KYC pending — proceed to Sender eKYC", "value": { "status": 0, "response_status_id": 0, "message": "Customer KYC Pending", "response_type_id": 2134, "data": { "otp_ref_id": "" } } }, "alternate_success_sender_already_onboarded_on_eko_kyc_pending": { "summary": "300 — Already onboarded, KYC pending — re-check stage with Get Sender Profile", "value": { "status": 0, "response_status_id": 0, "message": "Wallet opened successfully.", "response_type_id": 300, "data": { "customer_id_type": "mobile_number", "state_desc": "Non-Kyc", "state": "2", "customer_id": "9002331157" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "name": { "type": "string", "description": "Full name of the sender as per their ID proof.", "example": "Ramesh Kumar" }, "dob": { "type": "string", "description": "Date of birth in YYYY-MM-DD format.", "example": "1990-05-15", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "residence_address": { "type": "string", "description": "Customer's residence address as a JSON-encoded object with keys: line, city, state, pincode, district, area.", "example": "{\"line\":\"India\",\"city\":\"Indore\",\"state\":\"Madhya Pradesh\",\"pincode\":\"226024\",\"district\":\"Indore\",\"area\":\"gita bhavan\"}" } }, "required": [ "initiator_id", "name", "dob", "residence_address" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "name": "Ramesh Kumar", "dob": "1990-05-15", "residence_address": "{\"line\":\"India\",\"city\":\"Indore\",\"state\":\"Madhya Pradesh\",\"pincode\":\"226024\",\"district\":\"Indore\",\"area\":\"gita bhavan\"}" } } } } } }, "/customer/payment/dmt-fino/sender/{customer_id}/otp": { "put": { "operationId": "dmtFinoSenderEkyc", "summary": "Sender eKYC (Biometric)", "description": "Performs biometric eKYC using fingerprint data linked to the sender's Aadhaar number. Requires a compatible RD-service device; the PID XML is captured at the agent's terminal and submitted with the sender's Aadhaar number (include the `wadh` value when generating the PID). On success the system dispatches an OTP for confirmation; call Validate eKYC OTP next. A successful eKYC upgrades the sender's monthly limit from ₹5,000 to ₹25,000.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2129 | OTP sent — proceed to Validate eKYC OTP | [dmt-fino-validate-ekyc-otp](https://eps.eko.in/docs/dmt-fino-validate-ekyc-otp) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-fino-sender-ekyc", "x-eko-trxn-type-id": 810, "x-eko-product-code": 750, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "updates", "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9123456789" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "user_code": { "description": "Agent user code associated with the KYC request.", "example": "10472151", "type": "string" }, "intent_id": { "description": "Reserved intent identifier (empty in the standard flow).", "example": "", "type": "string" }, "kyc_request_id": { "description": "Unique identifier for this KYC request. Required for the Validate eKYC OTP step.", "example": "9332126", "type": "string" }, "otp_ref_id": { "description": "Reference ID for the OTP sent to the sender's Aadhaar-linked mobile. Required for the Validate eKYC OTP step.", "example": "666803844", "type": "string" } } } } }, "examples": { "success": { "summary": "2129 — OTP sent — proceed to Validate eKYC OTP", "value": { "status": 0, "response_status_id": 0, "message": "Validate the OTP", "response_type_id": 2129, "data": { "user_code": "10472151", "intent_id": "", "kyc_request_id": "9332126", "otp_ref_id": "666803844" } } }, "incorrect_pid_data_ekyc_verification_failed": { "summary": "Incorrect PID data — eKYC verification failed", "value": { "status": 2135, "response_status_id": 1, "message": "Customer KYC Pending", "response_type_id": 2135, "data": { "description": "K-100 EKYC Verification failed" } } }, "sender_already_has_an_existing_relationship_with_the_bank": { "summary": "Sender already has an existing relationship with the bank", "value": { "status": 2135, "response_status_id": 1, "message": "Customer KYC Pending", "response_type_id": 2135, "data": { "description": "Sorry! Since you already have an existing relationship with the bank" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "aadhar": { "type": "string", "description": "12-digit Aadhaar number of the sender.", "example": "234567890123", "pattern": "^\\d{12}$" }, "piddata": { "type": "string", "description": "XML-encoded biometric PID data captured from a certified biometric device (fingerprint scanner).", "example": "" } }, "required": [ "initiator_id", "aadhar", "piddata" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "aadhar": "234567890123", "piddata": "" } } } } } }, "/customer/payment/dmt-fino/sender/{customer_id}/otp/verify": { "put": { "operationId": "dmtFinoValidateEkycOtp", "summary": "Validate eKYC OTP", "description": "Final step of the sender eKYC flow. Submit the OTP received on the Aadhaar-linked mobile number along with the otp_ref_id and kyc_request_id from the Sender eKYC response. On success the sender's account is upgraded to fully KYC-verified status with a ₹25,000 monthly limit.", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-fino-validate-ekyc-otp", "x-eko-trxn-type-id": 812, "x-eko-product-code": 752, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "consumes-otp", "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9123456789" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "user_code": { "description": "Agent user code for the now KYC-verified sender. eKYC is complete on success.", "example": "10472151", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Customer Registration Completed", "response_type_id": 2132, "data": { "user_code": "10472151" } } }, "sender_already_registered": { "summary": "Sender already registered", "value": { "status": 2131, "response_status_id": 1, "message": "Validate OTP Failed", "response_type_id": 2131, "data": { "description": "Customer Already registred" } } }, "incorrect_otp_entered": { "summary": "Incorrect OTP entered", "value": { "status": 2131, "response_status_id": 302, "message": "Validate OTP Failed", "response_type_id": 2131, "data": { "description": "Wrong OTP" } } }, "otp_has_expired": { "summary": "OTP has expired", "value": { "status": 2131, "response_status_id": 303, "message": "Validate OTP Failed", "response_type_id": 2131, "data": { "description": "OTP expired" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "otp": { "type": "string", "description": "One-time password received on the sender's Aadhaar-linked mobile number.", "example": "784512" }, "otp_ref_id": { "type": "string", "description": "OTP reference ID returned by the Sender eKYC (or Onboard Sender) API call.", "example": "OTPREF20240101001" }, "kyc_request_id": { "type": "string", "description": "KYC request identifier returned by the Sender eKYC API call.", "example": "KYC20240101001" } }, "required": [ "initiator_id", "otp", "otp_ref_id", "kyc_request_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "otp": "784512", "otp_ref_id": "OTPREF20240101001", "kyc_request_id": "KYC20240101001" } } } } } }, "/customer/payment/dmt-fino/sender/{customer_id}/recipients": { "get": { "operationId": "dmtGetRecipients", "summary": "Get Recipients", "description": "Returns all beneficiaries (recipients) previously registered under the sender's DMT-Fino account. Use this before initiating a transfer — if the desired beneficiary already exists you can use their recipient_id directly to send money, skipping Add Recipient.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 22 | No recipients — add one before transacting | [dmt-add-recipient](https://eps.eko.in/docs/dmt-add-recipient) |\n| 23 | Recipients found — proceed to Send Transaction OTP | [dmt-send-otp](https://eps.eko.in/docs/dmt-send-otp) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-get-recipients", "x-eko-trxn-type-id": 82, "x-eko-product-code": 80, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9123456789" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "pan_required": { "description": "PAN requirement flag for the sender.", "example": 2, "type": "number" }, "remaining_limit_before_pan_required": { "description": "Amount the sender can still transfer before PAN becomes mandatory (INR).", "example": 50000, "type": "number" }, "recipient_list": { "description": "Registered beneficiaries for this sender.", "type": "array", "items": { "type": "object", "properties": { "recipient_id": { "description": "Identifier used in the Send Transaction OTP and Execute Transaction APIs.", "example": 117015428, "type": "number" }, "beneficiary_id": { "description": "Beneficiary identifier (mirrors recipient_id).", "example": 117015428, "type": "number" }, "bank_recipient_id": { "description": "Bank-side recipient identifier.", "example": 117015428, "type": "number" }, "recipient_name": { "description": "Beneficiary name.", "example": "yashwant basnett", "type": "string" }, "recipient_mobile": { "description": "Beneficiary mobile number.", "example": "9002331157", "type": "string" }, "bank": { "description": "Beneficiary bank name.", "example": "State Bank of India", "type": "string" }, "ifsc": { "description": "Beneficiary bank IFSC code.", "example": "SBIN0007515", "type": "string" }, "account": { "description": "Beneficiary bank account number.", "example": "38759149196", "type": "string" }, "account_type": { "description": "Type of the beneficiary account.", "example": "Bank Account", "type": "string" }, "ifsc_status": { "description": "Whether the IFSC is valid/active (1 = valid).", "example": 1, "type": "number" }, "is_verified": { "description": "Whether the account has been penny-drop verified (1 = verified).", "example": 0, "type": "number" }, "is_otp_required": { "description": "Whether an OTP is required to transact to this recipient.", "example": "0", "type": "string" }, "pipes": { "description": "Available settlement pipes for this recipient, keyed by pipe id.", "example": { "3": { "pipe": 3, "status": 1 } }, "type": "object" } } } } } } } }, "examples": { "success": { "summary": "23 — Recipients found — proceed to Send Transaction OTP", "value": { "status": 0, "response_status_id": 0, "message": "Success", "response_type_id": 23, "data": { "pan_required": 2, "recipient_list": [ { "recipient_id": 117015428, "beneficiary_id": 117015428, "bank_recipient_id": 117015428, "recipient_name": "yashwant basnett", "recipient_mobile": "9002331157", "bank": "State Bank of India", "ifsc": "SBIN0007515", "account": "38759149196", "account_type": "Bank Account", "ifsc_status": 1, "is_verified": 0, "is_otp_required": "0", "pipes": { "3": { "pipe": 3, "status": 1 } } } ], "remaining_limit_before_pan_required": 50000 } } }, "no_recipients_registered_yet_add_one": { "summary": "22 — No recipients — add one before transacting", "value": { "status": 0, "response_status_id": -1, "message": "No recepients found", "response_type_id": 22 } }, "customer_does_not_exist_in_system": { "summary": "Customer does not exist in system", "value": { "status": 463, "response_status_id": 1, "message": "customer_id does not exist in system", "response_type_id": -1, "invalid_params": { "customer_id": "Customer does not exist in System" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/dmt-fino/sender/{customer_id}/recipient": { "post": { "operationId": "dmtAddRecipient", "summary": "Add Recipient", "description": "Adds a new beneficiary to the sender's saved recipients list. Provide the recipient's full name, bank account number, IFSC code, and mobile number. On success a recipient_id is returned; use it in Send Transaction OTP and Execute Transaction.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 43 | Recipient added — proceed to Send Transaction OTP | [dmt-send-otp](https://eps.eko.in/docs/dmt-send-otp) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-add-recipient", "x-eko-trxn-type-id": 74, "x-eko-product-code": 72, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "creates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9123456789" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "recipient_id": { "description": "Unique identifier assigned to the newly added recipient. Required for Send Transaction OTP and Execute Transaction.", "example": 117015428, "type": "number" }, "customer_id": { "description": "Sender's mobile number (echoed back).", "example": "9155927131", "type": "string" }, "recipient_mobile": { "description": "Beneficiary mobile number (echoed back).", "example": "9002331157", "type": "string" }, "initiator_id": { "description": "Partner initiator ID (echoed back).", "example": "", "type": "string" }, "pipes": { "description": "Available settlement pipes for the new recipient.", "example": {}, "type": "object" }, "otp_ref_id": { "description": "OTP reference placeholder (empty on add).", "example": "", "type": "string" } } } } }, "examples": { "success": { "summary": "43 — Recipient added — proceed to Send Transaction OTP", "value": { "status": 0, "response_status_id": 0, "message": "Success!Please transact using Recipientid", "response_type_id": 43, "data": { "recipient_id": 117015428, "customer_id": "9155927131", "recipient_mobile": "9002331157", "initiator_id": "", "pipes": {}, "otp_ref_id": "" } } }, "recipient_already_registered_for_this_sender": { "summary": "Recipient already registered for this sender", "value": { "status": 342, "response_status_id": 1, "message": "Recipient already registered", "response_type_id": -1, "data": {} } }, "customer_does_not_exist_in_system": { "summary": "Customer does not exist in system", "value": { "status": 463, "response_status_id": 1, "message": "customer_id does not exist in system", "response_type_id": -1, "invalid_params": { "customer_id": "Customer does not exist in System" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "recipient_mobile": { "type": "string", "description": "Beneficiary's 10-digit mobile number.", "example": "9002331157" }, "recipient_name": { "type": "string", "description": "Full name of the beneficiary as it appears on their bank account.", "example": "yashwant basnett" }, "ifsc": { "type": "string", "description": "IFSC code of the beneficiary's bank branch.", "example": "SBIN0007515", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" }, "account": { "type": "string", "description": "Beneficiary's bank account number.", "example": "38759149196" } }, "required": [ "initiator_id", "recipient_mobile", "recipient_name", "ifsc", "account" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "recipient_mobile": "9002331157", "recipient_name": "yashwant basnett", "ifsc": "SBIN0007515", "account": "38759149196" } } } } } }, "/customer/payment/dmt-fino/otp": { "post": { "operationId": "dmtSendOtp", "summary": "Send Transaction OTP", "description": "Sends an OTP to the sender's registered mobile number as a pre-authorisation step before initiating the actual money transfer. Provide the recipient_id, the transfer amount, and the sender's customer_id. The returned otp_ref_id must be passed to Initiate Transfer along with the OTP entered by the customer.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2133 | Transaction OTP sent — proceed to Execute Transaction | [dmt-initiate-transfer](https://eps.eko.in/docs/dmt-initiate-transfer) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-send-otp", "x-eko-trxn-type-id": 811, "x-eko-product-code": 751, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "otp_ref_id": { "description": "Reference ID for the OTP sent. Must be passed to Execute Transaction along with the customer-entered OTP.", "example": "666902416", "type": "string" } } } } }, "examples": { "success": { "summary": "2133 — Transaction OTP sent — proceed to Execute Transaction", "value": { "status": 0, "response_status_id": 0, "message": "Send OTP", "response_type_id": 2133, "data": { "otp_ref_id": "666902416" } } }, "sender_monthly_limit_exhausted": { "summary": "Sender monthly limit exhausted", "value": { "status": 36, "response_type_id": 36, "response_status_id": 1, "message": "Sender/beneficiary monthly limit exhausted", "data": {} } }, "beneficiary_monthly_limit_exhausted": { "summary": "Beneficiary monthly limit exhausted", "value": { "status": 945, "response_type_id": 945, "response_status_id": 1, "message": "Beneficiary monthly limit exhausted", "data": {} } }, "customer_does_not_exist_in_system": { "summary": "Customer does not exist in system", "value": { "status": 463, "response_status_id": 1, "message": "customer_id does not exist in system", "response_type_id": -1, "invalid_params": { "customer_id": "Customer does not exist in System" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "recipient_id": { "type": "number", "description": "Unique recipient ID returned by Add Recipient or Get Recipients.", "example": 98765 }, "amount": { "type": "number", "description": "Transfer amount in INR (integer, no decimals).", "example": 500 }, "customer_id": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9123456789" } }, "required": [ "initiator_id", "recipient_id", "amount", "customer_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "recipient_id": 98765, "amount": 500, "customer_id": "9123456789" } } } } } }, "/customer/payment/dmt-fino": { "post": { "operationId": "dmtInitiateTransfer", "summary": "Initiate Transfer", "description": "The final and only financial step in the DMT flow. Debits the agent's wallet and initiates an IMPS transfer to the registered recipient's bank account after OTP validation. Requires the otp and otp_ref_id from Send Transaction OTP plus a unique client_ref_id per attempt for reconciliation (it is NOT an idempotency key — on a timeout, look the attempt up via Transaction Inquiry with `client_ref_id=` before retrying). The response returns tid (Eko transaction ID) and bank_ref_num (the IMPS RRN/UTR). Use a fresh otp_ref_id and OTP for each attempt — a consumed OTP is rejected — and always persist tid, bank_ref_num, and your client_ref_id to reconcile before retrying.", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-initiate-transfer", "x-eko-trxn-type-id": 81, "x-eko-product-code": 79, "x-eko-uat-unavailable": true, "x-eko-financial": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "tx_status": { "description": "Transaction state: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tx_status": { "description": "Transaction state within the data block: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "tid": { "description": "Eko's internal transaction ID. Store for reconciliation and support queries.", "example": "3570311831", "type": "string" }, "bank_ref_num": { "description": "Bank reference number (RRN / UTR) for the IMPS transaction.", "example": "620415011744", "type": "string" }, "amount": { "description": "Amount transferred (INR).", "example": "100.00", "type": "string" }, "fee": { "description": "Fee charged for the transfer (INR).", "example": "10.0", "type": "string" }, "collectable_amount": { "description": "Total collectable from the sender (amount + fee).", "example": "110.0", "type": "string" }, "service_tax": { "description": "Service tax component on the fee (INR).", "example": "1.53", "type": "string" }, "tds": { "description": "Tax deducted at source on the agent's commission (INR).", "example": "0.01", "type": "string" }, "commission": { "description": "Commission earned by the agent on this transaction (INR).", "example": "0.47", "type": "string" }, "sender_name": { "description": "Name of the sender.", "example": "Rahul", "type": "string" }, "recipient_name": { "description": "Name of the beneficiary credited.", "example": "Master YASHWANT BASNETT", "type": "string" }, "recipient_id": { "description": "Recipient identifier credited.", "example": 117015428, "type": "number" }, "bank": { "description": "Beneficiary bank name.", "example": "State Bank of India", "type": "string" }, "account": { "description": "Beneficiary account number credited.", "example": "38759149196", "type": "string" }, "channel_desc": { "description": "Settlement channel used (e.g. IMPS).", "example": "IMPS", "type": "string" }, "balance": { "description": "Agent wallet balance after the transaction (INR).", "example": "10131.18", "type": "string" }, "client_ref_id": { "description": "Echo of the partner reference sent in the request.", "example": "", "type": "string" }, "currency": { "description": "Currency code.", "example": "INR", "type": "string" }, "timestamp": { "description": "Server-side timestamp of the transaction.", "example": "2026-07-23T09:46:35.396Z", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Transaction successful", "response_type_id": 325, "data": { "tx_status": "0", "txstatus_desc": "Success", "tid": "3570311831", "amount": "100.00", "fee": "10.0", "collectable_amount": "110.0", "service_tax": "1.53", "tds": "0.01", "commission": "0.47", "sender_name": "Rahul", "recipient_name": "Master YASHWANT BASNETT", "recipient_id": 117015428, "bank": "State Bank of India", "account": "38759149196", "channel_desc": "IMPS", "bank_ref_num": "620415011744", "balance": "10131.18", "client_ref_id": "", "currency": "INR", "timestamp": "2026-07-23T09:46:35.396Z" } } }, "transaction_declined_otp_already_consumed": { "summary": "Transaction declined — OTP already consumed", "value": { "status": 55, "response_status_id": 1, "message": "Transaction declined. Please try after sometime.", "response_type_id": 55, "data": { "tx_status": "1", "txstatus_desc": "Failed", "reason": "OTP already Consumed", "amount": "100.00", "tid": "3570311840", "client_ref_id": "", "balance": "10021.64" } } }, "transaction_declined_insufficient_balance_in_agent_wallet": { "summary": "Transaction declined — insufficient balance in agent wallet", "value": { "status": 55, "response_status_id": 1, "message": "Transaction declined. Please try after sometime.", "response_type_id": 55, "data": { "tx_status": "1", "txstatus_desc": "Failed", "reason": "Insufficient balance" } } }, "transaction_declined_wrong_otp_entered": { "summary": "Transaction declined — wrong OTP entered", "value": { "status": 55, "response_status_id": 1, "message": "Transaction declined. Please try after sometime.", "response_type_id": 55, "data": { "tx_status": "1", "txstatus_desc": "Failed", "reason": "Wrong OTP" } } }, "transaction_declined_sender_monthly_limit_exhausted": { "summary": "Transaction declined — sender monthly limit exhausted", "value": { "status": 55, "response_status_id": 1, "message": "Transaction declined. Please try after sometime.", "response_type_id": 55, "data": { "tx_status": "1", "txstatus_desc": "Failed", "reason": "Sender/beneficiary monthly limit exhausted" } } }, "transaction_awaited_non_final_reconcile_by_tid_before_retrying": { "summary": "Transaction awaited (non-final) — reconcile by tid before retrying", "value": { "status": 0, "response_status_id": 0, "message": "Transaction in progress", "data": { "tx_status": "2", "txstatus_desc": "Awaited", "tid": "3570311831", "amount": "100.00" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "recipient_id": { "type": "number", "description": "Unique recipient ID from Add Recipient or Get Recipients.", "example": 117015428 }, "amount": { "type": "number", "description": "Transfer amount in INR (must match the amount sent to Send Transaction OTP).", "example": 100 }, "customer_id": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9155927131" }, "otp": { "type": "string", "description": "OTP entered by the customer, received on their registered mobile.", "example": "4702" }, "otp_ref_id": { "type": "string", "description": "OTP reference ID from the Send Transaction OTP response.", "example": "667007109" }, "client_ref_id": { "type": "string", "description": "Unique partner reference for this transaction, used for reconciliation and Transaction Inquiry lookup (`client_ref_id=`). Use a fresh value per attempt; it is not an idempotency key.", "example": "" } }, "required": [ "initiator_id", "recipient_id", "amount", "customer_id", "otp", "otp_ref_id", "client_ref_id" ] }, "example": { "initiator_id": "9962981729", "recipient_id": 117015428, "amount": 100, "customer_id": "9155927131", "otp": "4702", "otp_ref_id": "667007109", "client_ref_id": "" } } } } } }, "/admin/network/agent/{user_code}/aeps-fingpay/activate": { "put": { "operationId": "activateAepsFingpay", "summary": "Activate AePS Fingpay for Agent", "description": "This API enables an agent (identified by their `user_code`) to use the AePS Fingpay service. It accepts the agent's biometric device model, serial number, settlement account, address proofs, and KYC documents (PAN card, Aadhaar front and back) as a multipart form submission. After submission, the activation enters a 'pending' state and is approved within 2–3 business days. Only activated agents can perform AePS transactions. File uploads must be JPEG/JPG/PDF format, each under 1 MB; PNG is not accepted.\n\n> [!IMPORTANT]\n> This is **not** a form field per parameter. Every non-file field below travels together as one JSON object in a single form field named `form-data`, and each document is its own file part (`pan_card`, `aadhar_front`, `aadhar_back`).\n\n> [!NOTE]\n> This API must be called after onboarding your agent using the [**Onboard User API**](/docs/onboard-user).\n\n> [!WARNING]\n> The approval may take 1-2 business days.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1259 | AePS Registration Successful | [dmt-onboard-sender](https://eps.eko.in/docs/dmt-onboard-sender) |\n| 1297 | User does not exist | [onboard-user](https://eps.eko.in/docs/onboard-user) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "activate-aeps-fingpay", "x-eko-trxn-type-id": 383, "x-eko-product-code": 364, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": true, "billable": false, "sideEffects": [ "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "multipart/form-data — let your HTTP client set this header itself (it generates the required boundary); do not hardcode the value. Every non-file field travels as one JSON object in a single `form-data` part; each upload is its own part.", "schema": { "type": "string", "description": "multipart/form-data — let your HTTP client set this header itself (it generates the required boundary); do not hardcode the value. Every non-file field travels as one JSON object in a single `form-data` part; each upload is its own part.", "example": "multipart/form-data" } }, { "name": "user_code", "in": "path", "required": true, "description": "Unique code of the agent for whom AePS Fingpay service is being activated.", "schema": { "type": "string", "description": "Unique code of the agent for whom AePS Fingpay service is being activated.", "example": "20810200" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "service_status_desc": { "description": "Current state of the AePS Fingpay activation request. 'pending' means documents are submitted and under review.", "example": "pending", "type": "string" }, "service_status": { "description": "State-id of the AePS Fingpay activation request.", "example": "ACT20240101001", "type": "number" } } } } }, "examples": { "success": { "summary": "1259 — AePS Registration Successful", "value": { "status": 0, "response_status_id": 0, "response_type_id": 1259, "message": "AePS Registration Successful", "data": { "service_status_desc": "Activated", "balance": "", "user_code": "37659001", "initiator_id": "7042769383", "service_status": "1", "service_code": "43", "remarks": "" } } }, "agent_not_onboarded": { "summary": "1297 — User does not exist", "value": { "status": 1297, "response_status_id": 1, "response_type_id": 1297, "message": "This user does not exist", "data": { "initiator_id": "" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "form-data": { "type": "string", "description": "JSON object carrying every non-file field: `initiator_id`, `client_ref_id`, `modelname`, `devicenumber`, `account`, `ifsc`, `shop_type`, `office_address`, `address_as_per_proof`, `aadhar`, `latlong`.", "example": "{\"initiator_id\":\"9962981729\",\"client_ref_id\":\"2026010100123456789\",\"modelname\":\"Morpho 1300E3\",\"devicenumber\":\"SN1234567890\",\"account\":\"38759149196\",\"ifsc\":\"SBIN0007515\",\"shop_type\":\"4215\",\"office_address\":{\"line\":\"Middle Tarku Near Secondary School\",\"city\":\"Singtam\",\"state\":\"Sikkim\",\"pincode\":\"122002\",\"state_id\":\"23\"},\"address_as_per_proof\":{\"line\":\"Temi Tarku Secondary\",\"city\":\"Gurgaon\",\"state\":\"Haryana\",\"pincode\":\"122002\",\"state_id\":\"23\"},\"aadhar\":\"123456789012\",\"latlong\":\"28.6139,77.2090\"}" }, "pan_card": { "type": "string", "format": "binary", "description": "PAN card document, sent as its own file part. Accepted formats: JPEG, JPG, PDF. Max size: 1 MB. PNG not accepted." }, "aadhar_front": { "type": "string", "format": "binary", "description": "Front side of the Aadhaar card, sent as its own file part. Accepted formats: JPEG, JPG, PDF. Max size: 1 MB." }, "aadhar_back": { "type": "string", "format": "binary", "description": "Back side of the Aadhaar card, sent as its own file part. Accepted formats: JPEG, JPG, PDF. Max size: 1 MB." } }, "required": [ "form-data", "pan_card", "aadhar_front", "aadhar_back" ] }, "example": { "form-data": "{\"initiator_id\":\"9962981729\",\"client_ref_id\":\"2026010100123456789\",\"modelname\":\"Morpho 1300E3\",\"devicenumber\":\"SN1234567890\",\"account\":\"38759149196\",\"ifsc\":\"SBIN0007515\",\"shop_type\":\"4215\",\"office_address\":{\"line\":\"Middle Tarku Near Secondary School\",\"city\":\"Singtam\",\"state\":\"Sikkim\",\"pincode\":\"122002\",\"state_id\":\"23\"},\"address_as_per_proof\":{\"line\":\"Temi Tarku Secondary\",\"city\":\"Gurgaon\",\"state\":\"Haryana\",\"pincode\":\"122002\",\"state_id\":\"23\"},\"aadhar\":\"123456789012\",\"latlong\":\"28.6139,77.2090\"}", "pan_card": "", "aadhar_front": "", "aadhar_back": "" } } } } } }, "/user/collection/aeps-fingpay/get-Mcc-Category": { "get": { "operationId": "aepsFingpayShopTypes", "summary": "Get Shop Types", "description": "Returns the list of Merchant Category Codes (MCC). Use the `value` of the chosen entry as the `shop_type` in the Activate AePS Fingpay request.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2110 | Shop-type list returned successfully | [activate-aeps-fingpay](https://eps.eko.in/docs/activate-aeps-fingpay) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-shop-types", "x-eko-trxn-type-id": 798, "x-eko-product-code": 739, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Container for the returned list.", "type": "object", "properties": { "list_elements": { "description": "Array of available MCC categories.", "type": "array", "items": { "type": "object", "properties": { "label": { "description": "Human-readable category name (display to the agent).", "example": "Electronics Shops", "type": "string" }, "value": { "description": "Integer MCC code — use as `shop_type` in the Activate AePS Fingpay request.", "example": 5732, "type": "number" } } } } } } } } } }, "examples": { "success": { "summary": "2110 — Shop-type list returned successfully", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "label": "Courier services — air and ground and freight forwarders", "value": 4215 }, { "label": "Travel agencies and tour operators", "value": 4722 }, { "label": "Groceries and supermarkets", "value": 5411 }, { "label": "Electronics Shops", "value": 5732 }, { "label": "Fast food restaurants", "value": 5814 } ] }, "response_type_id": 2110, "message": "Success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/user/collection/aeps-fingpay/get-states": { "get": { "operationId": "aepsFingpayStates", "summary": "Get States", "description": "Returns the list of states. Use the `value` of the chosen state as the `state_id` inside the `address_as_per_proof` and `office_address` objects in the Activate AePS Fingpay request.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2127 | State list returned successfully | [activate-aeps-fingpay](https://eps.eko.in/docs/activate-aeps-fingpay) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-states", "x-eko-trxn-type-id": 799, "x-eko-product-code": 740, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Container for the returned list.", "type": "object", "properties": { "list_elements": { "description": "Array of available states.", "type": "array", "items": { "type": "object", "properties": { "stateCode": { "description": "Two-letter state code.", "example": "MH", "type": "string" }, "label": { "description": "State name (display to the agent).", "example": "Maharashtra", "type": "string" }, "value": { "description": "Integer state ID — use as `state_id` in the address objects.", "example": 15, "type": "number" } } } } } } } } } }, "examples": { "success": { "summary": "2127 — State list returned successfully", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "stateCode": "HR", "label": "Haryana", "value": 8 }, { "stateCode": "KA", "label": "Karnataka", "value": 12 }, { "stateCode": "MH", "label": "Maharashtra", "value": 15 }, { "stateCode": "SK", "label": "Sikkim", "value": 23 }, { "stateCode": "UP", "label": "Uttar Pradesh", "value": 27 } ] }, "response_type_id": 2127, "message": "Success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/user/collection/aeps-fingpay/kyc/otp": { "post": { "operationId": "aepsFingpaySendOtpKyc", "summary": "Send OTP (eKYC)", "description": "First-time KYC follows three steps in order: `Send OTP` → `Verify OTP` → `Biometric`. On subsequent days, use the Daily KYC (biometric-only) endpoint.\n\nThis is the first step in the one-time AePS Fingpay eKYC flow. The OTP is delivered to the number passed in `customer_id`. The eKYC flow — Send OTP → Verify OTP → Biometric — must be completed once per agent before they can perform any AePS transactions. This step is a prerequisite; do not confuse it with the Daily KYC which is required on each calendar day.\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1600 | OTP request has been sent | [aeps-fingpay-verify-otp-kyc](https://eps.eko.in/docs/aeps-fingpay-verify-otp-kyc) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-send-otp-kyc", "x-eko-trxn-type-id": 540, "x-eko-product-code": 512, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "reference_tid": { "description": "Transaction reference ID for this eKYC session. Must be passed to the Verify OTP API.", "example": "EKYKF4719702240123152147525I", "type": "string" }, "otp_ref_id": { "description": "Reference ID for the OTP session. Must be passed to the Verify OTP API.", "example": "2465238", "type": "string" } } } } }, "examples": { "success": { "summary": "1600 — OTP request has been sent", "value": { "response_status_id": 0, "data": { "reference_tid": "EKYKF4719702240123152147525I", "otp_ref_id": "2465238" }, "response_type_id": 1600, "message": "OTP request has been sent", "status": 0 } }, "aeps_fingpay_service_not_activated_for_this_agent": { "summary": "AePS Fingpay service not activated for this agent", "value": { "response_status_id": 1, "response_type_id": 346, "message": "Agent not allowed to this transaction", "status": 346 } }, "incorrectly_encrypted_aadhaar": { "summary": "Incorrectly encrypted Aadhaar", "value": { "response_status_id": 1, "invalid_params": { "aadhar": "Please provide the value of the field {2} {3}" }, "response_type_id": -1, "message": "Please provide the value of the field", "status": 97 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the agent undergoing eKYC. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "customer_id": { "type": "string", "description": "Registered mobile number of the agent/merchant undergoing eKYC. The OTP is delivered to this number.", "example": "9123456789" }, "latlong": { "type": "string", "description": "Agent's GPS coordinates as `latitude,longitude`. Required for security and fraud prevention.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" } }, "required": [ "initiator_id", "user_code", "aadhar", "customer_id", "latlong" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "20810200", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "customer_id": "9123456789", "latlong": "28.6139,77.2090" } } } } } }, "/user/collection/aeps-fingpay/kyc/otp/verify": { "put": { "operationId": "aepsFingpayVerifyOtpKyc", "summary": "Verify OTP (eKYC)", "description": "The second step of the one-time AePS Fingpay eKYC flow (Send OTP → Verify OTP → Biometric). Submits the OTP the agent received, together with the `otp_ref_id` and `reference_tid` returned by the Send OTP API, to validate the agent's identity before biometric capture.\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1604 | Validation successful | [aeps-fingpay-biometric-ekyc](https://eps.eko.in/docs/aeps-fingpay-biometric-ekyc) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-verify-otp-kyc", "x-eko-trxn-type-id": 542, "x-eko-product-code": 514, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "consumes-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "reference_tid": { "description": "Transaction reference ID for this eKYC verification. Carry forward to the Biometric eKYC step.", "example": "BEKYF4719702240123152147525I", "type": "string" }, "otp_ref_id": { "description": "Reference ID of the OTP session. Carry forward to the Biometric eKYC step.", "example": "815031", "type": "string" } } } } }, "examples": { "success": { "summary": "1604 — Validation successful", "value": { "response_status_id": 0, "data": { "reference_tid": "BEKYF4719702240123152147525I", "otp_ref_id": "815031" }, "response_type_id": 1604, "message": "Validation successful", "status": 0 } }, "invalid_or_expired_otp": { "summary": "Invalid or expired OTP", "value": { "response_status_id": 1, "data": { "last_used_okekey": "", "reason": "The details entered are incorrect or the OTP has expired. Kindly request a new OTP." }, "response_type_id": 461, "message": "Failed!Please try after some time", "status": 461 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" }, "customer_id": { "type": "string", "description": "Registered mobile number of the agent/merchant undergoing eKYC.", "example": "9123456789" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the agent undergoing eKYC. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "otp": { "type": "string", "description": "OTP received on the agent's Aadhaar-registered mobile number.", "example": "123456" }, "otp_ref_id": { "type": "string", "description": "Reference ID returned by the Send OTP (eKYC) API.", "example": "2465238" }, "reference_tid": { "type": "string", "description": "Transaction reference ID returned by the Send OTP (eKYC) API.", "example": "EKYKF4719702240123152147525I" }, "latlong": { "type": "string", "description": "Agent's GPS coordinates as `latitude,longitude`. Required for security and fraud prevention.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" } }, "required": [ "initiator_id", "user_code", "customer_id", "aadhar", "otp", "otp_ref_id", "reference_tid", "latlong" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "20810200", "customer_id": "9123456789", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "otp": "123456", "otp_ref_id": "2465238", "reference_tid": "EKYKF4719702240123152147525I", "latlong": "28.6139,77.2090" } } } } } }, "/user/collection/aeps-fingpay/kyc/biometric": { "put": { "operationId": "aepsFingpayBiometricEkyc", "summary": "Biometric eKYC", "description": "The final step in the one-time AePS Fingpay eKYC flow, called after OTP verification. Submits the agent's RSA-encrypted Aadhaar and live biometric PID to UIDAI; on success the agent is eligible for AePS transactions.\n\nIf you generate the PID block with your own code rather than the RD service default, set `wadh=E0jzJ/P8UopUHAieZn8CKqS4WPMi5ZSYXgfnlfkWjrc=` alongside `fCount`, `fType` and the other attributes.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1605 | eKYC successful — agent may now complete Daily KYC | [aeps-fingpay-daily-auth](https://eps.eko.in/docs/aeps-fingpay-daily-auth) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-biometric-ekyc", "x-eko-trxn-type-id": 543, "x-eko-product-code": 515, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "user_code": { "description": "User code of the agent whose eKYC is now complete.", "example": "20810200", "type": "string" } } } } }, "examples": { "success": { "summary": "1605 — eKYC successful — agent may now complete Daily KYC", "value": { "response_status_id": 0, "data": { "user_code": "20810200" }, "response_type_id": 1605, "message": "Congratulations! eKYC successful", "status": 0 } }, "otp_steps_skipped_send_otp_and_verify_otp_must_both_succeed_first": { "summary": "OTP steps skipped — Send OTP and Verify OTP must both succeed first", "value": { "response_status_id": 1, "data": { "last_used_okekey": "", "reason": "Merchant is Inactive or Invalid Details" }, "response_type_id": 461, "message": "Failed!Please try after some time", "status": 461 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the agent. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "customer_id": { "type": "string", "description": "Registered mobile number of the agent/merchant undergoing eKYC.", "example": "9123456789" }, "latlong": { "type": "string", "description": "Agent's GPS coordinates as `latitude,longitude`. Required for security and fraud prevention.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" }, "piddata": { "type": "string", "description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc in DeviceInfo).", "example": "..." }, "bank_code": { "type": "string", "description": "Eko bank code of the agent's bank. Resolve it using the [Get List of Banks](./get-banks) API.", "example": "HDFC" }, "otp_ref_id": { "type": "string", "description": "Reference ID returned by the preceding OTP step, linking this biometric capture to the verified OTP session.", "example": "2465238" }, "reference_tid": { "type": "string", "description": "Transaction reference ID returned by the preceding OTP step.", "example": "EKYKF4719702240123152147525I" } }, "required": [ "initiator_id", "user_code", "aadhar", "customer_id", "latlong", "piddata", "bank_code", "otp_ref_id", "reference_tid" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "20810200", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "customer_id": "9123456789", "latlong": "28.6139,77.2090", "piddata": "...", "bank_code": "HDFC", "otp_ref_id": "2465238", "reference_tid": "EKYKF4719702240123152147525I" } } } } } }, "/user/collection/aeps-fingpay/kyc/biometric/daily": { "put": { "operationId": "aepsFingpayDailyAuth", "summary": "Daily KYC", "description": "Biometric-only re-verification for the days after the one-time eKYC — no OTP step is required. AePS Fingpay requires every agent to re-authenticate themselves biometrically at the start of each working day, before their first transaction of the day.\n\nIf this fails with reason `Please complete bank eKYC to process the transaction.`, re-run the full first-time eKYC sequence — Send OTP → Verify OTP → Biometric — before retrying.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1713 | Daily KYC successful — the agent may transact today | — |\n| 1714 | Daily KYC failed — if `data.reason` is 'Please complete bank eKYC to process the transaction.', re-run the full eKYC from Send OTP | [aeps-fingpay-send-otp-kyc](https://eps.eko.in/docs/aeps-fingpay-send-otp-kyc) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-daily-auth", "x-eko-trxn-type-id": 594, "x-eko-product-code": 565, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "user_code": { "description": "User code of the agent whose daily KYC is now complete for the current calendar day.", "example": "20810200", "type": "string" } } } } }, "examples": { "success": { "summary": "1713 — Daily KYC successful — the agent may transact today", "value": { "response_status_id": 0, "data": { "user_code": "20810200" }, "response_type_id": 1713, "message": "KYC sucess", "status": 0 } }, "kyc_failed_no_reason_returned": { "summary": "1714 — Daily KYC failed — if `data.reason` is 'Please complete bank eKYC to process the transaction.', re-run the full eKYC from Send OTP", "value": { "response_status_id": 1, "data": { "reason": "", "comment": "" }, "response_type_id": 1714, "message": "KYC Fail", "status": 1714 } }, "invalid_biometric_data_check_the_wadh_value_in_the_pid_block": { "summary": "1714 — Daily KYC failed — if `data.reason` is 'Please complete bank eKYC to process the transaction.', re-run the full eKYC from Send OTP", "value": { "response_status_id": 1, "data": { "reason": "Authentication Failed. Invalid Biometric data.", "comment": "" }, "response_type_id": 1714, "message": "KYC Fail", "status": 1714 } }, "bank_ekyc_pending_re_run_send_otp_verify_otp_biometric_first": { "summary": "1714 — Daily KYC failed — if `data.reason` is 'Please complete bank eKYC to process the transaction.', re-run the full eKYC from Send OTP", "value": { "response_status_id": 1, "data": { "reason": "Please complete bank eKYC to process the transaction.", "comment": "" }, "response_type_id": 1714, "message": "KYC Fail", "status": 1714 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the agent performing Daily KYC. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "customer_id": { "type": "string", "description": "Registered mobile number of the agent/merchant.", "example": "9123456789" }, "latlong": { "type": "string", "description": "GPS coordinates of the agent's location at the time of daily KYC.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" }, "piddata": { "type": "string", "description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc in DeviceInfo). This represents the agent's own fingerprint, not the customer's. If you generate the PID block yourself, the value of `wadh` must be blank/empty for Daily KYC.", "example": "..." }, "bank_code": { "type": "string", "description": "Eko bank code of the agent's bank. Resolve it using the [Get List of Banks](./get-banks) API.", "example": "HDFC" } }, "required": [ "initiator_id", "user_code", "aadhar", "customer_id", "latlong", "piddata", "bank_code" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "20810200", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "customer_id": "9123456789", "latlong": "28.6139,77.2090", "piddata": "...", "bank_code": "HDFC" } } } } } }, "/customer/collection/aeps-fingpay/cash-withdrawal/otp/{customer_id}": { "post": { "operationId": "aepsFingpayCashWithdrawalOtp", "summary": "Cash Withdrawal OTP", "description": "Fingpay requires a fresh, transaction-scoped OTP for every cash withdrawal above **₹5,000**. Call this before Cash Withdrawal only when `amount` is greater than ₹5,000 — for ₹5,000 or less, skip it and call Cash Withdrawal directly.\n\nOn success the customer receives a 6-digit OTP by SMS on their Aadhaar-linked mobile, and the response returns `data.fp_transaction_id`. Send that id to Cash Withdrawal as `txn_otp_request_id`, and put the SMS OTP in the `otp` attribute of the PidOptions used to capture the customer's fingerprint. They are two different values, and Cash Withdrawal needs both. The id belongs to this one withdrawal attempt: generate a new one for every attempt and never reuse it.\n\nNo biometric capture happens in this call — it takes no `piddata`.\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1459 | OTP generated and sent to the customer by SMS — send `data.fp_transaction_id` as `txn_otp_request_id` to Cash Withdrawal | [aeps-fingpay-cash-withdrawal](https://eps.eko.in/docs/aeps-fingpay-cash-withdrawal) |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-cash-withdrawal-otp", "x-eko-trxn-type-id": 851, "x-eko-product-code": 784, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Customer's registered mobile number.", "schema": { "type": "string", "description": "Customer's registered mobile number.", "example": "9000000000" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "fp_transaction_id": { "description": "OTP reference id for this one withdrawal attempt. Send it to Cash Withdrawal as `txn_otp_request_id`. It is NOT the OTP — the customer receives that by SMS.", "example": "FP2609010001234567", "type": "string" } } } } }, "examples": { "success": { "summary": "1459 — OTP generated and sent to the customer by SMS — send `data.fp_transaction_id` as `txn_otp_request_id` to Cash Withdrawal", "value": { "response_status_id": 0, "data": { "fp_transaction_id": "FP2609010001234567" }, "response_type_id": 1459, "message": "OTP generated successfully. Use the reference ID for your transaction.", "status": 0 } }, "otp_generation_failed_generic_fingpay_failure_there_are_no_otp_specific_error_codes_yet_message_carries_the_gateway_s_reason": { "summary": "OTP generation failed — generic Fingpay failure. There are no OTP-specific error codes yet; `message` carries the gateway's reason", "value": { "response_status_id": 1, "message": "", "status": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "10000001" }, "bank_code": { "type": "string", "description": "Short bank code identifying the customer's Aadhaar-linked bank (e.g. `HDFC`, `SBIN`). Obtain from the bank list API. Recommended — send the same value you will use for the withdrawal.", "example": "HDFC" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the customer — the same value you send to Cash Withdrawal. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "latlong": { "type": "string", "description": "GPS coordinates of the agent's device in 'latitude,longitude' format.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" }, "amount": { "type": "number", "description": "Withdrawal amount in Indian Rupees (integer) — the same amount you will send to Cash Withdrawal. Only call this API when it is above ₹5,000.", "example": 6000 } }, "required": [ "initiator_id", "user_code", "aadhar", "latlong", "amount" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "10000001", "bank_code": "HDFC", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "latlong": "28.6139,77.2090", "amount": 6000 } } } } } }, "/customer/collection/aeps-fingpay/cash-withdrawl/{customer_id}": { "post": { "operationId": "aepsFingpayCashWithdrawal", "summary": "AePS Cash Withdrawal", "description": "Allows a customer to withdraw cash from their bank account at an agent/BC point by providing their Aadhaar number and a live fingerprint scan. The agent's biometric device captures a PID XML blob which is passed verbatim to this API. The customer's Aadhaar is RSA-encrypted before transmission. Requires the agent to have completed AePS Fingpay activation, the one-time eKYC (Send OTP → Verify OTP → Biometric), and the Daily KYC for the current day.\n\n**Above ₹5,000 a transaction OTP is required.** First call Cash Withdrawal OTP, then send its `fp_transaction_id` here as `txn_otp_request_id`, and put the customer's 6-digit SMS OTP in the `otp` attribute of the PidOptions used for the fingerprint capture. For ₹5,000 or less, no OTP step is needed.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1463 | Transaction Successful | — |\n| 1464 | Transaction Fail — above ₹5,000 this also covers an expired, invalid or already-used OTP (there is no separate code). Once the failure is final, generate a fresh OTP and re-capture before retrying | — |\n| 1465 | Transaction Pending — check final status later | [transaction-inquiry](https://eps.eko.in/docs/transaction-inquiry) |\n| 1459 | OTP required — `amount` is above ₹5,000 but no `txn_otp_request_id` was sent. Nothing was withdrawn; an OTP was sent to the customer. Retry with `data.fp_transaction_id` as `txn_otp_request_id` and the customer's SMS OTP in the PidOptions `otp` attribute — do not generate another OTP | — |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-cash-withdrawal", "x-eko-trxn-type-id": 345, "x-eko-product-code": 329, "x-eko-uat-unavailable": true, "x-eko-financial": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Customer's registered mobile number.", "schema": { "type": "string", "description": "Customer's registered mobile number.", "example": "9000000000" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "tx_status": { "description": "Transaction state: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tid": { "description": "Eko's internal transaction ID. Use for reconciliation and support queries.", "example": "0000000000", "type": "string" }, "amount": { "description": "Withdrawal amount processed in the transaction (INR).", "example": "1000.00", "type": "string" }, "bank": { "description": "Name of the customer's bank where the debit occurred.", "example": "Example Bank", "type": "string" }, "bank_ref_num": { "description": "Bank/NPCI reference number (RRN) for the transaction. Empty on failure.", "example": "0000000000", "type": "string" }, "balance": { "description": "Remaining balance in the customer's bank account after withdrawal, if returned by the bank.", "example": "0.00", "type": "string" }, "customer_balance": { "description": "Customer's account balance as reported by the bank. Empty when not returned.", "example": "0.00", "type": "string" }, "tds": { "description": "Tax deducted at source on the agent's commission (INR).", "example": "0.00", "type": "string" }, "commission": { "description": "Commission earned by the agent on this transaction (INR).", "example": "0.00", "type": "string" }, "fee": { "description": "Fee charged for the transaction (INR). May be empty.", "example": "0.00", "type": "string" }, "service_tax": { "description": "Service tax component on the fee (INR). May be empty.", "example": "0.00", "type": "string" }, "totalfee": { "description": "Total fee including taxes (INR). May be empty.", "example": "0.00", "type": "string" }, "shop": { "description": "Agent's shop/merchant name.", "example": "Test User", "type": "string" }, "shop_address_line1": { "description": "Agent's shop address. May be empty.", "example": "", "type": "string" }, "sender_name": { "description": "Name of the agent/sender initiating the transaction.", "example": "Test User", "type": "string" }, "merchantname": { "description": "Registered merchant name of the agent.", "example": "Test User", "type": "string" }, "merchant_code": { "description": "Merchant code of the agent. May be empty.", "example": "", "type": "string" }, "user_code": { "description": "Echo of the agent's user_code from the request.", "example": "10000001", "type": "string" }, "aadhar": { "description": "Masked Aadhaar number of the customer.", "example": "XXXX XXXX 0000", "type": "string" }, "auth_code": { "description": "Bank authorization code. May be empty.", "example": "", "type": "string" }, "stan": { "description": "System Trace Audit Number assigned by the switch. May be empty.", "example": "", "type": "string" }, "terminal_id": { "description": "Terminal identifier. May be empty.", "example": "", "type": "string" }, "tx_status": { "description": "Transaction state within the data block: 0=Success, 1=Fail, 2=Pending.", "example": "0", "type": "string" }, "transaction_date": { "description": "Transaction date (DD-MM-YY HH:MM:SS).", "example": "01-01-24 00:00:00", "type": "string" }, "transaction_time": { "description": "Transaction timestamp (DD-MM-YY HH:MM:SS).", "example": "01-01-24 00:00:00", "type": "string" }, "reason": { "description": "Failure reason, when the transaction did not complete. Empty on success.", "example": "", "type": "string" }, "comment": { "description": "Human-readable transaction remark from the provider (e.g. 'Request Completed').", "example": "Request Completed", "type": "string" }, "fp_transaction_id": { "description": "Returned only with `response_type_id` 1459 (OTP required — nothing was withdrawn): the OTP reference to send back as `txn_otp_request_id`.", "example": "FP2609010001234567", "type": "string" } } } } }, "examples": { "success": { "summary": "1463 — Transaction Successful", "value": { "response_status_id": 0, "data": { "tx_status": "0", "tds": "0.00", "shop": "Test User", "sender_name": "Test User", "tid": "0000000000", "bank": "Example Bank", "balance": "0.00", "user_code": "10000001", "merchantname": "Test User", "aadhar": "XXXX XXXX 0000", "customer_balance": "0.00", "transaction_time": "01-01-24 00:00:00", "commission": "0.00", "bank_ref_num": "0000000000", "transaction_date": "01-01-24 00:00:00", "amount": "1000.00", "comment": "Request Completed" }, "response_type_id": 1463, "message": "Transaction Successful", "status": 0 } }, "transaction_fail_incorrect_merchant_credentials": { "summary": "1464 — Transaction Fail — above ₹5,000 this also covers an expired, invalid or already-used OTP (there is no separate code). Once the failure is final, generate a fresh OTP and re-capture before retrying", "value": { "response_status_id": 1, "data": { "tx_status": "1", "transaction_date": "01-01-24 00:00:00", "reason": "", "amount": "1000.00", "merchant_code": "", "shop": "Test User", "sender_name": "Test User", "tid": "0000000000", "auth_code": "", "shop_address_line1": "", "user_code": "10000001", "merchantname": "Test User", "stan": "", "aadhar": "XXXX XXXX 0000", "customer_balance": "0.00", "transaction_time": "01-01-24 00:00:00", "comment": "Incorrect merchantId or pin", "bank_ref_num": "", "terminal_id": "" }, "response_type_id": 1464, "message": "Transaction Fail", "status": 1464 } }, "transaction_fail_invalid_bank_code_transaction_not_completed": { "summary": "1464 — Transaction Fail — above ₹5,000 this also covers an expired, invalid or already-used OTP (there is no separate code). Once the failure is final, generate a fresh OTP and re-capture before retrying", "value": { "response_status_id": 1, "data": { "tx_status": "", "transaction_date": "", "reason": "Transaction Not Completed", "amount": "", "merchant_code": "", "shop": "", "sender_name": "", "tid": "", "auth_code": "", "shop_address_line1": "", "user_code": "", "merchantname": "", "stan": "", "aadhar": "", "customer_balance": "", "transaction_time": "", "comment": "Transaction Not Completed", "bank_ref_num": "", "terminal_id": "" }, "response_type_id": 1464, "message": "Transaction Fail", "status": 1464 } }, "otp_required_amount_above_5_000_sent_without_txn_otp_request_id_nothing_was_withdrawn_an_otp_was_sent_to_the_customer_instead": { "summary": "1459 — OTP required — `amount` is above ₹5,000 but no `txn_otp_request_id` was sent. Nothing was withdrawn; an OTP was sent to the customer. Retry with `data.fp_transaction_id` as `txn_otp_request_id` and the customer's SMS OTP in the PidOptions `otp` attribute — do not generate another OTP", "value": { "response_status_id": 0, "data": { "fp_transaction_id": "FP2609010001234567" }, "response_type_id": 1459, "message": "OTP generated successfully. Use the reference ID for your transaction.", "status": 0 } }, "transaction_pending_awaiting_bank_confirmation": { "summary": "1465 — Transaction Pending — check final status later", "value": { "response_status_id": 2, "data": { "tx_status": "2", "transaction_date": "01-01-24 00:00:00", "reason": "Transaction Pending", "amount": "1000.00", "merchant_code": "", "shop": "Test User", "fee": "", "sender_name": "", "tid": "0000000000", "auth_code": "", "shop_address_line1": "", "user_code": "10000001", "service_tax": "0.00", "totalfee": "0.00", "merchantname": "Test User", "stan": "", "aadhar": "XXXX XXXX 0000", "customer_balance": "", "transaction_time": "01-01-24 00:00:00", "comment": "Transaction Pending", "bank_ref_num": "", "terminal_id": "" }, "response_type_id": 1465, "message": "Transaction Pending", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "10000001" }, "bank_code": { "type": "string", "description": "Short bank code identifying the customer's Aadhaar-linked bank (e.g. `HDFC`, `SBIN`). Obtain from the bank list API.", "example": "HDFC" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the customer. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "latlong": { "type": "string", "description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" }, "piddata": { "type": "string", "description": "PID data captured from the UIDAI-certified biometric device, as a raw XML string. Must use Data type='X' (XML, not Protobuf). DeviceInfo must include the 'mc' (device certificate) parameter. fType must be 2. For an `amount` above ₹5,000, set the `otp` attribute of the PidOptions `` element to the customer's 6-digit SMS OTP before capture — the OTP itself, not the `fp_transaction_id`.", "example": "..." }, "amount": { "type": "number", "description": "Withdrawal amount in Indian Rupees (integer). Must be greater than 0 for cash withdrawal. Above ₹5,000, call Cash Withdrawal OTP first and send `txn_otp_request_id`.", "example": 1000 }, "txn_otp_request_id": { "type": "string", "description": "Required when `amount` is above ₹5,000: the `fp_transaction_id` returned by Cash Withdrawal OTP for this attempt (e.g. `FP2609010001234567`). Omit for ₹5,000 or less." } }, "required": [ "initiator_id", "user_code", "bank_code", "aadhar", "latlong", "piddata", "amount" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "10000001", "bank_code": "HDFC", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "latlong": "28.6139,77.2090", "piddata": "...", "amount": 1000 } } } } } }, "/customer/collection/aeps-fingpay/balance-enquiry/{customer_id}": { "post": { "operationId": "aepsFingpayBalanceEnquiry", "summary": "AePS Balance Enquiry", "description": "Retrieves the real-time account balance from any Aadhaar-linked bank. Uses the dedicated `balance-enquiry` endpoint — the request shape matches Cash Withdrawal without the `amount` field. No money movement occurs and no debit takes place. The agent must have completed AePS Fingpay activation and the current-day daily authentication before calling this API.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1466 | Transaction Successful | — |\n| 1464 | Transaction Fail | — |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-balance-enquiry", "x-eko-trxn-type-id": 346, "x-eko-product-code": 330, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": false, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Customer's registered mobile number.", "schema": { "type": "string", "description": "Customer's registered mobile number.", "example": "9000000000" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tid": { "description": "Eko's internal transaction ID for this enquiry.", "example": "0000000000", "type": "string" }, "amount": { "description": "Echo of the transacted amount (INR). '0.0' for a balance enquiry.", "example": "0.00", "type": "string" }, "customer_balance": { "description": "Customer's account balance returned by the bank (INR). This is the key output of a Balance Enquiry.", "example": "0.00", "type": "string" }, "shop": { "description": "Agent's shop/merchant name.", "example": "Test User", "type": "string" }, "shop_address_line1": { "description": "Agent's shop address. May be empty.", "example": "", "type": "string" }, "sender_name": { "description": "Name of the agent/sender initiating the enquiry.", "example": "Test User", "type": "string" }, "merchantname": { "description": "Registered merchant name of the agent.", "example": "Test User", "type": "string" }, "merchant_code": { "description": "Merchant code of the agent. May be empty.", "example": "", "type": "string" }, "user_code": { "description": "Echo of the agent's user_code from the request.", "example": "10000001", "type": "string" }, "aadhar": { "description": "Masked Aadhaar number of the customer.", "example": "XXXX XXXX 0000", "type": "string" }, "auth_code": { "description": "Bank authorization code. May be empty.", "example": "", "type": "string" }, "stan": { "description": "System Trace Audit Number assigned by the switch. May be empty.", "example": "", "type": "string" }, "terminal_id": { "description": "Terminal identifier. May be empty.", "example": "", "type": "string" }, "fee": { "description": "Fee charged for the enquiry (INR). May be empty.", "example": "0.00", "type": "string" }, "service_tax": { "description": "Service tax component on the fee (INR). May be empty.", "example": "0.00", "type": "string" }, "totalfee": { "description": "Total fee including taxes (INR). May be empty.", "example": "0.00", "type": "string" }, "transaction_date": { "description": "Transaction date (DD-MM-YY HH:MM:SS).", "example": "01-01-24 00:00:00", "type": "string" }, "transaction_time": { "description": "Transaction timestamp (DD-MM-YY HH:MM:SS).", "example": "01-01-24 00:00:00", "type": "string" }, "reason": { "description": "Failure reason, when the enquiry did not complete. Empty on success.", "example": "", "type": "string" }, "comment": { "description": "Human-readable remark from the provider (e.g. 'Request Completed').", "example": "Request Completed", "type": "string" } } } } }, "examples": { "success": { "summary": "1466 — Transaction Successful", "value": { "response_status_id": 0, "data": { "transaction_date": "01-01-24 00:00:00", "amount": "0.00", "shop": "Test User", "sender_name": "Test User", "tid": "0000000000", "user_code": "10000001", "merchantname": "Test User", "aadhar": "XXXX XXXX 0000", "customer_balance": "0.00", "transaction_time": "01-01-24 00:00:00", "comment": "Request Completed" }, "response_type_id": 1466, "message": "Transaction Successful", "status": 0 } }, "transaction_fail_incorrect_merchant_credentials": { "summary": "1464 — Transaction Fail", "value": { "response_status_id": 1, "data": { "tx_status": "1", "transaction_date": "01-01-24 00:00:00", "reason": "", "amount": "0.00", "merchant_code": "", "shop": "Test User", "sender_name": "Test User", "tid": "0000000000", "auth_code": "", "shop_address_line1": "", "user_code": "10000001", "merchantname": "Test User", "stan": "", "aadhar": "XXXX XXXX 0000", "customer_balance": "0.00", "transaction_time": "01-01-24 00:00:00", "comment": "Incorrect merchantId or pin", "bank_ref_num": "", "terminal_id": "" }, "response_type_id": 1464, "message": "Transaction Fail", "status": 1464 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "10000001" }, "bank_code": { "type": "string", "description": "Short bank code identifying the customer's Aadhaar-linked bank (e.g. `HDFC`, `SBIN`). Obtain from the bank list API.", "example": "HDFC" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the customer. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "latlong": { "type": "string", "description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" }, "piddata": { "type": "string", "description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc present in DeviceInfo).", "example": "..." } }, "required": [ "initiator_id", "user_code", "bank_code", "aadhar", "latlong", "piddata" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "10000001", "bank_code": "HDFC", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "latlong": "28.6139,77.2090", "piddata": "..." } } } } } }, "/customer/collection/aeps-fingpay/mini-statement/{customer_id}": { "post": { "operationId": "aepsFingpayMiniStatement", "summary": "AePS Mini Statement", "description": "Fetches a mini statement (typically the last 5–10 transactions) from a customer's bank account by authenticating through Aadhaar biometrics. Uses the dedicated `mini-statement` endpoint — the request shape matches Balance Enquiry (no `amount`). No money movement occurs. The response includes a list of recent debit/credit transactions with amounts and dates. Useful for customers who want to verify recent activity at an agent point without visiting a branch.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\nThe `aadhar` parameter must be encrypted with Fingpay's RSA public key (PKCS#1 v1.5 padding) and Base64-encoded — never sent as plain text. See [Aadhaar Encryption (Fingpay AePS)](/docs/fingpay-aeps-aadhaar-encryption) for how to get the production key and code samples.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1527 | Transaction Successful | — |\n| 1528 | Transaction Fail | — |", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-fingpay-mini-statement", "x-eko-trxn-type-id": 497, "x-eko-product-code": 469, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": false, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Customer's registered mobile number.", "schema": { "type": "string", "description": "Customer's registered mobile number.", "example": "9000000000" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tid": { "description": "Eko's internal transaction ID for this enquiry.", "example": "0000000000", "type": "string" }, "mini_statement_list": { "description": "List of recent transactions. Each entry carries the transaction date, amount, direction (Dr/Cr), and narration.", "type": "array", "items": { "type": "object", "properties": { "date": { "description": "Transaction date (DD/MM).", "example": "01/01", "type": "string" }, "amount": { "description": "Transaction amount in INR.", "example": "0.00", "type": "string" }, "narration": { "description": "Bank-provided transaction narration or description.", "example": "MAT/W/000000", "type": "string" }, "txnType": { "description": "Transaction direction: 'Cr' for credit, 'Dr' for debit.", "example": "Dr", "type": "string" } } } }, "sender_name": { "description": "Name of the agent/sender initiating the enquiry.", "example": "Test User", "type": "string" }, "merchantname": { "description": "Registered merchant name of the agent.", "example": "Test User", "type": "string" }, "merchant_code": { "description": "Merchant code of the agent. May be empty.", "example": "", "type": "string" }, "user_code": { "description": "Echo of the agent's user_code from the request.", "example": "10000001", "type": "string" }, "customer_balance": { "description": "Customer's account balance as reported by the bank (INR). May be empty.", "example": "0.00", "type": "string" }, "commission": { "description": "Commission earned by the agent on this enquiry (INR).", "example": "0.00", "type": "string" }, "service_tax": { "description": "Service tax component on the fee (INR). May be empty.", "example": "0.00", "type": "string" }, "totalfee": { "description": "Total fee including taxes (INR). May be empty.", "example": "0.00", "type": "string" }, "terminal_id": { "description": "Terminal identifier. May be empty.", "example": "", "type": "string" }, "bank_ref_num": { "description": "NPCI/bank reference number for this statement fetch. May be empty.", "example": "", "type": "string" }, "transaction_date": { "description": "Transaction date (DD-MM-YY HH:MM:SS).", "example": "01-01-24 00:00:00", "type": "string" }, "transaction_time": { "description": "Transaction timestamp (DD-MM-YY HH:MM:SS).", "example": "01-01-24 00:00:00", "type": "string" }, "reason": { "description": "Failure reason, when the enquiry did not complete. Empty on success.", "example": "", "type": "string" }, "comment": { "description": "Human-readable remark from the provider (e.g. 'Request Completed').", "example": "Request Completed", "type": "string" } } } } }, "examples": { "success": { "summary": "1527 — Transaction Successful", "value": { "response_status_id": 0, "data": { "transaction_date": "01-01-24 00:00:00", "mini_statement_list": [ { "date": "01/01", "amount": "0.00", "narration": "MAT/W/000000", "txnType": "Dr" }, { "date": "31/12", "amount": "0.00", "narration": "MAT/D/000000", "txnType": "Cr" }, { "date": "28/12", "amount": "0.00", "narration": "POS/W/000000", "txnType": "Dr" } ], "sender_name": "Test User", "tid": "0000000000", "user_code": "10000001", "merchantname": "Test User", "customer_balance": "0.00", "transaction_time": "01-01-24 00:00:00", "commission": "0.00", "terminal_id": "", "comment": "Request Completed" }, "response_type_id": 1527, "message": "Transaction Successful", "status": 0 } }, "transaction_fail_incorrect_merchant_credentials": { "summary": "1528 — Transaction Fail", "value": { "response_status_id": 1, "data": { "transaction_date": "01-01-24 00:00:00", "reason": "", "merchant_code": "", "merchantname": "Test User", "customer_balance": "", "transaction_time": "01-01-24 00:00:00", "sender_name": "Test User", "comment": "Incorrect merchantId or pin", "bank_ref_num": "", "tid": "0000000000", "terminal_id": "" }, "response_type_id": 1528, "message": "Transaction Fail", "status": 1528 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "10000001" }, "bank_code": { "type": "string", "description": "Short bank code identifying the customer's Aadhaar-linked bank (e.g. `HDFC`, `SBIN`). Obtain from the bank list API.", "example": "HDFC" }, "aadhar": { "type": "string", "description": "RSA-encrypted (PKCS#1 v1.5), Base64-encoded Aadhaar number of the customer. See the Aadhaar Encryption (Fingpay AePS) guide for the key and code samples.", "example": "BASE64_ENCRYPTED_AADHAAR" }, "latlong": { "type": "string", "description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" }, "piddata": { "type": "string", "description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc present in DeviceInfo).", "example": "..." } }, "required": [ "initiator_id", "user_code", "bank_code", "aadhar", "latlong", "piddata" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "10000001", "bank_code": "HDFC", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "latlong": "28.6139,77.2090", "piddata": "..." } } } } } }, "/user/payment/aeps/settlement/account": { "post": { "operationId": "aepsAddSettlementAccount", "summary": "Add Settlement Bank Account", "description": "Adds and name-verifies a bank account to which an agent can settle AePS funds. On success a `recipient_id` is returned — pass it to Initiate Settlement. If the account holder name does not match, the response reports the mismatch. An agent can register up to 3 settlement accounts, and only banks that offer account verification are accepted.", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-add-settlement-account", "x-eko-trxn-type-id": 399, "x-eko-product-code": 380, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "creates", "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "recipient_id": { "description": "Settlement recipient identifier — pass to Initiate Settlement.", "example": 1893, "type": "number" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "recipient_id": 1893 }, "response_type_id": 1336, "message": "Account added", "status": 0 } }, "account_verification_failed_name_mismatch": { "summary": "Account verification failed — name mismatch", "value": { "response_status_id": 1, "data": { "sender_name": "SANATAN CSP", "recipient_name": "R K LAKSHYKAR" }, "response_type_id": 1335, "message": "Account verification fail, Name not matched", "status": 1335 } }, "account_verification_failed_name_not_returned_by_bank": { "summary": "Account verification failed — name not returned by bank", "value": { "response_status_id": 1, "response_type_id": 1334, "message": "Account verification fail name not returned by bank", "status": 1334 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" }, "bank_id": { "type": "integer", "description": "Unique identifier for the bank.", "example": 12 }, "ifsc": { "type": "string", "description": "IFSC code of the bank account.", "example": "SBIN0000000", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" }, "service_code": { "type": "integer", "description": "Service code for AePS fund settlement. Value: 39.", "example": 39 }, "account": { "type": "string", "description": "Account number of the user's bank account.", "example": "00000000000002" } }, "required": [ "initiator_id", "user_code", "bank_id", "ifsc", "service_code", "account" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "20810200", "bank_id": 12, "ifsc": "SBIN0000000", "service_code": 39, "account": "00000000000002" } } } } } }, "/user/payment/aeps/settlement/accounts": { "get": { "operationId": "aepsGetSettlementAccounts", "summary": "Get Settlement Bank Accounts", "description": "Returns the agent's saved settlement bank accounts (each with a `recipient_id`), the total unsettled fund, and the remaining daily settlement limit.", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-get-settlement-accounts", "x-eko-trxn-type-id": 391, "x-eko-product-code": 372, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "user_code", "in": "query", "required": true, "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "schema": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "unsettled_fund": { "description": "Total unsettled AePS fund available to settle (INR).", "example": "6100.0", "type": "string" }, "remaining_limit": { "description": "Remaining settlement limit for the day (INR).", "example": "190000", "type": "string" }, "fund_transfer_list": { "description": "Registered settlement recipients.", "type": "array", "items": { "type": "object", "properties": { "recipient_id": { "description": "Settlement recipient identifier — pass to Initiate Settlement.", "example": "1828", "type": "string" }, "name": { "description": "Account holder name.", "example": "Test Recipient", "type": "string" }, "account": { "description": "Bank account number.", "example": "00000000000001", "type": "string" }, "ifsc": { "description": "Bank branch IFSC.", "example": "SBIN0000000", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": -1, "data": { "unsettled_fund": "6100.0", "remaining_limit": "190000", "fund_transfer_list": [ { "name": "Test Recipient", "ifsc": "SBIN0000000", "account": "00000000000001", "recipient_id": "1828" }, { "name": "Test Recipient", "ifsc": "SBIN0000000", "account": "00000000000002", "recipient_id": "1829" } ] }, "response_type_id": 1321, "message": "List of fund transfer recipients", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/user/payment/aeps/settlement": { "post": { "operationId": "aepsInitiateSettlement", "summary": "Initiate Settlement", "description": "Initiates a fund settlement of the requested amount to a registered `recipient_id`. Returns the financial response envelope with `tx_status`, transaction id (`tid`), fee, and updated balance. Settlement is available Mon–Fri 10am–5pm (excl. RBI holidays); max ₹2,00,000 per transaction; requests after 5pm settle the next working day.", "tags": [ "AePS Cashout" ], "x-docs-slug": "aeps-initiate-settlement", "x-eko-trxn-type-id": 392, "x-eko-product-code": 373, "x-eko-uat-unavailable": true, "x-eko-financial": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "tx_status": { "description": "Transaction state: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tx_status": { "description": "Transaction status code (0 = success).", "example": "0", "type": "string" }, "amount": { "description": "Settled amount (INR).", "example": "5000.00", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "fee": { "description": "Base fee charged for the settlement (INR).", "example": "17.70", "type": "string" }, "gst": { "description": "GST charged on the settlement fee (INR).", "example": "2.70", "type": "string" }, "sender_name": { "description": "Name of the settling agent.", "example": "Test User", "type": "string" }, "tid": { "description": "Eko transaction ID for the settlement.", "example": "0000000000", "type": "string" }, "client_ref_id": { "description": "Client reference id echoed for the settlement.", "example": "00000000000000000000", "type": "string" }, "balance": { "description": "Agent balance after the settlement (INR).", "example": "0.00", "type": "string" }, "user_code": { "description": "Code of the user/agent the settlement was run for.", "example": "10000001", "type": "string" }, "totalfee": { "description": "Total fee charged for the settlement, incl. GST (INR).", "example": "17.70", "type": "string" }, "recipient_name": { "description": "Name on the destination bank account.", "example": "Test Recipient", "type": "string" }, "ifsc": { "description": "Destination branch IFSC.", "example": "SBIN0000000", "type": "string" }, "bank_ref_num": { "description": "Bank reference / UTR number. Empty until the bank confirms the transfer.", "example": "", "type": "string" }, "account": { "description": "Destination account number.", "example": "00000000000000", "type": "string" }, "timestamp": { "description": "Settlement timestamp. Empty on the initial response.", "example": "", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "tx_status": "0", "amount": "5000.00", "txstatus_desc": "Success", "fee": "17.70", "gst": "2.70", "sender_name": "Test User", "tid": "0000000000", "client_ref_id": "00000000000000000000", "balance": "0.00", "user_code": "10000001", "totalfee": "17.70", "recipient_name": "Test Recipient", "ifsc": "SBIN0000000", "bank_ref_num": "", "account": "00000000000000", "timestamp": "" }, "response_type_id": 1477, "message": "Transaction processed successfully", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" }, "amount": { "type": "integer", "description": "Settlement amount requested (INR). Max 200000 per transaction.", "example": 100 }, "recipient_id": { "type": "integer", "description": "Settlement recipient identifier (from Add / Get Settlement Account).", "example": 1829 }, "payment_mode": { "type": "integer", "description": "Transfer method: 4 = NEFT, 5 = IMPS, 13 = RTGS.", "example": 5 } }, "required": [ "initiator_id", "user_code", "amount", "recipient_id", "payment_mode" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "20810200", "amount": 100, "recipient_id": 1829, "payment_mode": 5 } } } } } }, "/customer/payment/bbps/categories": { "get": { "operationId": "bbpsGetCategories", "summary": "Get BBPS Categories", "description": "Returns all BBPS biller categories. Pass an `operator_category_id` from here as the `category` filter on Get Operators, and as the `category` param on Fetch Bill and Pay Bill.\n\nCommon ids: 1 Broadband Postpaid · 2 Gas · 4 DTH · 5 Mobile Prepaid · 6 Tax · 7 Credit Card · 8 Electricity · 9 Landline Postpaid · 10 Mobile Postpaid · 11 Water · 12 Housing Society · 13 Subscription · 14 Education · 15 Municipal Taxes · 16 Clubs and Associations · 17 Cable TV · 18 LPG Cylinder · 19 Hospital · 20 Insurance · 21 Loan · 22 FASTag · 23 Municipal Services · 24 Rental Payment · 27+ eChallan, Agent Collection, EV Recharge and others.\n\n**Do not hard-code these ids** — the live response is authoritative and the list grows. The category list is returned under `param_attributes.list_elements`, not under `data`.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2457 | Category list returned — pick one and list its billers. | [bbps-get-operators](https://eps.eko.in/docs/bbps-get-operators) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-get-categories", "x-eko-trxn-type-id": 844, "x-eko-product-code": 782, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Wrapper for the category list — returned at the top level of the response, not under `data`.", "type": "object", "properties": { "list_elements": { "description": "One entry per BBPS biller category.", "type": "array", "items": { "type": "object", "properties": { "operator_category_id": { "description": "Category identifier. Pass as the `category` filter on Get Operators, and as `category` on Fetch Bill / Pay Bill.", "example": 8, "type": "number" }, "operator_category_name": { "description": "Human-readable category name.", "example": "Electricity", "type": "string" }, "operator_category_group": { "description": "Grouping code for the category.", "example": "0", "type": "string" }, "status": { "description": "`1` = active.", "example": "1", "type": "string" } } } } } } } } } }, "examples": { "success": { "summary": "2457 — Category list returned — pick one and list its billers.", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "operator_category_name": "Broadband Postpaid", "operator_category_id": 1, "operator_category_group": "0", "status": "1" }, { "operator_category_name": "Electricity", "operator_category_id": 8, "operator_category_group": "0", "status": "1" }, { "operator_category_name": "Water", "operator_category_id": 11, "operator_category_group": "0", "status": "1" }, { "operator_category_name": "FASTag", "operator_category_id": 22, "operator_category_group": "0", "status": "1" } ] }, "response_type_id": 2457, "message": "BBPS category fetch success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/locations": { "get": { "operationId": "bbpsGetLocations", "summary": "Get BBPS Locations", "description": "Returns every operating location (state / UT). Pass an `operator_location_id` from here as the `location` filter on Get Operators to narrow the biller list to one state.\n\n`operator_location_id` is a **zero-padded string** (`\"06\"`, `\"35\"`), not a number — keep it as a string when you pass it back. The list is returned under `param_attributes.list_elements`, not under `data`.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2459 | Location list returned — use one as the `location` filter on Get Operators. | [bbps-get-operators](https://eps.eko.in/docs/bbps-get-operators) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-get-locations", "x-eko-trxn-type-id": 844, "x-eko-product-code": 782, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Wrapper for the location list — returned at the top level of the response, not under `data`.", "type": "object", "properties": { "list_elements": { "description": "One entry per operating state / UT.", "type": "array", "items": { "type": "object", "properties": { "operator_location_id": { "description": "Zero-padded location identifier. Pass as the `location` filter on Get Operators.", "example": "06", "type": "string" }, "operator_location_name": { "description": "State / UT name.", "example": "Haryana", "type": "string" }, "abbreviation": { "description": "Two-letter state code.", "example": "HR", "type": "string" } } } } } } } } } }, "examples": { "success": { "summary": "2459 — Location list returned — use one as the `location` filter on Get Operators.", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "operator_location_name": "Haryana", "operator_location_id": "06", "abbreviation": "HR" }, { "operator_location_name": "Madhya Pradesh", "operator_location_id": "23", "abbreviation": "MP" }, { "operator_location_name": "Andaman and Nicobar", "operator_location_id": "35", "abbreviation": "AN" } ] }, "response_type_id": 2459, "message": "BBPS location fetch success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/operators": { "get": { "operationId": "bbpsGetOperators", "summary": "Get BBPS Operators", "description": "Returns the list of billers. Filter by `category`, `location`, or both, using the identifiers from Get Categories and Get Locations; omit both to list every biller.\n\nThe `operator_id` returned here is what you pass as **`phone_operator_code`** to Fetch Bill and Pay Bill — the names differ. `billFetchResponse` tells you whether the biller supports a live bill fetch. The list is returned under `param_attributes.list_elements`, not under `data`.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2461 | Biller list returned — read the chosen operator's input fields next. | [bbps-get-operator-parameters](https://eps.eko.in/docs/bbps-get-operator-parameters) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-get-operators", "x-eko-trxn-type-id": 844, "x-eko-product-code": 782, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category — the `operator_category_id` from Get Categories.", "schema": { "type": "number", "description": "Filter by category — the `operator_category_id` from Get Categories.", "example": 11 } }, { "name": "location", "in": "query", "required": false, "description": "Filter by state / UT — the `operator_location_id` from Get Locations.", "schema": { "type": "number", "description": "Filter by state / UT — the `operator_location_id` from Get Locations.", "example": 35 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Wrapper for the biller list — returned at the top level of the response, not under `data`.", "type": "object", "properties": { "list_elements": { "description": "One entry per biller matching the filters.", "type": "array", "items": { "type": "object", "properties": { "operator_id": { "description": "Biller identifier. Pass as `phone_operator_code` to Fetch Bill and Pay Bill.", "example": 541, "type": "number" }, "name": { "description": "Biller name.", "example": "Port Blair Municipal Council - Water", "type": "string" }, "operator_category": { "description": "Category this operator belongs to.", "example": 11, "type": "number" }, "location_id": { "description": "Location this operator serves; `0` = pan-India.", "example": 35, "type": "number" }, "kyc_required": { "description": "Whether customer KYC is required for this operator.", "example": 0, "type": "number" }, "billFetchResponse": { "description": "Whether the operator supports live bill fetch (`1` = yes).", "example": 0, "type": "number" }, "high_commission_channel": { "description": "Whether the biller is available on the higher-commission channel.", "example": 0, "type": "number" } } } } } } } } } }, "examples": { "success": { "summary": "2461 — Biller list returned — read the chosen operator's input fields next.", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "operator_id": 159, "name": "ACT Fibernet", "billFetchResponse": 0, "high_commission_channel": 0, "kyc_required": 1, "operator_category": 1, "location_id": 0 }, { "operator_id": 541, "name": "Port Blair Municipal Council - Water", "billFetchResponse": 0, "high_commission_channel": 0, "kyc_required": 0, "operator_category": 11, "location_id": 35 } ] }, "response_type_id": 2461, "message": "BBPS operators fetch success", "status": 0 } }, "invalid_or_missing_initiator_id": { "summary": "Invalid or missing initiator_id", "value": { "response_status_id": 1, "invalid_params": { "initiator_id": "Merchant does not exist in system." }, "data": { "csp_id": "7042769385" }, "response_type_id": -1, "message": "Invalid Sender/Initiator", "status": 319 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/operator/{operator_id}/parameters": { "get": { "operationId": "bbpsGetOperatorParameters", "summary": "Get Operator Parameters", "description": "Returns the input fields the chosen operator requires — field names, labels, types and validation regex — so you can render the bill-entry form dynamically.\n\n**`list_elements` is the source of truth for this operator's fields.** The documented parameters on Fetch Bill and Pay Bill are only the common set; every `param_name` returned here must also be sent to **both** calls, with identical values. Call this once per operator and cache the result.\n\nThe payload is returned under `param_attributes`, not under `data`.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2463 | Parameter schema returned — collect these fields, then fetch the bill. | [bbps-fetch-bill](https://eps.eko.in/docs/bbps-fetch-bill) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-get-operator-parameters", "x-eko-trxn-type-id": 844, "x-eko-product-code": 782, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "operator_id", "in": "path", "required": true, "description": "The `operator_id` from the Get Operators response.", "schema": { "type": "number", "description": "The `operator_id` from the Get Operators response.", "example": 5 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Wrapper for the operator's parameter schema — returned at the top level of the response, not under `data`.", "type": "object", "properties": { "operator_name": { "description": "Display name of the operator.", "example": "BSNL Prepaid", "type": "string" }, "operator_id": { "description": "The operator this schema belongs to.", "example": 5, "type": "number" }, "fetchBill": { "description": "Whether live bill fetch is supported (`1` = yes).", "example": 0, "type": "number" }, "BBPS": { "description": "Whether the biller is on the BBPS network; display Bharat BillPay branding per NPCI guidelines.", "example": 0, "type": "number" }, "list_elements": { "description": "The input fields this operator requires. Send every `param_name` to BOTH Fetch Bill and Pay Bill.", "type": "array", "items": { "type": "object", "properties": { "param_name": { "description": "Field name to submit at bill-fetch / pay time.", "example": "utility_acc_no", "type": "string" }, "param_label": { "description": "Label to show the agent.", "example": "Mobile Number", "type": "string" }, "param_id": { "description": "Identifier for this field.", "example": "1", "type": "string" }, "param_type": { "description": "Field type — e.g. `Numeric`, `List`.", "example": "Numeric", "type": "string" }, "regex": { "description": "Client-side validation pattern.", "example": "^[0-9]{10}$", "type": "string" }, "error_message": { "description": "Validation message to show when the regex does not match.", "example": "Please enter a valid 10 digit Mobile Number (eg. 0940763946)", "type": "string" } } } } } } } } } }, "examples": { "success": { "summary": "2463 — Parameter schema returned — collect these fields, then fetch the bill.", "value": { "response_status_id": 0, "param_attributes": { "operator_name": "BSNL Prepaid", "list_elements": [ { "param_label": "Mobile Number", "param_name": "utility_acc_no", "param_id": "1", "param_type": "Numeric", "regex": "^[0-9]{10}$", "error_message": "Please enter a valid 10 digit Mobile Number (eg. 0940763946)" }, { "param_label": "Recharge Type", "param_name": "Recharge Type", "param_id": "99", "param_type": "List", "regex": "1|3", "error_message": "Please enter valid Recharge Type" } ], "operator_id": 5, "fetchBill": 0, "BBPS": 0 }, "response_type_id": 2463, "message": "BBPS operator parameters fetch success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/operators/190/district-discome": { "get": { "operationId": "bbpsDistrictDiscome", "summary": "Get District Discome (UPPCL)", "description": "Some electricity billers require a district-level distribution company (discome) code. This applies to **operator 190 (UPPCL) only** — no other biller needs it, and the path is fixed to `190` rather than parameterised.\n\nShow the agent each `label` and send the matching `value` as `district_discome` on both Fetch Bill and Pay Bill.\n\nThe list is returned under `param_attributes.list_elements`, not under `data`.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2110 | District list returned — pass the chosen `value` as `district_discome` when fetching the bill. | [bbps-fetch-bill](https://eps.eko.in/docs/bbps-fetch-bill) |\n| 2434 | Districts could not be fetched. The envelope still carries `status: 0`, so branch on this id rather than on `status`. | — |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-district-discome", "x-eko-trxn-type-id": 849, "x-eko-product-code": 783, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Wrapper for the district list — returned at the top level of the response, not under `data`.", "type": "object", "properties": { "list_elements": { "description": "One entry per UPPCL district.", "type": "array", "items": { "type": "object", "properties": { "label": { "description": "District name to show the agent.", "example": "Lucknow", "type": "string" }, "value": { "description": "The `district_discome` value to pass to Fetch Bill and Pay Bill for operator 190.", "example": "Lucknow-MVVNL", "type": "string" } } } } } } } } } }, "examples": { "success": { "summary": "2110 — District list returned — pass the chosen `value` as `district_discome` when fetching the bill.", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "label": "Agra", "value": "Agra-DVVNL" }, { "label": "Lucknow", "value": "Lucknow-MVVNL" }, { "label": "Kanpur Nagar", "value": "Kanpur Nagar-KESCO" }, { "label": "Varanasi", "value": "Varanasi-PUVNL" } ] }, "response_type_id": 2110, "message": "Success", "status": 0 } }, "districts_unavailable_note_this_still_returns_status_0_so_branch_on_response_type_id": { "summary": "2434 — Districts could not be fetched. The envelope still carries `status: 0`, so branch on this id rather than on `status`.", "value": { "response_status_id": 0, "response_type_id": 2434, "message": "Failed to fetch districts", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/recharge/{customer_mobile}/operator": { "get": { "operationId": "bbpsOperatorCodeCircle", "summary": "Get Operator Code and Circle", "description": "Detects the telecom operator and circle for a customer mobile number, returned as name/value pairs under `dependent_params` at the top level of the response (not under `data`).\n\n**Watch the rename:** this endpoint returns `circle_area`, but Get Recharge Plans expects that value as the **`circleid`** query parameter. The `phone_operator_code` value carries over under the same name.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1804 | Operator and circle detected — list the plans available for them. | [bbps-recharge-plans](https://eps.eko.in/docs/bbps-recharge-plans) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-operator-code-circle", "x-eko-trxn-type-id": 648, "x-eko-product-code": 608, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_mobile", "in": "path", "required": true, "description": "Customer's mobile number.", "schema": { "type": "string", "description": "Customer's mobile number.", "example": "9876543210" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "dependent_params": { "description": "Resolved operator/circle as name-value pairs (`phone_operator_code`, `circle_area`) — returned at the top level, not under `data`.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Parameter name (`phone_operator_code` or `circle_area`).", "example": "phone_operator_code", "type": "string" }, "value": { "description": "Parameter value. Pass `circle_area`'s value on as `circleid` to Get Recharge Plans.", "example": 400, "type": "number" } } } } } } } }, "examples": { "success": { "summary": "1804 — Operator and circle detected — list the plans available for them.", "value": { "response_status_id": 0, "dependent_params": [ { "name": "phone_operator_code", "value": 1 }, { "name": "circle_area", "value": "23" } ], "data": { "updates": "" }, "response_type_id": 1804, "message": "success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/recharge/{customer_mobile}/operator/plans": { "get": { "operationId": "bbpsRechargePlans", "summary": "Get Recharge Plans", "description": "Lists available recharge plans for an operator and circle. Plans arrive under `dependent_params` at the top level (not under `data`): the `req_list` entry's `value` array holds the plans, and its `type_metadata[].headers` describe which field is the price, the validity and the description.\n\n**`circleid` is the `circle_area` value** returned by Get Operator Code and Circle — the parameter is renamed between the two calls. Once the customer picks a plan, submit its `amount` through Pay Bill.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1804 | Plans returned — let the customer pick one, then submit its `amount` as the recharge. | [bbps-pay-bill](https://eps.eko.in/docs/bbps-pay-bill) |\n| 1805 | Plans could not be fetched. The envelope still carries `status: 0`, so branch on this id. The recharge can still proceed with an amount entered by the agent. | [bbps-pay-bill](https://eps.eko.in/docs/bbps-pay-bill) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-recharge-plans", "x-eko-trxn-type-id": 650, "x-eko-product-code": 610, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_mobile", "in": "path", "required": true, "description": "Customer's mobile number.", "schema": { "type": "string", "description": "Customer's mobile number.", "example": "9876543210" } }, { "name": "phone_operator_code", "in": "query", "required": true, "description": "Operator code from the Get Operator Code and Circle response.", "schema": { "type": "string", "description": "Operator code from the Get Operator Code and Circle response.", "example": "400" } }, { "name": "circleid", "in": "query", "required": true, "description": "Circle identifier — the value returned as `circle_area` by Get Operator Code and Circle. Note the name differs between the two endpoints.", "schema": { "type": "string", "description": "Circle identifier — the value returned as `circle_area` by Get Operator Code and Circle. Note the name differs between the two endpoints.", "example": "5" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "dependent_params": { "description": "Plan groups — returned at the top level, not under `data`. The entry named `req_list` carries the plans.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Group name; `req_list` holds the plan list.", "example": "req_list", "type": "string" }, "value": { "description": "The available plans.", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Plan price in rupees. Send this as `amount` to Pay Bill.", "example": "349", "type": "string" }, "validity": { "description": "How long the plan is valid for.", "example": "28 Days", "type": "string" }, "plan_description": { "description": "What the plan includes.", "example": "1.5 GB/day + Unlimited Calls ...", "type": "string" } } } }, "type_metadata": { "description": "Column metadata describing which plan field is the price, the validity and the description.", "type": "array", "items": {} } } } } } } } }, "examples": { "success": { "summary": "1804 — Plans returned — let the customer pick one, then submit its `amount` as the recharge.", "value": { "response_status_id": 0, "dependent_params": [ { "type_metadata": [ { "headers": [ { "name": "amount", "value": "price" }, { "name": "validity", "value": "validity" }, { "name": "plan_description", "value": "plan_description" } ], "dependent_params": [ { "name": "amount", "value": "amount" } ] } ], "name": "req_list", "value": [ { "amount": "224", "validity": "30 Days", "plan_description": "Unlimited Calls + 4GB data ..." }, { "amount": "349", "validity": "28 Days", "plan_description": "1.5 GB/day + Unlimited Calls ..." } ] } ], "response_type_id": 1804, "message": "success", "status": 0 } }, "plans_unavailable_note_this_still_returns_status_0_so_branch_on_response_type_id": { "summary": "1805 — Plans could not be fetched. The envelope still carries `status: 0`, so branch on this id. The recharge can still proceed with an amount entered by the agent.", "value": { "response_status_id": 0, "data": { "message": "Unable to fetch plans" }, "response_type_id": 1805, "message": "fail to fetch details", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps/bill": { "get": { "operationId": "bbpsFetchBill", "summary": "Fetch BBPS Bill", "description": "Retrieves the live bill amount and customer name for a biller. Call this before Pay Bill so the agent can confirm the amount with the customer.\n\n**Carry `amount` and `utilitycustomername` from this response into Pay Bill**, and use the same `client_ref_id` for the matching Pay Bill call. Paying anything other than the fetched amount is rejected with status `208`.\n\n**Parameters vary by operator.** The fields listed below are the common set — call Get Operator Parameters first and treat its `list_elements` as the source of truth. Every additional `param_name` it returns must be sent here **and** to Pay Bill, with the same values in both.\n\nNote that `response_status_id` is `-1` on success for this endpoint. Branch on `status` and `response_type_id`, never on `response_status_id`.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 1052 | Bill fetched — confirm the amount with the customer, then pay it. | [bbps-pay-bill](https://eps.eko.in/docs/bbps-pay-bill) |\n| 1468 | Bill fetch failed. Verify the account details and retry after some time — do not proceed to payment. | — |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-fetch-bill", "x-eko-trxn-type-id": 280, "x-eko-product-code": 265, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "phone_operator_code", "in": "query", "required": true, "description": "Biller identifier — the `operator_id` from the Get Operators response.", "schema": { "type": "string", "description": "Biller identifier — the `operator_id` from the Get Operators response.", "example": "53" } }, { "name": "utility_acc_no", "in": "query", "required": true, "description": "Bill/account number. For a prepaid recharge, the customer's mobile number.", "schema": { "type": "string", "description": "Bill/account number. For a prepaid recharge, the customer's mobile number.", "example": "3287820071" } }, { "name": "confirmation_mobile_no", "in": "query", "required": true, "description": "Customer's alternate mobile number. This is only used for sending the confirmation SMS. It may be same as the `utility_acc_no` for prepaid recharges.", "schema": { "type": "string", "description": "Customer's alternate mobile number. This is only used for sending the confirmation SMS. It may be same as the `utility_acc_no` for prepaid recharges.", "example": "9903457748" } }, { "name": "sender_name", "in": "query", "required": true, "description": "Customer name.", "schema": { "type": "string", "description": "Customer name.", "example": "Asaad" } }, { "name": "category", "in": "query", "required": true, "description": "The `operator_category_id` from Get Categories (e.g. `8` = Electricity).", "schema": { "type": "number", "description": "The `operator_category_id` from Get Categories (e.g. `8` = Electricity).", "example": 8 } }, { "name": "client_ref_id", "in": "query", "required": true, "description": "Unique partner reference for this request. Reuse the same value on the matching Pay Bill call; use a fresh one for every new payment attempt.", "schema": { "type": "string", "description": "Unique partner reference for this request. Reuse the same value on the matching Pay Bill call; use a fresh one for every new payment attempt.", "example": "2026010100123456789" } }, { "name": "source_ip", "in": "query", "required": true, "description": "Originating client IP address.", "schema": { "type": "string", "description": "Originating client IP address.", "example": "192.168.1.1" } }, { "name": "district_discome", "in": "query", "required": false, "description": "District-level distribution company code. Required for **operator 190 (UPPCL) only** — resolve it via the District Discome endpoint.", "schema": { "type": "string", "description": "District-level distribution company code. Required for **operator 190 (UPPCL) only** — resolve it via the District Discome endpoint.", "example": "Lucknow-MVVNL" } }, { "name": "state", "in": "query", "required": false, "description": "State code, where the operator requires it.", "schema": { "type": "string", "description": "State code, where the operator requires it.", "example": "1" } }, { "name": "communication", "in": "query", "required": false, "description": "Payment mode: `0` (default) = online — instant settlement, lower commission. `1` = offline — higher commission, but the bill takes a minimum of 6 working hours to settle. Pass the same value to Pay Bill.", "schema": { "type": "number", "description": "Payment mode: `0` (default) = online — instant settlement, lower commission. `1` = offline — higher commission, but the bill takes a minimum of 6 working hours to settle. Pass the same value to Pay Bill.", "example": 0 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "amount": { "description": "Bill amount due, in rupees. Present this to the customer and send the exact same value to Pay Bill.", "example": "2870.0", "type": "string" }, "utilitycustomername": { "description": "Customer name on the bill. Echo this back as `utilitycustomername` on Pay Bill.", "example": "Amit Kumar", "type": "string" }, "billDueDate": { "description": "Due date in `YYYYMMDD` format.", "example": "20260728", "type": "string" }, "customer_id": { "description": "Account / consumer number resolved by the biller.", "example": "3287820071", "type": "string" }, "billdate": { "description": "Date the bill was generated, where the biller returns it.", "example": "null", "type": "string" }, "billername": { "description": "Biller name, where provided.", "example": "", "type": "string" }, "bbpstrxnrefid": { "description": "BBPS transaction reference, where provided.", "example": "", "type": "string" }, "billDetailsList": { "description": "Additional bill line items, where the biller returns them.", "example": [], "type": "array", "items": {} }, "ifsc_status": { "description": "Biller-side status flag.", "example": 1, "type": "number" }, "user_code": { "description": "Agent's user code.", "example": "35739001", "type": "string" } } } } }, "examples": { "success": { "summary": "1052 — Bill fetched — confirm the amount with the customer, then pay it.", "value": { "response_status_id": -1, "data": { "amount": "2870.0", "utilitycustomername": "Amit Kumar", "ifsc_status": 1, "user_code": "35739001", "customer_id": "3287820071", "billDueDate": "20260728", "billdate": "null", "billDetailsList": [], "bbpstrxnrefid": "", "billername": "" }, "response_type_id": 1052, "message": "Due Bill Amount For utility", "status": 0 } }, "required_field_missing": { "summary": "Required field missing", "value": { "response_status_id": 1, "invalid_params": { "utility_acc_no": "Please provide the value of the field {2} {3}" }, "response_type_id": -1, "message": "Please provide the value of the field", "status": 97 } }, "bill_fetch_failed_at_the_biller": { "summary": "1468 — Bill fetch failed. Verify the account details and retry after some time — do not proceed to payment.", "value": { "response_status_id": 1, "data": { "reason": "Please try again after some time." }, "response_type_id": 1468, "message": "Unable to fetch bill", "status": 1468 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/bbps": { "post": { "operationId": "bbpsPayBill", "summary": "Pay BBPS Bill", "description": "The money-debit call that pays a bill or submits a recharge on the BBPS network. For a bill payment, send the `amount` confirmed at Fetch Bill and the `utilitycustomername` it returned. A prepaid recharge skips Fetch Bill, so it sends the chosen plan's amount and omits `utilitycustomername`.\n\n**Pay the exact amount returned by Fetch Bill** — a mismatch is rejected with status `208`. On `208`, re-fetch the bill and retry with a **fresh** `client_ref_id`; a `client_ref_id` identifies one payment attempt and must never be reused across retries. Persist `tid` and your `client_ref_id` before any retry — status `208` still returns a `tid`.\n\n**Parameters vary by operator.** The fields below are the common set; pass every `param_name` returned by Get Operator Parameters as well. The parameter set sent here must match the set sent to Fetch Bill for the same operator.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 333 | Payment successful — persist `tid` and `client_ref_id` for reconciliation. | — |\n| 208 | Amount does not match the bill. Re-fetch the bill and retry with a fresh `client_ref_id`; a `tid` is still returned, so persist it first. | [bbps-fetch-bill](https://eps.eko.in/docs/bbps-fetch-bill) |", "tags": [ "Bharat Bill Payment System (BBPS)" ], "x-docs-slug": "bbps-pay-bill", "x-eko-trxn-type-id": 63, "x-eko-product-code": 62, "x-eko-financial": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "tx_status": { "description": "Transaction state: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tid": { "description": "Eko transaction ID. Store it for reconciliation and dispute resolution — returned on failures too.", "example": "3570553488", "type": "string" }, "tx_status": { "description": "Transaction status (`0` = success).", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "status_text": { "description": "Status label from the biller.", "example": "SUCCESS", "type": "string" }, "amount": { "description": "Amount paid.", "example": "2870.0", "type": "string" }, "totalamount": { "description": "Total amount debited, including any fee.", "example": "2870.0", "type": "string" }, "fee": { "description": "Fee charged for this transaction.", "example": "0.0", "type": "string" }, "tds": { "description": "TDS deducted on the commission.", "example": "0.024", "type": "string" }, "commission": { "description": "Agent commission earned on this payment.", "example": "1.2", "type": "string" }, "balance": { "description": "Agent wallet balance after the payment.", "example": "46537.3", "type": "string" }, "operator_name": { "description": "Biller the payment was made to.", "example": "B.E.S.T Mumbai", "type": "string" }, "utilitycustomername": { "description": "Customer name on the bill.", "example": "Amit Kumar", "type": "string" }, "customermobilenumber": { "description": "Customer mobile number.", "example": "9903457748", "type": "string" }, "account": { "description": "Account / consumer number that was paid.", "example": "3287820071", "type": "string" }, "approvalreferencenumber": { "description": "Biller approval reference, where provided.", "example": "", "type": "string" }, "payment_mode_desc": { "description": "Payment mode used.", "example": "CASH", "type": "string" }, "user_code": { "description": "Agent's user code.", "example": "35739001", "type": "string" }, "last_used_okekey": { "description": "Last used OkeKey.", "example": "203", "type": "string" }, "timestamp": { "description": "Transaction timestamp.", "example": "2026-07-25T09:52:57.428Z", "type": "string" } } } } }, "examples": { "success": { "summary": "333 — Payment successful — persist `tid` and `client_ref_id` for reconciliation.", "value": { "response_status_id": 0, "data": { "tx_status": "0", "txstatus_desc": "Success", "status_text": "SUCCESS", "tid": "3570553488", "amount": "2870.0", "totalamount": "2870.0", "fee": "0.0", "tds": "0.024", "commission": "1.2", "balance": "46537.3", "user_code": "35739001", "operator_name": "B.E.S.T Mumbai", "utilitycustomername": "Amit Kumar", "customermobilenumber": "9903457748", "payment_mode_desc": "CASH", "last_used_okekey": "203", "account": "3287820071", "timestamp": "2026-07-25T09:52:57.428Z" }, "response_type_id": 333, "message": "Success Last_used_OkeyKey: 203", "status": 0 } }, "amount_mismatch_the_amount_paid_differs_from_the_fetched_bill": { "summary": "208 — Amount does not match the bill. Re-fetch the bill and retry with a fresh `client_ref_id`; a `tid` is still returned, so persist it first.", "value": { "response_status_id": 1, "data": { "last_used_okekey": "", "tid": "3571183956" }, "response_type_id": 208, "message": "utility.payment.failed Amount entered does not match with bill amount. Please try again", "status": 208 } }, "required_field_missing": { "summary": "Required field missing", "value": { "response_status_id": 1, "invalid_params": { "amount": "Please provide the value of the field {2} {3}" }, "response_type_id": -1, "message": "Please provide the value of the field", "status": 97 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "phone_operator_code": { "type": "string", "description": "Biller identifier — the `operator_id` from the Get Operators response.", "example": "53" }, "utility_acc_no": { "type": "string", "description": "Bill/account number. For a prepaid recharge, the customer's mobile number.", "example": "3287820071" }, "confirmation_mobile_no": { "type": "string", "description": "Customer's alternate mobile number. This is only used for sending the confirmation SMS. It may be same as the `utility_acc_no` for prepaid recharges.", "example": "9903457748" }, "sender_name": { "type": "string", "description": "Customer name.", "example": "Asaad" }, "category": { "type": "number", "description": "The `operator_category_id` from Get Categories (e.g. `8` = Electricity).", "example": 8 }, "amount": { "type": "number", "description": "Amount to pay, in rupees. Must equal the `amount` returned by Fetch Bill.", "example": 2870 }, "utilitycustomername": { "type": "string", "description": "Customer name as returned by Fetch Bill. Mandatory for bill payments where Bill Fetch is done. Not applicable to prepaid recharges, which skip Bill Fetch.", "example": "Amit Kumar" }, "client_ref_id": { "type": "string", "description": "Unique partner reference for this payment attempt. Reuse the value sent to the matching Fetch Bill call; generate a fresh one for every retry.", "example": "2026010100123456789" }, "source_ip": { "type": "string", "description": "Originating client IP address.", "example": "192.168.1.1" }, "district_discome": { "type": "string", "description": "District-level distribution company code. Required for **operator 190 (UPPCL) only** — pass the same value used at Fetch Bill.", "example": "Lucknow-MVVNL" }, "communication": { "type": "number", "description": "Payment mode: `0` (default) = online — instant settlement, lower commission. `1` = offline — higher commission, but the bill takes a minimum of 6 working hours to settle. Pass the same value used at Fetch Bill.", "example": 0 } }, "required": [ "initiator_id", "phone_operator_code", "utility_acc_no", "confirmation_mobile_no", "sender_name", "category", "amount", "client_ref_id", "source_ip" ] }, "example": { "initiator_id": "9962981729", "phone_operator_code": "53", "utility_acc_no": "3287820071", "confirmation_mobile_no": "9903457748", "sender_name": "Asaad", "category": 8, "amount": 2870, "utilitycustomername": "Amit Kumar", "client_ref_id": "2026010100123456789", "source_ip": "192.168.1.1", "district_discome": "Lucknow-MVVNL", "communication": 0 } } } } } }, "/tools/kyc/fetch-pan": { "post": { "operationId": "panFetch", "summary": "Fetch PAN Details", "description": "Fetch PAN is the lightest PAN lookup: pass only the PAN number and get back the registered full name, the holder category (person / company / firm …) and the PAN status. Unlike PAN Lite and PAN Advanced — which require the PAN number, holder name and date of birth to compute match flags — this endpoint needs no name or DOB, so use it when you have to *discover* the holder's name rather than verify one you already hold.", "tags": [ "PAN Verification" ], "x-docs-slug": "pan-fetch", "x-eko-trxn-type-id": 1013, "x-eko-product-code": 790, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "upstream_rrn": { "description": "Reference number of the lookup at the upstream source.", "example": "pan_ZLpBnmwapOwtixPUmijB", "type": "string" }, "pan_no": { "description": "The PAN number submitted in the request.", "example": "GGTPB7880Q", "type": "string" }, "fullname": { "description": "Full name registered against the PAN.", "example": "YASHWANT BASNETT", "type": "string" }, "category": { "description": "PAN holder category, e.g. 'person', 'company', 'firm', 'trust', 'huf'.", "example": "person", "type": "string" }, "status": { "description": "Outcome of the PAN lookup, e.g. 'success'.", "example": "success", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "upstream_rrn": "pan_ZLpBnmwapOwtixPUmijB", "pan_no": "GGTPB7880Q", "fullname": "YASHWANT BASNETT", "category": "person", "status": "success" }, "response_type_id": 0, "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "pan_number": { "type": "string", "description": "10-character alphanumeric PAN identifier (5 letters, 4 digits, 1 letter).", "example": "GGTPB7880Q", "pattern": "^[A-Z]{5}\\d{4}[A-Z]$" }, "source": { "type": "string", "description": "Origin of the request. Use 'API' for server-to-server calls.", "example": "API" } }, "required": [ "initiator_id", "pan_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "pan_number": "GGTPB7880Q", "source": "API" } } } } } }, "/tools/kyc/pan-lite": { "post": { "operationId": "panLite", "summary": "PAN Lite", "description": "PAN Lite performs a lightweight synchronous PAN verification. Supply the PAN number, holder name, and date of birth; the API returns match flags for name and DOB, the PAN activation status code, and whether the PAN is seeded (linked) with Aadhaar. Note: the name field in the response reflects the name you submitted, not the registered name on the PAN record — use PAN Advanced for the registered name.", "tags": [ "PAN Verification" ], "x-docs-slug": "pan-lite", "x-eko-trxn-type-id": 814, "x-eko-product-code": 754, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "pan": { "description": "The PAN number submitted in the request.", "example": "ABCDE1234F", "type": "string" }, "name": { "description": "Name as submitted in the request (not the registered name on the PAN card).", "example": "Rajesh Kumar", "type": "string" }, "dob": { "description": "Date of birth as submitted in the request (YYYY-MM-DD).", "example": "1994-08-29", "type": "string" }, "name_match": { "description": "Whether the submitted name matches the PAN record. Values: 'Y' (match), 'N' (no match), or null (unavailable).", "example": "Y", "type": "string" }, "dob_match": { "description": "Whether the submitted date of birth matches the PAN record. Values: 'Y' (match), 'N' (no match), or null (unavailable).", "example": "Y", "type": "string" }, "pan_status": { "description": "Granular PAN activation status code. E: Valid, EC: Valid (Acquisition), N: Non-existent, X: Deactivated, F: Fake, D: Deleted, EA: Valid (Amalgamation), ED: Valid (Death), EI: Valid (Dissolution), EL: Valid (Liquidated), EM: Valid (Merger), EP: Valid (Partition), ES: Valid (Split), EU: Valid (Under Liquidation)", "example": "E", "type": "string" }, "status": { "description": "High-level PAN validity: 'VALID' or 'INVALID'.", "example": "VALID", "type": "string" }, "aadhaar_seeding_status": { "description": "Aadhaar-PAN seeding/linking status. Values: 'Y' (seeded), 'R' (registered but not confirmed), 'NA' (not seeded), or null.", "example": "Y", "type": "string" }, "aadhaar_seeding_status_desc": { "description": "Human-readable description of the Aadhaar-PAN linkage status.", "example": "Aadhaar is linked to PAN", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "PAN verification successful", "response_type_id": 1388, "data": { "pan": "ABCDE1234F", "name": "Rajesh Kumar", "dob": "1994-08-29", "name_match": "Y", "dob_match": "Y", "pan_status": "E", "status": "VALID", "aadhaar_seeding_status": "Y", "aadhaar_seeding_status_desc": "Aadhaar is linked to PAN" } } }, "invalid_or_non_existent_pan": { "summary": "Invalid or non-existent PAN", "value": { "status": 1, "response_status_id": 1, "message": "PAN not found or invalid", "response_type_id": 1388, "data": { "pan": "ABCDE1234F", "pan_status": "N", "status": "INVALID", "name_match": null, "dob_match": null, "aadhaar_seeding_status": null, "aadhaar_seeding_status_desc": null } } } } } } }, "400": { "description": "Missing required parameter", "content": { "application/json": { "examples": { "missing_required_parameter": { "summary": "Missing required parameter", "value": { "status": 1, "message": "Bad request — missing or malformed parameter" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "pan_number": { "type": "string", "description": "10-character alphanumeric PAN identifier (5 letters, 4 digits, 1 letter).", "example": "ABCDE1234F", "pattern": "^[A-Z]{5}\\d{4}[A-Z]$" }, "name": { "type": "string", "description": "Individual's name to match against PAN records.", "example": "Rajesh Kumar" }, "dob": { "type": "string", "description": "Date of birth in YYYY-MM-DD format.", "example": "1994-08-29", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "initiator_id", "pan_number", "name", "dob" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "pan_number": "ABCDE1234F", "name": "Rajesh Kumar", "dob": "1994-08-29" } } } } } }, "/tools/kyc/pan-advanced": { "post": { "operationId": "panAdvanced", "summary": "PAN Advanced", "description": "PAN Advanced performs a deeper KYC lookup against the PAN database. In addition to the match flags returned by PAN Lite, it surfaces the registered name, name on the PAN card, PAN type (Individual / Company / etc.), gender, date of birth, masked Aadhaar number, Aadhaar link status, and structured address. Email and mobile fields are populated at a ~5–10% fill rate due to data-source availability. Use this API when downstream workflows need authoritative identity attributes beyond a pass/fail match.", "tags": [ "PAN Verification" ], "x-docs-slug": "pan-advanced", "x-eko-trxn-type-id": 817, "x-eko-product-code": 757, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "pan": { "description": "PAN number submitted in the request.", "example": "ABCDE1234F", "type": "string" }, "name_provided": { "description": "Name as submitted in the request.", "example": "Rajesh Kumar", "type": "string" }, "registered_name": { "description": "Authoritative name registered in the PAN database.", "example": "Rajesh Kumar", "type": "string" }, "name_pan_card": { "description": "Name printed on the physical PAN card.", "example": "Rajesh Kumar", "type": "string" }, "first_name": { "description": "First name parsed from the PAN record.", "example": "Rajesh", "type": "string" }, "last_name": { "description": "Last name parsed from the PAN record.", "example": "Kumar", "type": "string" }, "type": { "description": "PAN holder category (e.g., 'Individual', 'Company', 'Firm', 'Trust', 'HUF').", "example": "Individual", "type": "string" }, "gender": { "description": "Gender from PAN record. Values: 'M' (Male), 'F' (Female).", "example": "M", "type": "string" }, "date_of_birth": { "description": "Date of birth from the PAN record (YYYY-MM-DD).", "example": "1994-08-29", "type": "string" }, "masked_aadhaar_number": { "description": "Aadhaar number with first 8 digits masked for privacy (e.g., 'XXXX XXXX 1234').", "example": "XXXX XXXX 1234", "type": "string" }, "aadhaar_linked": { "description": "Whether the PAN is linked to an Aadhaar number.", "example": true, "type": "boolean" }, "email": { "description": "Masked email address associated with the PAN. Fill rate is approximately 5–10% due to data-source availability.", "example": "ra******ar@example.com", "type": "string" }, "mobile_number": { "description": "Masked mobile number associated with the PAN. Fill rate is approximately 5–10% due to data-source availability.", "example": "98******10", "type": "string" }, "address": { "description": "Structured address fields of the PAN holder.", "type": "object", "properties": { "full_address": { "description": "Complete address string.", "example": "Woodland Heights, Ghatkopar, Mumbai, Maharashtra 400072", "type": "string" }, "street": { "description": "Street name / house number.", "example": "Woodland Heights, Ghatkopar", "type": "string" }, "city": { "description": "City name.", "example": "Mumbai", "type": "string" }, "state": { "description": "State name.", "example": "Maharashtra", "type": "string" }, "pincode": { "description": "6-digit postal PIN code.", "example": 400072, "type": "number" }, "country": { "description": "Country name.", "example": "India", "type": "string" } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "PAN Advanced verification successful", "response_type_id": 1388, "data": { "pan": "ABCDE1234F", "name_provided": "Rajesh Kumar", "registered_name": "Rajesh Kumar", "name_pan_card": "Rajesh Kumar", "first_name": "Rajesh", "last_name": "Kumar", "type": "Individual", "gender": "M", "date_of_birth": "1994-08-29", "masked_aadhaar_number": "XXXX XXXX 1234", "aadhaar_linked": true, "email": "ra******ar@example.com", "mobile_number": "98******10", "address": { "full_address": "Woodland Heights, Ghatkopar, Mumbai, Maharashtra 400072", "street": "Woodland Heights, Ghatkopar", "city": "Mumbai", "state": "Maharashtra", "pincode": 400072, "country": "India" } } } }, "pan_not_found_in_database": { "summary": "PAN not found in database", "value": { "status": 1, "response_status_id": 1, "message": "PAN not found or verification failed", "response_type_id": 1388, "data": {} } } } } } }, "400": { "description": "Missing required parameter", "content": { "application/json": { "examples": { "missing_required_parameter": { "summary": "Missing required parameter", "value": { "status": 1, "message": "Bad request — missing or malformed parameter" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "pan_number": { "type": "string", "description": "10-character alphanumeric PAN identifier (first 5 alphabets, 4 digits, 1 alphabet).", "example": "ABCPV1234D", "pattern": "^[A-Z]{5}\\d{4}[A-Z]$" }, "name": { "type": "string", "description": "Individual's name per PAN information, used for match scoring.", "example": "Rajesh Kumar" } }, "required": [ "initiator_id", "pan_number", "name" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "pan_number": "ABCPV1234D", "name": "Rajesh Kumar" } } } } } }, "/tools/kyc/pan/bulk": { "post": { "operationId": "panBulkVerify", "summary": "Bulk PAN Verification", "description": "Bulk PAN Verification accepts an array of PAN entries (each with a PAN number and optional name) in a single POST request and returns a reference_id for tracking. Because verification runs asynchronously, callers must subsequently poll the Bulk PAN Verification Status API with the returned reference_id to retrieve individual results. Suited for high-volume operations such as employee on-boarding, merchant KYC batches, or overnight reconciliation runs.", "tags": [ "PAN Verification" ], "x-docs-slug": "pan-bulk-verify", "x-eko-trxn-type-id": 818, "x-eko-product-code": 758, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "enqueues" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "reference_id": { "description": "Unique identifier for the submitted batch. Pass this to the Bulk PAN Verification Status API to retrieve individual PAN results once processing is complete.", "example": 123456, "type": "number" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Bulk PAN verification request accepted. Poll status API for results.", "response_type_id": 1388, "data": { "reference_id": 123456 } } } } } } }, "400": { "description": "Empty or missing entries array", "content": { "application/json": { "examples": { "empty_or_missing_entries_array": { "summary": "Empty or missing entries array", "value": { "status": 1, "message": "Bad request — entries array is required and must not be empty" } }, "malformed_pan_in_one_or_more_entries": { "summary": "Malformed PAN in one or more entries", "value": { "status": 1, "message": "Bad request — one or more entries contain an invalid PAN format" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "entries": { "type": "string", "description": "Array of PAN verification entries. Each entry contains a PAN number (required), name (optional), user_code (optional), and source (optional, defaults to 'API').", "example": [ { "pan": "ABCPV1234D", "name": "John", "source": "API" }, { "pan": "ABCPV1234L", "name": "John Doe", "source": "API" } ] } }, "required": [ "initiator_id", "entries" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "entries": [ { "pan": "ABCPV1234D", "name": "John", "source": "API" }, { "pan": "ABCPV1234L", "name": "John Doe", "source": "API" } ] } } } } } }, "/tools/kyc/pan/bulk/status": { "get": { "operationId": "panBulkStatus", "summary": "Check Bulk PAN Verification Status", "description": "Retrieves the per-PAN results for a batch previously submitted via the Bulk PAN Verification API. Because bulk verification runs asynchronously, callers poll this endpoint with the reference_id from the submit response until the batch finishes processing. The response returns a count and an array of entries, one per PAN, each carrying the validity, registered name, name-match score/result, Aadhaar-seeding status, and PAN status.", "tags": [ "PAN Verification" ], "x-docs-slug": "pan-bulk-status", "x-eko-trxn-type-id": 819, "x-eko-product-code": 759, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "bulk_verification_id", "in": "query", "required": true, "description": "Unique `bulk_verification_id` returned by the Bulk PAN Verification API for the submitted batch.", "schema": { "type": "string", "description": "Unique `bulk_verification_id` returned by the Bulk PAN Verification API for the submitted batch.", "example": "" } }, { "name": "bulk_reference_id", "in": "query", "required": false, "description": "Unique id created to identify the bulk request, if you tracked one at submit time.", "schema": { "type": "string", "description": "Unique id created to identify the bulk request, if you tracked one at submit time.", "example": "BULK-PAN-20240101-001" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "count": { "description": "Number of entries in the results array.", "example": 2, "type": "number" }, "entries": { "description": "Per-PAN verification results for the batch.", "type": "array", "items": { "type": "object", "properties": { "pan": { "description": "10-character PAN identifier.", "example": "ABCPV1234D", "type": "string" }, "valid": { "description": "PAN card validity status.", "example": "true", "type": "string" }, "registered_name": { "description": "Name on record against the PAN.", "example": "John Doe", "type": "string" }, "name_provided": { "description": "Name submitted in the bulk request for this PAN.", "example": "John", "type": "string" }, "name_match_score": { "description": "Name verification score.", "example": "82.5", "type": "string" }, "name_match_result": { "description": "Name match result.", "example": "GOOD_PARTIAL_MATCH", "type": "string" }, "aadhaar_seeding_status": { "description": "Aadhaar-PAN linkage status.", "example": "Y", "type": "string" }, "pan_status": { "description": "Current PAN status.", "example": "VALID", "type": "string" }, "message": { "description": "Success or failure details for this entry.", "example": "PAN verified successfully", "type": "string" }, "reference_id": { "description": "Unique reference identifier for the entry.", "example": "123456", "type": "string" }, "last_updated_at": { "description": "Timestamp when the entry was last updated.", "example": "2024-01-01 12:30:45", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Success", "response_type_id": 1388, "data": { "count": 2, "entries": [ { "pan": "ABCPV1234D", "valid": "true", "registered_name": "John Doe", "name_provided": "John", "name_match_score": "82.5", "name_match_result": "GOOD_PARTIAL_MATCH", "aadhaar_seeding_status": "Y", "pan_status": "VALID", "message": "PAN verified successfully", "reference_id": "123456", "last_updated_at": "2024-01-01 12:30:45" }, { "pan": "ABCPV1234L", "valid": "true", "registered_name": "John Doe", "name_provided": "John Doe", "name_match_score": "100", "name_match_result": "EXACT_MATCH", "aadhaar_seeding_status": "Y", "pan_status": "VALID", "message": "PAN verified successfully", "reference_id": "123456", "last_updated_at": "2024-01-01 12:30:46" } ] } } } } } } }, "400": { "description": "Missing reference_id", "content": { "application/json": { "examples": { "missing_reference_id": { "summary": "Missing reference_id", "value": { "status": 1, "message": "Bad request — reference_id is required" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown or expired reference_id", "content": { "application/json": { "examples": { "unknown_or_expired_reference_id": { "summary": "Unknown or expired reference_id", "value": { "status": 1, "message": "No batch found for the supplied reference_id" } } } } } } } } }, "/customer/profile/{customer_id}/dmt-levin": { "get": { "operationId": "dmtLevinGetSender", "summary": "Get Sender Profile", "description": "The first step in the DMT Levin flow. Call this to check whether the sender exists on the platform. For an existing sender (response_type_id 309) the response returns their monthly limit, used amount and remaining limit. For a new sender (response_type_id 2136) it returns an `otp_ref_id` — proceed to Validate Aadhaar & Generate OTP to create the sender before using other services.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 309 | Sender found | [dmt-levin-get-recipients](https://eps.eko.in/docs/dmt-levin-get-recipients) |\n| 2136 | Sender not found, Aadhaar validation pending | [aadhaar-dmt-levin-validate](https://eps.eko.in/docs/aadhaar-dmt-levin-validate) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-get-sender", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9999999999" } }, { "name": "user_code", "in": "query", "required": true, "description": "Agent user code (sent as a query parameter).", "schema": { "type": "string", "description": "Agent user code (sent as a query parameter).", "example": "20180020" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "is_registered": { "description": "Registration flag from the profile lookup. Read customer_profile.kyc_state to determine KYC completion.", "example": 0, "type": "number" }, "next_allowed_limit": { "description": "Remaining remittance limit currently available (INR).", "example": 24900, "type": "number" }, "kyc_state": { "description": "Top-level KYC flag for the lookup response.", "example": 0, "type": "number" }, "customer_profile": { "description": "Sender profile summary.", "type": "object", "properties": { "name": { "description": "Sender name (null until set).", "example": null, "type": "string" }, "mobile": { "description": "Sender's mobile number.", "example": "9999999999", "type": "string" }, "balance": { "description": "Sender wallet balance (INR).", "example": "0.00", "type": "string" }, "total_monthly_limit": { "description": "Sender's monthly remittance limit (INR).", "example": "25000", "type": "string" }, "next_allowed_limit": { "description": "Remaining limit currently available (INR).", "example": "24900.0", "type": "string" }, "kyc_state": { "description": "Sender KYC state (1 = KYC complete on the profile).", "example": 0, "type": "number" }, "chart": { "description": "Per-period limit-usage breakdown.", "type": "array", "items": { "type": "object", "properties": { "data_type_id": { "description": "Identifier for the limit period/bucket.", "example": 10, "type": "number" }, "data": { "description": "Limit usage for the period.", "type": "object", "properties": { "unavailable": { "description": "Amount blocked/unavailable (INR).", "example": 0, "type": "number" }, "used": { "description": "Amount already used (INR).", "example": 100, "type": "number" }, "remaining": { "description": "Remaining limit for the period (INR).", "example": 24900, "type": "number" } } }, "label": { "description": "Display label for the period.", "example": "", "type": "string" } } } } } } } } } }, "examples": { "success": { "summary": "309 — Sender found", "value": { "response_status_id": -1, "data": { "customer_profile": { "total_monthly_limit": "25000", "mobile": "9999999999", "kyc_id": "", "ekyc_enabled": 0, "kyc_validity": "", "kyc_remark": "", "kyc_type": "", "balance": "0.00", "next_allowed_limit": "24900.0", "name": null, "digital_ekyc": 0, "chart": [ { "data_type_id": 10, "data": { "unavailable": 0, "used": 100, "remaining": 24900 }, "label": "" } ], "email": "", "kyc_state": 0 }, "wallet_token": "", "id_proof_type_id": "", "is_registered": 0, "id_proof": "", "otpOptionalSum": "", "sender_name": "", "otpNotRequiredSum": "", "ekyc_enabled": "", "wallet_id": "", "otpNotRequiredSumNeft": "", "next_allowed_limit": 24900, "kyc_state": 0, "otpOptionalSumNeft": "" }, "response_type_id": 309, "message": "Success!", "status": 0 } }, "new_sender_aadhaar_validation_pending_proceed_to_validate_aadhaar_generate_otp": { "summary": "2136 — Sender not found, Aadhaar validation pending", "value": { "response_status_id": 1, "data": { "description": "", "otp_ref_id": "MjQzMjYxMjQzMTMyMjQ1ODY1NzUzNTRhNjkzMDU0NGUzNjU4NjIzMjQxNDk3OTY1NGQ2ZjZkNWE3NTZlNzE2ODZkNzg0MjU3NmU0MjQ4MzA0NzQ4NTgzMzY3NzgzMzQ0NTc0YjU0NTY0ZTUxMzI2ZDM0MzM0MjRi" }, "response_type_id": 2136, "message": "Aadhar Validation Pending", "status": 2136 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/account/{customer_id}/dmt-levin": { "post": { "operationId": "dmtLevinOnboardSender", "summary": "Onboard Sender", "description": "Onboards a new sender and enables them for the DMT-Levin service. Provide the sender's name, date of birth, and residence address. Pass the name exactly as per the sender's ID — a random or mismatched name makes the transaction fail. On success the response (response_type_id 2136) returns an `otp_ref_id` — proceed to Validate Aadhaar & Generate OTP. OTP is not delivered to the customer's mobile on UAT systems.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2136 | Onboarded, Aadhaar validation pending | [aadhaar-dmt-levin-validate](https://eps.eko.in/docs/aadhaar-dmt-levin-validate) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-onboard-sender", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "creates", "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9999999999" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "otp_ref_id": { "description": "OTP reference — pass to Validate Aadhaar & Generate OTP.", "example": "MjQzMjYxMjQzMTMyMjQ2YTJlNWEzOTc5MzU1MTRiNDg1OTc0MzU1NjYxNDE3NzQ3NTgzNjZlNzg3NTUxNjk2ODQ2NzE0ZTQ5NzE0NzcyNTg2MjZkNTc3MTY2NGI3NjRiMzA2NzM4NTk0MzUwNTg3NjRlNTQ1MjY5", "type": "string" } } } } }, "examples": { "success": { "summary": "2136 — Onboarded, Aadhaar validation pending", "value": { "response_status_id": 1, "data": { "otp_ref_id": "MjQzMjYxMjQzMTMyMjQ2YTJlNWEzOTc5MzU1MTRiNDg1OTc0MzU1NjYxNDE3NzQ3NTgzNjZlNzg3NTUxNjk2ODQ2NzE0ZTQ5NzE0NzcyNTg2MjZkNTc3MTY2NGI3NjRiMzA2NzM4NTk0MzUwNTg3NjRlNTQ1MjY5" }, "response_type_id": 2136, "message": "Aadhar Validation Pending", "status": 2136 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "User code value of the retailer from whom the request is coming.", "example": "99080253" }, "name": { "type": "string", "description": "Full name of the sender as per their ID. Do not pass a random name — the transaction will fail.", "example": "Gaurav" }, "dob": { "type": "string", "description": "Date of birth of the sender in YYYY-MM-DD format.", "example": "1997-07-01", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "residence_address": { "type": "string", "description": "Sender's residence address as a nested JSON object with keys: line, city, state, pincode, district, area.", "example": { "line": "India", "city": "Lucknow", "state": "Uttar pradesh", "pincode": "226024", "district": "Lucknow", "area": "gomtinagar" } } }, "required": [ "initiator_id", "user_code", "name", "dob", "residence_address" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "99080253", "name": "Gaurav", "dob": "1997-07-01", "residence_address": { "line": "India", "city": "Lucknow", "state": "Uttar pradesh", "pincode": "226024", "district": "Lucknow", "area": "gomtinagar" } } } } } } }, "/customer/payment/dmt-levin/sender/{customer_id}/aadhaar/otp": { "post": { "operationId": "aadhaarDmtLevinValidate", "summary": "Validate Aadhaar & Generate OTP", "description": "Submits the sender's Aadhaar number via the DMT Levin channel to initiate OTP-based Aadhaar validation. The `otp_ref_id` from the sender's existing profile plus the Aadhaar number are required. Returns a new `otp_ref_id` for the validation session. Part of the Levin DMT sender onboarding flow.", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "aadhaar-dmt-levin-validate", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's mobile number.", "schema": { "type": "integer", "description": "Sender's mobile number.", "example": 9876543210 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "otp_ref_id": { "description": "New OTP reference ID for the Aadhaar validation session. Pass to Validate Sender Aadhaar OTP.", "example": "93847201", "type": "string" }, "mobile_hint": { "description": "Masked mobile number to which the OTP was dispatched.", "example": "******3210", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Aadhaar OTP dispatched successfully", "response_type_id": 1388, "data": { "otp_ref_id": "93847201", "mobile_hint": "******3210" } } }, "invalid_aadhaar_number": { "summary": "Invalid Aadhaar number", "value": { "status": 1, "response_status_id": 301, "message": "Invalid Aadhaar number provided.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "aadhar": { "type": "string", "description": "12-digit Aadhaar number of the sender.", "example": "123456789012", "pattern": "^\\d{12}$" }, "otp_ref_id": { "type": "string", "description": "Reference ID returned from the Get Sender Info (or Create Sender) API for this customer.", "example": "73849201" }, "additional_info": { "type": "string", "description": "Additional info flag. Defaults to 1.", "example": "1" } }, "required": [ "initiator_id", "aadhar", "otp_ref_id", "additional_info" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "aadhar": "123456789012", "otp_ref_id": "73849201", "additional_info": "1" } } } } } }, "/customer/payment/dmt-levin/sender/{customer_id}/aadhaar/otp/verify": { "post": { "operationId": "aadhaarDmtLevinVerifyOtp", "summary": "Validate Sender Aadhaar OTP", "description": "Validates the OTP received on the sender's Aadhaar-linked mobile number in the DMT Levin flow. Use `intent_id: 20` for Aadhaar validation (as opposed to `intent_id: 19` for sender onboarding). On success, the sender's identity is confirmed and their DMT Levin wallet profile is updated.", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "aadhaar-dmt-levin-verify-otp", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "consumes-otp", "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's mobile number.", "schema": { "type": "string", "description": "Sender's mobile number.", "example": "9876543210" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "verified": { "description": "True if Aadhaar OTP validation was successful.", "example": true, "type": "boolean" }, "name": { "description": "Verified sender name from Aadhaar.", "example": "Arjun Mehta", "type": "string" }, "gender": { "description": "Gender from Aadhaar record.", "example": "M", "type": "string" }, "dob": { "description": "Date of birth from Aadhaar.", "example": "10-01-1988", "type": "string" }, "masked_aadhaar": { "description": "Aadhaar number with first 8 digits masked.", "example": "XXXX-XXXX-3456", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Aadhaar OTP verified successfully", "response_type_id": 1388, "data": { "verified": true, "name": "Arjun Mehta", "gender": "M", "dob": "10-01-1988", "masked_aadhaar": "XXXX-XXXX-3456" } } }, "wrong_otp": { "summary": "Wrong OTP", "value": { "status": 1, "response_status_id": 302, "message": "Wrong OTP. Please check and retry.", "response_type_id": 1388, "data": {} } }, "otp_expired": { "summary": "OTP expired", "value": { "status": 1, "response_status_id": 303, "message": "OTP expired. Please regenerate.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "otp": { "type": "integer", "description": "OTP received on the Aadhaar-linked mobile number.", "example": 123456 }, "otp_ref_id": { "type": "integer", "description": "Reference ID from the Validate Aadhaar (DMT Levin) response.", "example": 93847201 }, "intent_id": { "type": "string", "description": "Set to \"19\" for sender onboarding or \"20\" for Aadhaar validation.", "example": "20" }, "additional_info": { "type": "string", "description": "Additional info flag. Defaults to 1.", "example": "1" } }, "required": [ "initiator_id", "otp_ref_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "otp": 123456, "otp_ref_id": 93847201, "intent_id": "20", "additional_info": "1" } } } } } }, "/customer/account/{customer_id}/dmt-levin/ekyc": { "post": { "operationId": "dmtLevinSenderEkyc", "summary": "DMT Customer KYC", "description": "One-time biometric eKYC using a fingerprint captured on an RD-service device, called after the sender's OTP is validated. Submit the `otp_ref_id` from Validate Sender Aadhaar OTP with the PID XML. On success (response_type_id 2132) the sender's registration is complete.\n\nIf you generate the PID block with your own code rather than the RD service default, set `wadh=E0jzJ/P8UopUHAieZn8CKqS4WPMi5ZSYXgfnlfkWjrc=` alongside `fCount`, `fType` and the other attributes.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2132 | Sender registration completed | [dmt-levin-get-recipients](https://eps.eko.in/docs/dmt-levin-get-recipients) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-sender-ekyc", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9911542536" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object" } } }, "examples": { "success": { "summary": "2132 — Sender registration completed", "value": { "response_status_id": 0, "response_type_id": 2132, "message": "Customer Registration Completed", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "8-digit code of the registered user (partner's merchant), received in the user onboarding response.", "example": "99080253" }, "otp_ref_id": { "type": "string", "description": "OTP reference received in the Validate OTP response.", "example": "Yd6uRIneZVJpTQRhqL6CZ1e46nmMhYYjxg40levn4pG4m+AWOZn5R29EUkNGljBEkwjW4GWlKNiPdQXFVtwHccxey5PZnPgz" }, "piddata": { "type": "string", "description": "PID XML returned by the biometric device, passed as a string.", "example": "..." } }, "required": [ "initiator_id", "user_code", "otp_ref_id", "piddata" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "99080253", "otp_ref_id": "Yd6uRIneZVJpTQRhqL6CZ1e46nmMhYYjxg40levn4pG4m+AWOZn5R29EUkNGljBEkwjW4GWlKNiPdQXFVtwHccxey5PZnPgz", "piddata": "..." } } } } } }, "/customer/payment/dmt-levin/sender/{customer_id}/recipients": { "get": { "operationId": "dmtLevinGetRecipients", "summary": "Get Recipients", "description": "Returns all recipients (beneficiaries) registered under the sender's DMT-Levin account, including each recipient's name, IFSC, beneficiary ID and recipient ID. Use this before initiating a transfer — if the desired recipient already exists you can use their recipient_id directly, skipping Add Recipient.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 23 | Recipient list returned — proceed to Send Transaction OTP | [dmt-levin-send-otp](https://eps.eko.in/docs/dmt-levin-send-otp) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-get-recipients", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "8969622436" } }, { "name": "user_code", "in": "query", "required": true, "description": "User code value of the retailer from whom the request is coming (sent as a query parameter).", "schema": { "type": "string", "description": "User code value of the retailer from whom the request is coming (sent as a query parameter).", "example": "32515001" } }, { "name": "additional_info", "in": "query", "required": false, "description": "Send a fixed value of 1 (sent as a query parameter).", "schema": { "type": "integer", "description": "Send a fixed value of 1 (sent as a query parameter).", "example": 1 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "pan_required": { "description": "PAN requirement flag for the sender.", "example": 2, "type": "number" }, "remaining_limit_before_pan_required": { "description": "Amount the sender can still transfer before PAN becomes mandatory (INR).", "example": 50000, "type": "number" }, "is_insured": { "description": "Insurance flag for the sender.", "example": "", "type": "string" }, "recipient_list": { "description": "Registered beneficiaries for this sender.", "type": "array", "items": { "type": "object", "properties": { "recipient_id": { "description": "Recipient identifier used to send money.", "example": 10018839, "type": "number" }, "beneficiary_id": { "description": "Beneficiary identifier (may be null).", "example": 40378, "type": "number" }, "recipient_name": { "description": "Beneficiary name.", "example": "Aditya", "type": "string" }, "recipient_mobile": { "description": "Beneficiary mobile number.", "example": "9999999990", "type": "string" }, "bank": { "description": "Beneficiary bank name.", "example": "Kotak Mahindra Bank", "type": "string" }, "ifsc": { "description": "Beneficiary bank IFSC code.", "example": "KKBK0000878", "type": "string" }, "account": { "description": "Masked beneficiary bank account number.", "example": "1XXXXXX90657", "type": "string" }, "account_type": { "description": "Type of the beneficiary account.", "example": "Bank Account", "type": "string" }, "recipient_id_type": { "description": "How the recipient is identified.", "example": "acc_ifsc", "type": "string" }, "ifsc_status": { "description": "Whether the IFSC is valid/active (1 = valid).", "example": 1, "type": "number" }, "is_verified": { "description": "Whether the account has been penny-drop verified (1 = verified).", "example": 0, "type": "number" }, "is_self_account": { "description": "Whether the account belongs to the sender (1 = self).", "example": "0", "type": "string" }, "is_otp_required": { "description": "Whether an OTP is required to transact to this recipient.", "example": "0", "type": "string" }, "channel": { "description": "Transfer channel for this recipient.", "example": 0, "type": "number" }, "allowed_channel": { "description": "Channel allowed for transfers to this recipient.", "example": 0, "type": "number" }, "available_channel": { "description": "Channel currently available for this recipient.", "example": 0, "type": "number" }, "imps_inactive_reason": { "description": "Reason IMPS is inactive for this recipient, if any.", "example": "", "type": "string" }, "pipes": { "description": "Available settlement pipes for this recipient, keyed by pipe id.", "example": { "3": { "pipe": 3, "status": 1 } }, "type": "object" } } } } } } } }, "examples": { "success": { "summary": "23 — Recipient list returned — proceed to Send Transaction OTP", "value": { "response_status_id": 0, "data": { "pan_required": 2, "recipient_list": [ { "channel_absolute": 0, "available_channel": 0, "account_type": "Bank Account", "ifsc_status": 1, "is_self_account": "0", "channel": 0, "is_imps_scheduled": 0, "recipient_id_type": "acc_ifsc", "imps_inactive_reason": "", "allowed_channel": 0, "is_verified": 0, "beneficiary_id": 40378, "bank": "Kotak Mahindra Bank", "is_otp_required": "0", "recipient_mobile": "9999999990", "recipient_name": "Aditya", "ifsc": "KKBK0000878", "account": "1XXXXXX90657", "pipes": { "3": { "pipe": 3, "status": 1 } }, "recipient_id": 10018839, "is_rblbc_recipient": 1 }, { "channel_absolute": 2, "available_channel": 2, "account_type": "Bank Account", "ifsc_status": 1, "is_self_account": "0", "channel": 2, "is_imps_scheduled": 0, "recipient_id_type": "acc_ifsc", "imps_inactive_reason": "", "allowed_channel": 2, "is_verified": 0, "beneficiary_id": null, "bank": "State Bank of India", "is_otp_required": "0", "recipient_mobile": "6888888886", "recipient_name": "ABCD", "ifsc": "SBIN00005656", "account": "43XXXXXXXXX45", "pipes": { "3": { "pipe": 3, "status": 1 } }, "recipient_id": 10065177, "is_rblbc_recipient": 1 } ], "remaining_limit_before_pan_required": 50000, "is_insured": "" }, "response_type_id": 23, "message": "Success", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/dmt-levin/sender/{customer_id}/recipient": { "post": { "operationId": "dmtLevinAddRecipient", "summary": "Add Recipient", "description": "Adds a new recipient or updates an existing recipient for the sender. Provide the recipient's name, mobile, bank account, IFSC and Eko `bank_id` (resolve it from the IFSC with Get IFSC Details). On success a `recipient_id` is returned — use it to send money. A sender can add a maximum of 5 recipients in a day.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 43 | Recipient added — proceed to Send Transaction OTP | [dmt-levin-send-otp](https://eps.eko.in/docs/dmt-levin-send-otp) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-add-recipient", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "creates", "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "customer_id", "in": "path", "required": true, "description": "Sender's 10-digit mobile number.", "schema": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9999999999" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "recipient_id": { "description": "Unique recipient identifier — use it to send money.", "example": 116456986, "type": "number" }, "customer_id": { "description": "Sender's mobile number (echoed back).", "example": "9999999999", "type": "string" }, "recipient_mobile": { "description": "Recipient mobile number (echoed back).", "example": "8888888888", "type": "string" }, "initiator_id": { "description": "Partner initiator ID (echoed back).", "example": "7384421232", "type": "string" }, "pipes": { "description": "Available settlement pipes for the new recipient.", "example": {}, "type": "object" } } } } }, "examples": { "success": { "summary": "43 — Recipient added — proceed to Send Transaction OTP", "value": { "response_status_id": 0, "data": { "bank_recipient_id": "", "initiator_id": "7384421232", "recipient_mobile": "8888888888", "recipient_id_type": "", "customer_id": "9999999999", "pipes": {}, "recipient_id": 116456986 }, "response_type_id": 43, "message": "Success!Please transact using Recipientid", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "User code value of the retailer from whom the request is coming.", "example": "99080253" }, "bank_id": { "type": "integer", "description": "Eko's unique ID for the recipient's bank. Resolve it from the IFSC with Get IFSC Details.", "example": 6 }, "recipient_name": { "type": "string", "description": "Full name of the recipient.", "example": "Rahul" }, "recipient_mobile": { "type": "string", "description": "Recipient's valid 10-digit mobile number.", "example": "8888888888" }, "recipient_type": { "type": "integer", "description": "Recipient type. Value will be 3.", "example": 3 }, "account": { "type": "string", "description": "Recipient's bank account number used for receiving funds.", "example": "1234567891023" }, "ifsc": { "type": "string", "description": "IFSC code of the recipient's bank branch.", "example": "HDFC0000583", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" }, "account_type": { "type": "integer", "description": "Account type. Defaults to 1.", "example": 1 }, "type": { "type": "string", "description": "Recipient identifier type. Defaults to `ifsc`.", "example": "ifsc" } }, "required": [ "initiator_id", "user_code", "bank_id", "recipient_name", "recipient_mobile", "recipient_type", "account_type", "type" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "99080253", "bank_id": 6, "recipient_name": "Rahul", "recipient_mobile": "8888888888", "recipient_type": 3, "account": "1234567891023", "ifsc": "HDFC0000583", "account_type": 1, "type": "ifsc" } } } } } }, "/customer/payment/dmt-levin/otp": { "post": { "operationId": "dmtLevinSendOtp", "summary": "Send Transaction OTP", "description": "Generates an OTP and delivers it to the sender's registered mobile number as a pre-authorisation step before the money transfer. Provide the recipient_id, the transfer amount, and the sender's customer_id. The returned otp_ref_id must be passed to the transfer call along with the OTP entered by the customer.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 2133 | Transaction OTP sent — proceed to Initiate Transaction | [dmt-levin-initiate-transfer](https://eps.eko.in/docs/dmt-levin-initiate-transfer) |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-send-otp", "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "otp_ref_id": { "description": "Reference ID for the OTP sent. Pass it to the transfer call along with the customer-entered OTP.", "example": "0ac275d7-2919-44ec-a64d-3a7ee0958563", "type": "string" } } } } }, "examples": { "success": { "summary": "2133 — Transaction OTP sent — proceed to Initiate Transaction", "value": { "response_status_id": 0, "data": { "otp_ref_id": "0ac275d7-2919-44ec-a64d-3a7ee0958563" }, "response_type_id": 2133, "message": "Send OTP", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "user_code": { "type": "string", "description": "User code value of the retailer from whom the request is coming.", "example": "99080253" }, "recipient_id": { "type": "integer", "description": "Unique recipient ID returned by Add Recipient or Get Recipients.", "example": 116456986 }, "amount": { "type": "integer", "description": "Transfer amount in INR.", "example": 500 }, "customer_id": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "9999999999" }, "beneficiary_id": { "type": "string", "description": "Unique ID generated when adding the recipient's bank details (see Get Recipients).", "example": "40378" } }, "required": [ "initiator_id", "user_code", "recipient_id", "amount", "customer_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "99080253", "recipient_id": 116456986, "amount": 500, "customer_id": "9999999999", "beneficiary_id": "40378" } } } } } }, "/customer/payment/dmt-levin": { "post": { "operationId": "dmtLevinInitiateTransfer", "summary": "Initiate DMT-Levin Transaction", "description": "The financial step in the DMT Levin flow. Debits the agent's wallet and initiates an IMPS transfer to the registered recipient's bank account. Requires the otp and otp_ref_id from Send Transaction OTP plus a unique client_ref_id per attempt. The response returns tid (Eko transaction ID) and bank_ref_num (the IMPS RRN/UTR); persist both with your client_ref_id for reconciliation.\n\nIf `tx_status` is any value other than those documented, treat the transaction as initiated and poll [Transaction Inquiry](/docs/transaction-inquiry) until a final status is received.\n\n**Timeout:** a transaction can time out due to a bad connection or a slow partner-bank response. Do not treat a timeout as declined or failed — look it up with [Transaction Inquiry](/docs/transaction-inquiry) using your `client_ref_id`.\n\n**Refund:** when a transaction fails, an OTP is automatically sent to the customer. Collect that OTP and call [Get Refund OTP](/docs/get-refund-otp) as consent that you refunded the cash to the customer; the eValue is then refunded to your account.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 325 | Transaction successful | — |", "tags": [ "Domestic Money Transfer (DMT)" ], "x-docs-slug": "dmt-levin-initiate-transfer", "x-eko-uat-unavailable": true, "x-eko-financial": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "tx_status": { "description": "Transaction state: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tid": { "description": "Eko's internal transaction ID. Store for reconciliation and support queries.", "example": "3111111112", "type": "string" }, "bank_ref_num": { "description": "Bank reference number (RRN / UTR) for the IMPS transaction.", "example": "51334977222863", "type": "string" }, "amount": { "description": "Amount transferred (INR).", "example": "110.00", "type": "string" }, "fee": { "description": "Fee charged for the transfer (INR).", "example": "0.0", "type": "string" }, "collectable_amount": { "description": "Total collectable from the sender (INR).", "example": "100.0", "type": "string" }, "service_tax": { "description": "Service tax component on the fee (INR).", "example": "0.00", "type": "string" }, "tds": { "description": "Tax deducted at source on the agent's commission (INR).", "example": "0.0", "type": "string" }, "commission": { "description": "Commission earned by the agent on this transaction (INR).", "example": "0.0", "type": "string" }, "sender_name": { "description": "Name of the sender.", "example": "Akash", "type": "string" }, "recipient_name": { "description": "Name of the beneficiary credited.", "example": "Rahul", "type": "string" }, "recipient_id": { "description": "Recipient identifier credited.", "example": 116456986, "type": "number" }, "bank": { "description": "Beneficiary bank name.", "example": "ICICI Bank", "type": "string" }, "account": { "description": "Beneficiary account number credited.", "example": "12345678912", "type": "string" }, "channel_desc": { "description": "Settlement channel used (e.g. IMPS).", "example": "IMPS", "type": "string" }, "balance": { "description": "Agent wallet balance after the transaction (INR).", "example": "1.48", "type": "string" }, "remaining_limit_before_pan_required": { "description": "Amount the sender can still transfer before PAN becomes mandatory (INR).", "example": 49800, "type": "number" }, "client_ref_id": { "description": "Echo of the partner reference sent in the request.", "example": "6634235566", "type": "string" }, "currency": { "description": "Currency code.", "example": "INR", "type": "string" }, "timestamp": { "description": "Server-side timestamp of the transaction.", "example": "2024-03-21T09:10:32.350Z", "type": "string" } } } } }, "examples": { "success": { "summary": "325 — Transaction successful", "value": { "response_status_id": 0, "data": { "tx_status": "0", "debit_user_id": "8888899999", "tds": "0.0", "txstatus_desc": "Success", "fee": "0.0", "total_sent": "", "channel": "2", "collectable_amount": "100.0", "txn_wallet": "0", "utility_acc_no": "8969622436", "sender_name": "Akash", "ekyc_enabled": "0", "remaining_limit_before_pan_required": 49800, "tid": "3111111112", "bank": "ICICI Bank", "insurance_acquired": "", "balance": "1.48", "totalfee": "", "next_allowed_limit": "", "is_otp_required": "0", "aadhar": "", "currency": "INR", "commission": "0.0", "pipe": 14, "state": "1", "bank_ref_num": "51334977222863", "recipient_id": 116456986, "timestamp": "2024-03-21T09:10:32.350Z", "gst_loss": "0", "amount": "110.00", "pan_required": 2, "pinNo": "", "gst_benefit": "0", "payment_mode_desc": "", "channel_desc": "IMPS", "last_used_okekey": "4", "client_ref_id": "6634235566", "npr": "", "insurance_amount": "", "service_tax": "0.00", "paymentid": "", "mdr": "", "recipient_name": "Rahul", "customer_id": "9999999999", "account": "12345678912", "kyc_state": "" }, "response_type_id": 325, "message": "Transaction successful Last_used_OkeyKey: 4", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "user_code": { "type": "string", "description": "User code value of the retailer from whom the request is coming.", "example": "17260001" }, "customer_id": { "type": "string", "description": "Sender's 10-digit mobile number.", "example": "8999999992" }, "recipient_id": { "type": "integer", "description": "Unique recipient ID from Add Recipient or Get Recipients.", "example": 10017680 }, "amount": { "type": "integer", "description": "Transfer amount in INR (must match the amount sent to Send Transaction OTP).", "example": 110 }, "otp": { "type": "string", "description": "OTP received from the Send Transaction OTP API.", "example": "778341" }, "otp_ref_id": { "type": "string", "description": "OTP reference ID from the Send Transaction OTP response.", "example": "zCISyglexo0Pjqp4YrS2ssweuD9v1GxjISTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=" }, "client_ref_id": { "type": "string", "description": "Unique reference number from your system — make it as unique as possible so it never matches another partner's reference. Used for Transaction Inquiry lookup.", "example": "RIM65656566" }, "timestamp": { "type": "string", "description": "Request date and time (`YYYY-MM-DD HH:mm:ss`).", "example": "2025-01-21 11:48:50" }, "currency": { "type": "string", "description": "Currency code. Always `INR`.", "example": "INR" }, "channel": { "type": "integer", "description": "Send the fixed value 2.", "example": 2 }, "state": { "type": "string", "description": "Send the fixed value 1.", "example": "1" }, "recipient_id_type": { "type": "integer", "description": "Send the fixed value 1.", "example": 1 }, "latlong": { "type": "string", "description": "GPS coordinates of the user from whom the request is coming, used in case of fraud — pass the valid location of the merchant's system. Format: ", "example": "26.8863786,75.7393589", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" } }, "required": [ "initiator_id", "user_code", "customer_id", "recipient_id", "amount", "otp", "otp_ref_id", "client_ref_id", "timestamp", "currency", "channel", "state", "recipient_id_type", "latlong" ] }, "example": { "initiator_id": "9962981729", "user_code": "17260001", "customer_id": "8999999992", "recipient_id": 10017680, "amount": 110, "otp": "778341", "otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1GxjISTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=", "client_ref_id": "RIM65656566", "timestamp": "2025-01-21 11:48:50", "currency": "INR", "channel": 2, "state": "1", "recipient_id_type": 1, "latlong": "26.8863786,75.7393589" } } } } } }, "/user/network/eps-agent": { "post": { "operationId": "onboardUser", "summary": "Onboard User", "description": "Onboards a merchant or retailer as a user on the platform. On success a unique `user_code` is returned — save it; every downstream request for that agent passes this `user_code`.", "tags": [ "User & Agent Management" ], "x-docs-slug": "onboard-user", "x-eko-trxn-type-id": 378, "x-eko-product-code": 359, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "creates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "user_code": { "description": "Unique code for the onboarded agent — save it and pass on every downstream request.", "example": "20110002", "type": "string" }, "initiator_id": { "description": "Your registered initiator id (echoed back).", "example": "9962981729", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": -1, "data": { "user_code": "20110002", "initiator_id": "9962981729" }, "response_type_id": 1290, "message": "User onboarding successfull", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "mobile": { "type": "string", "description": "Verified mobile number of the agent.", "example": "9876543210" }, "first_name": { "type": "string", "description": "First name of the agent.", "example": "Test" }, "last_name": { "type": "string", "description": "Last name of the agent.", "example": "User" }, "pan_number": { "type": "string", "description": "PAN card number of the agent.", "example": "ABCPV1234D", "pattern": "^[A-Z]{5}\\d{4}[A-Z]$" }, "email": { "type": "string", "description": "Email ID of the agent.", "example": "ramesh@example.com" }, "residence_address": { "type": "string", "description": "Residence address of the agent as an object with following fields: line, city, state, pincode, district, area.", "example": { "line": "Eko India", "city": "Gurgaon", "state": "Haryana", "pincode": "122002", "district": "Banswara", "area": "Mongol" } }, "dob": { "type": "string", "description": "Date of birth of the agent in YYYY-MM-DD format.", "example": "1990-05-15", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "shop_name": { "type": "string", "description": "Shop name of the agent (required for AePS onboarding).", "example": "Ramesh Mobile Store" } }, "required": [ "initiator_id", "mobile", "first_name", "last_name", "pan_number", "email", "residence_address", "dob", "shop_name" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "mobile": "9876543210", "first_name": "Test", "last_name": "User", "pan_number": "ABCPV1234D", "email": "ramesh@example.com", "residence_address": { "line": "Eko India", "city": "Gurgaon", "state": "Haryana", "pincode": "122002", "district": "Banswara", "area": "Mongol" }, "dob": "1990-05-15", "shop_name": "Ramesh Mobile Store" } } } } } }, "/admin/network/agent/{user_code}/service/{service_code}/activate": { "put": { "operationId": "activateUserService", "summary": "Activate Service for User", "description": "Enables a service for the given user (agent/retailer/distributor) so they can begin transacting on it. Activating a service is mandatory before your users can use it in production. The user is identified by their `user_code` and the service by its `service_code`, both supplied as path parameters. Look up service codes via the Get All Services API. After activation, confirm the status with the Get User's Services API.", "tags": [ "User & Agent Management" ], "x-docs-slug": "activate-user-service", "x-eko-trxn-type-id": 384, "x-eko-product-code": 365, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "updates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "user_code", "in": "path", "required": true, "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "schema": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" } }, { "name": "service_code", "in": "path", "required": true, "description": "Unique code of the service to activate for the user. See the service codes reference.", "schema": { "type": "string", "description": "Unique code of the service to activate for the user. See the service codes reference.", "example": "53" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object" } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Service activated successfully.", "response_type_id": 0, "data": {} } }, "service_already_activated": { "summary": "Service already activated", "value": { "status": 1295, "response_status_id": 1, "response_type_id": 1295, "message": "This service already exist for the user code", "data": { "service_status_desc": "", "user_code": "", "initiator_id": "", "name": "", "service_status": "", "service_code": "", "ifsc": "", "virtual_account_number": "" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, "required": [ "initiator_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789" } } } } } }, "/admin/network/agent/{user_code}/service/{service_code}/deactivate": { "put": { "operationId": "deactivateUserService", "summary": "Deactivate Service for User", "description": "Disables a previously activated service for the given agent. The agent is identified by their `user_code` and the service by its `service_code`, both supplied as path parameters. After deactivation, confirm the status with the Get User's Services API.", "tags": [ "User & Agent Management" ], "x-docs-slug": "deactivate-user-service", "x-eko-semantics": { "readOnly": false, "idempotent": true, "billable": false, "sideEffects": [ "deactivates" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "user_code", "in": "path", "required": true, "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "schema": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" } }, { "name": "service_code", "in": "path", "required": true, "description": "Unique code of the service to deactivate for the user. See the service codes reference.", "schema": { "type": "string", "description": "Unique code of the service to deactivate for the user. See the service codes reference.", "example": "53" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object" } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Service deactivated successfully.", "response_type_id": 0, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, "required": [ "initiator_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789" } } } } } }, "/user/account/services": { "get": { "operationId": "getUserServices", "summary": "Get User's Services", "description": "Returns every service enabled for the given `user_code`, with each service's\nactivation status, ops-verification status and timestamps. Use it to audit which\nservices one of your agents can actually transact on.\n\n## Service status (`service_status_list[].status`)\n\nNot to be confused with the top-level `status` — this one lives on each\nentry of `service_status_list`.\n\n| `status` | `status_desc` | Meaning |\n|---|---|---|\n| 0 | `DEACTIVATED` | Agent must re-upload their documents using the Activate Service API |\n| 1 | `ACTIVATED` | Service is live and usable |\n| 2 | `PENDING` | Activation pending for this agent |\n\n> [!NOTE]\n> Once the agent re-uploads their documents from the DEACTIVATED state, the\n> service moves to PENDING — not straight back to ACTIVATED.\n\n## Verification status (`verification_status`)\n\nTells you the action taken by the Eko operations team on the agent's documents\nfor that service.\n\n| `verification_status` | Meaning |\n|---|---|\n| 0 | Not applicable — this service needs no ops verification |\n| 1 | Verified — documents verified by the ops team |\n| 2 | Rejected — rejection reason is in the entry's `comments` field |\n| 3 | Pending — action pending from the ops team |", "tags": [ "User & Agent Management" ], "x-docs-slug": "get-user-services", "x-eko-trxn-type-id": 496, "x-eko-product-code": 468, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "user_code", "in": "query", "required": true, "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "schema": { "type": "string", "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users", "example": "20810200" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "service_status_list": { "description": "Per-service status for the user.", "type": "array", "items": { "type": "object", "properties": { "service_code": { "description": "Service code.", "example": "43", "type": "string" }, "status_desc": { "description": "Human-readable status (ACTIVATED / PENDING / DEACTIVATED).", "example": "ACTIVATED", "type": "string" }, "status": { "description": "Activation status — 0 = deactivated (agent must re-upload documents via Activate Service), 1 = activated, 2 = pending.", "example": 1, "type": "number" }, "verification_status": { "description": "Ops-team verification state — 0 = not applicable, 1 = verified, 2 = rejected (reason in `comments`), 3 = pending.", "example": 3, "type": "number" }, "comments": { "description": "Ops-team remark — holds the rejection reason when `verification_status` is 2, otherwise null.", "example": null, "type": "string" }, "createdAt": { "description": "When the service was created.", "example": "2019-11-11 13:21:25.0", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": -1, "data": { "user_code": "20110341", "initiator_id": "9962981729", "service_status_list": [ { "comments": null, "status_desc": "ACTIVATED", "city": null, "user_name": null, "mobile": null, "service_provider": null, "verification_status": 3, "createdAt": "2019-11-11 13:21:25.0", "user_code": null, "service_code": "43", "state": null, "status": 1, "updatedAt": "2019-11-11 13:21:25.0" }, { "comments": null, "status_desc": "PENDING", "city": null, "user_name": null, "mobile": null, "service_provider": null, "verification_status": 0, "createdAt": "2019-11-11 13:22:44.0", "user_code": null, "service_code": "1", "state": null, "status": 2, "updatedAt": "" } ] }, "response_type_id": 1299, "message": "Status of services for this user", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/catalog/service-codes": { "get": { "operationId": "getAllServices", "summary": "Get All Services", "description": "Returns the catalogue of services you can activate for your users — each with its `service_code` and provider name. Use the code with Activate Service for User.", "tags": [ "User & Agent Management" ], "x-docs-slug": "get-all-services", "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "service_list": { "description": "Available services.", "type": "array", "items": { "type": "object", "properties": { "service_name": { "description": "Display name of the service.", "example": "AEPS", "type": "string" }, "service_code": { "description": "Service code — pass to Activate Service for User.", "example": "43", "type": "string" }, "provider_name": { "description": "Service provider.", "example": "Fingpay", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": -1, "data": { "service_list": [ { "service_name": "Pan Verification", "service_code": "4", "provider_name": "NSDL" }, { "service_name": "AePS Fund Settlement", "service_code": "39", "provider_name": "Yes Bank" }, { "service_name": "AEPS", "service_code": "43", "provider_name": "Fingpay" }, { "service_name": "BBPS", "service_code": "53", "provider_name": "" } ] }, "response_type_id": 1280, "message": "List of active services", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/user/account/balance/{customer_id}": { "get": { "operationId": "getWalletBalance", "summary": "Get Wallet Balance", "description": "Returns the current wallet (settlement account) balance for the given registered mobile number (for your own account or that of your users/agents).", "tags": [ "User & Agent Management" ], "x-docs-slug": "get-wallet-balance", "x-eko-trxn-type-id": 9, "x-eko-product-code": 9, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "customer_id", "in": "path", "required": true, "description": "Registered mobile number for the wallet.", "schema": { "type": "string", "description": "Registered mobile number for the wallet.", "example": "9962981729" } }, { "name": "customer_id_type", "in": "query", "required": true, "description": "Identifier type. Fixed value: mobile_number.", "schema": { "type": "string", "description": "Identifier type. Fixed value: mobile_number.", "example": "mobile_number" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "balance": { "description": "Settlement-account balance (INR).", "example": "2.20834002375E9", "type": "string" }, "currency": { "description": "Currency.", "example": "INR", "type": "string" }, "customer_id": { "description": "Registered mobile number (echoed back).", "example": "9910028267", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": -1, "data": { "last_used_okekey": "0", "balance": "2.20834002375E9", "currency": "INR", "customer_id": "9910028267" }, "response_type_id": 1, "message": "SUCCESS", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/reference/transaction": { "get": { "operationId": "transactionInquiry", "summary": "Transaction Inquiry", "description": "Looks up a transaction's status using either Eko's TID or your own `client_ref_id` — useful when a response timed out and you never received the TID. tx_status codes: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required. A timeout should never be treated as an automatic failure — always inquire.", "tags": [ "Transactions & Refunds" ], "x-docs-slug": "transaction-inquiry", "x-eko-trxn-type-id": 98, "x-eko-product-code": 94, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "tid", "in": "query", "required": false, "description": "Eko TID that identifies the transaction. You must pass either this or your `client_ref_id`. If both are passed, Eko's TID takes precedence.", "schema": { "type": "string", "description": "Eko TID that identifies the transaction. You must pass either this or your `client_ref_id`. If both are passed, Eko's TID takes precedence.", "example": "12839273" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Your `client_ref_id` that identifies the transaction. You must pass either this or Eko's `tid`.", "schema": { "type": "string", "description": "Your `client_ref_id` that identifies the transaction. You must pass either this or Eko's `tid`.", "example": "28392661538393994551" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "tx_status": { "description": "Transaction status (0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required).", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "tid": { "description": "Eko transaction ID.", "example": "12971397", "type": "string" }, "client_ref_id": { "description": "Your reference id for the transaction.", "example": "Settlemet7206123420", "type": "string" }, "amount": { "description": "Transaction amount (INR).", "example": "1045.0", "type": "string" }, "bank_ref_num": { "description": "Bank/UTR reference number.", "example": "8761099407", "type": "string" }, "recipient_name": { "description": "Recipient's name.", "example": "Virender Singh", "type": "string" }, "timestamp": { "description": "Transaction timestamp.", "example": "2019-11-01 17:50:44", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "response_type_id": 70, "message": "Transaction details fetched successfully", "data": { "tx_status": "3", "amount": "1000.0", "txstatus_desc": "Refund Pending", "fee": "150.0", "channel": "", "branch": "", "gst_benefit": "", "tid": "12839273", "tx_desc": "Indo-Nepal Money Transfer", "allow_retry": "0", "service_tax": "", "currency": "INR", "pipe": "", "customer_id": "7777777777", "bank_ref_num": "1111187250183230", "recipient_id": 1157, "timestamp": "2018-10-01 17:09:54" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/customer/payment/refund/{tid}/otp": { "post": { "operationId": "getRefundOtp", "summary": "Get Refund OTP", "description": "For a failed transaction (tx_status 3), an OTP is sent to the customer's mobile. Call this to (re)send it and obtain the `otp_ref_id`; pass both into Initiate Refund. The OTP cannot be bypassed.", "tags": [ "Transactions & Refunds" ], "x-docs-slug": "get-refund-otp", "x-eko-trxn-type-id": 144, "x-eko-product-code": 135, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "tid", "in": "path", "required": true, "description": "Transaction ID from the Initiate Transaction call.", "schema": { "type": "string", "description": "Transaction ID from the Initiate Transaction call.", "example": "13192443" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "otp_ref_id": { "description": "OTP session reference — pass to Initiate Refund.", "example": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 1, "data": { "otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=" }, "response_type_id": 2133, "message": "Send OTP", "status": 2133 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, "required": [ "initiator_id" ] }, "example": { "initiator_id": "9962981729" } } } } } }, "/customer/payment/refund/{tid}": { "post": { "operationId": "initiateRefund", "summary": "Initiate Refund", "description": "Refunds the e-value for a failed transaction back to your account, acting as consent that you have returned the cash to the customer. Requires the OTP (and otp_ref_id) from Get Refund OTP. Returns the financial response envelope with the refund transaction id and reversed amounts.", "tags": [ "Transactions & Refunds" ], "x-docs-slug": "initiate-refund", "x-eko-trxn-type-id": 83, "x-eko-product-code": 81, "x-eko-financial": true, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "tid", "in": "path", "required": true, "description": "Transaction ID from the Initiate Transaction call.", "schema": { "type": "string", "description": "Transaction ID from the Initiate Transaction call.", "example": "13192443" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "tx_status": { "description": "Transaction state: 0=Success, 1=Fail, 2=Initiated / Response Awaited (NEFT) — poll Transaction Inquiry, 3=Refund Pending, 4=Refunded, 6=Response Awaited — Transaction Inquiry required.", "example": "0", "type": "string" }, "txstatus_desc": { "description": "Human-readable transaction status.", "example": "Success", "type": "string" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "refund_tid": { "description": "Transaction ID of the refund.", "example": "2147591637", "type": "string" }, "refunded_amount": { "description": "Total amount refunded (INR).", "example": "5050.00", "type": "string" }, "amount": { "description": "Original transaction amount (INR).", "example": "5000.00", "type": "string" }, "fee": { "description": "Fee reversed (INR).", "example": "50.0", "type": "string" }, "balance": { "description": "Account balance after the refund (INR).", "example": "2.22263731286E9", "type": "string" }, "tid": { "description": "Original transaction ID.", "example": "13192443", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "refund_tid": "2147591637", "amount": "5000.00", "tds": "7.1", "balance": "2.22263731286E9", "fee": "50.0", "currency": "INR", "commission_reverse": "28.38", "tid": "13192443", "timestamp": "2018-10-30T12:00:14.058Z", "refunded_amount": "5050.00" }, "response_type_id": 74, "message": "Refund done", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "otp": { "type": "integer", "description": "OTP sent to the customer's mobile number.", "example": 123456 }, "otp_ref_id": { "type": "string", "description": "otp_ref_id received from Get Refund OTP.", "example": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=" }, "service_code": { "type": "integer", "description": "Fixed service code. For PayPoint send 80.", "example": 80 }, "state": { "type": "integer", "description": "Fixed value. Send 1.", "example": 1 } }, "required": [ "initiator_id", "otp" ] }, "example": { "initiator_id": "9962981729", "otp": 123456, "otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=", "service_code": 80, "state": 1 } } } } } }, "/tools/reference/banks": { "get": { "operationId": "getBanks", "summary": "Get List of Banks", "description": "Returns a list of all banks. Use the [Get Bank Details API](./get-bank-details) to get additional information about a bank.\n\nThe bank list is returned under `param_attributes.list_elements`, not under `data`. Each bank carries its account-number rules and Eko `bank_id` in a `dependent_params` name/value list — look entries up by `name`, not by position.\n\n### Response types\n\nBranch on `response_type_id` to decide the next call:\n\n| response_type_id | Meaning | Next step |\n| --- | --- | --- |\n| 398 | Bank list returned successfully | — |", "tags": [ "Bank & IFSC" ], "x-docs-slug": "get-banks", "x-eko-trxn-type-id": 155, "x-eko-product-code": 144, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "param_attributes": { "description": "Container for the returned list.", "type": "object", "properties": { "list_elements": { "description": "Array of banks.", "type": "array", "items": { "type": "object", "properties": { "label": { "description": "Bank display name.", "example": "State Bank of India", "type": "string" }, "value": { "description": "Eko bank code — pass as `bank_code` to Get Bank Details.", "example": "SBIN", "type": "string" }, "dependent_params": { "description": "Bank-specific attributes as `name`/`value` pairs. Known names: `account` (account-number length rules), `ifsc_required` (1 = IFSC must be sent with the account), `varifiable` (1 = account verification available; key spelled as returned), `bank_id` (Eko bank identifier), `is_face_auth_available`, `is_iris_auth_available` (1 = supported).", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Attribute name.", "example": "bank_id", "type": "string" }, "value": { "description": "Attribute value. Absent on the `account` entry.", "example": 108, "type": "number" }, "length_min": { "description": "Minimum account-number length. Only on the `account` entry.", "example": 11, "type": "number" }, "length_max": { "description": "Maximum account-number length. Only on the `account` entry.", "example": 13, "type": "number" }, "pattern_error": { "description": "Validation message to show for an invalid account number. Optional; only on the `account` entry.", "example": "Please enter a valid 11-digit SBI account number", "type": "string" } } } } } } } } } } } } }, "examples": { "success": { "summary": "398 — Bank list returned successfully", "value": { "response_status_id": 0, "param_attributes": { "list_elements": [ { "dependent_params": [ { "pattern_error": "Please enter a valid 11-digit SBI account number", "name": "account", "length_max": 13, "length_min": 11 }, { "name": "ifsc_required", "value": 0 }, { "name": "varifiable", "value": 1 }, { "name": "bank_id", "value": 108 }, { "name": "is_face_auth_available", "value": 0 }, { "name": "is_iris_auth_available", "value": 0 } ], "label": "State Bank of India", "value": "SBIN" }, { "dependent_params": [ { "name": "account", "length_max": 16, "length_min": 16 }, { "name": "ifsc_required", "value": 0 }, { "name": "varifiable", "value": 1 }, { "name": "bank_id", "value": 11 }, { "name": "is_face_auth_available", "value": 0 }, { "name": "is_iris_auth_available", "value": 0 } ], "label": "Punjab National Bank", "value": "PUNB" }, { "dependent_params": [ { "name": "account", "length_max": 16, "length_min": 14 }, { "name": "ifsc_required", "value": 0 }, { "name": "varifiable", "value": 1 }, { "name": "bank_id", "value": 2 }, { "name": "is_face_auth_available", "value": 0 }, { "name": "is_iris_auth_available", "value": 0 } ], "label": "Bank of Baroda", "value": "BARB" } ] }, "response_type_id": 398, "message": "Success! Total Banks found in the System", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/reference/bank": { "get": { "operationId": "getBankDetails", "summary": "Get Bank Details", "description": "Returns metadata for a bank — Eko `bank_id`, display name, supported channels, and whether account verification is available. Optionally pass an IFSC to narrow the lookup.", "tags": [ "Bank & IFSC" ], "x-docs-slug": "get-bank-details", "x-eko-trxn-type-id": 163, "x-eko-product-code": 151, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "bank_code", "in": "query", "required": true, "description": "Eko bank code (see the bank list).", "schema": { "type": "string", "description": "Eko bank code (see the bank list).", "example": "IDFB" } }, { "name": "ifsc", "in": "query", "required": false, "description": "IFSC code to narrow the lookup.", "schema": { "type": "string", "description": "IFSC code to narrow the lookup.", "example": "IDFB0080202", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "name": { "description": "Bank display name.", "example": "IDFC Bank", "type": "string" }, "bank_id": { "description": "Eko bank identifier — use when adding a recipient.", "example": 262, "type": "number" }, "code": { "description": "Eko bank code.", "example": "IDFB", "type": "string" }, "ifsc_status": { "description": "IFSC verification status code.", "example": 4, "type": "number" }, "isverificationavailable": { "description": "Whether account verification is available (1) or not (0).", "example": "0", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "isverificationavailable": "0", "code": "IDFB", "ifsc_status": 4, "user_code": "20810200", "bank_id": 262, "name": "IDFC Bank", "available_channels": 0 }, "response_type_id": 466, "message": "Bank Detials Found", "status": 0 } }, "invalid_bank_details": { "summary": "Invalid bank details", "value": { "response_status_id": 1, "response_type_id": 467, "message": "Please provide valid bank details", "status": 467 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/reference/banks/ifsc": { "get": { "operationId": "getIfscDetails", "summary": "Get IFSC Details", "description": "Returns the bank name, branch, Eko `bank_id`, and verification availability for a given IFSC code.", "tags": [ "Bank & IFSC" ], "x-docs-slug": "get-ifsc-details", "x-eko-trxn-type-id": 161, "x-eko-product-code": 149, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "ifsc", "in": "query", "required": true, "description": "IFSC code of the bank branch.", "schema": { "type": "string", "description": "IFSC code of the bank branch.", "example": "HDFC0000001", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "bank": { "description": "Bank name for the IFSC.", "example": "INDIAN OVERSEAS BANK", "type": "string" }, "branch": { "description": "Branch for the IFSC.", "example": "SANGLI", "type": "string" }, "ifsc": { "description": "IFSC code (echoed back).", "example": "IOBA0002248", "type": "string" }, "bank_id": { "description": "Eko bank identifier.", "example": 10, "type": "number" }, "isverificationavailable": { "description": "Whether account verification is available (1) or not (0).", "example": "1", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": -1, "data": { "bank": "INDIAN OVERSEAS BANK", "isverificationavailable": "1", "ifsc_status": 3, "user_code": "20810200", "bank_id": 10, "available_channels": 0, "ifsc": "IOBA0002248", "branch": "SANGLI" }, "response_type_id": 414, "message": "Success ! Found bank Details for given Ifsc", "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/kyc/digilocker": { "post": { "operationId": "digilockerCreateUrl", "summary": "Create DigiLocker URL", "description": "Creates a one-time DigiLocker URL that redirects the customer to the DigiLocker portal for consent-based retrieval of Aadhaar (and other) documents. After the customer authorises access on DigiLocker, they are redirected back to the provided `redirect_url`. The `reference_id` returned is then used to fetch the verified document data via the Get DigiLocker Document API.", "tags": [ "DigiLocker Integration" ], "x-docs-slug": "digilocker-create-url", "x-eko-trxn-type-id": 821, "x-eko-product-code": 761, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "opens-session" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "reference_id": { "description": "Unique reference ID for this DigiLocker session. Store this to call Get DigiLocker Document after the customer completes the DigiLocker journey.", "example": 7483920, "type": "number" }, "url": { "description": "DigiLocker redirect URL. Present this URL to the customer to begin document authorisation.", "example": "https://digilocker.gov.in/auth?session_id=abc123xyz", "type": "string" }, "document_requested": { "description": "Echo of the document types requested.", "example": [ "AADHAAR" ], "type": "array", "items": {} }, "redirect_url": { "description": "The callback URL provided in the request.", "example": "https://yourapp.com/kyc/callback", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "DigiLocker URL created successfully", "response_type_id": 1388, "data": { "reference_id": 7483920, "url": "https://digilocker.gov.in/auth?session_id=abc123xyz", "document_requested": [ "AADHAAR" ], "redirect_url": "https://yourapp.com/kyc/callback" } } }, "invalid_redirect_url_format": { "summary": "Invalid redirect_url format", "value": { "status": 1, "response_status_id": 301, "message": "Invalid redirect URL provided.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "document_requested": { "type": "string", "description": "List of document types requested for verification. Defaults to [\"AADHAAR\"].", "example": [ "AADHAAR" ] }, "redirect_url": { "type": "string", "description": "The URL to redirect the customer back to after completing the DigiLocker authorisation journey.", "example": "https://yourapp.com/kyc/callback" } }, "required": [ "initiator_id", "document_requested", "redirect_url" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "document_requested": [ "AADHAAR" ], "redirect_url": "https://yourapp.com/kyc/callback" } } } } } }, "/tools/kyc/digilocker/document": { "post": { "operationId": "digilockerGetDocument", "summary": "Get DigiLocker Document", "description": "Fetches the verified Aadhaar (or other government document) data from DigiLocker using the `reference_id` obtained from Create DigiLocker URL. Must be called after the customer has completed authorisation on DigiLocker and been redirected back. Returns structured identity data extracted from the verified document.", "tags": [ "DigiLocker Integration" ], "x-docs-slug": "digilocker-get-document", "x-eko-trxn-type-id": 823, "x-eko-product-code": 763, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "documents": { "description": "List of verified documents retrieved from DigiLocker.", "type": "array", "items": { "type": "object", "properties": { "document_type": { "description": "Type of document retrieved (e.g. AADHAAR).", "example": "AADHAAR", "type": "string" }, "name": { "description": "Full name as per the verified document.", "example": "Vikram Singh", "type": "string" }, "dob": { "description": "Date of birth from the verified document.", "example": "12-11-1987", "type": "string" }, "gender": { "description": "Gender as per document: M, F, or T.", "example": "M", "type": "string" }, "masked_aadhaar": { "description": "Aadhaar number with first 8 digits masked.", "example": "XXXX-XXXX-2345", "type": "string" }, "address": { "description": "Residential address from the verified Aadhaar.", "type": "object", "properties": { "house": { "description": "House or flat number.", "example": "15B", "type": "string" }, "street": { "description": "Street or locality name.", "example": "Nehru Street", "type": "string" }, "village_or_city": { "description": "Village or city.", "example": "Chennai", "type": "string" }, "district": { "description": "District.", "example": "Chennai", "type": "string" }, "state": { "description": "State.", "example": "Tamil Nadu", "type": "string" }, "pincode": { "description": "6-digit postal code.", "example": "600001", "type": "string" } } }, "photo": { "description": "Base64-encoded photograph from the Aadhaar document.", "example": "/9j/4AAQSkZJRgABAQ...", "type": "string" }, "issue_date": { "description": "Date when the document was issued.", "example": "01-01-2020", "type": "string" } } } }, "verification_status": { "description": "Overall DigiLocker verification status: SUCCESS or PENDING.", "example": "SUCCESS", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Documents retrieved successfully", "response_type_id": 1388, "data": { "verification_status": "SUCCESS", "documents": [ { "document_type": "AADHAAR", "name": "Vikram Singh", "dob": "12-11-1987", "gender": "M", "masked_aadhaar": "XXXX-XXXX-2345", "photo": "/9j/4AAQSkZJRgABAQ...", "issue_date": "01-01-2020", "address": { "house": "15B", "street": "Nehru Street", "village_or_city": "Chennai", "district": "Chennai", "state": "Tamil Nadu", "pincode": "600001" } } ] } } }, "customer_has_not_completed_digilocker_authorisation_yet": { "summary": "Customer has not completed DigiLocker authorisation yet", "value": { "status": 1, "response_status_id": 327, "message": "Verification pending. Customer has not completed DigiLocker consent.", "response_type_id": 1388, "data": {} } }, "invalid_reference_id": { "summary": "Invalid reference_id", "value": { "status": 1, "response_status_id": 463, "message": "Invalid reference ID. Please check and retry.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "document_type": { "type": "string", "description": "List of document types to retrieve (e.g. [\"AADHAAR\"]).", "example": [ "AADHAAR" ] }, "verification_id": { "type": "string", "description": "Unique verification ID returned by the Create DigiLocker URL API.", "example": "vrf_digilocker_abc123" }, "reference_id": { "type": "string", "description": "Reference ID from the Create DigiLocker URL API response.", "example": "7483920" } }, "required": [ "initiator_id", "document_type", "verification_id", "reference_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "document_type": [ "AADHAAR" ], "verification_id": "vrf_digilocker_abc123", "reference_id": "7483920" } } } } } }, "/tools/kyc/digilocker/status": { "get": { "operationId": "digilockerVerificationStatus", "summary": "DigiLocker Verification Status", "description": "Poll this endpoint after redirecting the user to the DigiLocker URL. Returns the user's consent status and basic identity details (name, DOB, gender, mobile) once the consent flow is complete. Use reference_id from the Create DigiLocker URL response.", "tags": [ "DigiLocker Integration" ], "x-docs-slug": "digilocker-verification-status", "x-eko-trxn-type-id": 822, "x-eko-product-code": 762, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "reference_id", "in": "query", "required": true, "description": "Unique identifier received from the Create DigiLocker URL API response.", "schema": { "type": "number", "description": "Unique identifier received from the Create DigiLocker URL API response.", "example": 12345 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "user_details": { "description": "Identity details of the individual who completed the DigiLocker consent flow.", "type": "object", "properties": { "name": { "description": "Full name of the individual as registered in DigiLocker.", "example": "Rahul Sharma", "type": "string" }, "dob": { "description": "Date of birth in DD-MM-YYYY format.", "example": "15-08-1990", "type": "string" }, "gender": { "description": "Gender of the individual (M / F / T).", "example": "M", "type": "string" }, "eaadhaar": { "description": "Indicates whether the individual's e-Aadhaar is available in DigiLocker.", "example": "Y", "type": "string" }, "mobile": { "description": "Mobile number linked to the individual's DigiLocker account.", "example": "98XXXXXXXX", "type": "string" } } }, "document_requested": { "description": "List of document types that were requested in the original session.", "example": [ "AADHAAR" ], "type": "array", "items": {} }, "document_consent": { "description": "Consent status objects per requested document type. Indicates which documents the user approved for sharing.", "example": [ { "document_type": "AADHAAR", "consent": "Y" } ], "type": "array", "items": {} } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Verification status fetched successfully", "response_type_id": 1389, "data": { "user_details": { "name": "Rahul Sharma", "dob": "15-08-1990", "gender": "M", "eaadhaar": "Y", "mobile": "98XXXXXXXX" }, "document_requested": [ "AADHAAR" ], "document_consent": [ { "document_type": "AADHAAR", "consent": "Y" } ] } } }, "consent_flow_not_yet_completed_by_user": { "summary": "Consent flow not yet completed by user", "value": { "status": 1, "response_status_id": -1, "message": "Verification pending. User has not completed DigiLocker consent.", "data": {} } }, "invalid_or_expired_reference_id": { "summary": "Invalid or expired reference_id", "value": { "status": 1, "response_status_id": -1, "message": "Invalid reference_id", "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tools/kyc/bank-account/sync": { "post": { "operationId": "bankAccountVerification", "summary": "Bank Account Verification", "description": "Performs a live penny-drop transaction of ₹1 to the specified bank account and returns the account holder name as registered with the bank, account status, bank/branch details, and the Eko transaction id (tid). Use this before payouts to prevent failures and fraud. The ₹1 is credited to the beneficiary — no refund occurs. Supports all IMPS-enabled banks in India.", "tags": [ "Bank Account Verification" ], "x-docs-slug": "bank-account-verification", "x-eko-trxn-type-id": 839, "x-eko-product-code": 777, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "name_at_bank": { "description": "Account holder name as registered with the bank. Use for name matching against provided details.", "example": "JOHN DOE", "type": "string" }, "account_status": { "description": "Verification outcome for the account (e.g. VALID).", "example": "VALID", "type": "string" }, "account_status_code": { "description": "Machine-readable account status code (e.g. ACCOUNT_IS_VALID).", "example": "ACCOUNT_IS_VALID", "type": "string" }, "bank_name": { "description": "Name of the bank associated with the account.", "example": "YES BANK", "type": "string" }, "branch": { "description": "Branch name associated with the IFSC code.", "example": "SANTACRUZ, MUMBAI", "type": "string" }, "city": { "description": "City where the bank branch is located.", "example": "MUMBAI", "type": "string" }, "micr": { "description": "MICR (ECS identification) code of the branch.", "example": 400065001, "type": "number" }, "reference_id": { "description": "Unique reference id created for this verification.", "example": 5205950, "type": "number" }, "tid": { "description": "Eko transaction id for this verification. Persist it for reconciliation.", "example": 2887347145, "type": "number" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "reference_id": 5205950, "city": "MUMBAI", "bank_name": "YES BANK", "micr": 400065001, "account_status_code": "ACCOUNT_IS_VALID", "account_status": "VALID", "name_at_bank": "JOHN DOE", "branch": "SANTACRUZ, MUMBAI", "tid": 2887347145 }, "response_type_id": 0, "status": 0 } }, "invalid_ifsc_code_malformed_or_non_existent_ifsc_provided": { "summary": "Invalid IFSC code — malformed or non-existent IFSC provided", "value": { "status": 1, "response_status_id": 1, "message": "Invalid IFSC code" } }, "invalid_or_non_existent_bank_account_number_penny_drop_failed": { "summary": "Invalid or non-existent bank account number — penny drop failed", "value": { "status": 1, "response_status_id": 1, "message": "Invalid Account" } }, "bank_not_supported_not_live_on_imps_e_g_deutsche_bank_fincare_sfb": { "summary": "Bank not supported — not live on IMPS (e.g. Deutsche Bank, Fincare SFB)", "value": { "status": 1, "response_status_id": 1, "message": "Bank not supported for verification" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "bank_account": { "type": "string", "description": "Complete bank account number to be verified. Send as a string to preserve leading zeros.", "example": "026291800001191" }, "ifsc": { "type": "string", "description": "IFSC code of the bank account to be verified (11-character alphanumeric).", "example": "YESB0000262", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" } }, "required": [ "initiator_id", "bank_account", "ifsc" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "bank_account": "026291800001191", "ifsc": "YESB0000262" } } } } } }, "/tools/kyc/bank-acc-verify-pennyless": { "post": { "operationId": "bankAccountVerificationPennyless", "summary": "Bank Account Verification (Pennyless)", "description": "Validates a bank account and returns the beneficiary name registered with the bank, without performing a ₹1 penny-drop transfer. Because no money moves, there is no stray credit to reverse if the account details turn out to be wrong. Use the penny-drop API instead when you need proof that a real credit reached the account (a UTR).", "tags": [ "Bank Account Verification" ], "x-docs-slug": "bank-account-verification-pennyless", "x-eko-trxn-type-id": 1019, "x-eko-product-code": 796, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "verified_beneficiary_name": { "description": "Account holder name as registered with the bank. Use for name matching against the details you hold.", "example": "Master YASHWANT BASNETT", "type": "string" }, "status": { "description": "Verification outcome for the account, e.g. success.", "example": "success", "type": "string" }, "bank_account_no": { "description": "Bank account number echoed back from the request.", "example": "38759149196", "type": "string" }, "bank_ifsc": { "description": "IFSC code echoed back from the request.", "example": "SBIN0007515", "type": "string" }, "message": { "description": "Human-readable outcome of the verification.", "example": "Bank account verification successful", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "bank_ifsc": "SBIN0007515", "bank_account_no": "38759149196", "verified_beneficiary_name": "Master YASHWANT BASNETT", "message": "Bank account verification successful", "status": "success" }, "response_type_id": 0, "status": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "account": { "type": "string", "description": "Complete bank account number to be verified.", "example": "38759149196" }, "ifsc": { "type": "string", "description": "IFSC code of the bank account to be verified (11-character alphanumeric).", "example": "SBIN0007515", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" } }, "required": [ "initiator_id", "account", "ifsc" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "account": "38759149196", "ifsc": "SBIN0007515" } } } } } }, "/tools/kyc/bank-account/bulk": { "post": { "operationId": "bulkBankAccountVerification", "summary": "Bulk Bank Account Verification", "description": "Accepts an array of bank account + IFSC pairs and enqueues them for asynchronous penny-drop verification. Returns a bulk_reference_id immediately; use the Bulk Bank Account Verification Status API to retrieve per-account results once processing completes. Ideal for batch onboarding, payroll runs, and large-scale disbursement pipelines where sequential single-account calls would be too slow.", "tags": [ "Bank Account Verification" ], "x-docs-slug": "bulk-bank-account-verification", "x-eko-trxn-type-id": 834, "x-eko-product-code": 773, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "enqueues", "moves-money" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "bulk_reference_id": { "description": "Unique reference ID for this bulk verification batch. Pass this to the Bulk Bank Account Verification Status API to poll for per-account results.", "example": 90438, "type": "number" }, "status": { "description": "Processing state of the batch (e.g. RECEIVED).", "example": "RECEIVED", "type": "string" }, "bulk_verification_id": { "description": "Verification id assigned to the batch.", "example": "2887347146", "type": "string" }, "tid": { "description": "Eko transaction id for this batch. Persist it for reconciliation.", "example": 2887347146, "type": "number" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "response_status_id": 0, "data": { "bulk_reference_id": 90438, "bulk_verification_id": "2887347146", "tid": 2887347146, "status": "RECEIVED" }, "response_type_id": 0, "status": 0 } }, "invalid_ifsc_in_one_or_more_entries_batch_accepted_but_affected_entries_fail_in_status_poll": { "summary": "Invalid IFSC in one or more entries — batch accepted but affected entries fail in status poll", "value": { "response_status_id": 0, "data": { "bulk_reference_id": 90439, "bulk_verification_id": "2887347147", "tid": 2887347147, "status": "RECEIVED" }, "response_type_id": 0, "status": 0 } } } } } }, "400": { "description": "Invalid or malformed entries array — missing required fields in one or more entries", "content": { "application/json": { "examples": { "invalid_or_malformed_entries_array_missing_required_fields_in_one_or_more_entries": { "summary": "Invalid or malformed entries array — missing required fields in one or more entries", "value": { "response_status_id": 1, "code": "Bad request, please check API documentation", "response_type_id": 1, "type": "validation_error", "message": "Bad request, please check API documentation", "status": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "entries": { "type": "string", "description": "Array of bank account objects to verify. Each entry must contain a unique reference_id, bank_account and ifsc.", "example": [ { "reference_id": "1", "bank_account": "026291800001191", "ifsc": "YESB0000262" }, { "reference_id": "2", "bank_account": "00011020001772", "ifsc": "HDFC0000001" } ] }, "entries[].reference_id": { "type": "string", "description": "Your unique id for this entry within the batch. It is returned with this entry's result in the Bulk Bank Account Verification Status API.", "example": "1" }, "entries[].bank_account": { "type": "string", "description": "Bank account number for this entry. Send as a string to preserve leading zeros.", "example": "026291800001191" }, "entries[].ifsc": { "type": "string", "description": "IFSC code for this entry's bank account.", "example": "YESB0000262" } }, "required": [ "initiator_id", "entries", "entries[].reference_id", "entries[].bank_account", "entries[].ifsc" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "entries": [ { "reference_id": "1", "bank_account": "026291800001191", "ifsc": "YESB0000262" }, { "reference_id": "2", "bank_account": "00011020001772", "ifsc": "HDFC0000001" } ], "entries[].reference_id": "1", "entries[].bank_account": "026291800001191", "entries[].ifsc": "YESB0000262" } } } } } }, "/tools/kyc/bank-account/bulk/status": { "get": { "operationId": "bulkBankAccountVerificationStatus", "summary": "Check Bulk Bank Account Verification Status", "description": "Companion to the Bulk Bank Account Verification API. Because the batch runs asynchronously, callers poll this endpoint with the bulk_reference_id from the submit response to retrieve per-account penny-drop results as they complete. The response returns an entries array, one object per submitted account, each carrying the account-holder name at bank, bank/branch/MICR details, UTR, name-match score/result, and account status.", "tags": [ "Bank Account Verification" ], "x-docs-slug": "bulk-bank-account-verification-status", "x-eko-trxn-type-id": 835, "x-eko-product-code": 774, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "bulk_reference_id", "in": "query", "required": true, "description": "The bulk_reference_id returned by the Bulk Bank Account Verification API for the submitted batch.", "schema": { "type": "string", "description": "The bulk_reference_id returned by the Bulk Bank Account Verification API for the submitted batch.", "example": "90438" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "entries": { "description": "Per-account verification results — one object for each account submitted in the batch.", "type": "array", "items": { "type": "object", "properties": { "reference_id": { "description": "The reference_id you sent for this entry in the Bulk Bank Account Verification request.", "example": "1", "type": "string" }, "name_at_bank": { "description": "Account holder name as per bank records.", "example": "JOHN DOE", "type": "string" }, "bank_name": { "description": "Name of the financial institution.", "example": "YES BANK", "type": "string" }, "utr": { "description": "Unique transaction reference number for the penny-drop credit.", "example": "SBIN0123456789", "type": "string" }, "city": { "description": "City where the bank branch is located.", "example": "MUMBAI", "type": "string" }, "branch": { "description": "Bank branch name.", "example": "SANTACRUZ, MUMBAI", "type": "string" }, "micr": { "description": "MICR (ECS identification) code of the branch.", "example": 400065001, "type": "number" }, "name_match_score": { "description": "Confidence score for the supplied-name vs name-at-bank match.", "example": "100", "type": "string" }, "name_match_result": { "description": "Name match result (e.g. MATCH / NO_MATCH).", "example": "MATCH", "type": "string" }, "account_status": { "description": "Current status of the bank account verification.", "example": "VALID", "type": "string" }, "account_status_code": { "description": "Machine-readable account status code (e.g. ACCOUNT_IS_VALID).", "example": "ACCOUNT_IS_VALID", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Success", "response_type_id": 1388, "data": { "entries": [ { "reference_id": "1", "name_at_bank": "JOHN DOE", "bank_name": "YES BANK", "utr": "SBIN0123456789", "city": "MUMBAI", "branch": "SANTACRUZ, MUMBAI", "micr": 400065001, "name_match_score": "100", "name_match_result": "MATCH", "account_status": "VALID", "account_status_code": "ACCOUNT_IS_VALID" } ] } } } } } } }, "400": { "description": "Missing or invalid bulk_reference_id", "content": { "application/json": { "examples": { "missing_or_invalid_bulk_reference_id": { "summary": "Missing or invalid bulk_reference_id", "value": { "response_status_id": 1, "code": "Bad request, please check API documentation", "response_type_id": 1, "type": "validation_error", "message": "Bad request, please check API documentation", "status": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unknown or expired bulk_reference_id", "content": { "application/json": { "examples": { "unknown_or_expired_bulk_reference_id": { "summary": "Unknown or expired bulk_reference_id", "value": { "status": 1, "message": "No batch found for the supplied bulk_reference_id" } } } } } } } } }, "/tools/kyc/gstin": { "post": { "operationId": "verifyGstin", "summary": "GST Verification", "description": "The GST Verification API validates a GSTIN against official government records and returns the full registration profile: legal and trade names, taxpayer type, constitution of business, nature of activities, registration and last-update dates, state and centre jurisdiction, and the principal place of address (both as a flat string and as structured address components). Designed for KYB, vendor/merchant onboarding, compliance due diligence, and high-volume B2B verification pipelines.", "tags": [ "GST Verification" ], "x-docs-slug": "verify-gstin", "x-eko-trxn-type-id": 815, "x-eko-product-code": 755, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "gstin": { "description": "The GSTIN that was verified, echoed back from the government source.", "example": "29ABCDE1234F1Z5", "type": "string" }, "valid": { "description": "True if the GSTIN was found and is a valid registered number; false otherwise.", "example": true, "type": "boolean" }, "gst_in_status": { "description": "Current registration status of the GSTIN (e.g. Active, Cancelled, Suspended).", "example": "Active", "type": "string" }, "legal_name_of_business": { "description": "Official legal name of the business as registered with GST authorities.", "example": "Acme Private Limited", "type": "string" }, "taxpayer_type": { "description": "Classification of the taxpayer (e.g. Regular, Composition, Non-resident, Casual Taxable Person).", "example": "Regular", "type": "string" }, "constitution_of_business": { "description": "Legal structure / constitution of the business (e.g. Private Limited Company, Proprietorship, Partnership).", "example": "Private Limited Company", "type": "string" }, "date_of_registration": { "description": "Date on which the GSTIN was registered (DD/MM/YYYY format).", "example": "01/07/2017", "type": "string" }, "last_update_date": { "description": "Date of the most recent update to the GST registration record (DD/MM/YYYY format).", "example": "01/02/2022", "type": "string" }, "cancellation_date": { "description": "Date of cancellation of the GST registration, if applicable. Empty string or null for active registrations.", "example": "", "type": "string" }, "nature_of_business_activities": { "description": "Comma-separated list of business activity categories as declared during GST registration (e.g. Wholesale, Supplier of Services, Recipient of Goods or Services).", "example": "Wholesale, Supplier of Services, Recipient of Goods or Services", "type": "string" }, "state_jurisdiction": { "description": "State GST authority / jurisdiction under which the GSTIN is registered.", "example": "Karnataka", "type": "string" }, "center_jurisdiction": { "description": "Central GST authority / jurisdictional commissionerate for the registered business.", "example": "Commissionerate of Central Tax, Bangalore", "type": "string" }, "principal_place_address": { "description": "Principal place of business address as a single formatted string.", "example": "123, MG Road, Bangalore, Karnataka 560001", "type": "string" }, "principal_place_split_address": { "description": "Principal place of business address broken into structured components.", "type": "object", "properties": { "flat_number": { "description": "Flat, door, or unit number.", "example": "123", "type": "string" }, "building_name": { "description": "Name of the building or premises.", "example": "MG Towers", "type": "string" }, "street": { "description": "Street or road name.", "example": "MG Road", "type": "string" }, "location": { "description": "Locality or neighbourhood identifier.", "example": "Bangalore", "type": "string" }, "city": { "description": "City name.", "example": "Bangalore", "type": "string" }, "district": { "description": "District name.", "example": "Bangalore Urban", "type": "string" }, "state": { "description": "State name.", "example": "Karnataka", "type": "string" }, "pincode": { "description": "Postal / ZIP code.", "example": "560001", "type": "string" }, "latitude": { "description": "Geographic latitude of the principal place of business.", "example": 12.9716, "type": "number" }, "longitude": { "description": "Geographic longitude of the principal place of business.", "example": 77.5946, "type": "number" } } }, "additional_address_array": { "description": "Array of additional registered places of business. Each element has the same structure as principal_place_split_address plus a flat address string.", "type": "array", "items": { "type": "object", "properties": { "flat_number": { "description": "Flat, door, or unit number of the additional address.", "example": "B-201", "type": "string" }, "building_name": { "description": "Building name of the additional address.", "example": "Trade Centre", "type": "string" }, "street": { "description": "Street of the additional address.", "example": "Ring Road", "type": "string" }, "location": { "description": "Locality of the additional address.", "example": "Whitefield", "type": "string" }, "city": { "description": "City of the additional address.", "example": "Bangalore", "type": "string" }, "district": { "description": "District of the additional address.", "example": "Bangalore Urban", "type": "string" }, "state": { "description": "State of the additional address.", "example": "Karnataka", "type": "string" }, "pincode": { "description": "Pincode of the additional address.", "example": "560066", "type": "string" } } } }, "message": { "description": "Verification result message from the data source.", "example": "GSTIN verification successful", "type": "string" }, "status_code": { "description": "Internal status code from the upstream GST data source.", "example": 1, "type": "number" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "GSTIN verification successful", "response_type_id": 1388, "data": { "gstin": "29ABCDE1234F1Z5", "valid": true, "gst_in_status": "Active", "legal_name_of_business": "Acme Private Limited", "taxpayer_type": "Regular", "constitution_of_business": "Private Limited Company", "date_of_registration": "01/07/2017", "last_update_date": "01/02/2022", "cancellation_date": "", "nature_of_business_activities": "Wholesale, Supplier of Services, Recipient of Goods or Services", "state_jurisdiction": "Karnataka", "center_jurisdiction": "Commissionerate of Central Tax, Bangalore", "principal_place_address": "123, MG Road, Bangalore, Karnataka 560001", "principal_place_split_address": { "flat_number": "123", "building_name": "MG Towers", "street": "MG Road", "location": "Bangalore", "city": "Bangalore", "district": "Bangalore Urban", "state": "Karnataka", "pincode": "560001", "latitude": 12.9716, "longitude": 77.5946 }, "additional_address_array": [], "message": "GSTIN verification successful", "status_code": 1 } } }, "gstin_not_found_does_not_exist_in_government_records": { "summary": "GSTIN not found / does not exist in government records", "value": { "status": 1, "response_status_id": 1, "message": "GSTIN doesn't exist", "response_type_id": 1388, "data": { "valid": false, "gst_in_status": "" } } } } } } }, "400": { "description": "Missing required field (gstin or business_name not supplied)", "content": { "application/json": { "examples": { "missing_required_field_gstin_or_business_name_not_supplied": { "summary": "Missing required field (gstin or business_name not supplied)", "value": { "status": 1, "response_status_id": -1, "message": "Bad request: required parameter missing", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "gstin": { "type": "string", "description": "Goods and Services Tax Identification Number of the business to verify (15-character alphanumeric).", "example": "29AAICP2912R1ZR" }, "business_name": { "type": "string", "description": "Name of the business associated with the GSTIN (max 100 characters). Used for cross-reference in the verification response.", "example": "Acme Pvt Ltd" } }, "required": [ "initiator_id", "gstin", "business_name" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "gstin": "29AAICP2912R1ZR", "business_name": "Acme Pvt Ltd" } } } } } }, "/tools/kyc/gstin-with-pan": { "post": { "operationId": "gstinWithPan", "summary": "Fetch GSTINs by PAN", "description": "The GSTIN with PAN API accepts a PAN (Permanent Account Number) and returns a list of all GSTIN registrations associated with that PAN across every Indian state and union territory. Each entry in the list includes the GSTIN, its active/inactive status, and the state of registration. Ideal for identifying all GST registrations of a counterparty, detecting multi-state business presence, and de-duplicating vendor or merchant records during onboarding.", "tags": [ "GST Verification" ], "x-docs-slug": "gstin-with-pan", "x-eko-trxn-type-id": 820, "x-eko-product-code": 760, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "pan": { "description": "The PAN submitted in the request, echoed back for reference.", "example": "ABCDE1234F", "type": "string" }, "gstin_list": { "description": "List of all GSTIN registrations linked to the given PAN. Each element represents one GST registration across a state.", "type": "array", "items": { "type": "object", "properties": { "gstin": { "description": "A GSTIN number associated with the PAN.", "example": "29ABCDE1234F1Z5", "type": "string" }, "status": { "description": "Current registration status of this GSTIN (e.g. Active, Inactive, Cancelled).", "example": "Active", "type": "string" }, "state": { "description": "Indian state or union territory where this GSTIN is registered.", "example": "Maharashtra", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "GSTIN fetch successful", "response_type_id": 1388, "data": { "pan": "ABCDE1234F", "gstin_list": [ { "gstin": "29ABCDE1234F1Z5", "status": "Active", "state": "Maharashtra" }, { "gstin": "27ABCDE1234F1Z2", "status": "Inactive", "state": "Karnataka" } ] } } }, "no_gstins_found_for_the_given_pan": { "summary": "No GSTINs found for the given PAN", "value": { "status": 1, "response_status_id": 1, "message": "No GSTIN found for the provided PAN", "response_type_id": 1388, "data": { "pan": "ABCDE1234F", "gstin_list": [] } } } } } } }, "400": { "description": "Invalid PAN format", "content": { "application/json": { "examples": { "invalid_pan_format": { "summary": "Invalid PAN format", "value": { "status": 1, "response_status_id": -1, "message": "Bad request: invalid PAN format", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "pan_number": { "type": "string", "description": "10-character alphanumeric PAN of the business or individual (5 letters, 4 digits, 1 letter).", "example": "DUMPY1001A", "pattern": "^[A-Z]{5}\\d{4}[A-Z]$" } }, "required": [ "initiator_id", "pan_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "pan_number": "DUMPY1001A" } } } } } }, "/customer/payment/upi/validate-vpa": { "post": { "operationId": "upiValidateVpa", "summary": "UPI ID (VPA) Verification", "description": "Confirms whether a UPI ID (VPA) is active and returns the verified recipient name and registered mobile number. Use this before initiating any UPI transfer to reduce wrong-payee failures and payment fraud.", "tags": [ "UPI ID (VPA) Verification" ], "x-docs-slug": "upi-validate-vpa", "x-eko-trxn-type-id": 744, "x-eko-product-code": 687, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "vpa": { "description": "The validated UPI Virtual Payment Address (VPA / UPI ID) exactly as registered.", "example": "rajesh.kumar@okicici", "type": "string" }, "valid": { "description": "Whether the VPA is active and valid. true = valid VPA; false = invalid or inactive.", "example": true, "type": "boolean" }, "recipient_name": { "description": "Verified payee name as returned by the UPI network — use this for name-match checks before payment.", "example": "Rajesh Kumar", "type": "string" }, "mobile_number": { "description": "Registered mobile number linked to the VPA.", "example": "9876543210", "type": "string" }, "transaction_id": { "description": "Unique transaction / verification request ID generated by Eko's system for audit and support reference.", "example": "3560508954", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "VPA validation successful", "response_type_id": 1388, "data": { "vpa": "rajesh.kumar@okicici", "valid": true, "recipient_name": "Rajesh Kumar", "mobile_number": "9876543210", "transaction_id": "3560508954" } } }, "invalid_or_non_existent_vpa": { "summary": "Invalid or non-existent VPA", "value": { "status": 1, "response_status_id": 1, "message": "VPA is invalid or does not exist", "response_type_id": 1388, "data": { "vpa": "invalid.user@okicici", "valid": false, "recipient_name": null, "mobile_number": null, "transaction_id": "3560508955" } } }, "user_retailer_not_found": { "summary": "User (retailer) not found", "value": { "status": 1, "response_status_id": 463, "message": "User not found", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "customer_vpa": { "type": "string", "description": "The UPI Virtual Payment Address (VPA / UPI ID) to validate, e.g. rajesh.kumar@okicici.", "example": "rajesh.kumar@okicici" }, "recipient_mobile": { "type": "string", "description": "Mobile number of the recipient linked to the VPA, used for additional verification.", "example": "9876543210" }, "name": { "type": "string", "description": "Name of the recipient as expected — returned for match validation against the bank-verified payee name.", "example": "Rajesh Kumar" }, "latlong": { "type": "string", "description": "Geo-coordinates of the request origination point (latitude,longitude).", "example": "28.6139,77.2090", "pattern": "^-?\\d{1,3}(\\.\\d+)?,-?\\d{1,3}(\\.\\d+)?$" } }, "required": [ "initiator_id", "customer_vpa", "recipient_mobile", "name", "latlong" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "customer_vpa": "rajesh.kumar@okicici", "recipient_mobile": "9876543210", "name": "Rajesh Kumar", "latlong": "28.6139,77.2090" } } } } } }, "/tools/kyc/driving-license": { "post": { "operationId": "drivingLicense", "summary": "Driving License Verification", "description": "The Driving License Verification API validates a DL number against government records and returns structured identity and entitlement data including the holder's name, father/husband name, date of birth, address, license validity windows (transport and non-transport), class of vehicle (COV) details, and badge information. Ideal for KYC, driver onboarding, and compliance workflows.", "tags": [ "Driving Licence Verification" ], "x-docs-slug": "driving-license", "x-eko-trxn-type-id": 826, "x-eko-product-code": 765, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "dl_number": { "description": "The driving license number that was verified.", "example": "KA0120198900984", "type": "string" }, "dob": { "description": "Date of birth of the DL holder as returned by the authority.", "example": "1994-08-05", "type": "string" }, "status": { "description": "Overall status of the driving license (e.g. Active, Suspended, Expired).", "example": "Active", "type": "string" }, "details_of_driving_licence": { "description": "Core identity and administrative details extracted from the DL record.", "type": "object", "properties": { "name": { "description": "Full name of the driving license holder.", "example": "Rajesh Kumar", "type": "string" }, "father_or_husband_name": { "description": "Father's or husband's name as recorded on the DL.", "example": "Suresh Kumar", "type": "string" }, "date_of_issue": { "description": "Date the driving license was originally issued (YYYY-MM-DD).", "example": "2019-03-15", "type": "string" }, "date_of_last_transaction": { "description": "Date of the most recent administrative transaction on the license.", "example": "2023-01-10", "type": "string" }, "last_transacted_at": { "description": "RTO or office where the last transaction was processed.", "example": "Mumbai RTO", "type": "string" }, "status": { "description": "Status of the DL as returned in the detailed record (mirrors top-level status).", "example": "Active", "type": "string" }, "address_list": { "description": "List of addresses associated with the DL holder.", "type": "array", "items": { "type": "object", "properties": { "complete_address": { "description": "Full address string as recorded on the DL.", "example": "123, Andheri West, Mumbai, Maharashtra - 400053", "type": "string" }, "type": { "description": "Address type, e.g. permanent or temporary.", "example": "permanent", "type": "string" }, "split_address": { "description": "Address broken into components (street, city, state, pincode) when available.", "type": "object" } } } }, "address": { "description": "Single-string address fallback when address_list is unavailable.", "example": "123, Andheri West, Mumbai", "type": "string" }, "photo": { "description": "Base64-encoded photograph of the DL holder as stored in the authority's database.", "example": "/9j/4AAQSkZJRgAB...", "type": "string" }, "cov_details": { "description": "Class of Vehicle (COV) entitlement records — each entry lists a vehicle class and associated validity.", "type": "array", "items": { "type": "object", "properties": { "cov": { "description": "Vehicle class code, e.g. LMV, MCWG, TRANS.", "example": "LMV", "type": "string" }, "issue_date": { "description": "Date the COV entitlement was granted.", "example": "2019-03-15", "type": "string" } } } } } }, "dl_validity": { "description": "Validity windows for transport and non-transport license categories.", "type": "object", "properties": { "non_transport": { "description": "Validity period for non-transport (personal) vehicle authorisation.", "type": "object", "properties": { "from": { "description": "Non-transport validity start date (YYYY-MM-DD).", "example": "2019-03-15", "type": "string" }, "to": { "description": "Non-transport validity end date (YYYY-MM-DD).", "example": "2039-03-14", "type": "string" } } }, "transport": { "description": "Validity period for transport (commercial) vehicle authorisation.", "type": "object", "properties": { "from": { "description": "Transport validity start date (YYYY-MM-DD).", "example": "2019-03-15", "type": "string" }, "to": { "description": "Transport validity end date (YYYY-MM-DD).", "example": "2024-03-14", "type": "string" } } }, "hazardous_valid_till": { "description": "Date until which the hazardous-goods endorsement is valid, if applicable.", "example": "2024-03-14", "type": "string" }, "hill_valid_till": { "description": "Date until which the hill-driving endorsement is valid, if applicable.", "example": "2024-03-14", "type": "string" } } }, "badge_details": { "description": "Badge/transport endorsement records, each describing a permitted vehicle class group.", "type": "array", "items": { "type": "object", "properties": { "badge_no": { "description": "Badge number assigned by the transport authority.", "example": "MH-BADGE-001", "type": "string" }, "badge_issue_date": { "description": "Date the badge was issued.", "example": "2019-03-15", "type": "string" }, "class_of_vehicle": { "description": "List of vehicle classes covered under this badge (e.g. LMV, MCWG, TRANS).", "example": [ "LMV", "MCWG" ], "type": "array", "items": {} } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "DL verification successful", "response_type_id": 1388, "data": { "dl_number": "MH0220190001234", "dob": "1994-08-29", "status": "Active", "details_of_driving_licence": { "name": "Rajesh Kumar", "father_or_husband_name": "Suresh Kumar", "date_of_issue": "2019-03-15", "date_of_last_transaction": "2023-01-10", "last_transacted_at": "Mumbai RTO", "status": "Active", "address_list": [ { "complete_address": "123, Andheri West, Mumbai, Maharashtra - 400053", "type": "permanent", "split_address": {} } ], "address": "123, Andheri West, Mumbai", "photo": "/9j/4AAQSkZJRgAB...", "cov_details": [ { "cov": "LMV", "issue_date": "2019-03-15" }, { "cov": "MCWG", "issue_date": "2019-03-15" } ] }, "dl_validity": { "non_transport": { "from": "2019-03-15", "to": "2039-03-14" }, "transport": { "from": "2019-03-15", "to": "2024-03-14" }, "hazardous_valid_till": null, "hill_valid_till": null }, "badge_details": [ { "badge_no": "MH-BADGE-001", "badge_issue_date": "2019-03-15", "class_of_vehicle": [ "LMV", "MCWG" ] } ] } } }, "dl_number_not_found_in_government_records": { "summary": "DL number not found in government records", "value": { "status": 1, "response_status_id": 463, "message": "No record found for the provided DL number", "response_type_id": 1388, "data": {} } }, "dob_mismatch_provided_dob_does_not_match_authority_records": { "summary": "DOB mismatch — provided DOB does not match authority records", "value": { "status": 1, "response_status_id": 1, "message": "Date of birth does not match DL records", "response_type_id": 1388, "data": {} } }, "invalid_dl_number_format": { "summary": "Invalid DL number format", "value": { "status": 1, "response_status_id": 1, "message": "Invalid driving license number format", "response_type_id": 1388, "data": {} } }, "upstream_authority_service_temporarily_unavailable": { "summary": "Upstream authority service temporarily unavailable", "value": { "status": 1, "response_status_id": 1, "message": "Source unavailable. Please try again.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "dl_number": { "type": "string", "description": "Driving license number to verify (e.g. KA0120198900984).", "example": "KA0120198900984" }, "dob": { "type": "string", "description": "Date of birth of the DL holder in YYYY-MM-DD format. Used to cross-validate the license.", "example": "1994-08-05", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "initiator_id", "dl_number", "dob" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "dl_number": "KA0120198900984", "dob": "1994-08-05" } } } } } }, "/tools/kyc/vehicle-rc": { "post": { "operationId": "vehicleRc", "summary": "Vehicle & RC Verification", "description": "Send a vehicle registration number and receive a comprehensive RC dataset in a single API call. The response covers ownership (name, father's name, address), registration details (authority, dates, expiry), insurance (company, policy number, validity), compliance (blacklist, challan, PUCC, emission norms), commercial-vehicle specifics (permit type/validity, national permit, tax status), and financier information. Pan-India coverage via the VAHAN database makes it suitable for driver onboarding, fleet monitoring, motor insurance underwriting, vehicle finance, and used-car platforms. Source (VAHAN) data typically reflects real-world changes within 15–30 days.", "tags": [ "Vehicle & RC Verification" ], "x-docs-slug": "vehicle-rc", "x-eko-trxn-type-id": 824, "x-eko-product-code": 764, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "reference_id": { "description": "Unique reference ID for this verification request returned by Eko.", "example": "34247643", "type": "string" }, "status": { "description": "Verification status string (e.g. 'Active', 'Inactive').", "example": "Active", "type": "string" }, "reg_no": { "description": "Vehicle registration number as recorded in the VAHAN database.", "example": "HR26DA8398", "type": "string" }, "rc_status": { "description": "Current RC status — 'Active', 'Inactive', 'Suspended', etc.", "example": "Active", "type": "string" }, "status_as_on": { "description": "Date on which the RC status was last updated.", "example": "2024-01-01", "type": "string" }, "owner": { "description": "Full name of the registered owner of the vehicle.", "example": "Arya Sharma", "type": "string" }, "owner_father_name": { "description": "Father's name of the registered owner.", "example": "Rajesh Sharma", "type": "string" }, "owner_count": { "description": "Number of previous owners, including the current one.", "example": 1, "type": "number" }, "present_address": { "description": "Present address of the owner as a single string.", "example": "123, Sector 45, Gurgaon, Haryana 122003", "type": "string" }, "split_present_address": { "description": "Present address broken into structured components.", "type": "object", "properties": { "house_flat_number": { "description": "House/flat number.", "example": "123", "type": "string" }, "street": { "description": "Street or locality.", "example": "Sector 45", "type": "string" }, "city": { "description": "City name.", "example": "Gurgaon", "type": "string" }, "state": { "description": "State name.", "example": "Haryana", "type": "string" }, "pincode": { "description": "PIN code.", "example": "122003", "type": "string" } } }, "permanent_address": { "description": "Permanent address of the owner as a single string.", "example": "456, MG Road, Gurgaon, Haryana 122001", "type": "string" }, "split_permanent_address": { "description": "Permanent address broken into structured components.", "type": "object", "properties": { "house_flat_number": { "description": "House/flat number.", "example": "456", "type": "string" }, "street": { "description": "Street or locality.", "example": "MG Road", "type": "string" }, "city": { "description": "City name.", "example": "Gurgaon", "type": "string" }, "state": { "description": "State name.", "example": "Haryana", "type": "string" }, "pincode": { "description": "PIN code.", "example": "122001", "type": "string" } } }, "reg_authority": { "description": "Regional Transport Office (RTO) that issued the RC.", "example": "HR-26 Gurgaon", "type": "string" }, "reg_date": { "description": "Date of first registration of the vehicle (YYYY-MM-DD).", "example": "2020-06-15", "type": "string" }, "rc_expiry_date": { "description": "RC validity expiry date (YYYY-MM-DD). Private vehicles are typically 15 years from registration.", "example": "2039-06-14", "type": "string" }, "class": { "description": "Vehicle class as registered with the RTO (e.g. 'Motor Car', 'LMV', 'HTV').", "example": "Motor Car", "type": "string" }, "vehicle_category": { "description": "High-level vehicle category (e.g. 'LMV', 'HMV', 'M-Cycle').", "example": "LMV", "type": "string" }, "type": { "description": "Ownership type — 'Private' or 'Commercial'.", "example": "Private", "type": "string" }, "is_commercial": { "description": "True if the vehicle is registered for commercial use.", "example": false, "type": "boolean" }, "vehicle_manufacturer_name": { "description": "Manufacturer / make of the vehicle.", "example": "Mahindra & Mahindra", "type": "string" }, "model": { "description": "Vehicle model name.", "example": "XUV300", "type": "string" }, "body_type": { "description": "Body type of the vehicle (e.g. 'Hard Top', 'Open Body', 'Tipper').", "example": "Hard Top", "type": "string" }, "vehicle_color": { "description": "Color of the vehicle as registered.", "example": "Dark Grey", "type": "string" }, "fuel_type": { "description": "Fuel type — 'Petrol', 'Diesel', 'CNG', 'Electric', etc.", "example": "Petrol", "type": "string" }, "norms_type": { "description": "Emission standard the vehicle complies with (e.g. 'Bharat Stage VI').", "example": "Bharat Stage VI", "type": "string" }, "emission_norms": { "description": "Human-readable emission norms label returned in some responses.", "example": "Bharat Stage VI", "type": "string" }, "chassis": { "description": "Chassis number of the vehicle as per RC.", "example": "MA1TE2ELXLM123456", "type": "string" }, "engine": { "description": "Engine number of the vehicle as per RC.", "example": "N10A1234567", "type": "string" }, "vehicle_manufacturing_month_year": { "description": "Month and year of vehicle manufacture.", "example": "May 2020", "type": "string" }, "vehicle_cubic_capacity": { "description": "Engine cubic capacity in cc.", "example": "1497", "type": "string" }, "vehicle_cylinders_no": { "description": "Number of cylinders in the engine.", "example": "4", "type": "string" }, "vehicle_seat_capacity": { "description": "Seating capacity of the vehicle.", "example": "5", "type": "string" }, "vehicle_sleeper_capacity": { "description": "Sleeper capacity (relevant for transport/bus vehicles).", "example": "0", "type": "string" }, "vehicle_standing_capacity": { "description": "Standing capacity (relevant for buses).", "example": "0", "type": "string" }, "gross_vehicle_weight": { "description": "Gross vehicle weight in kg.", "example": "1680", "type": "string" }, "unladen_weight": { "description": "Unladen (kerb) weight of the vehicle in kg.", "example": "1230", "type": "string" }, "wheelbase": { "description": "Wheelbase of the vehicle in mm.", "example": "2600", "type": "string" }, "vehicle_insurance_company_name": { "description": "Name of the insurance company that issued the current motor policy.", "example": "Tata AIG General Insurance", "type": "string" }, "vehicle_insurance_policy_number": { "description": "Insurance policy number.", "example": "0165274682", "type": "string" }, "vehicle_insurance_upto": { "description": "Insurance validity date (YYYY-MM-DD). Check against today to flag lapsed policies.", "example": "2025-06-14", "type": "string" }, "rc_financer": { "description": "Name of the financier / lending institution if the vehicle is under a loan.", "example": "HDFC Bank Ltd", "type": "string" }, "vehicle_tax_upto": { "description": "Road tax validity date.", "example": "2024-06-14", "type": "string" }, "pucc_number": { "description": "Pollution Under Control Certificate (PUCC) number.", "example": "DL-EW-123456", "type": "string" }, "pucc_upto": { "description": "PUCC validity date.", "example": "2024-12-31", "type": "string" }, "blacklist_status": { "description": "Whether the vehicle appears on a blacklist — 'Not Blacklisted' or 'Blacklisted'.", "example": "Not Blacklisted", "type": "string" }, "blacklist_details": { "description": "Detailed blacklist information; populated only if the vehicle is blacklisted.", "type": "object", "properties": { "reason": { "description": "Reason for blacklisting.", "example": "Unpaid challan", "type": "string" }, "authority": { "description": "Authority that issued the blacklist order.", "example": "RTO Gurgaon", "type": "string" } } }, "challan_details": { "description": "Pending traffic challan information, if any.", "type": "object", "properties": { "challan_no": { "description": "Challan number.", "example": "CH20240001", "type": "string" }, "amount": { "description": "Challan amount in INR.", "example": "2000", "type": "string" }, "status": { "description": "Challan payment status.", "example": "Pending", "type": "string" } } }, "noc_details": { "description": "No Objection Certificate details, if applicable.", "example": null, "type": "string" }, "non_use_status": { "description": "Indicates if the vehicle has been declared 'non-use'.", "example": null, "type": "string" }, "non_use_from": { "description": "Start date of the non-use period, if applicable.", "example": null, "type": "string" }, "non_use_to": { "description": "End date of the non-use period, if applicable.", "example": null, "type": "string" }, "permit_number": { "description": "State permit number (commercial vehicles only).", "example": "HR/P/2021/00123", "type": "string" }, "permit_type": { "description": "Type of permit — e.g. 'Tourist', 'Contract Carriage', 'Goods'.", "example": "Tourist", "type": "string" }, "permit_issue_date": { "description": "Date on which the permit was issued.", "example": "2021-03-01", "type": "string" }, "permit_valid_from": { "description": "Permit validity start date.", "example": "2021-03-01", "type": "string" }, "permit_valid_upto": { "description": "Permit validity end date.", "example": "2026-02-28", "type": "string" }, "national_permit_number": { "description": "National permit number for goods/transport vehicles operating across states.", "example": "NP/HR/2021/00456", "type": "string" }, "national_permit_upto": { "description": "National permit validity date.", "example": "2026-02-28", "type": "string" }, "national_permit_issued_by": { "description": "State authority that issued the national permit.", "example": "HR-26 Gurgaon", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Vehicle RC verification successful", "response_type_id": 1388, "data": { "reference_id": "EKO-RC-9876543210-001", "status": "Active", "reg_no": "HR26DA8398", "rc_status": "Active", "status_as_on": "2024-01-01", "owner": "Arya Sharma", "owner_father_name": "Rajesh Sharma", "owner_count": 1, "mobile_number": "98XXXXXXXX", "present_address": "123, Sector 45, Gurgaon, Haryana 122003", "split_present_address": { "house_flat_number": "123", "street": "Sector 45", "city": "Gurgaon", "state": "Haryana", "pincode": "122003" }, "permanent_address": "456, MG Road, Gurgaon, Haryana 122001", "split_permanent_address": { "house_flat_number": "456", "street": "MG Road", "city": "Gurgaon", "state": "Haryana", "pincode": "122001" }, "reg_authority": "HR-26 Gurgaon", "reg_date": "2020-06-15", "rc_expiry_date": "2039-06-14", "class": "Motor Car", "vehicle_category": "LMV", "type": "Private", "is_commercial": false, "vehicle_manufacturer_name": "Mahindra & Mahindra", "model": "XUV300", "body_type": "Hard Top", "vehicle_color": "Dark Grey", "fuel_type": "Petrol", "norms_type": "Bharat Stage VI", "emission_norms": "Bharat Stage VI", "chassis": "MA1TE2ELXLM123456", "engine": "N10A1234567", "vehicle_manufacturing_month_year": "May 2020", "vehicle_cubic_capacity": "1497", "vehicle_cylinders_no": "4", "vehicle_seat_capacity": "5", "vehicle_sleeper_capacity": "0", "vehicle_standing_capacity": "0", "gross_vehicle_weight": "1680", "unladen_weight": "1230", "wheelbase": "2600", "vehicle_insurance_company_name": "Tata AIG General Insurance", "vehicle_insurance_policy_number": "0165274682", "vehicle_insurance_upto": "2025-06-14", "rc_financer": "HDFC Bank Ltd", "vehicle_tax_upto": "2024-06-14", "pucc_number": "DL-EW-123456", "pucc_upto": "2024-12-31", "blacklist_status": "Not Blacklisted", "blacklist_details": {}, "challan_details": {}, "noc_details": null, "non_use_status": null, "non_use_from": null, "non_use_to": null, "permit_number": null, "permit_type": null, "permit_issue_date": null, "permit_valid_from": null, "permit_valid_upto": null, "national_permit_number": null, "national_permit_upto": null, "national_permit_issued_by": null } } }, "invalid_or_unrecognised_vehicle_number": { "summary": "Invalid or unrecognised vehicle number", "value": { "status": 1, "response_status_id": 1, "message": "Vehicle number not found in VAHAN database", "response_type_id": 1388, "data": {} } }, "missing_required_parameter_vehicle_number_not_supplied": { "summary": "Missing required parameter (vehicle_number not supplied)", "value": { "status": 1, "response_status_id": 1, "message": "vehicle_number is required", "response_type_id": 1388, "data": {} } }, "vahan_source_temporarily_unavailable": { "summary": "VAHAN source temporarily unavailable", "value": { "status": 1, "response_status_id": 1, "message": "Source temporarily unavailable. Please try again.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "vehicle_number": { "type": "string", "description": "Vehicle registration number to verify (e.g. HJ01ME5678).", "example": "HJ01ME5678" } }, "required": [ "initiator_id", "vehicle_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "vehicle_number": "HJ01ME5678" } } } } } }, "/tools/kyc/advance-employment": { "post": { "operationId": "advanceEmployment", "summary": "Employee Verification (Advance)", "description": "Returns a rich, nested profile linked to the employee's Universal Account Number (UAN): basic identity details (name, gender, DOB, Aadhaar link), full employment history per UAN (member ID, establishment, joining/exit dates, leave reason), additional PII (PAN, bank account, email), and a structured recent-employment block that includes EPFO filing health, employer setup date, ownership type, and monthly PF contribution records. Designed for pre-employment checks, lending underwriting, and HR compliance workflows.", "tags": [ "Employee Verification" ], "x-docs-slug": "advance-employment", "x-eko-trxn-type-id": 830, "x-eko-product-code": 769, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "input": { "description": "Echo of the input parameters sent in the request.", "example": {}, "type": "object" }, "uan_details": { "description": "List of UAN records associated with the employee's phone number. One entry per UAN.", "type": "array", "items": { "type": "object", "properties": { "uan": { "description": "Universal Account Number assigned to the employee by EPFO.", "example": "1001234567890", "type": "string" }, "source": { "description": "Data source from which the UAN record was fetched.", "example": "EPFO", "type": "string" }, "source_score": { "description": "Confidence score of the data source match (0–100).", "example": 95, "type": "number" }, "basic_details": { "description": "Core identity details of the employee linked to this UAN.", "type": "object", "properties": { "employee_name": { "description": "Full name of the employee as registered with EPFO.", "example": "Rajesh Kumar", "type": "string" }, "gender": { "description": "Gender of the employee.", "example": "Male", "type": "string" }, "dob": { "description": "Date of birth of the employee in YYYY-MM-DD format.", "example": "1994-08-29", "type": "string" }, "phone": { "description": "Phone number linked to this UAN.", "example": "9876543210", "type": "string" }, "aadhaar_verified": { "description": "Whether the employee's Aadhaar is linked and verified against this UAN.", "example": false, "type": "boolean" }, "employee_confidence_score": { "description": "Model confidence score for the employee identity match (0–100).", "example": 88, "type": "number" } } }, "employment_details": { "description": "Employment record associated with this UAN entry.", "type": "object", "properties": { "member_id": { "description": "PF Member ID for this employment record (state/region/establishment/account format).", "example": "MH/BOM/12345/000/0000001", "type": "string" }, "establishment_id": { "description": "EPFO establishment ID of the employer.", "example": "MHBAN0012345000", "type": "string" }, "establishment_name": { "description": "Name of the employer/establishment as registered with EPFO.", "example": "Acme Pvt Ltd", "type": "string" }, "joining_date": { "description": "Date the employee joined this establishment (YYYY-MM-DD).", "example": "2019-04-01", "type": "string" }, "exit_date": { "description": "Date the employee exited this establishment (YYYY-MM-DD). Null if currently employed.", "example": "2023-06-30", "type": "string" }, "leave_reason": { "description": "Reason for exit as recorded in EPFO (e.g., Resignation, Superannuation).", "example": "Resignation", "type": "string" }, "employer_confidence_score": { "description": "Confidence score for the employer identity match (0–100).", "example": 90, "type": "number" } } }, "additional_details": { "description": "Supplementary PII and financial details linked to the UAN (may be partially populated).", "type": "object", "properties": { "pan": { "description": "PAN number linked to the employee.", "example": "ABCDE1234F", "type": "string" }, "aadhaar": { "description": "Masked or partial Aadhaar number.", "example": "XXXX-XXXX-1234", "type": "string" }, "email": { "description": "Email address linked to the UAN.", "example": "rajesh.kumar@example.com", "type": "string" }, "ifsc": { "description": "IFSC code of the linked bank account.", "example": "HDFC0001234", "type": "string" }, "bank_account": { "description": "Masked bank account number linked to the UAN.", "example": "XXXX1234", "type": "string" }, "bank_address": { "description": "Address of the linked bank branch.", "example": "HDFC Bank, Andheri West, Mumbai", "type": "string" }, "relative_name": { "description": "Name of the declared relative/nominee.", "example": "Sunita Kumar", "type": "string" }, "relation": { "description": "Relationship of the nominee to the employee.", "example": "Spouse", "type": "string" } } } } } }, "recent_employment_details": { "description": "Structured summary of the most recent employment, including EPFO health indicators and employer PF filing history.", "type": "object", "properties": { "employee_details": { "description": "Latest employment record for the employee with EPFO flags.", "type": "object", "properties": { "uan": { "description": "UAN for the most recent employment.", "example": "1001234567890", "type": "string" }, "member_id": { "description": "PF Member ID for the most recent establishment.", "example": "MH/BOM/12345/000/0000001", "type": "string" }, "joining_date": { "description": "Joining date for the most recent employment (YYYY-MM-DD).", "example": "2019-04-01", "type": "string" }, "exit_date": { "description": "Exit date for the most recent employment (YYYY-MM-DD). Null if currently active.", "example": "2023-06-30", "type": "string" }, "employed": { "description": "Whether the employee is currently active in this establishment per EPFO records.", "example": false, "type": "boolean" }, "exit_date_marked": { "description": "Whether the employer has formally marked an exit date in EPFO.", "example": true, "type": "boolean" }, "employee_name_match": { "description": "Whether the name in EPFO matches the name provided or derived from the phone lookup.", "example": true, "type": "boolean" }, "epfo": { "description": "EPFO-level flags indicating data quality and filing health.", "type": "object", "properties": { "recent": { "description": "Whether EPFO data for this employee was recently updated.", "example": true, "type": "boolean" }, "name_unique": { "description": "Whether the employee's name appears uniquely in EPFO (no duplicates).", "example": true, "type": "boolean" }, "pf_filings_details": { "description": "Whether PF filing details are available for this employee.", "example": true, "type": "boolean" } } } } }, "employer_details": { "description": "Details of the most recent employer including setup date, ownership type, and monthly PF contribution history.", "type": "object", "properties": { "establishment_id": { "description": "EPFO establishment ID of the most recent employer.", "example": "MHBAN0012345000", "type": "string" }, "establishment_name": { "description": "Name of the most recent employer as registered with EPFO.", "example": "Acme Pvt Ltd", "type": "string" }, "setup_date": { "description": "Date the employer establishment was set up/registered with EPFO.", "example": "2005-03-15", "type": "string" }, "ownership_type": { "description": "Ownership type of the establishment (e.g., Private, Government, Public Sector).", "example": "Private", "type": "string" }, "employer_confidence_score": { "description": "Model confidence score for employer identity resolution (0–100).", "example": 90, "type": "number" }, "employer_name_match": { "description": "Whether the resolved employer name matches the expected employer name.", "example": true, "type": "boolean" }, "pf_filing_details": { "description": "Monthly PF contribution records filed by the employer. Each entry represents one wage month.", "type": "array", "items": { "type": "object", "properties": { "wage_month": { "description": "The wage month for this PF filing entry (YYYY-MM format).", "example": "2023-05", "type": "string" }, "total_amount": { "description": "Total PF amount contributed by the employer for this wage month.", "example": 1800, "type": "number" }, "employees_count": { "description": "Number of employees covered under this PF filing for the wage month.", "example": 120, "type": "number" } } } } } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Employee verification successful", "response_type_id": 1388, "data": { "input": { "phone": "9876543210" }, "uan_details": [ { "uan": "1001234567890", "source": "EPFO", "source_score": 95, "basic_details": { "employee_name": "Rajesh Kumar", "gender": "Male", "dob": "1994-08-29", "phone": "9876543210", "aadhaar_verified": false, "employee_confidence_score": 88 }, "employment_details": { "member_id": "MH/BOM/12345/000/0000001", "establishment_id": "MHBAN0012345000", "establishment_name": "Acme Pvt Ltd", "joining_date": "2019-04-01", "exit_date": "2023-06-30", "leave_reason": "Resignation", "employer_confidence_score": 90 }, "additional_details": { "pan": "ABCDE1234F", "aadhaar": "XXXX-XXXX-1234", "email": "rajesh.kumar@example.com", "ifsc": "HDFC0001234", "bank_account": "XXXX1234", "bank_address": "HDFC Bank, Andheri West, Mumbai", "relative_name": "Sunita Kumar", "relation": "Spouse" } } ], "recent_employment_details": { "employee_details": { "uan": "1001234567890", "member_id": "MH/BOM/12345/000/0000001", "joining_date": "2019-04-01", "exit_date": "2023-06-30", "employed": false, "exit_date_marked": true, "employee_name_match": true, "epfo": { "recent": true, "name_unique": true, "pf_filings_details": true } }, "employer_details": { "establishment_id": "MHBAN0012345000", "establishment_name": "Acme Pvt Ltd", "setup_date": "2005-03-15", "ownership_type": "Private", "employer_confidence_score": 90, "employer_name_match": true, "pf_filing_details": [ { "wage_month": "2023-05", "total_amount": 1800, "employees_count": 120 }, { "wage_month": "2023-04", "total_amount": 1800, "employees_count": 118 }, { "wage_month": "2023-03", "total_amount": 1750, "employees_count": 115 } ] } } } } }, "phone_number_not_linked_to_any_uan_in_epfo_records": { "summary": "Phone number not linked to any UAN in EPFO records", "value": { "status": 1, "response_status_id": -1, "message": "No UAN found for the provided phone number", "response_type_id": 1388, "data": { "uan_details": [], "recent_employment_details": null } } }, "missing_required_parameter_phone": { "summary": "Missing required parameter (phone)", "value": { "status": 1, "response_status_id": -1, "message": "phone is required", "response_type_id": 1388, "data": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "phone": { "type": "string", "description": "Employee's registered mobile number used to look up UAN records from EPFO.", "example": "9876543210" } }, "required": [ "initiator_id", "phone" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "phone": "9876543210" } } } } } }, "/tools/kyc/reverse-geocoding": { "post": { "operationId": "reverseGeocoding", "summary": "Reverse Geocoding", "description": "The Reverse Geocoding API translates GPS coordinates into a human-readable, structured address. It is designed for address validation during onboarding, geo-compliance checks, field-agent location verification, and location-based fraud detection workflows. Pass a latitude/longitude pair and receive a normalised address broken down by locality, city, district, state, PIN code, and country — along with a confidence score.", "tags": [ "Reverse Geocoding" ], "x-docs-slug": "reverse-geocoding", "x-eko-trxn-type-id": 832, "x-eko-product-code": 771, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "latitude": { "description": "Echo of the latitude coordinate supplied in the request.", "example": "19.0760", "type": "string" }, "longitude": { "description": "Echo of the longitude coordinate supplied in the request.", "example": "72.8777", "type": "string" }, "address": { "description": "Full formatted street address resolved from the coordinates.", "example": "6/B Mahatyagi Road, Chhatrapati Shivaji Terminus", "type": "string" }, "city": { "description": "City name derived from the coordinates.", "example": "Mumbai", "type": "string" }, "state": { "description": "Full state name derived from the coordinates.", "example": "Maharashtra", "type": "string" }, "statecode": { "description": "Two-letter ISO / RTO state code.", "example": "MH", "type": "string" }, "countrycode": { "description": "Two-letter ISO 3166-1 alpha-2 country code.", "example": "IN", "type": "string" }, "pincode": { "description": "Indian 6-digit PIN code for the resolved location.", "example": "400001", "type": "string" }, "score": { "description": "Geocoding confidence score between 0 and 1; higher values indicate a more precise address match.", "example": 0.95, "type": "number" }, "status": { "description": "Status of the coordinate resolution (e.g. 'OK').", "example": "OK", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Reverse geocoding successful", "response_type_id": 1388, "data": { "latitude": "19.0760", "longitude": "72.8777", "address": "6/B Mahatyagi Road, Chhatrapati Shivaji Terminus", "city": "Mumbai", "state": "Maharashtra", "statecode": "MH", "countrycode": "IN", "pincode": "400001", "score": 0.95, "status": "OK" } } }, "invalid_or_out_of_range_coordinates": { "summary": "Invalid or out-of-range coordinates", "value": { "status": 1, "response_status_id": -1, "message": "Invalid latitude or longitude value", "response_type_id": 1388, "data": {} } }, "missing_required_parameter_latitude_or_longitude_omitted": { "summary": "Missing required parameter (latitude or longitude omitted)", "value": { "status": 1, "response_status_id": -1, "message": "Required parameter missing", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "latitude": { "type": "string", "description": "Geolocation latitude of the point to resolve (decimal degrees).", "example": "19.0760" }, "longitude": { "type": "string", "description": "Geolocation longitude of the point to resolve (decimal degrees).", "example": "72.8777" } }, "required": [ "initiator_id", "latitude", "longitude" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "latitude": "19.0760", "longitude": "72.8777" } } } } } }, "/tools/kyc/voter-id": { "post": { "operationId": "voterId", "summary": "Voter ID Verification", "description": "The Voter ID Verification API lets you verify an Electoral Photo Identity Card (EPIC) number against government electoral rolls. A single POST call returns the cardholder's full identity profile — name (English and regional language), date of birth, gender, guardian details, structured address, assembly and parliamentary constituency, and polling station — making it suitable for KYC, onboarding, and compliance workflows.", "tags": [ "Voter ID Verification" ], "x-docs-slug": "voter-id", "x-eko-trxn-type-id": 827, "x-eko-product-code": 766, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "name": { "description": "Cardholder's full name as recorded on the voter ID.", "example": "Rajesh Kumar", "type": "string" }, "name_in_regional_lang": { "description": "Cardholder's name in the regional/vernacular script.", "example": "राजेश कुमार", "type": "string" }, "age": { "description": "Age of the cardholder as per voter roll records.", "example": "34", "type": "string" }, "dob": { "description": "Date of birth in YYYY-MM-DD format.", "example": "1994-08-29", "type": "string" }, "gender": { "description": "Gender of the cardholder.", "example": "Male", "type": "string" }, "father_name": { "description": "Father's name as on the voter record.", "example": "Suresh Kumar", "type": "string" }, "relation_type": { "description": "Relationship type of the guardian (e.g., Father, Husband).", "example": "Father", "type": "string" }, "relation_name": { "description": "Guardian's name corresponding to the relation_type.", "example": "Suresh Kumar", "type": "string" }, "relation_name_in_regional_lang": { "description": "Guardian's name in the regional/vernacular script.", "example": "सुरेश कुमार", "type": "string" }, "epic_number": { "description": "The EPIC number that was verified.", "example": "ABC1234567", "type": "string" }, "address": { "description": "Full address string as recorded in the electoral roll.", "example": "Ward 12, Sector 5, Noida", "type": "string" }, "state": { "description": "State name corresponding to the voter's registered address.", "example": "Uttar Pradesh", "type": "string" }, "split_address": { "description": "Parsed address broken into individual components.", "type": "object", "properties": { "district": { "description": "District(s) extracted from the address.", "example": [ "Gautam Buddha Nagar" ], "type": "array", "items": {} }, "city": { "description": "City/town(s) extracted from the address.", "example": [ "Noida" ], "type": "array", "items": {} }, "state": { "description": "State(s) extracted from the address (may be nested arrays).", "example": [ [ "Uttar Pradesh" ] ], "type": "array", "items": {} }, "pincode": { "description": "PIN code extracted from the address.", "example": "201301", "type": "string" }, "country": { "description": "Country extracted from the address.", "example": [ "India" ], "type": "array", "items": {} }, "address_line": { "description": "Full address reassembled as a single line.", "example": "Ward 12, Sector 5, Noida, Gautam Buddha Nagar, Uttar Pradesh - 201301", "type": "string" } } }, "assembly_constituency": { "description": "Name of the assembly constituency (Vidhan Sabha) for the voter.", "example": "Noida (62)", "type": "string" }, "assembly_constituency_number": { "description": "Numerical code of the assembly constituency.", "example": "62", "type": "string" }, "parliamentary_constituency": { "description": "Name of the parliamentary constituency (Lok Sabha) for the voter.", "example": "Gautam Buddha Nagar", "type": "string" }, "parliamentary_constituency_number": { "description": "Numerical code of the parliamentary constituency.", "example": "47", "type": "string" }, "part_number": { "description": "Part/section number of the electoral roll in which the voter is listed.", "example": "142", "type": "string" }, "part_name": { "description": "Name of the electoral roll part/section.", "example": "Sector 5 Ward", "type": "string" }, "serial_number": { "description": "Serial number of the voter within the electoral roll part.", "example": "312", "type": "string" }, "polling_station": { "description": "Name and/or location of the designated polling station.", "example": "Govt. School Noida Sec 5", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Voter ID verification successful", "response_type_id": 1388, "data": { "name": "Rajesh Kumar", "name_in_regional_lang": "राजेश कुमार", "age": "34", "dob": "1994-08-29", "gender": "Male", "father_name": "Suresh Kumar", "relation_type": "Father", "relation_name": "Suresh Kumar", "relation_name_in_regional_lang": "सुरेश कुमार", "epic_number": "ABC1234567", "address": "Ward 12, Sector 5, Noida", "state": "Uttar Pradesh", "split_address": { "district": [ "Gautam Buddha Nagar" ], "city": [ "Noida" ], "state": [ [ "Uttar Pradesh" ] ], "pincode": "201301", "country": [ "India" ], "address_line": "Ward 12, Sector 5, Noida, Gautam Buddha Nagar, Uttar Pradesh - 201301" }, "assembly_constituency": "Noida (62)", "assembly_constituency_number": "62", "parliamentary_constituency": "Gautam Buddha Nagar", "parliamentary_constituency_number": "47", "part_number": "142", "part_name": "Sector 5 Ward", "serial_number": "312", "polling_station": "Govt. School Noida Sec 5" } } }, "invalid_or_non_existent_epic_number": { "summary": "Invalid or non-existent EPIC number", "value": { "status": 1, "response_status_id": -1, "message": "No record found for the provided EPIC number", "response_type_id": 1388, "data": {} } }, "missing_required_parameter_epic_number": { "summary": "Missing required parameter (epic_number)", "value": { "status": 1, "response_status_id": -1, "message": "epic_number is required", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "epic_number": { "type": "string", "description": "Unique Electoral Photo Identity Card (EPIC) number to verify.", "example": "UAI4574761" } }, "required": [ "initiator_id", "epic_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "epic_number": "UAI4574761" } } } } } }, "/tools/kyc/passport": { "post": { "operationId": "passportApplication", "summary": "Passport Application Validation", "description": "The Passport Application Validation API enables businesses to validate passport holder details using passport file number and date of birth. Returns holder name, DOB, application type, and application received date — suitable for KYC, employee background verification, travel compliance, and fintech onboarding workflows. Supports Indian passports only; not an OCR or MRZ scan API.", "tags": [ "Passport Application Validation" ], "x-docs-slug": "passport-application", "x-eko-trxn-type-id": 828, "x-eko-product-code": 767, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "file_number": { "description": "Unique alphanumeric code identifying the passport application, echoed back from the source.", "example": "J8369854", "type": "string" }, "name": { "description": "Full name of the passport holder as recorded in the government source.", "example": "Rajesh Kumar", "type": "string" }, "dob": { "description": "Date of birth of the passport holder (YYYY-MM-DD) as registered in the passport application.", "example": "1994-08-29", "type": "string" }, "application_type": { "description": "Type of passport application (e.g. Normal, Tatkal). Indicates the application category used when the passport was applied for.", "example": "Normal", "type": "string" }, "application_received_date": { "description": "Date on which the passport application was received by the issuing authority (YYYY-MM-DD format).", "example": "2023-01-15", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Passport verification successful", "response_type_id": 1388, "data": { "file_number": "J8369854", "name": "Rajesh Kumar", "dob": "1994-08-29", "application_type": "Normal", "application_received_date": "2023-01-15" } } }, "invalid_or_non_existent_passport_file_number_dob_mismatch": { "summary": "Invalid or non-existent passport file number / DOB mismatch", "value": { "status": 1, "response_status_id": 1, "message": "Passport details not found. Please verify the file number and date of birth.", "response_type_id": 1388, "data": {} } } } } } }, "400": { "description": "Missing required field (file_number or dob not supplied)", "content": { "application/json": { "examples": { "missing_required_field_file_number_or_dob_not_supplied": { "summary": "Missing required field (file_number or dob not supplied)", "value": { "status": 1, "response_status_id": -1, "message": "Bad request: required parameter missing", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "file_number": { "type": "string", "description": "Unique alphanumeric code that identifies an individual's passport application (passport file number).", "example": "PA1000000000001" }, "dob": { "type": "string", "description": "Date of birth of the passport holder in YYYY-MM-DD format.", "example": "1994-08-29", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "name": { "type": "string", "description": "Name of the passport holder. Optional — used for cross-checking in certain verification flows.", "example": "Rajesh Kumar" } }, "required": [ "initiator_id", "file_number", "dob" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "file_number": "PA1000000000001", "dob": "1994-08-29", "name": "Rajesh Kumar" } } } } } }, "/tools/kyc/cin": { "post": { "operationId": "cin", "summary": "CIN Verification", "description": "The CIN Verification API lets you validate a Company Identification Number (CIN) against Ministry of Corporate Affairs records in real time. It returns the registered company name, registration number, incorporation date, CIN status (active / struck-off / dormant / under liquidation), company email, country of incorporation, and a full list of directors with their DIN, designation, address, and date of birth. Use it for KYB onboarding, vendor due diligence, lending workflows, and corporate compliance checks.", "tags": [ "CIN Verification" ], "x-docs-slug": "cin", "x-eko-trxn-type-id": 829, "x-eko-product-code": 768, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "cin": { "description": "The CIN submitted in the request, echoed back for confirmation.", "example": "U72900KA2015PTC082988", "type": "string" }, "company_name": { "description": "MCA-registered legal name of the company.", "example": "Acme Technologies Pvt Ltd", "type": "string" }, "registration_number": { "description": "Numeric company registration number assigned by the Registrar of Companies.", "example": 82987, "type": "number" }, "incorporation_date": { "description": "Date the company was incorporated, in YYYY-MM-DD format.", "example": "2015-09-23", "type": "string" }, "cin_status": { "description": "Current status of the CIN as recorded by MCA — e.g. Active, Strike-Off, Dormant, Under Liquidation.", "example": "Active", "type": "string" }, "email": { "description": "Company email address from MCA records.", "example": "contact@acmetech.in", "type": "string" }, "incorporation_country": { "description": "Country in which the company was incorporated.", "example": "India", "type": "string" }, "director_details": { "description": "List of directors of the company as registered with MCA.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Full legal name of the director.", "example": "Rahul Mehta", "type": "string" }, "din": { "description": "Director Identification Number (DIN) allotted by MCA.", "example": "07168822", "type": "string" }, "designation": { "description": "Role/designation of the director at the company.", "example": "Director", "type": "string" }, "dob": { "description": "Date of birth of the director, in YYYY-MM-DD format.", "example": "1985-03-12", "type": "string" }, "address": { "description": "Registered address of the director as filed with MCA.", "example": "123 MG Road, Bengaluru, Karnataka 560001", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "CIN verification successful", "response_type_id": 1388, "data": { "cin": "U72900KA2015PTC082988", "company_name": "Acme Technologies Pvt Ltd", "registration_number": 82987, "incorporation_date": "2015-09-23", "cin_status": "Active", "email": "contact@acmetech.in", "incorporation_country": "India", "director_details": [ { "name": "Rahul Mehta", "din": "07168822", "designation": "Director", "dob": "1985-03-12", "address": "123 MG Road, Bengaluru, Karnataka 560001" }, { "name": "Priya Sharma", "din": "07168826", "designation": "Director", "dob": "1988-07-25", "address": "45 Residency Road, Bengaluru, Karnataka 560025" } ] } } }, "invalid_or_malformed_cin": { "summary": "Invalid or malformed CIN", "value": { "status": 1, "response_status_id": -1, "message": "Invalid CIN. Please provide a valid 21-character CIN.", "response_type_id": 1388, "data": null } }, "cin_not_found_in_mca_records": { "summary": "CIN not found in MCA records", "value": { "status": 1, "response_status_id": -1, "message": "No records found for the provided CIN.", "response_type_id": 1388, "data": null } }, "missing_required_body_parameter_cin": { "summary": "Missing required body parameter (cin)", "value": { "status": 1, "response_status_id": -1, "message": "cin is required.", "response_type_id": 1388, "data": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "cin": { "type": "string", "description": "Alphanumeric Company Identification Number (CIN) assigned by the Ministry of Corporate Affairs, India.", "example": "U72900KA2015PTC082988" } }, "required": [ "initiator_id", "cin" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "cin": "U72900KA2015PTC082988" } } } } } }, "/tools/kyc/ip": { "post": { "operationId": "ip", "summary": "IP Verification", "description": "Submit any IPv4 address to receive its geolocation (country, region, city), proxy/VPN classification, and dual risk scores (city-level and proxy-type). Use inline during transactions for fraud prevention and geo-compliance enforcement.", "tags": [ "IP Verification" ], "x-docs-slug": "ip", "x-eko-trxn-type-id": 831, "x-eko-product-code": 770, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "ip_address": { "description": "The IP address that was submitted for verification.", "example": "103.21.58.193", "type": "string" }, "proxy_type": { "description": "Classification of the connection type (e.g. None, VPN, DCH for data-centre hosting, RES for residential proxy, etc.).", "example": "None", "type": "string" }, "country_code": { "description": "ISO 3166-1 alpha-2 country code for the IP address.", "example": "IN", "type": "string" }, "country_name": { "description": "Full country name corresponding to the country code.", "example": "India", "type": "string" }, "region_name": { "description": "State or region within the country where the IP is geolocated.", "example": "Maharashtra", "type": "string" }, "city_name": { "description": "City within the region where the IP is geolocated.", "example": "Mumbai", "type": "string" }, "city_risk_score": { "description": "Risk score (0–100) for the geolocated city, based on cybersecurity threat intelligence and historical crime/fraud data for that city. Higher scores indicate greater risk.", "example": "12", "type": "string" }, "proxy_type_risk_score": { "description": "Risk score (0–100) for the detected proxy type. A score of 0 means a clean residential or direct connection; higher scores indicate proxy/VPN or data-centre traffic associated with fraud.", "example": "0", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "IP verification successful", "response_type_id": 1388, "data": { "ip_address": "103.21.58.193", "proxy_type": "None", "country_code": "IN", "country_name": "India", "region_name": "Maharashtra", "city_name": "Mumbai", "city_risk_score": "12", "proxy_type_risk_score": "0" } } }, "invalid_or_malformed_ip_address_supplied": { "summary": "Invalid or malformed IP address supplied", "value": { "status": 1, "response_status_id": -1, "message": "Invalid IP address", "data": {} } }, "missing_required_parameter_ip_address": { "summary": "Missing required parameter ip_address", "value": { "status": 1, "response_status_id": -1, "message": "ip_address is required", "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "ip_address": { "type": "string", "description": "The IPv4 address to verify. Must be a valid, routable IP address.", "example": "103.21.58.193" } }, "required": [ "initiator_id", "ip_address" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "ip_address": "103.21.58.193" } } } } } }, "/tools/kyc/name-match": { "post": { "operationId": "nameMatch", "summary": "Name Match API", "description": "Name Match is an AI-powered name comparison API built for India's complex naming conventions. Trained on over 100 million Indian name records, it handles initials, abbreviations, phonetic and regional spelling variants, salutation patterns (S/O, D/O), subset matching, and name ordering variations — returning a numeric score and match category that let you set rule-based pass/fail thresholds.", "tags": [ "Name Match" ], "x-docs-slug": "name-match", "x-eko-trxn-type-id": 833, "x-eko-product-code": 772, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "name_1": { "description": "The first name string as submitted in the request.", "example": "S K Mishra", "type": "string" }, "name_2": { "description": "The second name string as submitted in the request.", "example": "Satish Kumar Mishra", "type": "string" }, "score": { "description": "Numeric match score between 0 and 1. Thresholds: 1.0 = Direct Match; 0.85–0.99 = Good Partial Match; 0.60–0.84 = Moderate Partial Match; 0.34–0.59 = Poor Partial Match; 0.00–0.33 = No Match.", "example": 0.92, "type": "number" }, "reason": { "description": "Human-readable explanation of the match result — effectively the match category label along with the AI model's rationale (e.g. initials expansion, phonetic match, subset match).", "example": "Names match with initials expanded", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Name match successful", "response_type_id": 1388, "data": { "name_1": "S K Mishra", "name_2": "Satish Kumar Mishra", "score": 0.92, "reason": "Names match with initials expanded" } } }, "one_or_both_name_parameters_missing_or_empty": { "summary": "One or both name parameters missing or empty", "value": { "status": 1, "response_status_id": -1, "message": "name_1 and name_2 are required fields.", "response_type_id": 1388, "data": {} } }, "no_match_names_are_unrelated_score_0_33": { "summary": "No match — names are unrelated (score ≤ 0.33)", "value": { "status": 0, "response_status_id": 0, "message": "Name match successful", "response_type_id": 1388, "data": { "name_1": "Ramesh Gupta", "name_2": "Priya Sharma", "score": 0.05, "reason": "Names do not match" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "name_1": { "type": "string", "description": "First name string to compare (e.g. the name from a PAN card or bank record).", "example": "S K Mishra" }, "name_2": { "type": "string", "description": "Second name string to compare against name_1 (e.g. the name from an Aadhaar or GST record).", "example": "Satish Kumar Mishra" } }, "required": [ "initiator_id", "name_1", "name_2" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "name_1": "S K Mishra", "name_2": "Satish Kumar Mishra" } } } } } }, "/tools/kyc/itr-compliance": { "post": { "operationId": "itrCompliance", "summary": "ITR Compliance Check", "description": "The ITR Compliance Check API verifies whether a given PAN holder has filed income tax returns and returns their compliance status, ITR filing flag, and the relevant assessment year. It gives lenders, NBFCs, and compliance teams an instant signal of a borrower's or vendor's tax-filing behaviour without requiring manual document collection. A single PAN input is all that is needed — no document uploads or consent flows.", "tags": [ "ITR Compliance Check" ], "x-docs-slug": "itr-compliance", "x-eko-trxn-type-id": 1021, "x-eko-product-code": 798, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "pan_number": { "description": "The PAN number that was queried, echoed back from the source for confirmation.", "example": "ABCDE1234F", "type": "string" }, "itr_filed": { "description": "Indicates whether the PAN holder has filed an income tax return for the queried assessment year. true = filed; false = not filed.", "example": true, "type": "boolean" }, "assessment_year": { "description": "The income-tax assessment year for which the ITR status is reported (e.g. '2024-25' corresponds to FY 2023-24).", "example": "2024-25", "type": "string" }, "compliance_status": { "description": "Overall tax compliance standing of the PAN holder as returned by the authority (e.g. Compliant, Non-Compliant, Pending).", "example": "Compliant", "type": "string" }, "filing_status": { "description": "Granular ITR filing status string as returned by the source — may carry values such as 'Filed', 'Not Filed', 'Under Processing', or 'Defective'.", "example": "Filed", "type": "string" }, "filing_date": { "description": "Date on which the ITR was filed (YYYY-MM-DD), if available from the source.", "example": "2024-07-25", "type": "string" }, "acknowledgement_number": { "description": "ITR acknowledgement number issued by the Income Tax Department upon successful e-filing, if returned by the source.", "example": "123456789012345", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "ITR compliance check successful", "response_type_id": 1388, "data": { "pan_number": "ABCDE1234F", "itr_filed": true, "assessment_year": "2024-25", "compliance_status": "Compliant", "filing_status": "Filed", "filing_date": "2024-07-25", "acknowledgement_number": "123456789012345" } } }, "pan_not_found_in_income_tax_department_records": { "summary": "PAN not found in Income Tax Department records", "value": { "status": 1, "response_status_id": 463, "message": "No ITR record found for the provided PAN number", "response_type_id": 1388, "data": {} } }, "itr_not_filed_for_the_queried_assessment_year": { "summary": "ITR not filed for the queried assessment year", "value": { "status": 0, "response_status_id": 0, "message": "ITR compliance check successful", "response_type_id": 1388, "data": { "pan_number": "ABCDE1234F", "itr_filed": false, "assessment_year": "2024-25", "compliance_status": "Non-Compliant", "filing_status": "Not Filed" } } }, "invalid_pan_format_must_be_10_alphanumeric_characters_matching_aaaaa9999a_pattern": { "summary": "Invalid PAN format — must be 10 alphanumeric characters matching AAAAA9999A pattern", "value": { "status": 1, "response_status_id": 1, "message": "Invalid PAN number format", "response_type_id": 1388, "data": {} } }, "upstream_itr_source_temporarily_unavailable": { "summary": "Upstream ITR source temporarily unavailable", "value": { "status": 1, "response_status_id": 1, "message": "Source unavailable. Please try again.", "response_type_id": 1388, "data": {} } } } } } }, "400": { "description": "Missing required field — pan_number not supplied in the request body", "content": { "application/json": { "examples": { "missing_required_field_pan_number_not_supplied_in_the_request_body": { "summary": "Missing required field — pan_number not supplied in the request body", "value": { "status": 1, "response_status_id": -1, "message": "Bad request: pan_number is required", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "pan_number": { "type": "string", "description": "PAN number of the individual or entity to check for ITR compliance (10-character alphanumeric, e.g. ABCDE1234F).", "example": "ABCDE1234F", "pattern": "^[A-Z]{5}\\d{4}[A-Z]$" } }, "required": [ "initiator_id", "pan_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "pan_number": "ABCDE1234F" } } } } } }, "/tools/kyc/din-verification": { "post": { "operationId": "dinVerification", "summary": "DIN Verification", "description": "The DIN Verification API lets you validate a Director Identification Number (DIN) against Ministry of Corporate Affairs (MCA) records in real time. It returns the director's full name, current DIN status (Active / Deactivated / Surrendered), designation, and the associated company name. Use it for corporate KYB onboarding, director background checks, vendor due diligence, lending to corporate borrowers, and compliance workflows that require authoritative director-identity validation.", "tags": [ "DIN Verification" ], "x-docs-slug": "din-verification", "x-eko-trxn-type-id": 1025, "x-eko-product-code": 802, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "din": { "description": "The DIN submitted in the request, echoed back for confirmation.", "example": "06731826", "type": "string" }, "director_name": { "description": "Full legal name of the director as registered with MCA.", "example": "Abhishek Sagar", "type": "string" }, "din_status": { "description": "Current status of the DIN as recorded by MCA — e.g. Active, Deactivated, Surrendered, Disqualified.", "example": "Active", "type": "string" }, "designation": { "description": "Role or designation of the director as filed with MCA.", "example": "Director", "type": "string" }, "company_name": { "description": "Name of the company with which the director is associated, as recorded in MCA records.", "example": "Eko India Financial Services Pvt Ltd", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "DIN verification successful", "response_type_id": 1388, "data": { "din": "06731826", "director_name": "Abhishek Sagar", "din_status": "Active", "designation": "Director", "company_name": "Eko India Financial Services Pvt Ltd" } } }, "invalid_or_malformed_din_not_8_digits": { "summary": "Invalid or malformed DIN (not 8 digits)", "value": { "status": 1, "response_status_id": -1, "message": "Invalid DIN. Please provide a valid 8-digit DIN.", "response_type_id": 1388, "data": null } }, "din_not_found_in_mca_records": { "summary": "DIN not found in MCA records", "value": { "status": 1, "response_status_id": -1, "message": "No records found for the provided DIN.", "response_type_id": 1388, "data": null } }, "missing_required_body_parameter_din_number": { "summary": "Missing required body parameter (din_number)", "value": { "status": 1, "response_status_id": -1, "message": "din_number is required.", "response_type_id": 1388, "data": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "din_number": { "type": "string", "description": "The 8-digit Director Identification Number (DIN) assigned by the Ministry of Corporate Affairs to the individual director.", "example": "06731826" } }, "required": [ "initiator_id", "din_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "din_number": "06731826" } } } } } }, "/tools/kyc/e-challan": { "post": { "operationId": "eChallan", "summary": "E-Challan Verification", "description": "Send a vehicle registration number to the E-Challan Verification API and receive a complete list of pending traffic violations from the national e-challan system (Parivahan). The response includes each challan's unique number, offence description, fine amount, date of violation, payment status, and issuing state/authority. Use it to automate fleet compliance checks, assess driver risk during onboarding, support motor insurance underwriting, or surface challan data in used-vehicle platforms.", "tags": [ "E-Challan Verification" ], "x-docs-slug": "e-challan", "x-eko-trxn-type-id": 1036, "x-eko-product-code": 813, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "vehicle_number": { "description": "Registration number of the vehicle as echoed back from the source system.", "example": "MH02AB1234", "type": "string" }, "pending_challans": { "description": "Total count of pending (unpaid) challans found for the vehicle.", "example": 2, "type": "number" }, "total_fine_amount": { "description": "Aggregate fine amount in INR across all pending challans.", "example": 3500, "type": "number" }, "challans": { "description": "List of individual challan records. Each element represents one traffic violation.", "type": "array", "items": { "type": "object", "properties": { "challan_number": { "description": "Unique challan reference number issued by the traffic authority.", "example": "MH2024001234", "type": "string" }, "challan_id": { "description": "Internal challan ID in the national e-challan system.", "example": "EC20241001", "type": "string" }, "violation": { "description": "Description of the traffic offence (e.g. 'Overspeeding', 'Red Light Jump', 'No Helmet').", "example": "Overspeeding", "type": "string" }, "date": { "description": "Date on which the violation was recorded (YYYY-MM-DD).", "example": "2024-12-10", "type": "string" }, "fine": { "description": "Fine amount in INR for this individual challan.", "example": 2000, "type": "number" }, "status": { "description": "Payment status of the challan — typically 'Pending' or 'Paid'.", "example": "Pending", "type": "string" }, "state": { "description": "State in which the challan was issued.", "example": "Maharashtra", "type": "string" }, "issuing_authority": { "description": "Traffic police unit or RTO that issued the challan.", "example": "Mumbai Traffic Police", "type": "string" }, "payment_source": { "description": "Payment channel through which the fine can be paid (e.g. 'Online', 'Court').", "example": "Online", "type": "string" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "E-Challan check successful", "response_type_id": 1388, "data": { "vehicle_number": "MH02AB1234", "pending_challans": 2, "total_fine_amount": 3500, "challans": [ { "challan_number": "MH2024001234", "challan_id": "EC20241210", "violation": "Overspeeding", "date": "2024-12-10", "fine": 2000, "status": "Pending", "state": "Maharashtra", "issuing_authority": "Mumbai Traffic Police", "payment_source": "Online" }, { "challan_number": "MH2024000987", "challan_id": "EC20241105", "violation": "Red Light Jump", "date": "2024-11-05", "fine": 1500, "status": "Pending", "state": "Maharashtra", "issuing_authority": "Mumbai Traffic Police", "payment_source": "Online" } ] } } }, "vehicle_registration_number_not_found_in_the_national_e_challan_system": { "summary": "Vehicle registration number not found in the national e-challan system", "value": { "status": 1, "response_status_id": 1, "message": "No records found for the given registration number", "response_type_id": 1388, "data": {} } }, "missing_required_parameter_registration_number_not_supplied": { "summary": "Missing required parameter — registration_number not supplied", "value": { "status": 1, "response_status_id": 1, "message": "registration_number is required", "response_type_id": 1388, "data": {} } }, "no_pending_challans_found_for_the_vehicle_clean_record": { "summary": "No pending challans found for the vehicle (clean record)", "value": { "status": 0, "response_status_id": 0, "message": "E-Challan check successful", "response_type_id": 1388, "data": { "vehicle_number": "MH02AB1234", "pending_challans": 0, "total_fine_amount": 0, "challans": [] } } }, "e_challan_source_parivahan_temporarily_unavailable": { "summary": "E-challan source (Parivahan) temporarily unavailable", "value": { "status": 1, "response_status_id": 1, "message": "Source temporarily unavailable. Please try again.", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "registration_number": { "type": "string", "description": "Vehicle registration number to look up challans for (e.g. MH02AB1234).", "example": "MH02AB1234" } }, "required": [ "initiator_id", "registration_number" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "registration_number": "MH02AB1234" } } } } } }, "/tools/kyc/check-email": { "post": { "operationId": "checkEmail", "summary": "Email Verification", "description": "Validates whether an email address is genuine and deliverable by checking MX (mail exchange) records for the domain. Returns domain age in days, the resolved MX record list, and flags for validity and disposability — giving you the signals needed to block fake signups, catch typos, and assess account trust during onboarding.", "tags": [ "Email Verification" ], "x-docs-slug": "check-email", "x-eko-trxn-type-id": 1032, "x-eko-product-code": 809, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "email": { "description": "The email address that was checked, echoed back for confirmation.", "example": "rajesh.kumar@example.com", "type": "string" }, "domain": { "description": "Domain portion of the email address (part after @). Used to anchor all domain-level checks.", "example": "example.com", "type": "string" }, "is_valid": { "description": "Whether the email address is valid and deliverable. true = domain has live MX records and can receive mail; false = domain has no mail server or is otherwise undeliverable.", "example": true, "type": "boolean" }, "is_disposable": { "description": "Whether the email domain belongs to a known disposable / temporary email provider. true = disposable (high fraud risk); false = regular email domain.", "example": false, "type": "boolean" }, "domain_age_days": { "description": "Age of the email domain in days since registration. Newly created domains (< 30 days) are a strong fraud signal; legitimate email providers have domains that are years old.", "example": 6970, "type": "number" }, "mx_records": { "description": "List of MX (mail exchange) hostnames discovered for the domain, ordered by priority. An empty array means the domain cannot receive email.", "example": [ "aspmx.l.google.com", "alt1.aspmx.l.google.com", "alt2.aspmx.l.google.com", "alt3.aspmx.l.google.com", "alt4.aspmx.l.google.com" ], "type": "array", "items": {} } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "Email verification successful", "response_type_id": 1388, "data": { "email": "rajesh.kumar@example.com", "domain": "example.com", "is_valid": true, "is_disposable": false, "domain_age_days": 6970, "mx_records": [ "aspmx.l.google.com", "alt1.aspmx.l.google.com", "alt2.aspmx.l.google.com", "alt3.aspmx.l.google.com", "alt4.aspmx.l.google.com" ] } } }, "invalid_email_domain_has_no_mx_records_or_does_not_exist": { "summary": "Invalid email — domain has no MX records or does not exist", "value": { "status": 1, "response_status_id": 1, "message": "Email verification failed — domain has no mail server", "response_type_id": 1388, "data": { "email": "test@nonexistentdomain12345.xyz", "domain": "nonexistentdomain12345.xyz", "is_valid": false, "is_disposable": false, "domain_age_days": null, "mx_records": [] } } }, "disposable_temporary_email_address_detected": { "summary": "Disposable / temporary email address detected", "value": { "status": 0, "response_status_id": 0, "message": "Email verification successful", "response_type_id": 1388, "data": { "email": "temp123@mailinator.com", "domain": "mailinator.com", "is_valid": true, "is_disposable": true, "domain_age_days": 7300, "mx_records": [ "mail.mailinator.com" ] } } }, "user_retailer_not_found": { "summary": "User (retailer) not found", "value": { "status": 1, "response_status_id": 463, "message": "User not found", "response_type_id": 1388, "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "email": { "type": "string", "description": "The email address to verify, e.g. rajesh.kumar@example.com.", "example": "rajesh.kumar@example.com" } }, "required": [ "initiator_id", "email" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "email": "rajesh.kumar@example.com" } } } } } }, "/tools/kyc/fetch-fssai": { "post": { "operationId": "fetchFssai", "summary": "FSSAI License Verification", "description": "Validates a Food Safety and Standards Authority of India (FSSAI) license number and returns the registered food business operator (FBO) details — name, address, license category, status, and expiry date. Use for food marketplace onboarding, delivery platform compliance, and food safety regulatory audits.", "tags": [ "FSSAI License Verification" ], "x-docs-slug": "fetch-fssai", "x-eko-trxn-type-id": 1024, "x-eko-product-code": 801, "x-eko-uat-unavailable": true, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": true }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "fssai_number": { "description": "The FSSAI license number that was queried.", "example": "11521998000045", "type": "string" }, "license_status": { "description": "Current status of the FSSAI license — Active, Expired, Suspended, or Cancelled.", "example": "Active", "type": "string" }, "license_category": { "description": "Category of the FSSAI license — Registration, State License, or Central License — reflecting the scale of the food business.", "example": "State License", "type": "string" }, "business_name": { "description": "Registered name of the food business operator (FBO) as on the FSSAI license.", "example": "Spice Garden Restaurant", "type": "string" }, "address": { "description": "Registered business address of the FBO as on the FSSAI license.", "example": "123 Main Street, Mumbai, Maharashtra", "type": "string" }, "state": { "description": "Indian state in which the food business is registered.", "example": "Maharashtra", "type": "string" }, "pincode": { "description": "6-digit PIN code of the registered business address.", "example": "400001", "type": "string" }, "expiry_date": { "description": "License validity expiry date in YYYY-MM-DD format. Use to flag expired or soon-to-expire licenses.", "example": "2026-03-15", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "message": "FSSAI verification successful", "response_type_id": 1388, "data": { "fssai_number": "11521998000045", "license_status": "Active", "license_category": "State License", "business_name": "Spice Garden Restaurant", "address": "123 Main Street, Mumbai, Maharashtra", "state": "Maharashtra", "pincode": "400001", "expiry_date": "2026-03-15" } } }, "invalid_or_non_existent_fssai_license_number": { "summary": "Invalid or non-existent FSSAI license number", "value": { "status": 1, "response_status_id": 1, "message": "Invalid FSSAI license number", "response_type_id": 1388, "data": {} } }, "expired_fssai_license_license_found_but_no_longer_valid": { "summary": "Expired FSSAI license — license found but no longer valid", "value": { "status": 0, "response_status_id": 0, "message": "FSSAI verification successful", "response_type_id": 1388, "data": { "fssai_number": "10012345000012", "license_status": "Expired", "license_category": "State License", "business_name": "Old Dhaba Pvt Ltd", "address": "45 Ring Road, Delhi", "state": "Delhi", "pincode": "110001", "expiry_date": "2023-08-31" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "fssai": { "type": "string", "description": "FSSAI license number of the food business operator (FBO) to verify. Typically 14 digits.", "example": "11521998000045" } }, "required": [ "initiator_id", "fssai" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "fssai": "11521998000045" } } } } } }, "/tools/kyc/mobile/otp": { "post": { "operationId": "mobileOtpSend", "summary": "Send OTP", "description": "Triggers an OTP SMS to the supplied mobile number and returns a transaction id plus the OTP expiry timestamp. The customer enters the OTP, which you confirm with the Verify OTP API. By default the SMS is sent with the **Eko India** sender signature; to use your own Sender ID and template, complete telecom DLT registration (see below).", "tags": [ "Mobile/OTP Verification" ], "x-docs-slug": "mobile-otp-send", "x-eko-trxn-type-id": 553, "x-eko-product-code": 525, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": true, "sideEffects": [ "sends-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "client_ref_id": { "description": "Unique reference id for this OTP request, echoed back.", "example": "211101129871", "type": "string" }, "initiator_id": { "description": "Registered mobile number of the API user that initiated the call.", "example": "1234567891", "type": "string" }, "otp_expiry_timestamp": { "description": "Timestamp until which the OTP stays valid. Verify before this time.", "example": "Fri May 22 16:04:04 IST 2026", "type": "string" }, "tid": { "description": "Unique transaction id for this OTP send, for tracking and support.", "example": "2886978474", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "response_type_id": 1623, "message": "OTP has been sent", "data": { "client_ref_id": "211101129871", "initiator_id": "1234567891", "otp_expiry_timestamp": "Fri May 22 16:04:04 IST 2026", "tid": "2886978474" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "csp_id": { "type": "string", "description": "Customer Service Point id of the agent/retailer the OTP is being sent on behalf of.", "example": "9002336768" }, "mobile": { "type": "string", "description": "Customer's 10-digit primary mobile number to send the OTP to.", "example": "9002336768", "pattern": "^[6-9]\\d{9}$" } }, "required": [ "initiator_id", "csp_id", "mobile" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "csp_id": "9002336768", "mobile": "9002336768" } } } } } }, "/tools/kyc/mobile/otp/verify": { "put": { "operationId": "mobileOtpVerify", "summary": "Verify OTP", "description": "Validates the OTP sent by the Send OTP API. On success (`status` = 0) it returns a signed JWT `otp_verification_token` containing the verified `mobile` and a unique token id. The token is valid for **5 minutes** and acts as proof that OTP verification was performed — pass it to any transaction that depends on a verified mobile, and use the Validate OTP-Verification-Token API to confirm its authenticity.", "tags": [ "Mobile/OTP Verification" ], "x-docs-slug": "mobile-otp-verify", "x-eko-trxn-type-id": 555, "x-eko-product-code": 527, "x-eko-semantics": { "readOnly": false, "idempotent": false, "billable": false, "sideEffects": [ "consumes-otp" ] }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "client_ref_id": { "description": "Unique reference id for this OTP flow, echoed back.", "example": "211101129871", "type": "string" }, "otp_verification_token": { "description": "Signed JWT proving the OTP was verified. Contains the verified mobile and a unique token id; valid for 5 minutes. Validate it with the Validate OTP-Verification-Token API.", "example": "eyJ0eXAiOiJKV1QiLCJ...5aXdrqrNcEbhfYfDsI", "type": "string" }, "initiator_id": { "description": "Registered mobile number of the API user that initiated the call.", "example": "1234567891", "type": "string" }, "mobile": { "description": "The mobile number that was verified.", "example": "9002336768", "type": "string" }, "tid": { "description": "Unique transaction id for this verification.", "example": "2886978475", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "response_type_id": 1632, "message": "OTP verification successful.", "data": { "client_ref_id": "211101129871", "otp_verification_token": "eyJ0eXAiOiJKV1QiLCJ...5aXdrqrNcEbhfYfDsI", "initiator_id": "1234567891", "mobile": "9002336768", "tid": "2886978475" } } }, "incorrect_or_expired_otp": { "summary": "Incorrect or expired OTP", "value": { "status": 1, "response_status_id": 1, "response_type_id": 1632, "message": "OTP verification failed.", "data": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initiator_id": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" }, "client_ref_id": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 }, "otp": { "type": "string", "description": "The OTP value the customer received via SMS from the Send OTP API. For UAT, the Send OTP API returns the OTP in the response for testing purposes; in production, the OTP is only sent via SMS.", "example": "" }, "mobile": { "type": "string", "description": "The same 10-digit mobile number the OTP was sent to.", "example": "9002336768", "pattern": "^[6-9]\\d{9}$" }, "otp_ref_id": { "type": "string", "description": "Reference id returned by the Send OTP API, used to track the OTP flow.", "example": "" } }, "required": [ "initiator_id", "otp", "mobile", "otp_ref_id" ] }, "example": { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "otp": "", "mobile": "9002336768", "otp_ref_id": "" } } } } } }, "/tools/kyc/mobile/otp/validate-token": { "get": { "operationId": "mobileOtpValidateToken", "summary": "Validate OTP-Verification-Token", "description": "Validates the authenticity of an `otp_verification_token` issued by the Verify OTP API, proving the OTP verification was actually performed within its 5-minute validity window. Returns `status` = 0 when the token is valid; a timed-out or tampered/invalid token returns `status` = 1 with a descriptive message.", "tags": [ "Mobile/OTP Verification" ], "x-docs-slug": "mobile-otp-validate-token", "x-eko-trxn-type-id": 1061, "x-eko-product-code": 829, "x-eko-semantics": { "readOnly": true, "idempotent": true, "billable": false }, "parameters": [ { "name": "developer_key", "in": "header", "required": true, "description": "Static API key issued to your account after KYC.", "schema": { "type": "string", "description": "Static API key issued to your account after KYC." } }, { "name": "secret-key", "in": "header", "required": true, "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).", "schema": { "type": "string", "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))." } }, { "name": "secret-key-timestamp", "in": "header", "required": true, "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.", "schema": { "type": "string", "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time." } }, { "name": "content-type", "in": "header", "required": true, "description": "application/json", "schema": { "type": "string", "description": "application/json", "example": "application/json" } }, { "name": "initiator_id", "in": "query", "required": true, "description": "Registered mobile number of the API user (see Platform Credentials).", "schema": { "type": "string", "description": "Registered mobile number of the API user (see Platform Credentials).", "example": "9962981729" } }, { "name": "client_ref_id", "in": "query", "required": false, "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "schema": { "type": "string", "description": "Unique reference ID per API call, generated by your system (10–20 characters; 10 recommended). The SDKs generate one for every non-GET call when you don't.", "example": "2026010100123456789", "pattern": "^[A-Za-z0-9_-]{1,20}$", "maxLength": 20 } }, { "name": "otp_verification_token", "in": "query", "required": true, "description": "The token returned by the Verify OTP API.", "schema": { "type": "string", "description": "The token returned by the Verify OTP API.", "example": "" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Primary success indicator (0 = success).", "example": 0, "type": "number" }, "message": { "description": "Human-readable response / error message.", "example": "Verification successful", "type": "string" }, "response_status_id": { "description": "UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented.", "example": 0, "type": "number" }, "response_type_id": { "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.", "example": 1388, "type": "number" }, "data": { "description": "API-specific response payload.", "type": "object", "properties": { "client_ref_id": { "description": "Unique reference id for the original OTP flow, echoed back.", "example": "211101129871", "type": "string" }, "otp_verification_token": { "description": "The token that was validated, echoed back.", "example": "eyJ0eXAiOiJKV1QiLCJ...5aXdrqrNcEbhfYfDsI", "type": "string" }, "initiator_id": { "description": "Registered mobile number of the API user that initiated the call.", "example": "1234567891", "type": "string" }, "mobile": { "description": "The mobile number the token certifies as verified.", "example": "9002336768", "type": "string" }, "tid": { "description": "Unique transaction id for this validation.", "example": "2886978475", "type": "string" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "status": 0, "response_status_id": 0, "response_type_id": 1633, "message": "OTP verification token is valid.", "data": { "client_ref_id": "211101129871", "otp_verification_token": "eyJ0eXAiOiJKV1QiLCJ...5aXdrqrNcEbhfYfDsI", "initiator_id": "1234567891", "mobile": "9002336768", "tid": "2886978475" } } }, "token_timed_out_older_than_5_minutes": { "summary": "Token timed out (older than 5 minutes)", "value": { "status": 1, "response_status_id": 1, "response_type_id": 1634, "message": "The OTP verification token has timed out." } }, "invalid_or_tampered_token": { "summary": "Invalid or tampered token", "value": { "status": 1, "response_status_id": 1, "response_type_id": 1634, "message": "The OTP verification token is invalid." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "externalDocs": { "url": "https://eps.eko.in/docs", "description": "Developer docs" }, "x-tagGroups": [ { "name": "Banking & Cash APIs", "tags": [ "Domestic Money Transfer (DMT)", "AePS Cashout" ] }, { "name": "Payments APIs", "tags": [ "Bharat Bill Payment System (BBPS)" ] }, { "name": "Verification APIs", "tags": [ "PAN Verification", "DigiLocker Integration", "Bank Account Verification", "GST Verification", "UPI ID (VPA) Verification", "Driving Licence Verification", "Vehicle & RC Verification", "Employee Verification", "Reverse Geocoding", "Voter ID Verification", "Passport Application Validation", "CIN Verification", "IP Verification", "Name Match", "ITR Compliance Check", "DIN Verification", "E-Challan Verification", "Email Verification", "FSSAI License Verification", "Mobile/OTP Verification" ] }, { "name": "Utility & Helper APIs", "tags": [ "User & Agent Management", "Transactions & Refunds", "Bank & IFSC" ] } ] }