@ekoindia/eps-transact-mcp 0.1.23 → 0.1.24

package/data/eps.json

@@ -2,7 +2,7 @@
   "meta": {
     "org": "ekoindia",
     "apiVersion": "v3",
-    "bundleVersion": "ceae6d30",
+    "bundleVersion": "c109bedc",
     "environments": [
       {
         "id": "sandbox",
@@ -3716,6 +3716,196 @@
         }
       ]
     },
+    {
+      "slug": "aeps-fingpay-cash-withdrawal-otp",
+      "productId": "aeps",
+      "productName": "AePS Cashout",
+      "name": "Cash Withdrawal OTP",
+      "method": "POST",
+      "path": "/customer/collection/aeps-fingpay/cash-withdrawal/otp/{customer_id}",
+      "summary": "Generate the transaction OTP required before an AePS cash withdrawal above ₹5,000.",
+      "category": "bc",
+      "relevance": "H",
+      "description": "Fingpay requires a fresh, transaction-scoped OTP for every cash withdrawal above **₹5,000**. Call this before Cash Withdrawal only when `amount` is greater than ₹5,000 — for ₹5,000 or less, skip it and call Cash Withdrawal directly.\n\nOn success the customer receives a 6-digit OTP by SMS on their Aadhaar-linked mobile, and the response returns `data.fp_transaction_id`. Send that id to Cash Withdrawal as `txn_otp_request_id`, and put the SMS OTP in the `otp` attribute of the PidOptions used to capture the customer's fingerprint. They are two different values, and Cash Withdrawal needs both. The id belongs to this one withdrawal attempt: generate a new one for every attempt and never reuse it.\n\nNo biometric capture happens in this call — it takes no `piddata`.",
+      "bestFor": "BC agents and CSPs pre-authorising AePS cash withdrawals above ₹5,000",
+      "docsUrl": "https://eps.eko.in/docs/aeps-fingpay-cash-withdrawal-otp",
+      "headers": [
+        {
+          "name": "developer_key",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "Static API key issued to your account after KYC."
+        },
+        {
+          "name": "secret-key",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))."
+        },
+        {
+          "name": "secret-key-timestamp",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time."
+        },
+        {
+          "name": "content-type",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "application/json",
+          "example": "application/json"
+        }
+      ],
+      "requestParams": [
+        {
+          "name": "initiator_id",
+          "type": "string",
+          "required": true,
+          "description": "Registered mobile number of the API user (see Platform Credentials).",
+          "example": "9962981729",
+          "in": "body"
+        },
+        {
+          "name": "client_ref_id",
+          "type": "string",
+          "required": false,
+          "description": "Unique reference ID per API call, generated by your system (max 20 characters). The SDKs generate one for every non-GET call when you don't.",
+          "example": "2026010100123456789",
+          "format": "client-ref",
+          "maxLength": 20,
+          "in": "body"
+        },
+        {
+          "name": "user_code",
+          "type": "string",
+          "required": true,
+          "description": "Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users",
+          "example": "10000001",
+          "in": "body"
+        },
+        {
+          "name": "customer_id",
+          "type": "string",
+          "required": true,
+          "description": "Customer's registered mobile number.",
+          "example": "9000000000",
+          "in": "path"
+        },
+        {
+          "name": "bank_code",
+          "type": "string",
+          "required": false,
+          "description": "Short bank code identifying the customer's Aadhaar-linked bank (e.g. `HDFC`, `SBIN`). Obtain from the bank list API. Recommended — send the same value you will use for the withdrawal.",
+          "example": "HDFC",
+          "in": "body"
+        },
+        {
+          "name": "aadhar",
+          "type": "string",
+          "required": true,
+          "description": "RSA-encrypted, Base64-encoded Aadhaar number of the customer — the same value you send to Cash Withdrawal. Encrypt the 12-digit Aadhaar with the Eko RSA public key using PKCS#1 v1.5 padding (Java's default `Cipher.getInstance(\"RSA\")`), then Base64-encode the ciphertext.",
+          "example": "BASE64_ENCRYPTED_AADHAAR",
+          "in": "body"
+        },
+        {
+          "name": "latlong",
+          "type": "string",
+          "format": "lat-long",
+          "required": true,
+          "description": "GPS coordinates of the agent's device in 'latitude,longitude' format.",
+          "example": "28.6139,77.2090",
+          "in": "body"
+        },
+        {
+          "name": "amount",
+          "type": "number",
+          "required": true,
+          "description": "Withdrawal amount in Indian Rupees (integer) — the same amount you will send to Cash Withdrawal. Only call this API when it is above ₹5,000.",
+          "example": 6000,
+          "in": "body"
+        }
+      ],
+      "sampleRequest": {
+        "initiator_id": "9962981729",
+        "client_ref_id": "2026010100123456789",
+        "user_code": "10000001",
+        "bank_code": "HDFC",
+        "aadhar": "BASE64_ENCRYPTED_AADHAAR",
+        "latlong": "28.6139,77.2090",
+        "amount": 6000
+      },
+      "responseFields": [
+        {
+          "name": "status",
+          "type": "number",
+          "description": "Primary success indicator (0 = success).",
+          "example": 0
+        },
+        {
+          "name": "message",
+          "type": "string",
+          "description": "Human-readable response / error message.",
+          "example": "Verification successful"
+        },
+        {
+          "name": "response_status_id",
+          "type": "number",
+          "description": "Granular status id; see the shared error-codes table.",
+          "example": 0
+        },
+        {
+          "name": "response_type_id",
+          "type": "number",
+          "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.",
+          "example": 1388
+        },
+        {
+          "name": "data",
+          "type": "object",
+          "description": "API-specific response payload.",
+          "children": [
+            {
+              "name": "fp_transaction_id",
+              "type": "string",
+              "description": "OTP reference id for this one withdrawal attempt. Send it to Cash Withdrawal as `txn_otp_request_id`. It is NOT the OTP — the customer receives that by SMS.",
+              "imp": true,
+              "example": "FP2609010001234567"
+            }
+          ]
+        }
+      ],
+      "sampleSuccessResponse": {
+        "response_status_id": 0,
+        "data": {
+          "fp_transaction_id": "FP2609010001234567"
+        },
+        "response_type_id": 1459,
+        "message": "OTP generated successfully. Use the reference ID for your transaction.",
+        "status": 0
+      },
+      "errorScenarios": [
+        {
+          "scenario": "OTP generation failed — generic Fingpay failure. There are no OTP-specific error codes yet; `message` carries the gateway's reason",
+          "statusCode": 200,
+          "example": {
+            "response_status_id": 1,
+            "message": "<failure description from the Fingpay gateway>",
+            "status": 1
+          }
+        }
+      ],
+      "responseTypes": [
+        {
+          "id": 1459,
+          "meaning": "OTP generated and sent to the customer by SMS — send `data.fp_transaction_id` as `txn_otp_request_id` to Cash Withdrawal",
+          "next": "aeps-fingpay-cash-withdrawal"
+        }
+      ]
+    },
     {
       "slug": "aeps-fingpay-cash-withdrawal",
       "productId": "aeps",
@@ -3726,7 +3916,7 @@
       "summary": "Withdraw cash from any Aadhaar-linked bank account using biometric fingerprint authentication — no card or PIN required.",
       "category": "bc",
       "relevance": "H",
-      "description": "Allows a customer to withdraw cash from their bank account at an agent/BC point by providing their Aadhaar number and a live fingerprint scan. The agent's biometric device captures a PID XML blob which is passed verbatim to this API. The customer's Aadhaar is RSA-encrypted before transmission. Requires the agent to have completed AePS Fingpay activation, the one-time eKYC (Send OTP → Verify OTP → Biometric), and the Daily KYC for the current day.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).",
+      "description": "Allows a customer to withdraw cash from their bank account at an agent/BC point by providing their Aadhaar number and a live fingerprint scan. The agent's biometric device captures a PID XML blob which is passed verbatim to this API. The customer's Aadhaar is RSA-encrypted before transmission. Requires the agent to have completed AePS Fingpay activation, the one-time eKYC (Send OTP → Verify OTP → Biometric), and the Daily KYC for the current day.\n\n**Above ₹5,000 a transaction OTP is required.** First call Cash Withdrawal OTP, then send its `fp_transaction_id` here as `txn_otp_request_id`, and put the customer's 6-digit SMS OTP in the `otp` attribute of the PidOptions used for the fingerprint capture. For ₹5,000 or less, no OTP step is needed.\n\nTo capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice).",
       "bestFor": "BC agents, CSPs, and kirana-store banking points enabling cardless cash withdrawal for rural customers",
       "docsUrl": "https://eps.eko.in/docs/aeps-fingpay-cash-withdrawal",
       "financial": true,
@@ -3825,7 +4015,7 @@
           "name": "piddata",
           "type": "string",
           "required": true,
-          "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.",
+          "description": "PID data captured from the UIDAI-certified biometric device, as a raw XML string. Must use Data type='X' (XML, not Protobuf). DeviceInfo must include the 'mc' (device certificate) parameter. fType must be 2. For an `amount` above ₹5,000, set the `otp` attribute of the PidOptions `<Opts>` element to the customer's 6-digit SMS OTP before capture — the OTP itself, not the `fp_transaction_id`.",
           "example": "<?xml version='1.0'?><PidData><Data type='X'>...</Data><DeviceInfo mc='...' /></PidData>",
           "in": "body"
         },
@@ -3833,9 +4023,16 @@
           "name": "amount",
           "type": "number",
           "required": true,
-          "description": "Withdrawal amount in Indian Rupees (integer). Must be greater than 0 for cash withdrawal.",
+          "description": "Withdrawal amount in Indian Rupees (integer). Must be greater than 0 for cash withdrawal. Above ₹5,000, call Cash Withdrawal OTP first and send `txn_otp_request_id`.",
           "example": 1000,
           "in": "body"
+        },
+        {
+          "name": "txn_otp_request_id",
+          "type": "string",
+          "required": false,
+          "description": "Required when `amount` is above ₹5,000: the `fp_transaction_id` returned by Cash Withdrawal OTP for this attempt (e.g. `FP2609010001234567`). Omit for ₹5,000 or less.",
+          "in": "body"
         }
       ],
       "sampleRequest": {
@@ -4050,6 +4247,12 @@
               "type": "string",
               "description": "Human-readable transaction remark from the provider (e.g. 'Request Completed').",
               "example": "Request Completed"
+            },
+            {
+              "name": "fp_transaction_id",
+              "type": "string",
+              "description": "Returned only with `response_type_id` 1459 (OTP required — nothing was withdrawn): the OTP reference to send back as `txn_otp_request_id`.",
+              "example": "FP2609010001234567"
             }
           ]
         }
@@ -4142,6 +4345,19 @@
             "status": 1464
           }
         },
+        {
+          "scenario": "OTP required — `amount` above ₹5,000 sent without `txn_otp_request_id`. NOTHING was withdrawn: an OTP was sent to the customer instead",
+          "statusCode": 200,
+          "example": {
+            "response_status_id": 0,
+            "data": {
+              "fp_transaction_id": "FP2609010001234567"
+            },
+            "response_type_id": 1459,
+            "message": "OTP generated successfully. Use the reference ID for your transaction.",
+            "status": 0
+          }
+        },
         {
           "scenario": "Transaction Pending — awaiting bank confirmation",
           "statusCode": 200,
@@ -4184,12 +4400,16 @@
         },
         {
           "id": 1464,
-          "meaning": "Transaction Fail"
+          "meaning": "Transaction Fail — above ₹5,000 this also covers an expired, invalid or already-used OTP (there is no separate code). Once the failure is final, generate a fresh OTP and re-capture before retrying"
         },
         {
           "id": 1465,
           "meaning": "Transaction Pending — check final status later",
           "next": "transaction-inquiry"
+        },
+        {
+          "id": 1459,
+          "meaning": "OTP required — `amount` is above ₹5,000 but no `txn_otp_request_id` was sent. Nothing was withdrawn; an OTP was sent to the customer. Retry with `data.fp_transaction_id` as `txn_otp_request_id` and the customer's SMS OTP in the PidOptions `otp` attribute — do not generate another OTP"
         }
       ]
     },
@@ -23626,7 +23846,7 @@
       "id": "aeps-fingpay-cash-withdrawal",
       "slug": "aeps-fingpay-cash-withdrawal",
       "name": "AePS (Fingpay) — Cash Withdrawal",
-      "summary": "Aadhaar-enabled cash withdrawal: one-time agent activation and eKYC, daily KYC, then the biometric withdrawal.",
+      "summary": "Aadhaar-enabled cash withdrawal: one-time agent activation and eKYC, daily KYC, a transaction OTP for amounts above ₹5,000, then the biometric withdrawal.",
       "productId": "aeps",
       "steps": [
         {
@@ -23654,9 +23874,14 @@
           "purpose": "Daily KYC — biometric-only, repeated once per calendar day before the agent's first transaction.",
           "frequency": "daily"
         },
+        {
+          "specSlug": "aeps-fingpay-cash-withdrawal-otp",
+          "appliesWhen": "amount > ₹5,000",
+          "purpose": "Generate the transaction OTP: the customer receives a 6-digit OTP by SMS on their Aadhaar-linked mobile, and the response returns `fp_transaction_id`. Generate a fresh one for every withdrawal attempt — it is never reusable."
+        },
         {
           "specSlug": "aeps-fingpay-cash-withdrawal",
-          "purpose": "Perform the biometric Aadhaar-enabled cash withdrawal.",
+          "purpose": "Perform the biometric Aadhaar-enabled cash withdrawal. Above ₹5,000, send the `fp_transaction_id` as `txn_otp_request_id` AND put the customer's SMS OTP in the PidOptions `otp` attribute before the fingerprint capture — two different values, both required. A `response_type_id` of 1459 means the OTP step was skipped and nothing was withdrawn. Persist `tid`; on Pending (1465) reconcile via Transaction Inquiry before any retry.",
           "branches": [
             {
               "onStatus": 0,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ekoindia/eps-transact-mcp",
-	"version": "0.1.23",
+	"version": "0.1.24",
 	"description": "Transactional MCP server for Eko Platform Services (EPS) verification APIs — remote (streamable HTTP) and local (stdio).",
 	"license": "MIT",
 	"type": "module",