{
"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. These\nare modeled as required header parameters, not a security scheme — a\ngenerated client cannot sign requests on its own. See /docs/how-auth-works."
},
"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": "PPI Wallet",
"description": "Prepaid (PPI) wallets — sender onboarding, Aadhaar KYC, wallet load & bank transfers (Levin & DigiKhata)"
},
{
"name": "User & Agent Management",
"description": "Onboard agents/retailers, manage their services, and check settlement balance"
},
{
"name": "Customer Management",
"description": "Rail-agnostic customer onboarding, lookup, and OTP verification"
},
{
"name": "Bharat Bill Payment System (BBPS)",
"description": "Bill payments for 25+ biller categories via Bharat Connect"
},
{
"name": "Transactions & Refunds",
"description": "Transaction status inquiry and OTP-based refunds"
},
{
"name": "Utility & Helper APIs",
"description": "Bank/IFSC lookup and generic mobile OTP helpers"
},
{
"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 Verification",
"description": "Verify Indian passport 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"
}
],
"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. If not found (response_status_id 463), proceed to Onboard Sender.",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-get-sender",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_id": {
"description": "Sender's mobile number (echoed back).",
"example": "9123456789",
"type": "string"
},
"name": {
"description": "Registered name of the sender.",
"example": "Ramesh Kumar",
"type": "string"
},
"dob": {
"description": "Date of birth in YYYY-MM-DD format.",
"example": "1990-05-15",
"type": "string"
},
"kyc_verified": {
"description": "Whether the sender has completed eKYC verification.",
"example": true,
"type": "boolean"
},
"available_limit": {
"description": "Remaining transfer limit for the current month (in INR).",
"example": 25000,
"type": "number"
},
"used_limit": {
"description": "Transfer amount already used this month (in INR).",
"example": 0,
"type": "number"
},
"monthly_limit": {
"description": "Total allowed monthly transfer limit for this sender (in INR).",
"example": 25000,
"type": "number"
},
"state": {
"description": "Sender account state: 0=Active, 10=Pending verification.",
"example": 0,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Customer found",
"response_type_id": 1388,
"data": {
"customer_id": "9123456789",
"name": "Ramesh Kumar",
"dob": "1990-05-15",
"kyc_verified": true,
"available_limit": 25000,
"used_limit": 0,
"monthly_limit": 25000,
"state": 0
}
}
},
"sender_not_found_proceed_to_onboard_sender": {
"summary": "Sender not found — proceed to Onboard Sender",
"value": {
"status": 1,
"response_status_id": 463,
"message": "Customer not found",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
}
},
"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 created in a pending state; biometric eKYC (via Sender KYC) must follow to activate full monthly limits. An OTP is dispatched to the customer's mobile number for confirmation.",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-onboard-sender",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_id": {
"description": "Mobile number of the newly registered sender.",
"example": "9123456789",
"type": "string"
},
"state": {
"description": "Account state: 10=Pending KYC verification.",
"example": 10,
"type": "number"
},
"otp_ref_id": {
"description": "Reference ID for the OTP sent to the sender's mobile. Used in the Validate eKYC OTP step.",
"example": "OTP20240101001",
"type": "string"
},
"available_limit": {
"description": "Initial transfer limit before eKYC (in INR). Typically ₹5,000.",
"example": 5000,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Customer registered successfully",
"response_type_id": 1388,
"data": {
"customer_id": "9123456789",
"state": 10,
"otp_ref_id": "OTP20240101001",
"available_limit": 5000
}
}
},
"sender_already_exists_in_the_system": {
"summary": "Sender already exists in the system",
"value": {
"status": 1,
"response_status_id": 17,
"message": "User wallet already exists",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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"
},
"residence_address": {
"type": "string",
"description": "Customer's residence address as a JSON-encoded array of address lines.",
"example": "[\"123 Main Street\", \"Connaught Place\", \"New Delhi\", \"110001\"]"
}
},
"required": [
"initiator_id",
"user_code",
"name",
"dob",
"residence_address"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"name": "Ramesh Kumar",
"dob": "1990-05-15",
"residence_address": "[\"123 Main Street\", \"Connaught Place\", \"New Delhi\", \"110001\"]"
}
}
}
}
}
},
"/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 biometric capture device. The biometric PID data (XML payload) is captured at the agent's terminal and submitted along with the Aadhaar number. 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.",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-fino-sender-ekyc",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"kyc_request_id": {
"description": "Unique identifier for this KYC request. Required for the Validate eKYC OTP step.",
"example": "KYC20240101001",
"type": "string"
},
"otp_ref_id": {
"description": "Reference ID for the OTP sent to the sender's Aadhaar-linked mobile.",
"example": "OTPREF20240101001",
"type": "string"
},
"mobile": {
"description": "Masked mobile number to which the OTP was dispatched.",
"example": "XXXXXXX789",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "OTP sent for eKYC verification",
"response_type_id": 1388,
"data": {
"kyc_request_id": "KYC20240101001",
"otp_ref_id": "OTPREF20240101001",
"mobile": "XXXXXXX789"
}
}
},
"sender_already_kyc_verified_no_further_upgrade_needed": {
"summary": "Sender already KYC verified — no further upgrade needed",
"value": {
"status": 1,
"response_status_id": 585,
"message": "Customer already KYC approved",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhar": {
"type": "string",
"description": "12-digit Aadhaar number of the sender.",
"example": "234567890123"
},
"piddata": {
"type": "string",
"description": "XML-encoded biometric PID data captured from a certified biometric device (fingerprint scanner).",
"example": ""
}
},
"required": [
"initiator_id",
"user_code",
"aadhar",
"piddata"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_id": {
"description": "Sender's mobile number (echoed back).",
"example": "9123456789",
"type": "string"
},
"kyc_verified": {
"description": "Confirms successful eKYC completion.",
"example": true,
"type": "boolean"
},
"available_limit": {
"description": "Updated monthly transfer limit after KYC (in INR).",
"example": 25000,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "eKYC verification successful",
"response_type_id": 1388,
"data": {
"customer_id": "9123456789",
"kyc_verified": true,
"available_limit": 25000
}
}
},
"incorrect_otp_entered": {
"summary": "Incorrect OTP entered",
"value": {
"status": 1,
"response_status_id": 302,
"message": "Wrong OTP",
"response_type_id": 1388,
"data": {}
}
},
"otp_has_expired": {
"summary": "OTP has expired",
"value": {
"status": 1,
"response_status_id": 303,
"message": "OTP expired",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"otp",
"otp_ref_id",
"kyc_request_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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.",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-get-recipients",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "Granular status id; see the shared error-codes table.",
"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": "Total number of recipients registered under this sender.",
"example": 2,
"type": "number"
},
"recipient": {
"description": "List of registered beneficiaries.",
"type": "array",
"items": {
"type": "object",
"properties": {
"recipient_id": {
"description": "Unique identifier for the recipient. Used as input to Send OTP and Initiate Transfer APIs.",
"example": 98765,
"type": "number"
},
"recipient_name": {
"description": "Full name of the beneficiary.",
"example": "Sunil Sharma",
"type": "string"
},
"account": {
"description": "Beneficiary's bank account number.",
"example": "012345678901",
"type": "string"
},
"ifsc": {
"description": "IFSC code of the beneficiary's bank branch.",
"example": "SBIN0001234",
"type": "string"
},
"bank_name": {
"description": "Name of the beneficiary's bank.",
"example": "State Bank of India",
"type": "string"
},
"recipient_mobile": {
"description": "Mobile number registered for the recipient.",
"example": "9988776655",
"type": "string"
},
"is_verified": {
"description": "Whether the recipient's account has been penny-drop verified.",
"example": true,
"type": "boolean"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Success",
"response_type_id": 1388,
"data": {
"count": 2,
"recipient": [
{
"recipient_id": 98765,
"recipient_name": "Sunil Sharma",
"account": "012345678901",
"ifsc": "SBIN0001234",
"bank_name": "State Bank of India",
"recipient_mobile": "9988776655",
"is_verified": true
},
{
"recipient_id": 98766,
"recipient_name": "Priya Verma",
"account": "987654321098",
"ifsc": "HDFC0002345",
"bank_name": "HDFC Bank",
"recipient_mobile": "9811223344",
"is_verified": true
}
]
}
}
}
}
}
}
}
}
}
},
"/customer/payment/dmt-fino/sender/{customer_id}/recipient1": {
"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. The bank_id identifies the destination bank (fetch from the bank list if needed). On success a recipient_id is returned; use it in Send OTP and Initiate Transfer. The system may validate the account via penny-drop before activating the recipient.",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-add-recipient",
"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": "Granular status id; see the shared error-codes table.",
"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 OTP and Initiate Transfer.",
"example": 98765,
"type": "number"
},
"recipient_name": {
"description": "Name of the recipient as registered.",
"example": "Sunil Sharma",
"type": "string"
},
"account": {
"description": "Bank account number of the recipient.",
"example": "012345678901",
"type": "string"
},
"ifsc": {
"description": "IFSC code of the recipient's bank branch.",
"example": "SBIN0001234",
"type": "string"
},
"is_verified": {
"description": "Whether the account passed penny-drop verification.",
"example": false,
"type": "boolean"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Recipient added successfully",
"response_type_id": 1388,
"data": {
"recipient_id": 98765,
"recipient_name": "Sunil Sharma",
"account": "012345678901",
"ifsc": "SBIN0001234",
"is_verified": false
}
}
},
"recipient_already_registered_for_this_sender": {
"summary": "Recipient already registered for this sender",
"value": {
"status": 1,
"response_status_id": 342,
"message": "Recipient already registered",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_name": {
"type": "string",
"description": "Full name of the beneficiary as it appears on their bank account.",
"example": "Sunil Sharma"
},
"account": {
"type": "string",
"description": "Beneficiary's bank account number.",
"example": "012345678901"
},
"ifsc": {
"type": "string",
"description": "IFSC code of the beneficiary's bank branch.",
"example": "SBIN0001234"
},
"bank_id": {
"type": "number",
"description": "Unique bank identifier from Eko's bank list API.",
"example": 20
},
"recipient_mobile": {
"type": "string",
"description": "10-digit mobile number of the recipient.",
"example": "9988776655"
},
"recipient_type": {
"type": "string",
"description": "Recipient type. Fixed value: \"3\" for DMT-Fino bank account recipients.",
"example": "3"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_name",
"account",
"ifsc",
"bank_id",
"recipient_mobile",
"recipient_type"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_name": "Sunil Sharma",
"account": "012345678901",
"ifsc": "SBIN0001234",
"bank_id": 20,
"recipient_mobile": "9988776655",
"recipient_type": "3"
}
}
}
}
}
},
"/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.",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-send-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": "Granular status id; see the shared error-codes table.",
"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 Initiate Transfer along with the customer-entered OTP.",
"example": "TXNOTP20240101001",
"type": "string"
},
"mobile": {
"description": "Masked mobile number to which the OTP was sent (for display to agent/customer).",
"example": "XXXXXX6789",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "OTP sent successfully",
"response_type_id": 1388,
"data": {
"otp_ref_id": "TXNOTP20240101001",
"mobile": "XXXXXX6789"
}
}
},
"sender_monthly_limit_exhausted": {
"summary": "Sender monthly limit exhausted",
"value": {
"status": 1,
"response_status_id": 945,
"message": "Sender/beneficiary monthly limit exhausted",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"recipient_id",
"amount",
"customer_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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. Requires the OTP and otp_ref_id from Send Transaction OTP and the merchant's GPS coordinates (latlong). The response returns a tid (Eko transaction ID) and the banking UTR for the IMPS transaction. Always poll Get Transaction Status if tx_status is 2 (Awaited).",
"tags": [
"Domestic Money Transfer (DMT)"
],
"x-docs-slug": "dmt-initiate-transfer",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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 this for status enquiries and reconciliation.",
"example": "2309876543",
"type": "string"
},
"utrnumber": {
"description": "Unique Transaction Reference (UTR) from the IMPS network — the banking-side reference number.",
"example": "412345678901",
"type": "string"
},
"amount": {
"description": "Amount transferred in INR.",
"example": 500,
"type": "number"
},
"recipient_name": {
"description": "Name of the beneficiary credited.",
"example": "Sunil Sharma",
"type": "string"
},
"account": {
"description": "Beneficiary account number credited.",
"example": "012345678901",
"type": "string"
},
"ifsc": {
"description": "IFSC code of the credited bank account.",
"example": "SBIN0001234",
"type": "string"
},
"fee": {
"description": "Transaction fee charged (in INR).",
"example": 5,
"type": "number"
},
"commission": {
"description": "Commission earned by the agent on this transaction (in INR).",
"example": 3,
"type": "number"
},
"balance": {
"description": "Remaining wallet balance of the agent after the transaction.",
"example": 4495,
"type": "number"
},
"client_ref_id": {
"description": "Your system's reference ID (echoed back).",
"example": "REF-20240101-001",
"type": "string"
},
"timestamp": {
"description": "Server-side timestamp of the transaction.",
"example": "2024-01-01T10:30:05Z",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Transaction successful",
"tx_status": "0",
"txstatus_desc": "Success",
"data": {
"tid": "2309876543",
"utrnumber": "412345678901",
"amount": 500,
"tx_status": "0",
"recipient_name": "Sunil Sharma",
"account": "012345678901",
"ifsc": "SBIN0001234",
"fee": 5,
"commission": 3,
"balance": 4495,
"client_ref_id": "REF-20240101-001",
"timestamp": "2024-01-01T10:30:05Z"
}
}
},
"insufficient_balance_in_agent_wallet": {
"summary": "Insufficient balance in agent wallet",
"value": {
"status": 1,
"response_status_id": 347,
"message": "Insufficient balance",
"tx_status": "1",
"txstatus_desc": "Failed",
"data": {}
}
},
"transaction_pending_awaited_poll_get_transaction_status": {
"summary": "Transaction pending / awaited — poll Get Transaction Status",
"value": {
"status": 0,
"response_status_id": 0,
"message": "Transaction in progress",
"tx_status": "2",
"txstatus_desc": "Awaited",
"data": {
"tid": "2309876543",
"amount": 500
}
}
},
"wrong_otp_entered": {
"summary": "Wrong OTP entered",
"value": {
"status": 1,
"response_status_id": 302,
"message": "Wrong OTP",
"tx_status": "1",
"txstatus_desc": "Failed",
"data": {}
}
},
"sender_monthly_limit_exhausted": {
"summary": "Sender monthly limit exhausted",
"value": {
"status": 1,
"response_status_id": 945,
"message": "Sender/beneficiary monthly limit exhausted",
"tx_status": "1",
"txstatus_desc": "Failed",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "number",
"description": "Unique recipient ID from Add Recipient or Get Recipients.",
"example": 98765
},
"amount": {
"type": "number",
"description": "Transfer amount in INR (must match the amount sent to Send OTP).",
"example": 500
},
"customer_id": {
"type": "string",
"description": "Sender's 10-digit mobile number.",
"example": "9123456789"
},
"otp": {
"type": "string",
"description": "OTP entered by the customer, received on their registered mobile.",
"example": "251834"
},
"otp_ref_id": {
"type": "string",
"description": "OTP reference ID from the Send Transaction OTP response.",
"example": "TXNOTP20240101001"
},
"latlong": {
"type": "string",
"description": "GPS coordinates of the agent/merchant's device at the time of transaction (required for regulatory compliance).",
"example": "28.6139,77.2090"
},
"state": {
"type": "string",
"description": "Fixed value: \"1\".",
"example": "1"
},
"recipient_id_type": {
"type": "string",
"description": "Fixed value: \"1\" for bank account recipients.",
"example": "1"
},
"channel": {
"type": "number",
"description": "Transfer channel. Fixed value: 2 (IMPS). Defaults to 2.",
"example": 2
},
"currency": {
"type": "string",
"description": "Currency code. Defaults to \"INR\".",
"example": "INR"
},
"timestamp": {
"type": "string",
"description": "ISO 8601 request timestamp.",
"example": "2024-01-01T10:30:00Z"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_id",
"amount",
"customer_id",
"otp",
"otp_ref_id",
"latlong",
"state",
"recipient_id_type"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": 98765,
"amount": 500,
"customer_id": "9123456789",
"otp": "251834",
"otp_ref_id": "TXNOTP20240101001",
"latlong": "28.6139,77.2090",
"state": "1",
"recipient_id_type": "1",
"channel": 2,
"currency": "INR",
"timestamp": "2024-01-01T10:30:00Z"
}
}
}
}
}
},
"/customer/collection/aeps-fingpay/cash-withdrawal/{customer_id}": {
"post": {
"operationId": "aepsCashWithdrawal",
"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, OTP-based eKYC, and the daily 2FA authentication for the current day.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-cash-withdrawal",
"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": "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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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": "EKO20240101001234",
"type": "string"
},
"amount": {
"description": "Withdrawal amount processed in the transaction (INR).",
"example": 1000,
"type": "number"
},
"bank_name": {
"description": "Name of the customer's bank where the debit occurred.",
"example": "State Bank of India",
"type": "string"
},
"bank_ref_num": {
"description": "Bank/NPCI reference number for the transaction.",
"example": "NPCI20240101ABCD",
"type": "string"
},
"balance": {
"description": "Remaining balance in the customer's bank account after withdrawal, if returned by the bank.",
"example": "4500.00",
"type": "string"
},
"aadhaar_ref_num": {
"description": "Aadhaar authentication reference number from UIDAI.",
"example": "UIDAI123456789",
"type": "string"
},
"service_type": {
"description": "Echo of the service_type from the request (2 for Cash Withdrawal).",
"example": 2,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Cash Withdrawal successful",
"tx_status": "0",
"txstatus_desc": "Success",
"data": {
"tid": "EKO20240101001234",
"tx_status": "0",
"txstatus_desc": "Success",
"amount": 1000,
"bank_name": "State Bank of India",
"bank_ref_num": "NPCI20240101ABCD",
"balance": "4500.00",
"aadhaar_ref_num": "UIDAI123456789",
"service_type": 2
}
}
},
"biometric_authentication_failure": {
"summary": "Biometric authentication failure",
"value": {
"status": 1,
"response_status_id": 108,
"message": "Biometric authentication failed. Please retry with a fresh fingerprint scan.",
"tx_status": "1",
"txstatus_desc": "Failed",
"data": {
"tid": "EKO20240101001235",
"tx_status": "1",
"amount": 1000
}
}
},
"insufficient_balance_in_customer_account": {
"summary": "Insufficient balance in customer account",
"value": {
"status": 1,
"response_status_id": 347,
"message": "Insufficient balance in customer account.",
"tx_status": "1",
"txstatus_desc": "Failed",
"data": {
"tid": "EKO20240101001236",
"tx_status": "1",
"amount": 1000
}
}
},
"daily_2fa_reference_id_missing_or_invalid": {
"summary": "Daily 2FA reference_id missing or invalid",
"value": {
"status": 1,
"response_status_id": 155,
"message": "Daily authentication (2FA) required. Complete daily eKYC before performing transactions.",
"data": {}
}
},
"transaction_awaited_bank_timeout": {
"summary": "Transaction awaited / bank timeout",
"value": {
"status": 2,
"response_status_id": 2,
"message": "Transaction is being processed. Check status using Transaction Inquiry API.",
"tx_status": "2",
"txstatus_desc": "Awaited",
"data": {
"tid": "EKO20240101001237",
"tx_status": "2"
}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_code": {
"type": "string",
"description": "Bank IIN/IFS code identifying the customer's bank. Obtain from the bank list API.",
"example": "607153"
},
"amount": {
"type": "number",
"description": "Withdrawal amount in Indian Rupees (integer). Must be greater than 0 for cash withdrawal.",
"example": 1000
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number. Encrypt the 12-digit Aadhaar using the Eko RSA public key with OPENSSL_SSLV23_PADDING, then Base64-encode the ciphertext.",
"example": "BASE64_ENCRYPTED_AADHAAR"
},
"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.",
"example": "..."
},
"pipe": {
"type": "number",
"description": "Routing pipe selector. Use 0 (default).",
"example": 0
},
"notify_customer": {
"type": "number",
"description": "Send SMS notification to the customer. 1 = yes, 0 = no.",
"example": 1
},
"latlong": {
"type": "string",
"description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.",
"example": "28.6139,77.2090"
},
"source_ip": {
"type": "string",
"description": "IP address of the merchant/agent system initiating the transaction.",
"example": "103.56.78.90"
},
"reference_id": {
"type": "string",
"description": "2FA reference ID obtained from the Daily Authentication (daily eKYC) API. Required for every Cash Withdrawal transaction due to compliance 2FA mandate.",
"example": "DAKYC20240101001"
}
},
"required": [
"initiator_id",
"user_code",
"bank_code",
"amount",
"aadhaar",
"piddata",
"pipe",
"notify_customer",
"latlong",
"source_ip",
"reference_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_code": "607153",
"amount": 1000,
"aadhaar": "BASE64_ENCRYPTED_AADHAAR",
"piddata": "...",
"pipe": 0,
"notify_customer": 1,
"latlong": "28.6139,77.2090",
"source_ip": "103.56.78.90",
"reference_id": "DAKYC20240101001"
}
}
}
}
}
},
"/customer/collection/aeps-fingpay/balance-enquiry/{customer_id}": {
"post": {
"operationId": "aepsBalanceEnquiry",
"summary": "AePS Balance Enquiry",
"description": "Retrieves the real-time account balance from any Aadhaar-linked bank. Uses the dedicated `balance-enquiry` endpoint with amount=0. 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.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-balance-enquiry",
"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": "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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"example": "0",
"type": "string"
},
"txstatus_desc": {
"description": "Human-readable transaction status.",
"example": "Success",
"type": "string"
},
"data": {
"description": "API-specific response payload.",
"type": "object",
"properties": {
"balance": {
"description": "Current account balance returned by the bank (INR). This is the key output of a Balance Enquiry.",
"example": "5500.75",
"type": "string"
},
"bank_name": {
"description": "Name of the customer's bank.",
"example": "State Bank of India",
"type": "string"
},
"tid": {
"description": "Eko's internal transaction ID for this enquiry.",
"example": "EKO20240101005678",
"type": "string"
},
"bank_ref_num": {
"description": "NPCI/bank reference number.",
"example": "NPCI20240101EFGH",
"type": "string"
},
"aadhaar_ref_num": {
"description": "UIDAI authentication reference number.",
"example": "UIDAI987654321",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Balance Enquiry successful",
"tx_status": "0",
"txstatus_desc": "Success",
"data": {
"tid": "EKO20240101005678",
"tx_status": "0",
"txstatus_desc": "Success",
"balance": "5500.75",
"bank_name": "State Bank of India",
"bank_ref_num": "NPCI20240101EFGH",
"aadhaar_ref_num": "UIDAI987654321"
}
}
},
"bank_server_timeout_balance_unavailable": {
"summary": "Bank server timeout / balance unavailable",
"value": {
"status": 1,
"response_status_id": 108,
"message": "Unable to fetch balance. Bank server did not respond in time.",
"tx_status": "1",
"data": {}
}
},
"aadhaar_not_linked_to_selected_bank": {
"summary": "Aadhaar not linked to selected bank",
"value": {
"status": 1,
"response_status_id": 463,
"message": "Aadhaar not linked to this bank. Please select the correct bank.",
"tx_status": "1",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_code": {
"type": "string",
"description": "Bank IIN/IFS code identifying the customer's bank.",
"example": "607153"
},
"amount": {
"type": "number",
"description": "Must be 0 for Balance Enquiry. No debit is performed.",
"example": 0
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number of the customer.",
"example": "BASE64_ENCRYPTED_AADHAAR"
},
"piddata": {
"type": "string",
"description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc present in DeviceInfo).",
"example": "..."
},
"pipe": {
"type": "number",
"description": "Routing pipe selector. Use 0 (default).",
"example": 0
},
"notify_customer": {
"type": "number",
"description": "Send SMS notification to the customer. 1 = yes, 0 = no.",
"example": 0
},
"latlong": {
"type": "string",
"description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.",
"example": "28.6139,77.2090"
},
"source_ip": {
"type": "string",
"description": "IP address of the merchant/agent system initiating the transaction.",
"example": "103.56.78.90"
}
},
"required": [
"initiator_id",
"user_code",
"bank_code",
"amount",
"aadhaar",
"piddata",
"pipe",
"notify_customer",
"latlong",
"source_ip"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_code": "607153",
"amount": 0,
"aadhaar": "BASE64_ENCRYPTED_AADHAAR",
"piddata": "...",
"pipe": 0,
"notify_customer": 0,
"latlong": "28.6139,77.2090",
"source_ip": "103.56.78.90"
}
}
}
}
}
},
"/admin/network/agent/{user_code}/aeps-fingpay/activate": {
"put": {
"operationId": "aepsActivateFingpay",
"summary": "Activate AePS Fingpay for Agent",
"description": "This onboarding API registers an agent (identified by their user_code) for the AePS Fingpay service. It accepts the agent's biometric device model, serial number, 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.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-activate-fingpay",
"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 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": "Granular status id; see the shared error-codes table.",
"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": {
"activation_status": {
"description": "Current state of the AePS Fingpay activation request. 'pending' means documents are submitted and under review.",
"example": "pending",
"type": "string"
},
"activation_id": {
"description": "Unique identifier for this activation request, for tracking and support.",
"example": "ACT20240101001",
"type": "string"
},
"message": {
"description": "Human-readable message about the activation status.",
"example": "Activation request submitted. Approval expected within 2-3 business days.",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "AePS Fingpay activation request submitted successfully. Approval expected within 2-3 business days.",
"response_type_id": 1388,
"data": {
"activation_status": "pending",
"activation_id": "ACT20240101001",
"message": "Activation request submitted. Approval expected within 2-3 business days."
}
}
},
"agent_user_code_not_found": {
"summary": "Agent user_code not found",
"value": {
"status": 1,
"response_status_id": 463,
"message": "Agent not found. Please verify the user_code.",
"data": {}
}
}
}
}
}
},
"400": {
"description": "File format not accepted (PNG uploaded)",
"content": {
"application/json": {
"examples": {
"file_format_not_accepted_png_uploaded": {
"summary": "File format not accepted (PNG uploaded)",
"value": {
"status": 1,
"message": "Invalid file format. Only JPEG, JPG, and PDF are accepted."
}
},
"file_size_exceeds_1_mb": {
"summary": "File size exceeds 1 MB",
"value": {
"status": 1,
"message": "File size exceeds the maximum allowed limit of 1 MB."
}
}
}
}
}
}
},
"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"
},
"modelname": {
"type": "string",
"description": "Model name/designation of the UIDAI-certified biometric device (e.g., Morpho 1300E3, Mantra MFS100).",
"example": "Morpho 1300E3"
},
"devicenumber": {
"type": "string",
"description": "Serial number of the biometric device as printed on the device or its packaging.",
"example": "SN1234567890"
},
"office_address": {
"type": "string",
"description": "Agent's current office/operating address as a JSON object with keys: line, city, state, pincode.",
"example": {
"line": "Shop No. 5, Gandhi Market",
"city": "Patna",
"state": "Bihar",
"pincode": "800001"
}
},
"address_as_per_proof": {
"type": "string",
"description": "Agent's address exactly as it appears on the submitted address proof document. JSON object with keys: line, city, state, pincode.",
"example": {
"line": "Shop No. 5, Gandhi Market",
"city": "Patna",
"state": "Bihar",
"pincode": "800001"
}
},
"pan_card": {
"type": "string",
"description": "PAN card document upload (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB. PNG not accepted.",
"example": ""
},
"aadhar_front": {
"type": "string",
"description": "Front side of the Aadhaar card (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB.",
"example": ""
},
"aadhar_back": {
"type": "string",
"description": "Back side of the Aadhaar card (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB.",
"example": ""
}
},
"required": [
"initiator_id",
"modelname",
"devicenumber",
"office_address",
"address_as_per_proof",
"pan_card",
"aadhar_front",
"aadhar_back"
]
},
"example": {
"initiator_id": "9962981729",
"modelname": "Morpho 1300E3",
"devicenumber": "SN1234567890",
"office_address": {
"line": "Shop No. 5, Gandhi Market",
"city": "Patna",
"state": "Bihar",
"pincode": "800001"
},
"address_as_per_proof": {
"line": "Shop No. 5, Gandhi Market",
"city": "Patna",
"state": "Bihar",
"pincode": "800001"
},
"pan_card": "",
"aadhar_front": "",
"aadhar_back": ""
}
}
}
}
}
},
"/customer/aeps/fingpay/kyc/daily": {
"post": {
"operationId": "aepsDailyAuth",
"summary": "AePS Fingpay — Daily Authentication (2FA)",
"description": "AePS Fingpay requires every agent to authenticate themselves biometrically at the start of each working day. This daily 2FA must be completed before the first Cash Withdrawal transaction of the day (and is available only 3 or more days after the initial eKYC is completed). The API returns a `reference_id` that must be included in every subsequent Cash Withdrawal request as proof of daily authentication. Daily Auth does not need to be repeated for Balance Enquiry or Mini Statement within the same day.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-daily-auth",
"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": "Granular status id; see the shared error-codes table.",
"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": "Daily authentication reference ID. Pass this as the 'reference_id' parameter in every Cash Withdrawal request made during the current day. Valid for the current calendar day only.",
"example": "DAKYC20240101001",
"type": "string"
},
"auth_status": {
"description": "Result of the daily biometric authentication. 'success' means the agent is cleared to perform Cash Withdrawal transactions for the day.",
"example": "success",
"type": "string"
},
"valid_till": {
"description": "Expiry timestamp of this daily auth token (end of the current calendar day, IST).",
"example": "2024-01-01T23:59:59+05:30",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Daily authentication successful. You can now process Cash Withdrawal transactions.",
"response_type_id": 1388,
"data": {
"reference_id": "DAKYC20240101001",
"auth_status": "success",
"valid_till": "2024-01-01T23:59:59+05:30"
}
}
},
"biometric_authentication_failed": {
"summary": "Biometric authentication failed",
"value": {
"status": 1,
"response_status_id": 108,
"message": "Daily biometric authentication failed. Please re-scan fingerprint.",
"data": {}
}
},
"ekyc_not_completed_daily_auth_not_yet_eligible": {
"summary": "eKYC not completed — daily auth not yet eligible",
"value": {
"status": 1,
"response_status_id": 327,
"message": "eKYC not completed or daily auth not eligible yet (minimum 3 days after eKYC required).",
"data": {}
}
},
"daily_auth_already_completed_for_today": {
"summary": "Daily auth already completed for today",
"value": {
"status": 1,
"response_status_id": 17,
"message": "Daily authentication already completed for today. Use the existing reference_id for transactions.",
"data": {
"reference_id": "DAKYC20240101001"
}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number of the agent performing daily authentication.",
"example": "BASE64_ENCRYPTED_AADHAAR"
},
"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.",
"example": "..."
},
"latlong": {
"type": "string",
"description": "GPS coordinates of the agent's location at the time of daily authentication.",
"example": "25.5941,85.1376"
},
"source_ip": {
"type": "string",
"description": "IP address of the agent's terminal/system.",
"example": "103.56.78.90"
}
},
"required": [
"initiator_id",
"user_code",
"aadhaar",
"piddata",
"latlong",
"source_ip"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"aadhaar": "BASE64_ENCRYPTED_AADHAAR",
"piddata": "...",
"latlong": "25.5941,85.1376",
"source_ip": "103.56.78.90"
}
}
}
}
}
},
"/customer/collection/aeps-fingpay/mini-statement/{customer_id}": {
"post": {
"operationId": "aepsMiniStatement",
"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 with amount=0. 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.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-mini-statement",
"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": "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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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 for this enquiry.",
"example": "EKO20240101009012",
"type": "string"
},
"bank_name": {
"description": "Name of the customer's bank.",
"example": "Punjab National Bank",
"type": "string"
},
"ministatement": {
"description": "List of recent transactions. Each entry contains transaction date, amount, transaction type (debit/credit), and narration.",
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"description": "Transaction date (DD-MM-YYYY or YYYY-MM-DD depending on bank).",
"example": "2024-01-01",
"type": "string"
},
"amount": {
"description": "Transaction amount in INR.",
"example": "500.00",
"type": "string"
},
"txn_type": {
"description": "Transaction direction: 'C' for credit, 'D' for debit.",
"example": "D",
"type": "string"
},
"narration": {
"description": "Bank-provided transaction narration or description.",
"example": "AePS CW",
"type": "string"
}
}
}
},
"bank_ref_num": {
"description": "NPCI/bank reference number for this statement fetch.",
"example": "NPCI20240101IJKL",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Mini Statement fetched successfully",
"tx_status": "0",
"txstatus_desc": "Success",
"data": {
"tid": "EKO20240101009012",
"tx_status": "0",
"txstatus_desc": "Success",
"bank_name": "Punjab National Bank",
"bank_ref_num": "NPCI20240101IJKL",
"ministatement": [
{
"date": "2024-01-01",
"amount": "500.00",
"txn_type": "D",
"narration": "AePS CW"
},
{
"date": "2023-12-30",
"amount": "2000.00",
"txn_type": "C",
"narration": "NEFT CR"
},
{
"date": "2023-12-28",
"amount": "300.00",
"txn_type": "D",
"narration": "AePS CW"
}
]
}
}
},
"mini_statement_not_supported_by_bank": {
"summary": "Mini statement not supported by bank",
"value": {
"status": 1,
"response_status_id": 108,
"message": "Mini statement service not available for this bank.",
"tx_status": "1",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_code": {
"type": "string",
"description": "Bank IIN/IFS code identifying the customer's bank.",
"example": "607153"
},
"amount": {
"type": "number",
"description": "Must be 0 for Mini Statement. No debit is performed.",
"example": 0
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number of the customer.",
"example": "BASE64_ENCRYPTED_AADHAAR"
},
"piddata": {
"type": "string",
"description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc present in DeviceInfo).",
"example": "..."
},
"pipe": {
"type": "number",
"description": "Routing pipe selector. Use 0 (default).",
"example": 0
},
"notify_customer": {
"type": "number",
"description": "Send SMS notification to the customer. 1 = yes, 0 = no.",
"example": 0
},
"latlong": {
"type": "string",
"description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.",
"example": "28.6139,77.2090"
},
"source_ip": {
"type": "string",
"description": "IP address of the merchant/agent system initiating the transaction.",
"example": "103.56.78.90"
}
},
"required": [
"initiator_id",
"user_code",
"bank_code",
"amount",
"aadhaar",
"piddata",
"pipe",
"notify_customer",
"latlong",
"source_ip"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_code": "607153",
"amount": 0,
"aadhaar": "BASE64_ENCRYPTED_AADHAAR",
"piddata": "...",
"pipe": 0,
"notify_customer": 0,
"latlong": "28.6139,77.2090",
"source_ip": "103.56.78.90"
}
}
}
}
}
},
"/customer/collection/aeps-fingpay": {
"post": {
"operationId": "aepsAadhaarPay",
"summary": "AePS Aadhaar Pay",
"description": "Aadhaar Pay (service_type=5) enables merchants to accept payments from customers whose bank accounts are Aadhaar-linked, authenticated with a fingerprint scan. Unlike Cash Withdrawal (where cash is dispensed), the funds are transferred to the merchant. This is useful for last-mile digital payments at kirana stores and service points where customers have no UPI or debit card. The flow is identical to Cash Withdrawal but with a positive merchant-side credit.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-aadhaar-pay",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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.",
"example": "EKO20240101012345",
"type": "string"
},
"amount": {
"description": "Payment amount processed (INR).",
"example": 250,
"type": "number"
},
"bank_name": {
"description": "Name of the customer's debited bank.",
"example": "Bank of Baroda",
"type": "string"
},
"bank_ref_num": {
"description": "NPCI/bank reference number.",
"example": "NPCI20240101MNOP",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Aadhaar Pay successful",
"tx_status": "0",
"txstatus_desc": "Success",
"data": {
"tid": "EKO20240101012345",
"tx_status": "0",
"txstatus_desc": "Success",
"amount": 250,
"bank_name": "Bank of Baroda",
"bank_ref_num": "NPCI20240101MNOP"
}
}
},
"biometric_authentication_failed": {
"summary": "Biometric authentication failed",
"value": {
"status": 1,
"response_status_id": 108,
"message": "Fingerprint authentication failed. Please re-scan.",
"tx_status": "1",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"service_type": {
"type": "number",
"description": "Transaction type. Use 5 for Aadhaar Pay.",
"example": 5
},
"customer_id": {
"type": "string",
"description": "Customer's registered mobile number.",
"example": "9876543210"
},
"bank_code": {
"type": "string",
"description": "Bank IIN/IFS code identifying the customer's bank.",
"example": "607153"
},
"amount": {
"type": "number",
"description": "Payment amount in INR (integer). This amount is debited from the customer and credited to the merchant.",
"example": 250
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number of the paying customer.",
"example": "BASE64_ENCRYPTED_AADHAAR"
},
"piddata": {
"type": "string",
"description": "PID XML string from UIDAI-certified biometric device (fType=2, Data type='X', mc in DeviceInfo).",
"example": "..."
},
"pipe": {
"type": "number",
"description": "Routing pipe selector. Use 0 (default).",
"example": 0
},
"notify_customer": {
"type": "number",
"description": "Send SMS notification to the customer. 1 = yes, 0 = no.",
"example": 1
},
"latlong": {
"type": "string",
"description": "GPS coordinates of the transaction origin in 'latitude,longitude' format.",
"example": "28.6139,77.2090"
},
"source_ip": {
"type": "string",
"description": "IP address of the merchant system initiating the transaction.",
"example": "103.56.78.90"
}
},
"required": [
"initiator_id",
"user_code",
"service_type",
"customer_id",
"bank_code",
"amount",
"aadhaar",
"piddata",
"pipe",
"notify_customer",
"latlong",
"source_ip"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"service_type": 5,
"customer_id": "9876543210",
"bank_code": "607153",
"amount": 250,
"aadhaar": "BASE64_ENCRYPTED_AADHAAR",
"piddata": "...",
"pipe": 0,
"notify_customer": 1,
"latlong": "28.6139,77.2090",
"source_ip": "103.56.78.90"
}
}
}
}
}
},
"/customer/aeps/fingpay/kyc/otp": {
"post": {
"operationId": "aepsSendOtpKyc",
"summary": "AePS Fingpay — Send OTP (eKYC)",
"description": "The first step in the one-time AePS Fingpay eKYC flow. Sends an OTP to the mobile number registered with the agent's Aadhaar. The eKYC flow — Send OTP → Verify OTP → Biometric Capture — 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 authentication (2FA) which is required on each calendar day.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-send-otp-kyc",
"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": "Granular status id; see the shared error-codes table.",
"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 session. Must be passed to the Verify OTP API.",
"example": "OTPREF20240101001",
"type": "string"
},
"mobile_hint": {
"description": "Masked mobile number to which the OTP was sent (e.g., ******7890), for UI display.",
"example": "******7890",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "OTP sent successfully to Aadhaar-linked mobile number.",
"response_type_id": 1388,
"data": {
"otp_ref_id": "OTPREF20240101001",
"mobile_hint": "******7890"
}
}
},
"otp_already_sent_too_many_requests": {
"summary": "OTP already sent / too many requests",
"value": {
"status": 1,
"response_status_id": 302,
"message": "OTP already sent. Please wait before requesting a new OTP."
}
},
"aadhaar_not_eligible_for_ekyc": {
"summary": "Aadhaar not eligible for eKYC",
"value": {
"status": 1,
"response_status_id": 463,
"message": "Aadhaar not found or not eligible for eKYC.",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number of the agent undergoing eKYC.",
"example": "BASE64_ENCRYPTED_AADHAAR"
}
},
"required": [
"initiator_id",
"user_code",
"aadhaar"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"aadhaar": "BASE64_ENCRYPTED_AADHAAR"
}
}
}
}
}
},
"/customer/aeps/fingpay/kyc/biometric": {
"post": {
"operationId": "aepsBiometricEkyc",
"summary": "AePS Fingpay — Biometric eKYC",
"description": "The final step in the one-time AePS Fingpay eKYC flow, called after OTP verification. Submits the agent's Aadhaar and biometric PID data to UIDAI for identity verification. On success, the agent's eKYC is marked complete and they can start performing AePS transactions (subject to completing daily 2FA each day). This step uses the same RSA-encrypted Aadhaar and PID XML format as the transaction APIs.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-biometric-ekyc",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"kyc_status": {
"description": "Result of the eKYC verification. 'completed' means the agent is now KYC-verified for AePS.",
"example": "completed",
"type": "string"
},
"aadhaar_ref_num": {
"description": "UIDAI authentication reference number for the biometric capture.",
"example": "UIDAI112233445",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Biometric eKYC completed successfully. Agent is now eligible for AePS transactions.",
"response_type_id": 1388,
"data": {
"kyc_status": "completed",
"aadhaar_ref_num": "UIDAI112233445"
}
}
},
"biometric_match_failed": {
"summary": "Biometric match failed",
"value": {
"status": 1,
"response_status_id": 108,
"message": "Biometric verification failed. Please retry with a fresh fingerprint scan.",
"data": {}
}
},
"otp_session_expired": {
"summary": "OTP session expired",
"value": {
"status": 1,
"response_status_id": 303,
"message": "OTP reference expired. Please restart the eKYC flow from Send OTP.",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhaar": {
"type": "string",
"description": "RSA-encrypted, Base64-encoded Aadhaar number of the agent.",
"example": "BASE64_ENCRYPTED_AADHAAR"
},
"piddata": {
"type": "string",
"description": "PID XML string from the UIDAI-certified biometric device (fType=2, Data type='X', mc in DeviceInfo).",
"example": "..."
},
"otp_ref_id": {
"type": "string",
"description": "Reference ID returned by the Send OTP (eKYC) API, linking this biometric capture to the verified OTP session.",
"example": "OTPREF20240101001"
}
},
"required": [
"initiator_id",
"user_code",
"aadhaar",
"piddata",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"aadhaar": "BASE64_ENCRYPTED_AADHAAR",
"piddata": "...",
"otp_ref_id": "OTPREF20240101001"
}
}
}
}
}
},
"/customer/payment/bbps/categories": {
"get": {
"operationId": "bbpsGetCategories",
"summary": "Get BBPS Categories",
"description": "Returns all active biller categories available on the BBPS network. Use the returned category_id to filter the Get Operators call. Categories include electricity, gas, water, DTH, broadband, prepaid recharge, FASTag, insurance, EMI payments, LPG booking, credit card, and more.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-get-categories",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"categories": {
"description": "List of all supported BBPS biller categories.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique category identifier (category_id). Pass as the `category` query param when filtering operators.",
"example": 5,
"type": "number"
},
"category_name": {
"description": "Human-readable category label.",
"example": "Electricity",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Success",
"response_type_id": 1388,
"data": {
"categories": [
{
"id": 1,
"category_name": "Prepaid"
},
{
"id": 2,
"category_name": "DTH"
},
{
"id": 4,
"category_name": "Postpaid"
},
{
"id": 5,
"category_name": "Electricity"
},
{
"id": 6,
"category_name": "Gas"
},
{
"id": 7,
"category_name": "Water"
},
{
"id": 8,
"category_name": "Broadband"
},
{
"id": 9,
"category_name": "Landline"
},
{
"id": 10,
"category_name": "Insurance"
},
{
"id": 11,
"category_name": "FASTag"
},
{
"id": 12,
"category_name": "LPG Booking"
},
{
"id": 13,
"category_name": "EMI Payments"
},
{
"id": 14,
"category_name": "Credit Card"
},
{
"id": 15,
"category_name": "Education"
},
{
"id": 16,
"category_name": "Metro"
},
{
"id": 17,
"category_name": "Municipal Corp"
}
]
}
}
}
}
}
}
}
}
}
},
"/customer/payment/bbps/locations": {
"get": {
"operationId": "bbpsGetLocations",
"summary": "Get BBPS Locations",
"description": "Returns all supported location (state) identifiers. Pass the returned location_id as the `location` query parameter in the Get Operators call to narrow results to a specific state or circle.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-get-locations",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"locations": {
"description": "List of supported state/location entries.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Location identifier to use as the `location` filter when querying operators.",
"example": 7,
"type": "number"
},
"location_name": {
"description": "State or circle name.",
"example": "Delhi",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Success",
"response_type_id": 1388,
"data": {
"locations": [
{
"id": 1,
"location_name": "Andhra Pradesh"
},
{
"id": 2,
"location_name": "Bihar"
},
{
"id": 3,
"location_name": "Gujarat"
},
{
"id": 4,
"location_name": "Karnataka"
},
{
"id": 5,
"location_name": "Maharashtra"
},
{
"id": 6,
"location_name": "Rajasthan"
},
{
"id": 7,
"location_name": "Delhi"
},
{
"id": 8,
"location_name": "Tamil Nadu"
},
{
"id": 9,
"location_name": "Uttar Pradesh"
},
{
"id": 10,
"location_name": "West Bengal"
}
]
}
}
}
}
}
}
}
}
}
},
"/customer/payment/bbps/operators": {
"get": {
"operationId": "bbpsGetOperators",
"summary": "Get BBPS Operators",
"description": "Returns every currently active BBPS biller. Use `category` and `location` query parameters to narrow results. The `billFetchResponse` flag on each operator tells you whether the Fetch Bill step is mandatory before payment. Operators that are temporarily disabled are excluded from the response — poll this endpoint periodically to keep your list fresh.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-get-operators",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"name": "category",
"in": "query",
"required": false,
"description": "Filter by category — use the `id` from Get Categories.",
"schema": {
"type": "number",
"description": "Filter by category — use the `id` from Get Categories.",
"example": 5
}
},
{
"name": "location",
"in": "query",
"required": false,
"description": "Filter by state/circle — use the `id` from Get Locations.",
"schema": {
"type": "number",
"description": "Filter by state/circle — use the `id` from Get Locations.",
"example": 7
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"operators": {
"description": "List of active BBPS billers matching the filters.",
"type": "array",
"items": {
"type": "object",
"properties": {
"operator_id": {
"description": "Unique operator identifier. Pass this value in Fetch Bill and Pay Bill requests.",
"example": 83,
"type": "number"
},
"operator_name": {
"description": "Display name of the biller.",
"example": "BSES Rajdhani",
"type": "string"
},
"category_id": {
"description": "Category this operator belongs to.",
"example": 5,
"type": "number"
},
"billFetchResponse": {
"description": "1 = must call Fetch Bill API before Pay Bill; 0 = can pay directly.",
"example": 1,
"type": "number"
},
"high_commission_channel": {
"description": "0 = instant settlement (default); 1 = delayed channel with higher commissions.",
"example": 0,
"type": "number"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Success",
"response_type_id": 1388,
"data": {
"operators": [
{
"operator_id": 83,
"operator_name": "BSES Rajdhani",
"category_id": 5,
"billFetchResponse": 1,
"high_commission_channel": 0
},
{
"operator_id": 84,
"operator_name": "BSES Yamuna",
"category_id": 5,
"billFetchResponse": 1,
"high_commission_channel": 0
},
{
"operator_id": 87,
"operator_name": "Tata Power Delhi Distribution",
"category_id": 5,
"billFetchResponse": 0,
"high_commission_channel": 0
}
]
}
}
}
}
}
}
}
}
}
},
"/customer/payment/bbps/operator/{operator_id}/parameters": {
"get": {
"operationId": "bbpsGetOperatorParameters",
"summary": "Get Operator Parameters",
"description": "Returns the operator-specific parameter schema — field names, labels, data types, and validation regex — needed to build a dynamic payment form. Also returns `fetchBill` (1 = mandatory Fetch Bill step) and `BBPS` (1 = show Bharat BillPay branding). Call this once per operator and cache the result.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-get-operator-parameters",
"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": "operator_id",
"in": "path",
"required": true,
"description": "The operator/biller ID from the Get Operators response.",
"schema": {
"type": "number",
"description": "The operator/biller ID from the Get Operators response.",
"example": 83
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"fetchBill": {
"description": "1 = Fetch Bill API must be called before Pay Bill; 0 = direct payment allowed.",
"example": 1,
"type": "number"
},
"BBPS": {
"description": "1 = biller is on the BBPS network; display the Bharat BillPay logo per NPCI guidelines.",
"example": 1,
"type": "number"
},
"data": {
"description": "List of input parameters required by this biller.",
"type": "array",
"items": {
"type": "object",
"properties": {
"param_name": {
"description": "API field name to send in the Fetch Bill / Pay Bill request.",
"example": "utility_acc_no",
"type": "string"
},
"param_label": {
"description": "UI label to display to the end user.",
"example": "Consumer Number",
"type": "string"
},
"param_type": {
"description": "Input type: Numeric, Decimal, AlphaNumeric, or List.",
"example": "Numeric",
"type": "string"
},
"regex": {
"description": "Regular expression to validate the user's input before submission.",
"example": "^[0-9]{10,12}$",
"type": "string"
},
"error_message": {
"description": "Validation error message to show when the regex does not match.",
"example": "Please enter a valid 10-12 digit consumer number.",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Success",
"response_type_id": 1388,
"data": {
"fetchBill": 1,
"BBPS": 1,
"data": [
{
"param_name": "utility_acc_no",
"param_label": "Consumer Number",
"param_type": "Numeric",
"regex": "^[0-9]{10,12}$",
"error_message": "Please enter a valid 10-12 digit consumer number."
}
]
}
}
}
}
}
}
}
}
}
},
"/customer/payment/bbps/bill": {
"get": {
"operationId": "bbpsFetchBill",
"summary": "Fetch BBPS Bill",
"description": "Fetches the live bill for a customer from the biller's system. Required for operators where `billFetchResponse = 1`. The response includes the outstanding amount, due date, and a `billfetchresponse` token that must be forwarded verbatim in the subsequent Pay Bill call. Pass `hc_channel=1` to use the higher-commission delayed channel.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-fetch-bill",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"name": "utility_acc_no",
"in": "query",
"required": true,
"description": "Customer's account / consumer number with the biller.",
"schema": {
"type": "string",
"description": "Customer's account / consumer number with the biller.",
"example": "1234567890"
}
},
{
"name": "confirmation_mobile_no",
"in": "query",
"required": true,
"description": "Customer's mobile number for transaction confirmation.",
"schema": {
"type": "string",
"description": "Customer's mobile number for transaction confirmation.",
"example": "9999988888"
}
},
{
"name": "sender_name",
"in": "query",
"required": true,
"description": "Customer's full name.",
"schema": {
"type": "string",
"description": "Customer's full name.",
"example": "Ramesh Kumar"
}
},
{
"name": "operator_id",
"in": "query",
"required": true,
"description": "Biller identifier from the Get Operators response.",
"schema": {
"type": "string",
"description": "Biller identifier from the Get Operators response.",
"example": "83"
}
},
{
"name": "source_ip",
"in": "query",
"required": true,
"description": "IP address of the agent or retailer making this request.",
"schema": {
"type": "string",
"description": "IP address of the agent or retailer making this request.",
"example": "192.168.1.1"
}
},
{
"name": "latlong",
"in": "query",
"required": true,
"description": "Agent's GPS coordinates as `latitude,longitude`. Mandatory for agent activation compliance.",
"schema": {
"type": "string",
"description": "Agent's GPS coordinates as `latitude,longitude`. Mandatory for agent activation compliance.",
"example": "28.6139,77.2090"
}
},
{
"name": "hc_channel",
"in": "query",
"required": false,
"description": "Payment channel: 0 = Instant (default), 1 = Delayed (higher commissions).",
"schema": {
"type": "number",
"description": "Payment channel: 0 = Instant (default), 1 = Delayed (higher commissions).",
"example": 0
}
},
{
"name": "dob",
"in": "query",
"required": false,
"description": "Date of birth of the policy holder in DD/MM/YYYY format. Required for LIC policies.",
"schema": {
"type": "string",
"description": "Date of birth of the policy holder in DD/MM/YYYY format. Required for LIC policies.",
"example": "15/08/1985"
}
},
{
"name": "cycle_number",
"in": "query",
"required": false,
"description": "Electricity bill cycle number. Required for MSEB billers.",
"schema": {
"type": "string",
"description": "Electricity bill cycle number. Required for MSEB billers.",
"example": "202406"
}
},
{
"name": "authenticator",
"in": "query",
"required": false,
"description": "MSEB portal password. Required for certain MSEB accounts.",
"schema": {
"type": "string",
"description": "MSEB portal password. Required for certain MSEB accounts.",
"example": "mypassword123"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"bill_amount": {
"description": "Outstanding bill amount in paise (divide by 100 for rupees).",
"example": "135000",
"type": "string"
},
"due_date": {
"description": "Bill due date returned by the biller.",
"example": "30/06/2024",
"type": "string"
},
"bill_number": {
"description": "Biller-assigned bill or reference number.",
"example": "BN20240601XYZ",
"type": "string"
},
"bill_date": {
"description": "Date the bill was generated.",
"example": "01/06/2024",
"type": "string"
},
"customer_name": {
"description": "Customer name as registered with the biller.",
"example": "Ramesh Kumar",
"type": "string"
},
"billfetchresponse": {
"description": "Opaque token from the biller's system. Must be passed as-is in the Pay Bill request body when the operator requires it.",
"example": "eyJhbGciOiJSUzI1NiJ9...",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Bill fetched successfully",
"response_type_id": 1388,
"data": {
"bill_amount": "135000",
"due_date": "30/06/2024",
"bill_number": "BN20240601XYZ",
"bill_date": "01/06/2024",
"customer_name": "Ramesh Kumar",
"billfetchresponse": "eyJhbGciOiJSUzI1NiJ9..."
}
}
},
"invalid_consumer_number_biller_returns_no_bill": {
"summary": "Invalid consumer number — biller returns no bill",
"value": {
"status": 1,
"response_status_id": 131,
"message": "Invalid account number. Please check and retry.",
"data": {}
}
},
"biller_system_unavailable": {
"summary": "Biller system unavailable",
"value": {
"status": 1,
"response_status_id": 151,
"message": "Biller system is temporarily unavailable. Please try again later.",
"data": {}
}
}
}
}
}
}
}
}
},
"/customer/payment/bbps": {
"post": {
"operationId": "bbpsPayBill",
"summary": "Pay BBPS Bill",
"description": "The core money-debit API that executes a bill payment or prepaid recharge on the BBPS network. For operators where `billFetchResponse = 1`, the `billfetchresponse` token returned by the Fetch Bill API must be included.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-pay-bill",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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 unique transaction identifier. Use this for status enquiry and dispute resolution.",
"example": "1734567890",
"type": "string"
},
"operator_ref_id": {
"description": "Reference number issued by the biller / BBPS network confirming receipt of payment.",
"example": "BBPS202406011234",
"type": "string"
},
"amount": {
"description": "Amount debited for this transaction.",
"example": "1350",
"type": "string"
},
"balance": {
"description": "Remaining wallet balance of the agent after this transaction.",
"example": "4820.50",
"type": "string"
},
"utility_acc_no": {
"description": "Consumer/account number against which the payment was made.",
"example": "1234567890",
"type": "string"
},
"client_ref_id": {
"description": "Your reference ID echoed back.",
"example": "BBPS-20240601-001",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Bill payment successful",
"response_type_id": 2,
"tx_status": "0",
"txstatus_desc": "Success",
"data": {
"tid": "1734567890",
"operator_ref_id": "BBPS202406011234",
"amount": "1350",
"balance": "4820.50",
"utility_acc_no": "1234567890",
"client_ref_id": "BBPS-20240601-001"
}
}
},
"insufficient_agent_wallet_balance": {
"summary": "Insufficient agent wallet balance",
"value": {
"status": 1,
"response_status_id": 347,
"message": "Insufficient balance.",
"tx_status": "1",
"txstatus_desc": "Fail",
"data": {}
}
},
"transaction_awaited_biller_not_confirmed_yet": {
"summary": "Transaction awaited — biller not confirmed yet",
"value": {
"status": 0,
"response_status_id": 0,
"message": "Transaction is being processed.",
"tx_status": "2",
"txstatus_desc": "Response Awaited",
"data": {
"tid": "1734567891",
"amount": "1350"
}
}
},
"amount_mismatch_pay_amount_differs_from_fetched_bill": {
"summary": "Amount mismatch — pay amount differs from fetched bill",
"value": {
"status": 1,
"response_status_id": 148,
"message": "Amount mismatch. Please fetch the bill again and retry.",
"tx_status": "1",
"txstatus_desc": "Fail",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"utility_acc_no": {
"type": "string",
"description": "Customer's account or consumer number with the biller.",
"example": "1234567890"
},
"confirmation_mobile_no": {
"type": "string",
"description": "Customer's mobile number for payment confirmation.",
"example": "9999988888"
},
"sender_name": {
"type": "string",
"description": "Customer's full name.",
"example": "Ramesh Kumar"
},
"operator_id": {
"type": "string",
"description": "Biller identifier from the Get Operators response.",
"example": "83"
},
"amount": {
"type": "string",
"description": "Payment amount in rupees (e.g. '1350' for ₹1,350).",
"example": "1350"
},
"source_ip": {
"type": "string",
"description": "IP address of the agent or retailer making this request.",
"example": "192.168.1.1"
},
"latlong": {
"type": "string",
"description": "Agent's GPS coordinates as `latitude,longitude`. Mandatory for agent activation compliance.",
"example": "28.6139,77.2090"
},
"billfetchresponse": {
"type": "string",
"description": "The opaque token returned by the Fetch Bill API. Required when the operator's `billFetchResponse = 1`.",
"example": "eyJhbGciOiJSUzI1NiJ9..."
},
"dob": {
"type": "string",
"description": "Date of birth of the policy holder in DD/MM/YYYY format. Required for LIC policy payments.",
"example": "15/08/1985"
},
"postalcode": {
"type": "number",
"description": "6-digit PIN code of the customer. Required for MSEB electricity payments.",
"example": 400001
}
},
"required": [
"initiator_id",
"user_code",
"utility_acc_no",
"confirmation_mobile_no",
"sender_name",
"operator_id",
"amount",
"source_ip",
"latlong"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"utility_acc_no": "1234567890",
"confirmation_mobile_no": "9999988888",
"sender_name": "Ramesh Kumar",
"operator_id": "83",
"amount": "1350",
"source_ip": "192.168.1.1",
"latlong": "28.6139,77.2090",
"billfetchresponse": "eyJhbGciOiJSUzI1NiJ9...",
"dob": "15/08/1985",
"postalcode": 400001
}
}
}
}
}
},
"/user/service/activate": {
"put": {
"operationId": "bbpsActivateService",
"summary": "Activate BBPS Service",
"description": "Before a retailer can process BBPS payments, the BBPS service (service_code = 53) must be activated for their `user_code`. This is a one-time setup call per agent. After activation, verify the status using the User Service Enquiry API. The agent's GPS coordinates (`latlong`) are mandatory for production compliance.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-activate-service",
"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": "Granular status id; see the shared error-codes table.",
"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_code": {
"description": "The service code that was activated.",
"example": 53,
"type": "number"
},
"service_status": {
"description": "Activation status for the service on the agent's account.",
"example": "activated",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "BBPS service activated successfully",
"response_type_id": 1388,
"data": {
"service_code": 53,
"service_status": "activated"
}
}
},
"service_already_activated_for_this_agent": {
"summary": "Service already activated for this agent",
"value": {
"status": 1,
"response_status_id": 17,
"message": "Service is already active for this user.",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"service_code": {
"type": "number",
"description": "Service identifier for BBPS. Always 53.",
"example": 53
},
"latlong": {
"type": "string",
"description": "Agent's GPS coordinates as `latitude,longitude`. Mandatory for BBPS agent activation.",
"example": "28.6139,77.2090"
}
},
"required": [
"initiator_id",
"user_code",
"service_code",
"latlong"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"service_code": 53,
"latlong": "28.6139,77.2090"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"pan_number": {
"type": "string",
"description": "10-character alphanumeric PAN identifier (5 letters, 4 digits, 1 letter).",
"example": "ABCDE1234F"
},
"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"
}
},
"required": [
"initiator_id",
"user_code",
"pan_number",
"name",
"dob"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": "Email address associated with the PAN. Fill rate is approximately 5–10% due to data-source availability.",
"example": "rajesh.kumar@example.com",
"type": "string"
},
"mobile_number": {
"description": "Mobile number associated with the PAN. Fill rate is approximately 5–10% due to data-source availability.",
"example": "9876543210",
"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": {
"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": "rajesh.kumar@example.com",
"mobile_number": "9876543210",
"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"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"pan": {
"type": "string",
"description": "10-character alphanumeric PAN identifier (first 5 alphabets, 4 digits, 1 alphabet).",
"example": "ABCDE1234F"
},
"name": {
"type": "string",
"description": "Individual's name per PAN information, used for match scoring.",
"example": "Rajesh Kumar"
},
"dob": {
"type": "string",
"description": "Date of birth in YYYY-MM-DD format.",
"example": "1994-08-29"
}
},
"required": [
"initiator_id",
"user_code",
"pan",
"name",
"dob"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"pan": "ABCDE1234F",
"name": "Rajesh Kumar",
"dob": "1994-08-29"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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"
}
}
}
}
}
}
},
"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.",
"example": "REQ-20260101-001"
},
"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": "REQ-20260101-001",
"entries": [
{
"pan": "ABCPV1234D",
"name": "John",
"source": "API"
},
{
"pan": "ABCPV1234L",
"name": "John Doe",
"source": "API"
}
]
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhar": {
"type": "string",
"description": "12-digit Aadhaar number of the sender.",
"example": "123456789012"
},
"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",
"user_code",
"aadhar",
"otp_ref_id",
"additional_info"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 123456,
"otp_ref_id": 93847201,
"intent_id": "20",
"additional_info": "1"
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/aadhaar/otp": {
"post": {
"operationId": "aadhaarPpiLevinValidate",
"summary": "Validate Aadhaar",
"description": "Triggers Aadhaar OTP dispatch for a PPI Levin wallet sender. Requires a `wallet_token` and `wallet_id` from the preceding Verify Sender OTP step. Returns an `otp_ref_id` to be used in the PPI Levin Validate OTP call.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "aadhaar-ppi-levin-validate",
"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": "Granular status id; see the shared error-codes table.",
"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 Aadhaar OTP session — pass to the PPI Levin Validate OTP call.",
"example": "66748392",
"type": "string"
},
"mobile_hint": {
"description": "Masked mobile number to which the Aadhaar OTP was dispatched.",
"example": "******3210",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Aadhaar OTP sent successfully",
"response_type_id": 1388,
"data": {
"otp_ref_id": "66748392",
"mobile_hint": "******3210"
}
}
},
"invalid_or_expired_wallet_token": {
"summary": "Invalid or expired wallet token",
"value": {
"status": 1,
"response_status_id": 463,
"message": "Invalid wallet token. Please re-authenticate the sender.",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhar": {
"type": "string",
"description": "12-digit Aadhaar number of the sender.",
"example": "123456789012"
},
"wallet_token": {
"type": "string",
"description": "Wallet authentication token returned from the Verify Sender OTP response.",
"example": "wtkn_abc123xyz"
},
"wallet_id": {
"type": "string",
"description": "Wallet identifier returned from the Verify Sender OTP response.",
"example": "wlt_0091234"
}
},
"required": [
"initiator_id",
"user_code",
"aadhar",
"wallet_token",
"wallet_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"aadhar": "123456789012",
"wallet_token": "wtkn_abc123xyz",
"wallet_id": "wlt_0091234"
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/aadhaar/otp/verify": {
"post": {
"operationId": "aadhaarPpiLevinVerifyOtp",
"summary": "Validate Aadhaar OTP",
"description": "Validates the OTP dispatched during the PPI Levin Aadhaar validation step. On success, the sender's Aadhaar identity is confirmed and their PPI Levin wallet profile is updated with verified KYC data. Wallet-level parameters `wallet_token` and `wallet_id` may be required.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "aadhaar-ppi-levin-verify-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": "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": "Granular status id; see the shared error-codes table.",
"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 verification was successful.",
"example": true,
"type": "boolean"
},
"name": {
"description": "Verified sender name from Aadhaar.",
"example": "Sneha Patel",
"type": "string"
},
"gender": {
"description": "Gender from Aadhaar record: M, F, or T.",
"example": "F",
"type": "string"
},
"dob": {
"description": "Date of birth as per Aadhaar.",
"example": "05-07-1992",
"type": "string"
},
"masked_aadhaar": {
"description": "Aadhaar number with first 8 digits masked.",
"example": "XXXX-XXXX-7890",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Aadhaar OTP verified successfully",
"response_type_id": 1388,
"data": {
"verified": true,
"name": "Sneha Patel",
"gender": "F",
"dob": "05-07-1992",
"masked_aadhaar": "XXXX-XXXX-7890"
}
}
},
"wrong_otp": {
"summary": "Wrong OTP",
"value": {
"status": 1,
"response_status_id": 302,
"message": "Wrong OTP. Please check and retry.",
"response_type_id": 1388,
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"otp": {
"type": "integer",
"description": "OTP received on the Aadhaar-linked mobile number.",
"example": 654321
},
"otp_ref_id": {
"type": "integer",
"description": "Reference ID from the PPI Levin Validate Aadhaar response.",
"example": 66748392
},
"intent_id": {
"type": "string",
"description": "Intent flag: \"19\" for sender onboarding, \"20\" for Aadhaar validation.",
"example": "20"
},
"wallet_token": {
"type": "string",
"description": "Wallet token for authenticated context.",
"example": "wtkn_abc123xyz"
},
"wallet_id": {
"type": "string",
"description": "Wallet identifier for the sender.",
"example": "wlt_0091234"
}
},
"required": [
"initiator_id",
"user_code",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 654321,
"otp_ref_id": 66748392,
"intent_id": "20",
"wallet_token": "wtkn_abc123xyz",
"wallet_id": "wlt_0091234"
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}": {
"get": {
"operationId": "ppiLevinGetSender",
"summary": "Get Sender Information",
"description": "First step of the PPI Levin flow. For an enrolled sender the response returns an `otp_ref_id` and asks you to validate the OTP (call Verify Sender OTP). If the customer is not enrolled (response_type_id 308), proceed to Onboard Sender.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-get-sender",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next onboarding/validation step (19 = sender onboarding).",
"example": 19,
"type": "number"
},
"kyc_request_id": {
"description": "KYC request reference, when a KYC step is pending.",
"example": "",
"type": "string"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Sender OTP.",
"example": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94Yii3g+9fOBmbMsVTuaEQpDOEateP4tSTkQw==",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94Yii3g+9fOBmbMsVTuaEQpDOEateP4tSTkQw=="
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 2129
}
},
"customer_not_enrolled_proceed_to_onboard_sender": {
"summary": "Customer not enrolled — proceed to Onboard Sender",
"value": {
"response_status_id": 1,
"data": {
"sender_name": "",
"ekyc_enabled": ""
},
"response_type_id": 308,
"message": "Failure!Customer Not Enrolled",
"status": 308
}
}
}
}
}
}
}
},
"post": {
"operationId": "ppiLevinOnboardSender",
"summary": "Onboard Sender",
"description": "Registers a new PPI Levin sender. Provide name, date of birth, and residence address. On success an OTP is dispatched and an `otp_ref_id` returned — call Verify Sender OTP next.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-onboard-sender",
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next step (19 = sender onboarding).",
"example": 19,
"type": "number"
},
"kyc_request_id": {
"description": "KYC request reference, when a KYC step is pending.",
"example": "",
"type": "string"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Sender OTP.",
"example": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94YigSXr5Qr+aS8OTg/e0YrVEoPAbap746K5g==",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94YigSXr5Qr+aS8OTg/e0YrVEoPAbap746K5g=="
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 2129
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"name": {
"type": "string",
"description": "Name of the sender as per ID.",
"example": "Shobhit"
},
"dob": {
"type": "string",
"description": "Date of birth of the sender in YYYY-MM-DD format.",
"example": "1990-05-15"
},
"residence_address": {
"type": "string",
"description": "Sender's address as an array of strings.",
"example": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
]
},
"service_code": {
"type": "integer",
"description": "Fixed service code. Send 80.",
"example": 80
}
},
"required": [
"initiator_id",
"user_code",
"name",
"dob",
"residence_address"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"name": "Shobhit",
"dob": "1990-05-15",
"residence_address": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
],
"service_code": 80
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/otp/verify": {
"post": {
"operationId": "ppiLevinVerifyOtp",
"summary": "Verify Sender OTP",
"description": "Validates the OTP issued by Get Sender Information / Onboard Sender. For an existing sender the response returns the full wallet `customer_profile` (limits, balance, KYC state) and a `wallet_token` used by downstream calls. For a new customer the flow continues to Aadhaar validation (Aadhar Validation Pending) and then PAN (Pan Number Required).",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-verify-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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_profile": {
"description": "Sender's wallet profile — limits, balance, KYC state, and usage chart.",
"type": "object",
"properties": {
"name": {
"description": "Registered name of the sender.",
"example": "Shobhit",
"type": "string"
},
"mobile": {
"description": "Sender's mobile number.",
"example": "9444444444",
"type": "string"
},
"total_monthly_limit": {
"description": "Total monthly transfer limit (INR).",
"example": "50000",
"type": "string"
},
"next_allowed_limit": {
"description": "Remaining transfer limit for the period (INR).",
"example": "50000.0",
"type": "string"
},
"balance": {
"description": "Current wallet balance (INR).",
"example": "0.00",
"type": "string"
},
"ekyc_enabled": {
"description": "Whether biometric eKYC is enabled (1) or not (0).",
"example": 0,
"type": "number"
},
"kyc_state": {
"description": "KYC completion state.",
"example": 0,
"type": "number"
},
"chart": {
"description": "Usage breakdown (used / remaining / unavailable).",
"type": "array",
"items": {
"type": "object",
"properties": {
"data_type_id": {
"description": "Chart data type identifier.",
"example": 10,
"type": "number"
},
"data": {
"description": "Used / remaining / unavailable amounts.",
"type": "object",
"properties": {
"used": {
"description": "Amount used in the period (INR).",
"example": 0,
"type": "number"
},
"remaining": {
"description": "Amount remaining in the period (INR).",
"example": 50000,
"type": "number"
},
"unavailable": {
"description": "Amount blocked/unavailable (INR).",
"example": 0,
"type": "number"
}
}
}
}
}
}
}
},
"wallet_token": {
"description": "Wallet authentication token (JWT) required by downstream PPI Levin calls.",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJZGVudGlmaWNhdGlvbkNvZGUiOiJQaFY2Wkc1QjMzRDE2NzZWZGhKTStBPT0iLCJCQ0FnZW50SWQiOiJxYkxIdm1LMDBYU1NTcS9rL0tSN0pBPT0iLCJleHAiOjE3NDg0MTg0OTIsImlzcyI6IlBheVBvaW50IiwiYXVkIjoiUGFydG5lcnMifQ.ylDVDuNjIymfjBE9jB0ZU0Lqhvj67AWRQ_dC76HOHbA",
"type": "string"
},
"is_registered": {
"description": "Whether the sender is already fully registered.",
"example": 0,
"type": "number"
},
"next_allowed_limit": {
"description": "Remaining transfer limit at the top level (INR).",
"example": 50000,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": -1,
"data": {
"customer_profile": {
"total_monthly_limit": "50000",
"mobile": "9444444444",
"kyc_id": "",
"ekyc_enabled": 0,
"kyc_validity": "",
"kyc_remark": "",
"kyc_type": "",
"balance": "0.00",
"next_allowed_limit": "50000.0",
"name": "Shobhit",
"digital_ekyc": 0,
"chart": [
{
"data_type_id": 10,
"data": {
"unavailable": 0,
"used": 0,
"remaining": 50000
},
"label": ""
}
],
"email": "",
"kyc_state": 0
},
"wallet_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJZGVudGlmaWNhdGlvbkNvZGUiOiJQaFY2Wkc1QjMzRDE2NzZWZGhKTStBPT0iLCJCQ0FnZW50SWQiOiJxYkxIdm1LMDBYU1NTcS9rL0tSN0pBPT0iLCJleHAiOjE3NDg0MTg0OTIsImlzcyI6IlBheVBvaW50IiwiYXVkIjoiUGFydG5lcnMifQ.ylDVDuNjIymfjBE9jB0ZU0Lqhvj67AWRQ_dC76HOHbA",
"id_proof_type_id": "",
"is_registered": 0,
"id_proof": "",
"otpOptionalSum": "",
"sender_name": "",
"otpNotRequiredSum": "",
"ekyc_enabled": "",
"wallet_id": "",
"otpNotRequiredSumNeft": "",
"next_allowed_limit": 50000,
"kyc_state": 0,
"otpOptionalSumNeft": ""
},
"response_type_id": 309,
"message": "Success!",
"status": 0
}
},
"new_customer_aadhaar_validation_pending": {
"summary": "New customer — Aadhaar validation pending",
"value": {
"response_status_id": 1,
"response_type_id": 2136,
"message": "Aadhar Validation Pending",
"status": 2136
}
},
"aadhaar_validated_pan_required_next": {
"summary": "Aadhaar validated — PAN required next",
"value": {
"response_status_id": 0,
"data": {
"application_id": ""
},
"response_type_id": 2147,
"message": "Pan Number Required",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"otp": {
"type": "integer",
"description": "OTP received from Get Sender Information, Onboard Sender, or Validate Aadhaar.",
"example": 123456
},
"otp_ref_id": {
"type": "integer",
"description": "otp_ref_id received from Get Sender Information, Onboard Sender, or Validate Aadhaar.",
"example": 66748392
},
"intent_id": {
"type": "string",
"description": "Intent flag: \"19\" for sender onboarding, \"20\" for Aadhaar validation.",
"example": "19"
}
},
"required": [
"initiator_id",
"user_code",
"otp",
"otp_ref_id",
"intent_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 123456,
"otp_ref_id": 66748392,
"intent_id": "19"
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/pan": {
"post": {
"operationId": "ppiLevinValidatePan",
"summary": "Validate PAN",
"description": "Submits the sender's PAN to finish PPI Levin onboarding KYC. On success the response returns the updated `customer_profile` (with the verified sender name and recalculated limits).",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-validate-pan",
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_profile": {
"description": "Updated wallet profile with verified sender name and recalculated limits.",
"type": "object",
"properties": {
"name": {
"description": "Verified registered name of the sender.",
"example": "Karan Garg",
"type": "string"
},
"next_allowed_limit": {
"description": "Remaining transfer limit for the period (INR).",
"example": "5287.0",
"type": "string"
},
"balance": {
"description": "Current wallet balance (INR).",
"example": "0.00",
"type": "string"
}
}
},
"sender_name": {
"description": "Verified name of the sender.",
"example": "Karan Garg",
"type": "string"
},
"next_allowed_limit": {
"description": "Remaining transfer limit at the top level (INR).",
"example": 5287,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": -1,
"data": {
"customer_profile": {
"total_monthly_limit": "50000.0",
"mobile": "9444444444",
"kyc_id": "",
"ekyc_enabled": 0,
"kyc_validity": "",
"kyc_remark": "",
"kyc_type": "",
"balance": "0.00",
"next_allowed_limit": "5287.0",
"name": "Karan Garg",
"digital_ekyc": 0,
"chart": [
{
"data_type_id": 10,
"data": {
"unavailable": 0,
"used": 44713,
"remaining": 5287
},
"label": ""
}
],
"email": "",
"kyc_state": 0
},
"id_proof_type_id": "",
"is_registered": 0,
"id_proof": "",
"otpOptionalSum": "",
"sender_name": "Karan Garg",
"otpNotRequiredSum": "",
"ekyc_enabled": "",
"otpNotRequiredSumNeft": "",
"next_allowed_limit": 5287,
"account": "",
"kyc_state": 0,
"otpOptionalSumNeft": ""
},
"response_type_id": 309,
"message": "Success!",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"pan_number": {
"type": "string",
"description": "The PAN number of the sender.",
"example": "ABCDE1234F"
},
"wallet_id": {
"type": "string",
"description": "Wallet identifier, when applicable.",
"example": ""
},
"wallet_token": {
"type": "string",
"description": "Wallet authentication token, when applicable.",
"example": ""
}
},
"required": [
"initiator_id",
"user_code"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"pan_number": "ABCDE1234F",
"wallet_id": "",
"wallet_token": ""
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/recipients": {
"get": {
"operationId": "ppiLevinGetRecipients",
"summary": "Get List of Recipients",
"description": "Returns every recipient saved under a PPI Levin sender, with bank/account details, verification status, available channels (IMPS/NEFT), and the sender's remaining limit before PAN becomes mandatory.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-get-recipients",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "9444444444"
}
},
{
"name": "wallet_token",
"in": "query",
"required": false,
"description": "Wallet authentication token, when applicable.",
"schema": {
"type": "string",
"description": "Wallet authentication token, when applicable.",
"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": "Granular status id; see the shared error-codes table.",
"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": "Whether PAN is required to continue transacting (2 = not yet required).",
"example": 2,
"type": "number"
},
"remaining_limit_before_pan_required": {
"description": "Amount the sender can still transfer before PAN is required (INR).",
"example": 50000,
"type": "number"
},
"recipient_list": {
"description": "Saved beneficiaries for this sender.",
"type": "array",
"items": {
"type": "object",
"properties": {
"recipient_id": {
"description": "Unique recipient identifier — use to transact.",
"example": 10018839,
"type": "number"
},
"recipient_name": {
"description": "Beneficiary's name.",
"example": "Aditya",
"type": "string"
},
"recipient_mobile": {
"description": "Beneficiary's mobile number.",
"example": "9999999990",
"type": "string"
},
"bank": {
"description": "Beneficiary's bank name.",
"example": "Kotak Mahindra Bank",
"type": "string"
},
"account": {
"description": "Masked beneficiary account number.",
"example": "1XXXXXX90657",
"type": "string"
},
"ifsc": {
"description": "Beneficiary branch IFSC.",
"example": "KKBK0000878",
"type": "string"
},
"beneficiary_id": {
"description": "Beneficiary identifier, when bank-registered.",
"example": 40378,
"type": "number"
},
"channel": {
"description": "Allowed transfer channel (0 = IMPS, 2 = NEFT).",
"example": 0,
"type": "number"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"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": "Madness",
"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
}
}
}
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/recipient": {
"post": {
"operationId": "ppiLevinAddRecipient",
"summary": "Add Recipient",
"description": "Adds a beneficiary (bank account) to a PPI Levin sender. On success a `recipient_id` is returned — use it to send transaction OTP and initiate the transfer. Maximum 5 recipients per day.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-add-recipient",
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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 to transact.",
"example": 10017740,
"type": "number"
},
"recipient_mobile": {
"description": "Recipient's mobile number (echoed back).",
"example": "9775597777",
"type": "string"
},
"customer_id": {
"description": "Sender's mobile number (echoed back).",
"example": "9444444444",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"initiator_id": "6000000094",
"recipient_mobile": "9775597777",
"recipient_id_type": "",
"customer_id": "9444444444",
"pipes": {},
"recipient_id": 10017740
},
"response_type_id": 43,
"message": "Success!Please transact using Recipientid",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_id": {
"type": "integer",
"description": "Unique ID assigned to the beneficiary's bank.",
"example": 12
},
"recipient_name": {
"type": "string",
"description": "Full name of the recipient.",
"example": "Aditya"
},
"recipient_mobile": {
"type": "string",
"description": "Recipient's 10-digit mobile number.",
"example": "9775597777"
},
"recipient_type": {
"type": "string",
"description": "Recipient type. Value will be 3.",
"example": "3"
},
"account": {
"type": "string",
"description": "Recipient's bank account number.",
"example": "1234567890657"
},
"ifsc": {
"type": "string",
"description": "IFSC code of the recipient's bank branch.",
"example": "KKBK0000878"
},
"type": {
"type": "string",
"description": "Recipient identifier type. Defaults to `ifsc`.",
"example": "ifsc"
},
"account_type": {
"type": "string",
"description": "Account type. Defaults to 1.",
"example": "1"
}
},
"required": [
"initiator_id",
"user_code",
"bank_id",
"recipient_name",
"recipient_mobile",
"recipient_type",
"account",
"ifsc"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_id": 12,
"recipient_name": "Aditya",
"recipient_mobile": "9775597777",
"recipient_type": "3",
"account": "1234567890657",
"ifsc": "KKBK0000878",
"type": "ifsc",
"account_type": "1"
}
}
}
}
}
},
"/customer/payment/ppi-levin/sender/{customer_id}/bank/recipient": {
"post": {
"operationId": "ppiLevinAddRecipientBank",
"summary": "Add Recipient Bank",
"description": "Adds bank details for a recipient, returning a `beneficiary_id` used when initiating NEFT/IMPS transfers to that recipient.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-add-recipient-bank",
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"beneficiary_id": {
"description": "Beneficiary identifier — pass when initiating a transfer.",
"example": "40367",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"beneficiary_id": "40367",
"recipient_name": "",
"ifsc": "",
"account": "",
"recipient_id": ""
},
"response_type_id": 1741,
"message": "Beneficiary added",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "string",
"description": "Recipient ID of the recipient.",
"example": "10017740"
},
"wallet_token": {
"type": "string",
"description": "Wallet authentication token, when applicable.",
"example": ""
}
},
"required": [
"initiator_id",
"user_code"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": "10017740",
"wallet_token": ""
}
}
}
}
}
},
"/customer/payment/ppi-levin/otp": {
"post": {
"operationId": "ppiLevinSendTransactionOtp",
"summary": "Send Transaction OTP",
"description": "Dispatches an OTP to the sender for an upcoming transfer to a given recipient and amount. Returns an `otp_ref_id` to pass, with the OTP, into Initiate Transaction.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-send-transaction-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": "Granular status id; see the shared error-codes table.",
"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 Transaction.",
"example": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY="
},
"response_type_id": 2133,
"message": "Send OTP",
"status": 2133
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "integer",
"description": "Unique ID generated while adding the recipient.",
"example": 10017740
},
"amount": {
"type": "integer",
"description": "Amount to be transferred (INR).",
"example": 110
},
"customer_id": {
"type": "string",
"description": "Sender's 10-digit mobile number.",
"example": "9444444444"
},
"service_code": {
"type": "integer",
"description": "Fixed service code. Send 80.",
"example": 80
},
"beneficiary_id": {
"type": "string",
"description": "Beneficiary ID generated when adding the recipient's bank.",
"example": "40367"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_id",
"amount",
"customer_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": 10017740,
"amount": 110,
"customer_id": "9444444444",
"service_code": 80,
"beneficiary_id": "40367"
}
}
}
}
}
},
"/customer/payment/ppi-levin": {
"post": {
"operationId": "ppiLevinInitiateTransaction",
"summary": "Initiate Transaction",
"description": "Initiates the money transfer from the sender's PPI Levin wallet to the recipient. Returns the financial response envelope with `tx_status`, transaction id (`tid`), bank reference number, fee, and updated balance.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-levin-initiate-transaction",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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.",
"example": "2886522975",
"type": "string"
},
"tx_status": {
"description": "Transaction status (0 = success).",
"example": "0",
"type": "string"
},
"txstatus_desc": {
"description": "Human-readable transaction status.",
"example": "Success",
"type": "string"
},
"bank_ref_num": {
"description": "Bank/UTR reference number for the transfer.",
"example": "250121123714472002",
"type": "string"
},
"amount": {
"description": "Transferred amount (INR).",
"example": "110.00",
"type": "string"
},
"fee": {
"description": "Fee charged for the transfer (INR).",
"example": "4.0",
"type": "string"
},
"balance": {
"description": "Sender's wallet balance after the transfer (INR).",
"example": "814.0",
"type": "string"
},
"bank": {
"description": "Recipient's bank name.",
"example": "UCO Bank",
"type": "string"
},
"channel_desc": {
"description": "Channel used (IMPS/NEFT).",
"example": "IMPS",
"type": "string"
},
"recipient_name": {
"description": "Recipient's name.",
"example": "Krishna",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"tx_status": "0",
"debit_user_id": "6000000094",
"tds": "0.0",
"txstatus_desc": "Success",
"fee": "4.0",
"total_sent": "",
"channel": "2",
"collectable_amount": "114.0",
"txn_wallet": "0",
"utility_acc_no": "8999999992",
"sender_name": "8999999992",
"ekyc_enabled": "0",
"remaining_limit_before_pan_required": 49678,
"tid": "2886522975",
"bank": "UCO Bank",
"utrnumber": "",
"insurance_acquired": "",
"balance": "814.0",
"totalfee": "",
"next_allowed_limit": "",
"is_otp_required": "0",
"aadhar": "",
"currency": "INR",
"commission": "0.0",
"pipe": 13,
"state": "1",
"bank_ref_num": "250121123714472002",
"recipient_id": 10017680,
"timestamp": "2025-01-21T07:07:20.562Z",
"amount": "110.00",
"pan_required": 2,
"pinNo": "",
"gst_benefit": "0",
"payment_mode_desc": "",
"channel_desc": "IMPS",
"last_used_okekey": "0",
"npr": "",
"insurance_amount": "",
"service_tax": "0.61",
"paymentid": "",
"mdr": "",
"recipient_name": "Krishna",
"customer_id": "8999999992",
"account": "67544100008454",
"kyc_state": ""
},
"response_type_id": 325,
"message": "Transaction successful",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "integer",
"description": "Unique ID generated while adding the recipient.",
"example": 10017680
},
"amount": {
"type": "integer",
"description": "Amount to be transferred (INR).",
"example": 110
},
"timestamp": {
"type": "string",
"description": "Request timestamp (ISO 8601).",
"example": "2025-01-21T07:07:20.562Z"
},
"currency": {
"type": "string",
"description": "Currency. Must be INR.",
"example": "INR"
},
"customer_id": {
"type": "string",
"description": "Sender's 10-digit mobile number.",
"example": "8999999992"
},
"channel": {
"type": "integer",
"description": "Transfer channel. Defaults to 2 (NEFT); 0 for IMPS.",
"example": 2
},
"otp": {
"type": "string",
"description": "OTP received from Send Transaction OTP.",
"example": "123456"
},
"otp_ref_id": {
"type": "string",
"description": "otp_ref_id received from Send Transaction OTP.",
"example": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY="
},
"beneficiary_id": {
"type": "string",
"description": "Beneficiary ID generated while getting the recipient details.",
"example": "40367"
},
"latlong": {
"type": "string",
"description": "Geographic coordinates of the user's location.",
"example": "28.63,77.22"
},
"state": {
"type": "string",
"description": "State parameter.",
"example": "1"
},
"recipient_id_type": {
"type": "string",
"description": "Recipient ID type. Defaults to 1.",
"example": "1"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_id",
"amount",
"timestamp",
"currency",
"customer_id",
"channel"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": 10017680,
"amount": 110,
"timestamp": "2025-01-21T07:07:20.562Z",
"currency": "INR",
"customer_id": "8999999992",
"channel": 2,
"otp": "123456",
"otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=",
"beneficiary_id": "40367",
"latlong": "28.63,77.22",
"state": "1",
"recipient_id_type": "1"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}": {
"get": {
"operationId": "ppiDigikhataGetSender",
"summary": "Get Sender Information",
"description": "First step of the PPI DigiKhata flow. For an enrolled sender the response returns an `otp_ref_id` and asks you to validate the OTP (call Verify Sender OTP). If the customer is not enrolled (response_type_id 308), proceed to Onboard Sender.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-get-sender",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next onboarding/validation step (19 = sender onboarding).",
"example": 19,
"type": "number"
},
"kyc_request_id": {
"description": "KYC request reference, when a KYC step is pending.",
"example": "",
"type": "string"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Sender OTP.",
"example": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94Yii3g+9fOBmbMsVTuaEQpDOEateP4tSTkQw==",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94Yii3g+9fOBmbMsVTuaEQpDOEateP4tSTkQw=="
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 2129
}
},
"customer_not_enrolled_proceed_to_onboard_sender": {
"summary": "Customer not enrolled — proceed to Onboard Sender",
"value": {
"response_status_id": 1,
"data": {
"sender_name": "",
"ekyc_enabled": ""
},
"response_type_id": 308,
"message": "Failure!Customer Not Enrolled",
"status": 308
}
}
}
}
}
}
}
},
"post": {
"operationId": "ppiDigikhataOnboardSender",
"summary": "Onboard Sender",
"description": "Registers a new DigiKhata sender. Provide name, date of birth, and residence address. For a new sender an OTP is dispatched and an `otp_ref_id` returned — call Verify Sender OTP next. If the wallet already exists the response confirms `Wallet opened successfully`.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-onboard-sender",
"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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next step (19 = sender onboarding).",
"example": 19,
"type": "number"
},
"kyc_request_id": {
"description": "KYC request reference, when a KYC step is pending.",
"example": "",
"type": "string"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Sender OTP.",
"example": "leSLbMTFJpWWyG+NIDZW1IM6D+1tVJ6hgzp33AcOnMOJNPmRic8dJQazrKttIV3oIOpXKP8OdkARMo2DvP8bWEKK2P3h2dAK",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "leSLbMTFJpWWyG+NIDZW1IM6D+1tVJ6hgzp33AcOnMOJNPmRic8dJQazrKttIV3oIOpXKP8OdkARMo2DvP8bWEKK2P3h2dAK"
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 0
}
},
"wallet_already_exists_for_this_sender": {
"summary": "Wallet already exists for this sender",
"value": {
"response_status_id": 0,
"data": {
"customer_id_type": "mobile_number",
"state_desc": "Non-Kyc",
"state": "2",
"customer_id": "8617567988"
},
"response_type_id": 300,
"message": "Wallet opened successfully.",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"name": {
"type": "string",
"description": "Name of the sender as per ID.",
"example": "Yashwant Basnett"
},
"dob": {
"type": "string",
"description": "Date of birth of the sender in YYYY-MM-DD format.",
"example": "1990-05-15"
},
"residence_address": {
"type": "string",
"description": "Sender's address as an array of strings.",
"example": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
]
}
},
"required": [
"initiator_id",
"user_code",
"name",
"dob",
"residence_address"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"name": "Yashwant Basnett",
"dob": "1990-05-15",
"residence_address": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
]
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/otp": {
"post": {
"operationId": "ppiDigikhataGenerateSenderOtp",
"summary": "Generate Sender Verification OTP",
"description": "Generates and dispatches a verification OTP to the sender. Returns an `otp_ref_id` to pass, with the OTP, into Verify Sender OTP.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-generate-sender-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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next step (19 = sender onboarding).",
"example": 19,
"type": "number"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Sender OTP.",
"example": "leSLbMTFJpWWyG+NIDZW1IM6D+1tVJ6haUuWCwcbJVCWUgeMOoj5vNqXAGuOK+Cro+AqdfLdmm5z5AQ+PGkPdHUQJ9nuLPKS",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "leSLbMTFJpWWyG+NIDZW1IM6D+1tVJ6haUuWCwcbJVCWUgeMOoj5vNqXAGuOK+Cro+AqdfLdmm5z5AQ+PGkPdHUQJ9nuLPKS"
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
}
},
"required": [
"initiator_id",
"user_code"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/otp/verify": {
"post": {
"operationId": "ppiDigikhataVerifyOtp",
"summary": "Verify Sender OTP",
"description": "Validates the OTP issued by Get Sender Information / Onboard Sender / Generate Sender OTP. For an existing sender the response returns the full wallet `customer_profile` (limits, balance, KYC state). For a new sender the flow continues to Aadhaar validation (Aadhar Validation Pending).",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-verify-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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_profile": {
"description": "Sender's wallet profile — limits, balance, KYC state, and usage chart.",
"type": "object",
"properties": {
"name": {
"description": "Registered name of the sender.",
"example": "Yashwant Basnett",
"type": "string"
},
"mobile": {
"description": "Sender's mobile number.",
"example": "8617567988",
"type": "string"
},
"total_monthly_limit": {
"description": "Total monthly transfer limit (INR).",
"example": "50000.0",
"type": "string"
},
"next_allowed_limit": {
"description": "Remaining transfer limit for the period (INR).",
"example": "50000.0",
"type": "string"
},
"balance": {
"description": "Current wallet balance (INR).",
"example": "0.00",
"type": "string"
},
"kyc_state": {
"description": "KYC completion state.",
"example": 1,
"type": "number"
}
}
},
"sender_name": {
"description": "Registered name of the sender.",
"example": "Yashwant Basnett",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": -1,
"data": {
"customer_profile": {
"total_monthly_limit": "50000.0",
"mobile": "8617567988",
"kyc_id": "",
"ekyc_enabled": 0,
"kyc_validity": "",
"kyc_remark": "",
"kyc_type": "",
"balance": "0.00",
"next_allowed_limit": "50000.0",
"name": "Yashwant Basnett",
"digital_ekyc": 0,
"chart": [
{
"data_type_id": 10,
"data": {
"unavailable": 0,
"used": 0,
"remaining": 50000
},
"label": ""
}
],
"email": "",
"kyc_state": 1
},
"wallet_token": "",
"id_proof_type_id": "",
"is_registered": 0,
"id_proof": "",
"otpOptionalSum": "",
"sender_name": "Yashwant Basnett",
"otpNotRequiredSum": "",
"ekyc_enabled": "",
"wallet_id": "",
"otpNotRequiredSumNeft": "",
"next_allowed_limit": 50000,
"account": "",
"kyc_state": 0,
"otpOptionalSumNeft": ""
},
"response_type_id": 309,
"message": "Success!",
"status": 0
}
},
"new_sender_aadhaar_validation_pending": {
"summary": "New sender — Aadhaar validation pending",
"value": {
"response_status_id": 1,
"data": {
"otp_ref_id": ""
},
"response_type_id": 2136,
"message": "Aadhar Validation Pending",
"status": 2136
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"otp": {
"type": "integer",
"description": "OTP received from Get Sender Information, Onboard Sender, or Generate Sender OTP.",
"example": 123456
},
"otp_ref_id": {
"type": "integer",
"description": "otp_ref_id received from Get Sender Information, Onboard Sender, or Generate Sender OTP.",
"example": 66748392
}
},
"required": [
"initiator_id",
"user_code",
"otp",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 123456,
"otp_ref_id": 66748392
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/aadhaar/consent/languages": {
"get": {
"operationId": "ppiDigikhataConsentLanguages",
"summary": "Get Aadhaar KYC Consent Languages",
"description": "Returns the supported consent languages (with their `pkid`) for DigiKhata Aadhaar e-KYC. Pass the chosen `pkid` as `consent_language` to Get Aadhaar KYC Consent Details.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-consent-languages",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "8617567988"
}
},
{
"name": "org_id",
"in": "query",
"required": true,
"description": "Organisation identifier. Defaults to 1.",
"schema": {
"type": "string",
"description": "Organisation identifier. Defaults to 1.",
"example": "1"
}
},
{
"name": "client_ref_id",
"in": "query",
"required": true,
"description": "Unique reference identifier for the request.",
"schema": {
"type": "string",
"description": "Unique reference identifier for the request.",
"example": "ref_20250121_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": "Granular status id; see the shared error-codes table.",
"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": {
"consent_language_list": {
"description": "Supported consent languages.",
"type": "array",
"items": {
"type": "object",
"properties": {
"pkid": {
"description": "Language identifier — pass as consent_language to Get Consent Details.",
"example": "1",
"type": "string"
},
"consentLanguage": {
"description": "Display name of the language.",
"example": "English",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"consent_language_list": [
{
"pkid": "1",
"consentLanguage": "English"
},
{
"pkid": "2",
"consentLanguage": "Bengali"
},
{
"pkid": "3",
"consentLanguage": "Gujarati"
},
{
"pkid": "4",
"consentLanguage": "Hindi"
},
{
"pkid": "5",
"consentLanguage": "Kannada"
},
{
"pkid": "6",
"consentLanguage": "Malayalam"
},
{
"pkid": "7",
"consentLanguage": "Marathi"
},
{
"pkid": "8",
"consentLanguage": "Odia"
},
{
"pkid": "9",
"consentLanguage": "Tamil"
},
{
"pkid": "10",
"consentLanguage": "Telugu"
},
{
"pkid": "11",
"consentLanguage": "Urdu"
},
{
"pkid": "12",
"consentLanguage": "Assamese"
},
{
"pkid": "13",
"consentLanguage": "Punjabi"
}
]
},
"response_type_id": 2444,
"message": "Consent Language Successfully Retrieved",
"status": 0
}
}
}
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/aadhaar/consent/details": {
"get": {
"operationId": "ppiDigikhataConsentDetails",
"summary": "Get Aadhaar KYC Consent Details",
"description": "Returns the full Aadhaar e-KYC consent content, short consent statement, and an audio URL for the language selected (via `consent_language` = the `pkid` from Get Aadhaar KYC Consent Languages). Display/play this consent before collecting Aadhaar OTP.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-consent-details",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "8617567988"
}
},
{
"name": "org_id",
"in": "query",
"required": true,
"description": "Organisation identifier. Defaults to 1.",
"schema": {
"type": "string",
"description": "Organisation identifier. Defaults to 1.",
"example": "1"
}
},
{
"name": "client_ref_id",
"in": "query",
"required": true,
"description": "Unique reference identifier for the request.",
"schema": {
"type": "string",
"description": "Unique reference identifier for the request.",
"example": "ref_20250121_001"
}
},
{
"name": "consent_language",
"in": "query",
"required": true,
"description": "The pkid from Get Aadhaar KYC Consent Languages.",
"schema": {
"type": "string",
"description": "The pkid from Get Aadhaar KYC Consent Languages.",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"consent_detail": {
"description": "Consent content, short statement, and audio URL.",
"type": "object",
"properties": {
"consentContent": {
"description": "Full Aadhaar e-KYC consent text.",
"example": "Use my Aadhaar / Virtual ID details …",
"type": "string"
},
"consent": {
"description": "Short consent statement to display.",
"example": "Consent for Authentication: I, the holder of Aadhaar number, hereby give my consent …",
"type": "string"
},
"audioUrl": {
"description": "Audio rendition of the consent in the chosen language.",
"example": "https://paypointindia.co.in/audio/Consent_English.mp3",
"type": "string"
},
"consentId": {
"description": "Consent identifier.",
"example": 1,
"type": "number"
},
"consentLanguage": {
"description": "Language of the returned consent.",
"example": "English",
"type": "string"
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"consent_detail": {
"consentContent": "Use my Aadhaar / Virtual ID details (as applicable) for the purpose of e-KYC for/with PayPoint India to authenticate my identity through the Aadhaar Authentication system (Aadhaar based e-KYC services of UIDAI) in accordance with the provisions of the Aadhaar (Targeted Delivery of Financial and other Subsidies, Benefits and Services) Act, 2016 and the allied rules and regulations notified thereunder and for no other purpose.\r\n Authenticate my Aadhaar/Virtual ID through OTP or Biometric for authenticating my identity through the Aadhaar Authentication system for obtaining my e-KYC through Aadhaar based e-KYC services of UIDAI and use my Photo and Demographic details (Name, Gender, Date of Birth and Address) for the purpose of e-KYC for/with PayPoint India.\r\n I understand that Security and confidentiality of personal identity data provided, for the purpose of Aadhaar based authentication is ensured by PayPoint and the data will be stored by PayPoint till such time as mentioned in guidelines from UIDAI from time to time.",
"audioUrl": "https://paypointindia.co.in/audio/Consent_English.mp3",
"consentId": 1,
"consent": "Consent for Authentication: I, the holder of Aadhaar number, hereby give my consent to Paypoint India Network Private Limited to perform authentication and obtain my e-KYC with UIDAI for the purpose of creating my wallet.",
"consentLanguage": "English"
}
},
"response_type_id": 2446,
"message": "Consent Language Successfully Retrieved",
"status": 0
}
}
}
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/aadhaar/otp": {
"post": {
"operationId": "ppiDigikhataGenerateAadhaarOtp",
"summary": "Generate Sender Aadhaar OTP",
"description": "Submits the sender's Aadhaar number and dispatches an OTP to the Aadhaar-linked mobile for e-KYC. Returns an `otp_ref_id` to pass into Validate Sender Aadhaar OTP.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-generate-aadhaar-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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag (20 = Aadhaar validation).",
"example": 20,
"type": "number"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Validate Sender Aadhaar OTP.",
"example": "leSLbMTFJpWWyG+NIDZW1IM6D+1tVJ6haUuWCwcbJVCWUgeMOoj5vNqXAGuOK+Cro+AqdfLdmm5z5AQ+PGkPdHUQJ9nuLPKS",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"intent_id": 20,
"kyc_request_id": "",
"otp_ref_id": "leSLbMTFJpWWyG+NIDZW1IM6D+1tVJ6haUuWCwcbJVCWUgeMOoj5vNqXAGuOK+Cro+AqdfLdmm5z5AQ+PGkPdHUQJ9nuLPKS"
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"aadhar": {
"type": "string",
"description": "12-digit Aadhaar number of the sender.",
"example": "123456789012"
}
},
"required": [
"initiator_id",
"user_code",
"aadhar"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"aadhar": "123456789012"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/aadhaar/otp/verify": {
"post": {
"operationId": "ppiDigikhataVerifyAadhaarOtp",
"summary": "Validate Sender Aadhaar OTP",
"description": "Validates the OTP dispatched during Generate Sender Aadhaar OTP. On success the Aadhaar identity is confirmed and the flow proceeds to PAN validation (Pan Number Required).",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-verify-aadhaar-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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"application_id": {
"description": "KYC application identifier, when issued.",
"example": "",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"application_id": ""
},
"response_type_id": 2147,
"message": "Pan Number Required",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"otp": {
"type": "integer",
"description": "OTP received from Generate Sender Aadhaar OTP.",
"example": 654321
},
"otp_ref_id": {
"type": "integer",
"description": "otp_ref_id received from Generate Sender Aadhaar OTP.",
"example": 66748392
}
},
"required": [
"initiator_id",
"user_code",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 654321,
"otp_ref_id": 66748392
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/pan": {
"post": {
"operationId": "ppiDigikhataValidatePan",
"summary": "Validate Sender PAN",
"description": "Submits the sender's PAN to finish DigiKhata onboarding KYC. On success the response returns the updated `customer_profile` (verified sender name and recalculated limits).",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-validate-pan",
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_profile": {
"description": "Updated wallet profile with verified sender name and recalculated limits.",
"type": "object",
"properties": {
"name": {
"description": "Verified registered name of the sender.",
"example": "Karan Garg",
"type": "string"
},
"next_allowed_limit": {
"description": "Remaining transfer limit for the period (INR).",
"example": "5287.0",
"type": "string"
}
}
},
"sender_name": {
"description": "Verified name of the sender.",
"example": "Karan Garg",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": -1,
"data": {
"customer_profile": {
"total_monthly_limit": "50000.0",
"mobile": "9444444444",
"kyc_id": "",
"ekyc_enabled": 0,
"kyc_validity": "",
"kyc_remark": "",
"kyc_type": "",
"balance": "0.00",
"next_allowed_limit": "5287.0",
"name": "Karan Garg",
"digital_ekyc": 0,
"chart": [
{
"data_type_id": 10,
"data": {
"unavailable": 0,
"used": 44713,
"remaining": 5287
},
"label": ""
}
],
"email": "",
"kyc_state": 0
},
"id_proof_type_id": "",
"is_registered": 0,
"id_proof": "",
"otpOptionalSum": "",
"sender_name": "Karan Garg",
"otpNotRequiredSum": "",
"ekyc_enabled": "",
"otpNotRequiredSumNeft": "",
"next_allowed_limit": 5287,
"account": "",
"kyc_state": 0,
"otpOptionalSumNeft": ""
},
"response_type_id": 309,
"message": "Success!",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"pan_number": {
"type": "string",
"description": "The PAN number of the sender.",
"example": "ABCDE1234F"
}
},
"required": [
"initiator_id",
"user_code",
"pan_number"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"pan_number": "ABCDE1234F"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/wallet/loadwallet": {
"post": {
"operationId": "ppiDigikhataLoadWallet",
"summary": "Load Sender DigiKhata Wallet",
"description": "Credits the sender's DigiKhata wallet with the given amount. Returns a transaction id (`tid`) and the fee charged for the load.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-load-wallet",
"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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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 transaction ID for the wallet load.",
"example": "355419717321",
"type": "string"
},
"fee": {
"description": "Fee charged for the wallet load (INR).",
"example": "5.0",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"fee": "5.0",
"description": "",
"customer_id": "",
"bank_ref_num": "",
"tid": "355419717321"
},
"response_type_id": 2447,
"message": "The Digi Khata wallet has been loaded successfully.",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"amount": {
"type": "string",
"description": "Amount to load into the wallet (INR).",
"example": "500"
},
"org_id": {
"type": "string",
"description": "Organisation identifier. Defaults to 1.",
"example": "1"
}
},
"required": [
"initiator_id",
"user_code",
"amount",
"org_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"amount": "500",
"org_id": "1"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/recipients": {
"get": {
"operationId": "ppiDigikhataGetRecipients",
"summary": "Get List of Recipients",
"description": "Returns every recipient saved under a DigiKhata sender, with bank/account details, verification status, available channels (IMPS/NEFT), and the sender's remaining limit before PAN becomes mandatory.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-get-recipients",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": "Whether PAN is required to continue transacting (2 = not yet required).",
"example": 2,
"type": "number"
},
"remaining_limit_before_pan_required": {
"description": "Amount the sender can still transfer before PAN is required (INR).",
"example": 50000,
"type": "number"
},
"recipient_list": {
"description": "Saved beneficiaries for this sender.",
"type": "array",
"items": {
"type": "object",
"properties": {
"recipient_id": {
"description": "Unique recipient identifier — use to transact.",
"example": 10018839,
"type": "number"
},
"recipient_name": {
"description": "Beneficiary's name.",
"example": "Aditya",
"type": "string"
},
"bank": {
"description": "Beneficiary's bank name.",
"example": "Kotak Mahindra Bank",
"type": "string"
},
"account": {
"description": "Masked beneficiary account number.",
"example": "1XXXXXX90657",
"type": "string"
},
"ifsc": {
"description": "Beneficiary branch IFSC.",
"example": "KKBK0000878",
"type": "string"
},
"beneficiary_id": {
"description": "Beneficiary identifier, when bank-registered.",
"example": 40378,
"type": "number"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"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": "Madness",
"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
}
}
}
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/recipient": {
"post": {
"operationId": "ppiDigikhataAddRecipient",
"summary": "Add Recipient",
"description": "Adds a beneficiary (bank account) to a DigiKhata sender. On success a `recipient_id` is returned — use it to send transaction OTP and initiate the transfer. Maximum 5 recipients per day.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-add-recipient",
"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": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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 to transact.",
"example": 10017740,
"type": "number"
},
"recipient_mobile": {
"description": "Recipient's mobile number (echoed back).",
"example": "9775597777",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"initiator_id": "6000000094",
"recipient_mobile": "9775597777",
"recipient_id_type": "",
"customer_id": "9444444444",
"pipes": {},
"recipient_id": 10017740
},
"response_type_id": 43,
"message": "Success!Please transact using Recipientid",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_id": {
"type": "integer",
"description": "Unique ID assigned to the beneficiary's bank.",
"example": 12
},
"recipient_name": {
"type": "string",
"description": "Full name of the recipient.",
"example": "Aditya"
},
"recipient_mobile": {
"type": "string",
"description": "Recipient's 10-digit mobile number.",
"example": "9775597777"
},
"account": {
"type": "string",
"description": "Recipient's bank account number.",
"example": "1234567890657"
},
"bank_code": {
"type": "string",
"description": "IFSC code of the recipient's bank branch.",
"example": "KKBK0000878"
}
},
"required": [
"initiator_id",
"user_code",
"bank_id",
"recipient_name",
"recipient_mobile",
"account",
"bank_code"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_id": 12,
"recipient_name": "Aditya",
"recipient_mobile": "9775597777",
"account": "1234567890657",
"bank_code": "KKBK0000878"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/recipient/bank/otp": {
"post": {
"operationId": "ppiDigikhataRecipientBankOtp",
"summary": "Generate Add Recipient Bank OTP",
"description": "Initiates bank registration for a recipient and dispatches an OTP. Returns a `beneficiary_id` and `otp_ref_id` to pass into Validate OTP to Add Recipient.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-recipient-bank-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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"beneficiary_id": {
"description": "Beneficiary identifier created for the recipient bank.",
"example": "4202888",
"type": "string"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Validate OTP to Add Recipient.",
"example": "8617567988~8617567988~Channel4~4202888~4202888",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"beneficiary_id": "4202888",
"recipient_name": "",
"ifsc": "",
"account": "",
"otp_ref_id": "8617567988~8617567988~Channel4~4202888~4202888",
"recipient_id": ""
},
"response_type_id": 1741,
"message": "Beneficiary added",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "string",
"description": "Recipient ID of the recipient to register a bank for.",
"example": "10017740"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": "10017740"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/sender/{customer_id}/recipient/bank/otp/verify": {
"post": {
"operationId": "ppiDigikhataValidateRecipientOtp",
"summary": "Validate OTP to Add Recipient",
"description": "Validates the OTP issued by Generate Add Recipient Bank OTP to confirm the recipient's bank registration.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-validate-recipient-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": "8617567988"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"application_id": {
"description": "Application identifier, when issued.",
"example": "",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"application_id": ""
},
"response_type_id": 2131,
"message": "Validate OTP",
"status": 2131
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"otp": {
"type": "integer",
"description": "OTP received from Generate Add Recipient Bank OTP.",
"example": 654321
},
"otp_ref_id": {
"type": "integer",
"description": "otp_ref_id received from Generate Add Recipient Bank OTP.",
"example": 66748392
}
},
"required": [
"initiator_id",
"user_code",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 654321,
"otp_ref_id": 66748392
}
}
}
}
}
},
"/customer/payment/ppi-digikhata/otp": {
"post": {
"operationId": "ppiDigikhataSendTransactionOtp",
"summary": "Send Transaction OTP",
"description": "Dispatches an OTP to the sender for an upcoming transfer to a given recipient and amount. Returns an `otp_ref_id` to pass, with the OTP, into Initiate Transaction.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-send-transaction-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": "Granular status id; see the shared error-codes table.",
"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 Transaction.",
"example": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY="
},
"response_type_id": 2133,
"message": "Send OTP",
"status": 2133
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "integer",
"description": "Unique ID generated while adding the recipient.",
"example": 10017740
},
"amount": {
"type": "integer",
"description": "Amount to be transferred (INR).",
"example": 110
},
"customer_id": {
"type": "string",
"description": "Sender's 10-digit mobile number.",
"example": "8617567988"
},
"service_code": {
"type": "integer",
"description": "Fixed service code. Send 80.",
"example": 80
},
"beneficiary_id": {
"type": "string",
"description": "Beneficiary ID generated when adding the recipient's bank.",
"example": "4202888"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_id",
"amount",
"customer_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": 10017740,
"amount": 110,
"customer_id": "8617567988",
"service_code": 80,
"beneficiary_id": "4202888"
}
}
}
}
}
},
"/customer/payment/ppi-digikhata": {
"post": {
"operationId": "ppiDigikhataInitiateTransaction",
"summary": "Initiate Transaction",
"description": "Initiates the money transfer from the sender's DigiKhata wallet to the recipient. Returns the financial response envelope with `tx_status`, transaction id (`tid`), bank reference number, fee, and updated balance.",
"tags": [
"PPI Wallet"
],
"x-docs-slug": "ppi-digikhata-initiate-transaction",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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.",
"example": "2886522975",
"type": "string"
},
"tx_status": {
"description": "Transaction status (0 = success).",
"example": "0",
"type": "string"
},
"txstatus_desc": {
"description": "Human-readable transaction status.",
"example": "Success",
"type": "string"
},
"bank_ref_num": {
"description": "Bank/UTR reference number for the transfer.",
"example": "250121123714472002",
"type": "string"
},
"amount": {
"description": "Transferred amount (INR).",
"example": "110.00",
"type": "string"
},
"fee": {
"description": "Fee charged for the transfer (INR).",
"example": "4.0",
"type": "string"
},
"balance": {
"description": "Sender's wallet balance after the transfer (INR).",
"example": "814.0",
"type": "string"
},
"channel_desc": {
"description": "Channel used (IMPS/NEFT).",
"example": "IMPS",
"type": "string"
},
"recipient_name": {
"description": "Recipient's name.",
"example": "Krishna",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"tx_status": "0",
"debit_user_id": "6000000094",
"tds": "0.0",
"txstatus_desc": "Success",
"fee": "4.0",
"total_sent": "",
"channel": "2",
"collectable_amount": "114.0",
"txn_wallet": "0",
"utility_acc_no": "8999999992",
"sender_name": "8999999992",
"ekyc_enabled": "0",
"remaining_limit_before_pan_required": 49678,
"tid": "2886522975",
"bank": "UCO Bank",
"utrnumber": "",
"insurance_acquired": "",
"balance": "814.0",
"totalfee": "",
"next_allowed_limit": "",
"is_otp_required": "0",
"aadhar": "",
"currency": "INR",
"commission": "0.0",
"pipe": 13,
"state": "1",
"bank_ref_num": "250121123714472002",
"recipient_id": 10017680,
"timestamp": "2025-01-21T07:07:20.562Z",
"amount": "110.00",
"pan_required": 2,
"pinNo": "",
"gst_benefit": "0",
"payment_mode_desc": "",
"channel_desc": "IMPS",
"last_used_okekey": "0",
"npr": "",
"insurance_amount": "",
"service_tax": "0.61",
"paymentid": "",
"mdr": "",
"recipient_name": "Krishna",
"customer_id": "8999999992",
"account": "67544100008454",
"kyc_state": ""
},
"response_type_id": 325,
"message": "Transaction successful",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"recipient_id": {
"type": "integer",
"description": "Unique ID generated while adding the recipient.",
"example": 10017680
},
"amount": {
"type": "integer",
"description": "Amount to be transferred (INR).",
"example": 110
},
"timestamp": {
"type": "string",
"description": "Request timestamp (ISO 8601).",
"example": "2025-01-21T07:07:20.562Z"
},
"currency": {
"type": "string",
"description": "Currency. Must be INR.",
"example": "INR"
},
"customer_id": {
"type": "string",
"description": "Sender's 10-digit mobile number.",
"example": "8999999992"
},
"channel": {
"type": "integer",
"description": "Transfer channel. Defaults to 2 (NEFT); 0 for IMPS.",
"example": 2
},
"otp": {
"type": "string",
"description": "OTP received from Send Transaction OTP.",
"example": "123456"
},
"otp_ref_id": {
"type": "string",
"description": "otp_ref_id received from Send Transaction OTP.",
"example": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY="
},
"beneficiary_id": {
"type": "string",
"description": "Beneficiary ID generated while getting the recipient details.",
"example": "4202888"
},
"service_code": {
"type": "integer",
"description": "Fixed service code. Defaults to 80.",
"example": 80
},
"latlong": {
"type": "string",
"description": "Geographic coordinates of the user's location.",
"example": "28.63,77.22"
},
"state": {
"type": "string",
"description": "State parameter. Defaults to 1.",
"example": "1"
}
},
"required": [
"initiator_id",
"user_code",
"recipient_id",
"amount",
"timestamp",
"currency",
"customer_id",
"channel"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"recipient_id": 10017680,
"amount": 110,
"timestamp": "2025-01-21T07:07:20.562Z",
"currency": "INR",
"customer_id": "8999999992",
"channel": 2,
"otp": "123456",
"otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=",
"beneficiary_id": "4202888",
"service_code": 80,
"latlong": "28.63,77.22",
"state": "1"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"value": {
"response_status_id": -1,
"data": {
"user_code": "20110002",
"initiator_id": "9962981729"
},
"response_type_id": 1290,
"message": "User onboarding successfull",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"pan_number": {
"type": "string",
"description": "PAN card number of the agent.",
"example": "ABCDE1234F"
},
"mobile": {
"type": "string",
"description": "Verified mobile number of the agent.",
"example": "9876543210"
},
"first_name": {
"type": "string",
"description": "First name of the agent.",
"example": "Ramesh"
},
"last_name": {
"type": "string",
"description": "Last name of the agent.",
"example": "Kumar"
},
"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 array of strings.",
"example": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
]
},
"dob": {
"type": "string",
"description": "Date of birth of the agent in YYYY-MM-DD format.",
"example": "1990-05-15"
},
"shop_name": {
"type": "string",
"description": "Shop name of the agent (required for AePS onboarding).",
"example": "Ramesh Mobile Store"
}
},
"required": [
"initiator_id",
"user_code",
"pan_number",
"mobile",
"first_name",
"last_name",
"email",
"residence_address",
"dob",
"shop_name"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"pan_number": "ABCDE1234F",
"mobile": "9876543210",
"first_name": "Ramesh",
"last_name": "Kumar",
"email": "ramesh@example.com",
"residence_address": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
],
"dob": "1990-05-15",
"shop_name": "Ramesh Mobile Store"
}
}
}
}
}
},
"/user/account/services": {
"get": {
"operationId": "getUserServices",
"summary": "Get User's Services",
"description": "Returns the list of services for the given `user_code` with each service's status (ACTIVATED / PENDING), verification status, and timestamps.",
"tags": [
"User & Agent Management"
],
"x-docs-slug": "get-user-services",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"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": "Granular status id; see the shared error-codes table.",
"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).",
"example": "ACTIVATED",
"type": "string"
},
"status": {
"description": "Numeric status (1 = active, 2 = pending).",
"example": 1,
"type": "number"
},
"verification_status": {
"description": "Verification state of the service.",
"example": 3,
"type": "number"
},
"createdAt": {
"description": "When the service was created.",
"example": "2019-11-11 13:21:25.0",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"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
}
}
}
}
}
}
}
}
},
"/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",
"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"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
}
}
}
},
"/user/account/balance": {
"get": {
"operationId": "getWalletBalance",
"summary": "Get Settlement Account Balance",
"description": "Returns the current settlement-account balance for the given registered mobile number.",
"tags": [
"User & Agent Management"
],
"x-docs-slug": "get-wallet-balance",
"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": "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"
}
},
{
"name": "customer_id",
"in": "query",
"required": true,
"description": "Registered mobile number for the wallet.",
"schema": {
"type": "string",
"description": "Registered mobile number for the wallet.",
"example": "9910028267"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
}
}
}
},
"/customer/account/{customer_id}": {
"post": {
"operationId": "onboardCustomer",
"summary": "Onboard Customer",
"description": "Creates a rail-agnostic customer record. An OTP is dispatched and an `otp_ref_id` returned — call Verify Customer OTP next to complete onboarding.",
"tags": [
"Customer Management"
],
"x-docs-slug": "onboard-customer",
"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 10-digit mobile number.",
"schema": {
"type": "string",
"description": "Customer's 10-digit mobile number.",
"example": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next step (19 = onboarding).",
"example": 19,
"type": "number"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Customer OTP.",
"example": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94YigSXr5Qr+aS8OTg/e0YrVEoPAbap746K5g==",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94YigSXr5Qr+aS8OTg/e0YrVEoPAbap746K5g=="
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 2129
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"name": {
"type": "string",
"description": "Name of the customer as per ID.",
"example": "Karan Garg"
},
"dob": {
"type": "string",
"description": "Date of birth of the customer in YYYY-MM-DD format.",
"example": "1990-05-15"
},
"residence_address": {
"type": "string",
"description": "Customer's address as an array of strings.",
"example": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
]
}
},
"required": [
"initiator_id",
"user_code",
"name",
"dob",
"residence_address"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"name": "Karan Garg",
"dob": "1990-05-15",
"residence_address": [
"123 MG Road",
"Bangalore",
"Karnataka",
"560001"
]
}
}
}
}
}
},
"/customer/profile/{customer_id}": {
"get": {
"operationId": "getCustomerInfo",
"summary": "Get Customer Information",
"description": "Looks up a customer. For an enrolled customer the response returns an `otp_ref_id` to validate; if not enrolled (response_type_id 308) proceed to Onboard Customer.",
"tags": [
"Customer Management"
],
"x-docs-slug": "get-customer-info",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"name": "customer_id",
"in": "path",
"required": true,
"description": "Customer's 10-digit mobile number.",
"schema": {
"type": "string",
"description": "Customer's 10-digit mobile number.",
"example": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"intent_id": {
"description": "Intent flag for the next step (19 = onboarding).",
"example": 19,
"type": "number"
},
"otp_ref_id": {
"description": "OTP session reference — pass to Verify Customer OTP.",
"example": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94Yii3g+9fOBmbMsVTuaEQpDOEateP4tSTkQw==",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 1,
"data": {
"intent_id": 19,
"kyc_request_id": "",
"otp_ref_id": "IXrygqm0vTNbN35Lp5AfcbP69ifPhQ1Ee3u74AHY5fA9aMp2d94Yii3g+9fOBmbMsVTuaEQpDOEateP4tSTkQw=="
},
"response_type_id": 2129,
"message": "Validate the OTP",
"status": 2129
}
},
"customer_not_enrolled_proceed_to_onboard_customer": {
"summary": "Customer not enrolled — proceed to Onboard Customer",
"value": {
"response_status_id": 1,
"data": {
"sender_name": "",
"ekyc_enabled": ""
},
"response_type_id": 308,
"message": "Failure!Customer Not Enrolled",
"status": 308
}
}
}
}
}
}
}
}
},
"/customer/account/{customer_id}/otp/verify": {
"post": {
"operationId": "verifyCustomerOtp",
"summary": "Verify Customer OTP",
"description": "Validates the OTP issued by Onboard Customer / Get Customer Information. For an existing customer the response returns the full `customer_profile` (limits, balance, KYC state). For a new customer the flow continues to Aadhaar validation and PAN.",
"tags": [
"Customer Management"
],
"x-docs-slug": "verify-customer-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 10-digit mobile number.",
"schema": {
"type": "string",
"description": "Customer's 10-digit mobile number.",
"example": "9444444444"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"customer_profile": {
"description": "Customer's profile — limits, balance, KYC state, and usage chart.",
"type": "object",
"properties": {
"name": {
"description": "Registered name of the customer.",
"example": "Karan Garg",
"type": "string"
},
"mobile": {
"description": "Customer's mobile number.",
"example": "9444444444",
"type": "string"
},
"next_allowed_limit": {
"description": "Remaining transfer limit for the period (INR).",
"example": "5287.0",
"type": "string"
},
"balance": {
"description": "Current balance (INR).",
"example": "0.00",
"type": "string"
},
"kyc_state": {
"description": "KYC completion state.",
"example": 0,
"type": "number"
}
}
},
"sender_name": {
"description": "Registered name of the customer.",
"example": "Karan Garg",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": -1,
"data": {
"customer_profile": {
"total_monthly_limit": "50000.0",
"mobile": "9444444444",
"kyc_id": "",
"ekyc_enabled": 0,
"kyc_validity": "",
"kyc_remark": "",
"kyc_type": "",
"balance": "0.00",
"next_allowed_limit": "5287.0",
"name": "Karan Garg",
"digital_ekyc": 0,
"chart": [
{
"data_type_id": 10,
"data": {
"unavailable": 0,
"used": 44713,
"remaining": 5287
},
"label": ""
}
],
"email": "",
"kyc_state": 0
},
"id_proof_type_id": "",
"is_registered": 0,
"id_proof": "",
"otpOptionalSum": "",
"sender_name": "Karan Garg",
"otpNotRequiredSum": "",
"ekyc_enabled": "",
"otpNotRequiredSumNeft": "",
"next_allowed_limit": 5287,
"account": "",
"kyc_state": 0,
"otpOptionalSumNeft": ""
},
"response_type_id": 309,
"message": "Success!",
"status": 0
}
},
"new_customer_aadhaar_validation_pending": {
"summary": "New customer — Aadhaar validation pending",
"value": {
"response_status_id": 1,
"response_type_id": 2136,
"message": "Aadhar Validation Pending",
"status": 2136
}
},
"aadhaar_validated_pan_required_next": {
"summary": "Aadhaar validated — PAN required next",
"value": {
"response_status_id": 0,
"data": {
"application_id": ""
},
"response_type_id": 2147,
"message": "Pan Number Required",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"otp": {
"type": "integer",
"description": "OTP received from Onboard Customer, Get Customer Information, or Validate Aadhaar.",
"example": 123456
},
"otp_ref_id": {
"type": "integer",
"description": "otp_ref_id received from Onboard Customer, Get Customer Information, or Validate Aadhaar.",
"example": 66748392
}
},
"required": [
"initiator_id",
"user_code",
"otp_ref_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"otp": 123456,
"otp_ref_id": 66748392
}
}
}
}
}
},
"/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.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-add-settlement-account",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_id": {
"type": "integer",
"description": "Unique identifier for the bank.",
"example": 12
},
"ifsc": {
"type": "string",
"description": "IFSC code of the bank account.",
"example": "BKID0006701"
},
"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": "987867867967969"
}
},
"required": [
"initiator_id",
"user_code",
"bank_id",
"ifsc",
"service_code",
"account"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_id": 12,
"ifsc": "BKID0006701",
"service_code": 39,
"account": "987867867967969"
}
}
}
}
}
},
"/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",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"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": "Granular status id; see the shared error-codes table.",
"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": "Gaurav Mallik",
"type": "string"
},
"account": {
"description": "Bank account number.",
"example": "9989834392752938",
"type": "string"
},
"ifsc": {
"description": "Bank branch IFSC.",
"example": "PUNB0309300",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": -1,
"data": {
"unsettled_fund": "6100.0",
"remaining_limit": "190000",
"fund_transfer_list": [
{
"name": "Gaurav Mallik",
"ifsc": "PUNB0309300",
"account": "9989834392752938",
"recipient_id": "1828"
},
{
"name": "Gaurav Mallik",
"ifsc": "BKID0006701",
"account": "987867867967969",
"recipient_id": "1829"
}
]
},
"response_type_id": 1321,
"message": "List of fund transfer recipients",
"status": 0
}
}
}
}
}
}
}
}
},
"/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; max ₹2,00,000 per transaction.",
"tags": [
"AePS Cashout"
],
"x-docs-slug": "aeps-initiate-settlement",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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 for the settlement.",
"example": "12937465",
"type": "string"
},
"tx_status": {
"description": "Transaction status (2 = initiated).",
"example": "2",
"type": "string"
},
"txstatus_desc": {
"description": "Human-readable transaction status.",
"example": "Initiated",
"type": "string"
},
"amount": {
"description": "Settled amount (INR).",
"example": "100.00",
"type": "string"
},
"totalfee": {
"description": "Total fee charged for the settlement (INR).",
"example": "5.00",
"type": "string"
},
"balance": {
"description": "Agent balance after the settlement (INR).",
"example": "2.251010664E7",
"type": "string"
},
"account": {
"description": "Destination account number.",
"example": "987867867967969",
"type": "string"
},
"ifsc": {
"description": "Destination branch IFSC.",
"example": "BKID0006701",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"data": {
"tx_status": "2",
"amount": "100.00",
"balance": "2.251010664E7",
"txstatus_desc": "Initiated",
"totalfee": "5.00",
"ifsc": "BKID0006701",
"account": "987867867967969",
"tid": "12937465"
},
"response_type_id": 1329,
"message": "Transaction initiated successfully",
"status": 0
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"amount": 100,
"recipient_id": 1829,
"payment_mode": 5
}
}
}
}
}
},
"/tools/reference/transaction/{transaction-reference}": {
"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 = Awaited/Initiated (NEFT), 3 = Refund Pending, 4 = Refunded, 5 = Hold. A timeout should never be treated as an automatic failure — always inquire.",
"tags": [
"Transactions & Refunds"
],
"x-docs-slug": "transaction-inquiry",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"name": "transaction-reference",
"in": "path",
"required": true,
"description": "Eko TID or your client_ref_id identifying the transaction.",
"schema": {
"type": "string",
"description": "Eko TID or your client_ref_id identifying the transaction.",
"example": "12971397"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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 Awaited, 3 Refund Pending, 4 Refunded, 5 Hold).",
"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": {
"value": {
"response_type_id": 1472,
"data": {
"bank_ref_num": "8761099407",
"account": "234243534",
"fee": "5.0",
"client_ref_id": "Settlemet7206123420",
"gst": "0.76",
"sender_name": "Flipkart",
"timestamp": "2019-11-01 17:50:44",
"ifsc": "SBIN0000001",
"beneficiary_account_type": 1,
"txstatus_desc": "Success",
"tx_status": "0",
"tid": "12971397",
"amount": "1045.0",
"payment_mode": 5,
"recipient_name": "Virender Singh"
},
"message": "Sucess! Enquiry success.",
"status": 0,
"response_status_id": 0
}
}
}
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"value": {
"response_status_id": 1,
"data": {
"otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY="
},
"response_type_id": 2133,
"message": "Send OTP",
"status": 2133
}
}
}
}
}
}
},
"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",
"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": "Granular status id; see the shared error-codes table.",
"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=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold.",
"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": {
"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
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"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",
"user_code",
"otp"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"otp": 123456,
"otp_ref_id": "zCISyglexo0Pjqp4YrS2ssweuD9v1c3aLKGxjTW8wU7An8Wem1UyNws5830yh7q/sf5J4R3BY=",
"service_code": 80,
"state": 1
}
}
}
}
}
},
"/tools/reference/bank/{bank_code}": {
"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": [
"Utility & Helper APIs"
],
"x-docs-slug": "get-bank-details",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"name": "bank_code",
"in": "path",
"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"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
}
}
}
},
"/tools/reference/banks/ifsc/{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": [
"Utility & Helper APIs"
],
"x-docs-slug": "get-ifsc-details",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"name": "ifsc",
"in": "path",
"required": true,
"description": "IFSC code of the bank branch.",
"schema": {
"type": "string",
"description": "IFSC code of the bank branch.",
"example": "IOBA0002248"
}
}
],
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
}
}
}
},
"/customer/payment/bbps/recharge/{customer_mobile}/operator": {
"get": {
"operationId": "bbpsOperatorCodeCircle",
"summary": "Get Operator Code and Circle",
"description": "Returns the `phone_operator_code` and `circle_area` for a customer mobile number — returned under `dependent_params`. Pass these into Get Recharge Plans.",
"tags": [
"Bharat Bill Payment System (BBPS)"
],
"x-docs-slug": "bbps-operator-code-circle",
"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": "user_code",
"in": "query",
"required": true,
"description": "User code of the retailer/agent the service is run for.",
"schema": {
"type": "string",
"description": "User code of the retailer/agent the service is run for.",
"example": "20810200"
}
},
{
"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": "Granular status id; see the shared error-codes table.",
"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.",
"example": "400",
"type": "string"
}
}
}
}
}
}
}
},
"examples": {
"success": {
"value": {
"response_status_id": 0,
"dependent_params": [
{
"name": "phone_operator_code",
"value": 400
},
{
"name": "circle_area",
"value": "5"
}
],
"data": {
"updates": ""
},
"response_type_id": 1804,
"message": "success",
"status": 0
}
}
}
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"document_requested",
"redirect_url"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"document_type",
"verification_id",
"reference_id"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"document_type": [
"AADHAAR"
],
"verification_id": "vrf_digilocker_abc123",
"reference_id": "7483920"
}
}
}
}
}
},
"/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, IFSC details, and the UTR of the debit. 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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"account_exists": {
"description": "Whether the bank account is valid and active.",
"example": true,
"type": "boolean"
},
"account_name": {
"description": "Account holder name as registered with the bank. Use for name matching against provided details.",
"example": "Rajesh Kumar",
"type": "string"
},
"ifsc": {
"description": "IFSC code confirmed by the bank for the verified account.",
"example": "SBIN0001234",
"type": "string"
},
"bank": {
"description": "Full name of the bank associated with the account.",
"example": "State Bank of India",
"type": "string"
},
"branch": {
"description": "Branch name associated with the IFSC code.",
"example": "MG Road Branch",
"type": "string"
},
"utr": {
"description": "Unique Transaction Reference number of the ₹1 penny-drop credit. Useful for reconciliation.",
"example": "431712345678",
"type": "string"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Bank account verification successful",
"response_type_id": 1388,
"data": {
"account_exists": true,
"account_name": "Rajesh Kumar",
"ifsc": "SBIN0001234",
"bank": "State Bank of India",
"branch": "MG Road Branch",
"utr": "431712345678"
}
}
},
"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",
"response_type_id": 1388,
"data": {
"account_exists": false,
"account_name": null,
"ifsc": "INVALID001",
"bank": null,
"branch": null,
"utr": null
}
}
},
"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",
"response_type_id": 1388,
"data": {
"account_exists": false,
"account_name": null,
"ifsc": "SBIN0001234",
"bank": "State Bank of India",
"branch": "MG Road Branch",
"utr": null
}
}
},
"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",
"response_type_id": 1388,
"data": {
"account_exists": false,
"account_name": null,
"ifsc": null,
"bank": null,
"branch": null,
"utr": null
}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"bank_account": {
"type": "number",
"description": "Complete bank account number to be verified.",
"example": 1234567890
},
"ifsc": {
"type": "string",
"description": "IFSC code of the bank account to be verified (11-character alphanumeric).",
"example": "SBIN0001234"
}
},
"required": [
"initiator_id",
"user_code",
"bank_account",
"ifsc"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"bank_account": 1234567890,
"ifsc": "SBIN0001234"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": "3356655212",
"type": "string"
},
"reference_id": {
"description": "Numeric reference ID for the submitted batch request, used for internal tracking.",
"example": 123456,
"type": "number"
}
}
}
}
},
"examples": {
"success": {
"value": {
"status": 0,
"response_status_id": 0,
"message": "Bulk verification request accepted. Poll status API for results.",
"response_type_id": 1388,
"data": {
"bulk_reference_id": "3356655212",
"reference_id": 123456
}
}
},
"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": {
"status": 0,
"response_status_id": 0,
"message": "Bulk verification request accepted. Poll status API for results.",
"response_type_id": 1388,
"data": {
"bulk_reference_id": "3356655213",
"reference_id": 123457
}
}
}
}
}
}
},
"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": {
"status": 1,
"response_status_id": -1,
"message": "Invalid request: entries array is missing or malformed",
"data": null
}
}
}
}
}
}
},
"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.",
"example": "REQ-20260101-001"
},
"entries": {
"type": "string",
"description": "Array of bank account objects to verify. Each entry must contain bank_account and ifsc. Optionally include user_code per entry to attribute verifications to different retailers.",
"example": [
{
"bank_account": "1234567890",
"ifsc": "SBIN0001234"
},
{
"bank_account": "9876543210123",
"ifsc": "HDFC0005678"
}
]
},
"entries[].bank_account": {
"type": "string",
"description": "Bank account number for this entry.",
"example": "1234567890"
},
"entries[].ifsc": {
"type": "string",
"description": "IFSC code for this entry's bank account.",
"example": "SBIN0001234"
},
"entries[].user_code": {
"type": "string",
"description": "Per-entry retailer user code, if attributing individual verifications to different agents.",
"example": "20810200"
}
},
"required": [
"initiator_id",
"entries",
"entries[].bank_account",
"entries[].ifsc"
]
},
"example": {
"initiator_id": "9962981729",
"client_ref_id": "REQ-20260101-001",
"entries": [
{
"bank_account": "1234567890",
"ifsc": "SBIN0001234"
},
{
"bank_account": "9876543210123",
"ifsc": "HDFC0005678"
}
],
"entries[].bank_account": "1234567890",
"entries[].ifsc": "SBIN0001234",
"entries[].user_code": "20810200"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key / timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key_timestamp": {
"summary": "Authentication failure — wrong or expired secret-key / timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Forbidden: invalid authentication credentials",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"gstin": {
"type": "string",
"description": "Goods and Services Tax Identification Number of the business to verify (15-character alphanumeric).",
"example": "29ABCDE1234F1Z5"
},
"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",
"user_code",
"gstin",
"business_name"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"gstin": "29ABCDE1234F1Z5",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key / timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key_timestamp": {
"summary": "Authentication failure — wrong or expired secret-key / timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Forbidden: invalid authentication credentials",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"pan": {
"type": "string",
"description": "10-character alphanumeric PAN of the business or individual (5 letters, 4 digits, 1 letter).",
"example": "ABCDE1234F"
}
},
"required": [
"initiator_id",
"user_code",
"pan"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"pan": "ABCDE1234F"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong secret-key or stale timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_secret_key_or_stale_timestamp": {
"summary": "Authentication failure — wrong secret-key or stale timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Unauthorized — invalid secret-key or secret-key-timestamp.",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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"
}
},
"required": [
"initiator_id",
"user_code",
"customer_vpa",
"recipient_mobile",
"name",
"latlong"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": "MH0220190001234",
"type": "string"
},
"dob": {
"description": "Date of birth of the DL holder as returned by the authority.",
"example": "1994-08-29",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong secret-key or timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_secret_key_or_timestamp": {
"summary": "Authentication failure — wrong secret-key or timestamp",
"value": {
"status": 1,
"message": "Unauthorized: invalid secret-key or timestamp"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"dl_number": {
"type": "string",
"description": "Driving license number to verify (e.g. MH0220190001234).",
"example": "MH0220190001234"
},
"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-29"
}
},
"required": [
"initiator_id",
"user_code",
"dl_number",
"dob"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"dl_number": "MH0220190001234",
"dob": "1994-08-29"
}
}
}
}
}
},
"/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, fitness certificate, 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.",
"tags": [
"Vehicle & RC Verification"
],
"x-docs-slug": "vehicle-rc",
"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": "Granular status id; see the shared error-codes table.",
"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": "EKO-RC-9876543210-001",
"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"
},
"mobile_number": {
"description": "Mobile number of the owner as registered with the RTO, if available.",
"example": "98XXXXXXXX",
"type": "string"
},
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key": {
"summary": "Authentication failure — wrong or expired secret-key",
"value": {
"status": 1,
"message": "Forbidden: invalid secret-key or timestamp mismatch"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"vehicle_number": {
"type": "string",
"description": "Vehicle registration number to verify (e.g. HR26DA8398).",
"example": "HR26DA8398"
}
},
"required": [
"initiator_id",
"user_code",
"vehicle_number"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"vehicle_number": "HR26DA8398"
}
}
}
}
}
},
"/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
},
"403": {
"description": "Invalid or unauthorized developer key",
"content": {
"application/json": {
"examples": {
"invalid_or_unauthorized_developer_key": {
"summary": "Invalid or unauthorized developer key",
"value": {
"status": 1,
"message": "Forbidden: invalid developer_key or secret-key"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"phone": {
"type": "string",
"description": "Employee's registered mobile number used to look up UAN records from EPFO.",
"example": "9876543210"
}
},
"required": [
"initiator_id",
"user_code",
"phone"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong secret-key or timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_secret_key_or_timestamp": {
"summary": "Authentication failure — wrong secret-key or timestamp",
"value": {
"status": 1,
"message": "Forbidden"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"latitude",
"longitude"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key": {
"summary": "Authentication failure — wrong or expired secret-key",
"value": {
"status": 1,
"message": "Forbidden — incorrect secret-key or timestamp"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"epic_number": {
"type": "string",
"description": "Unique Electoral Photo Identity Card (EPIC) number to verify.",
"example": "ABC1234567"
},
"name": {
"type": "string",
"description": "Name of the Voter ID cardholder. Optional; can be used for cross-verification against returned name.",
"example": "Rajesh Kumar"
}
},
"required": [
"initiator_id",
"user_code",
"epic_number"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"epic_number": "ABC1234567",
"name": "Rajesh Kumar"
}
}
}
}
}
},
"/tools/kyc/passport": {
"post": {
"operationId": "passport",
"summary": "Passport Verification",
"description": "The Passport Verification 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 Verification"
],
"x-docs-slug": "passport",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key / timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key_timestamp": {
"summary": "Authentication failure — wrong or expired secret-key / timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Forbidden: invalid authentication credentials",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"file_number": {
"type": "string",
"description": "Unique alphanumeric code that identifies an individual's passport application (passport file number).",
"example": "J8369854"
},
"dob": {
"type": "string",
"description": "Date of birth of the passport holder in YYYY-MM-DD format.",
"example": "1994-08-29"
},
"name": {
"type": "string",
"description": "Name of the passport holder. Optional — used for cross-checking in certain verification flows.",
"example": "Rajesh Kumar"
}
},
"required": [
"initiator_id",
"user_code",
"file_number",
"dob"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"file_number": "J8369854",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
},
"403": {
"description": "Authentication failure — invalid secret-key or timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_invalid_secret_key_or_timestamp": {
"summary": "Authentication failure — invalid secret-key or timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Forbidden: invalid or expired secret-key.",
"data": null
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"cin": {
"type": "string",
"description": "Alphanumeric Company Identification Number (CIN) assigned by the Ministry of Corporate Affairs, India.",
"example": "U72900KA2015PTC082988"
}
},
"required": [
"initiator_id",
"user_code",
"cin"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key": {
"summary": "Authentication failure — wrong or expired secret-key",
"value": {
"status": 1,
"response_status_id": -1,
"message": "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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"ip_address"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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"
}
}
}
}
}
}
},
"403": {
"description": "Invalid / missing developer_key — authentication failure",
"content": {
"application/json": {
"examples": {
"invalid_missing_developer_key_authentication_failure": {
"summary": "Invalid / missing developer_key — authentication failure",
"value": {
"status": 1,
"message": "Forbidden — incorrect developer_key or secret-key."
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"name_1",
"name_2"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"name_1": "S K Mishra",
"name_2": "Satish Kumar Mishra"
}
}
}
}
}
},
"/tools/kyc/touras/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. Built on the Eko TOURAS network, 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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key or timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key_or_timestamp": {
"summary": "Authentication failure — wrong or expired secret-key or timestamp",
"value": {
"status": 1,
"message": "Unauthorized: invalid secret-key or timestamp"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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"
}
},
"required": [
"initiator_id",
"user_code",
"pan_number"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"pan_number": "ABCDE1234F"
}
}
}
}
}
},
"/tools/kyc/touras/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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
}
}
}
}
}
},
"403": {
"description": "Authentication failure — invalid secret-key or timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_invalid_secret_key_or_timestamp": {
"summary": "Authentication failure — invalid secret-key or timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Forbidden: invalid or expired secret-key.",
"data": null
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"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",
"user_code",
"din_number"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"din_number": "06731826"
}
}
}
}
}
},
"/tools/kyc/touras/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong or expired secret-key",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_or_expired_secret_key": {
"summary": "Authentication failure — wrong or expired secret-key",
"value": {
"status": 1,
"message": "Forbidden: invalid secret-key or timestamp mismatch"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"registration_number": {
"type": "string",
"description": "Vehicle registration number to look up challans for (e.g. MH02AB1234).",
"example": "MH02AB1234"
}
},
"required": [
"initiator_id",
"user_code",
"registration_number"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"registration_number": "MH02AB1234"
}
}
}
}
}
},
"/tools/kyc/touras/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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": {}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong secret-key or stale timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_secret_key_or_stale_timestamp": {
"summary": "Authentication failure — wrong secret-key or stale timestamp",
"value": {
"status": 1,
"response_status_id": -1,
"message": "Unauthorized — invalid secret-key or secret-key-timestamp.",
"data": {}
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"email": {
"type": "string",
"description": "The email address to verify, e.g. rajesh.kumar@example.com.",
"example": "rajesh.kumar@example.com"
}
},
"required": [
"initiator_id",
"user_code",
"email"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"email": "rajesh.kumar@example.com"
}
}
}
}
}
},
"/tools/kyc/touras/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",
"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": "Granular status id; see the shared error-codes table.",
"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": {
"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"
}
}
}
}
}
}
},
"403": {
"description": "Authentication failure — wrong secret-key or timestamp",
"content": {
"application/json": {
"examples": {
"authentication_failure_wrong_secret_key_or_timestamp": {
"summary": "Authentication failure — wrong secret-key or timestamp",
"value": {
"status": 1,
"message": "Forbidden: invalid authentication credentials"
}
}
}
}
}
}
},
"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 of the retailer/agent the service is run for.",
"example": "20810200"
},
"client_ref_id": {
"type": "string",
"description": "Unique reference id per API call, generated by your system.",
"example": "REQ-20260101-001"
},
"fssai": {
"type": "string",
"description": "FSSAI license number of the food business operator (FBO) to verify. Typically 14 digits.",
"example": "11521998000045"
}
},
"required": [
"initiator_id",
"user_code",
"fssai"
]
},
"example": {
"initiator_id": "9962981729",
"user_code": "20810200",
"client_ref_id": "REQ-20260101-001",
"fssai": "11521998000045"
}
}
}
}
}
}
},
"externalDocs": {
"url": "https://eps.eko.in/docs",
"description": "Developer docs"
},
"x-tagGroups": [
{
"name": "Banking & Cash",
"tags": [
"Domestic Money Transfer (DMT)",
"AePS Cashout",
"PPI Wallet",
"User & Agent Management",
"Customer Management"
]
},
{
"name": "Payments",
"tags": [
"Bharat Bill Payment System (BBPS)",
"Transactions & Refunds",
"Utility & Helper APIs"
]
},
{
"name": "Verification",
"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 Verification",
"CIN Verification",
"IP Verification",
"Name Match",
"ITR Compliance Check",
"DIN Verification",
"E-Challan Verification",
"Email Verification",
"FSSAI License Verification"
]
}
]
}