--- title: "AePS Cash Withdrawal API Reference" description: "Withdraw cash from any Aadhaar-linked bank account using biometric fingerprint authentication — no card or PIN required." canonical: "https://eps.eko.in/docs/aeps-fingpay-cash-withdrawal" --- > **Canonical URL:** https://eps.eko.in/docs/aeps-fingpay-cash-withdrawal > This is a machine-readable Markdown version of the page for AI agents and LLMs. The primary (HTML) version lives at the canonical URL above. # AePS Cash Withdrawal API Reference `POST https://staging.eko.in/ekoapi/v3/customer/collection/aeps-fingpay/cash-withdrawl/{customer_id}` Withdraw cash from any Aadhaar-linked bank account using biometric fingerprint authentication — no card or PIN required. 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. To capture the `piddata` PID block with an RDService-compliant fingerprint scanner, see the [Aadhaar Biometric Authentication guide](/docs/aadhaar-biometric-rdservice). > View product & pricing details: [AePS Cashout](https://eps.eko.in/products/aeps-api.md) ## Path parameters | Field | Type | Required | Description | | --- | --- | --- | --- | | customer_id | string | yes | Customer's registered mobile number. e.g. 9000000000 | ## Body parameters | Field | Type | Required | Description | | --- | --- | --- | --- | | initiator_id | string | yes | Registered mobile number of the API user (see Platform Credentials). e.g. 9962981729 | | client_ref_id | string | no | Unique reference ID per API call, generated by your system (max 20 characters). e.g. 2026010100123456789 | | user_code | string | yes | Unique code of your user/agent/retailer the service is run for. Use `Onboard Agent` API to register your users e.g. 10000001 | | bank_code | string | yes | Short bank code identifying the customer's Aadhaar-linked bank (e.g. `HDFC`, `SBIN`). Obtain from the bank list API. e.g. HDFC | | aadhar | string | yes | RSA-encrypted, Base64-encoded Aadhaar number. 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. e.g. BASE64_ENCRYPTED_AADHAAR | | latlong | string | yes | GPS coordinates of the transaction origin in 'latitude,longitude' format. e.g. 28.6139,77.2090 | | piddata | string | yes | 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. e.g. ... | | amount | number | yes | Withdrawal amount in Indian Rupees (integer). Must be greater than 0 for cash withdrawal. e.g. 1000 | ## Headers | Field | Type | Required | Description | | --- | --- | --- | --- | | developer_key | string | yes | Static API key issued to your account after KYC. | | secret-key | string | yes | Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))). | | secret-key-timestamp | string | yes | Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time. | | content-type | string | yes | application/json e.g. application/json | ## Response ⭐ marks fields highlighted as verifiable. | Field | Type | Description | | --- | --- | --- | | status | number | Primary success indicator (0 = success). | | message | string | Human-readable response / error message. | | response_status_id | number | Granular status id; see the shared error-codes table. | | response_type_id | number | A unique id for every possible response shape (success or error) — useful for client logic branching and analytics. | | tx_status | string | Transaction state: 0=Success, 1=Fail, 2=Awaited, 3=Refund Pending, 4=Refunded, 5=On Hold. | | txstatus_desc | string | Human-readable transaction status. | | data | object | API-specific response payload. | | data.tid ⭐ | string | Eko's internal transaction ID. Use for reconciliation and support queries. | | data.amount ⭐ | string | Withdrawal amount processed in the transaction (INR). | | data.bank ⭐ | string | Name of the customer's bank where the debit occurred. | | data.bank_ref_num ⭐ | string | Bank/NPCI reference number (RRN) for the transaction. Empty on failure. | | data.balance | string | Remaining balance in the customer's bank account after withdrawal, if returned by the bank. | | data.customer_balance ⭐ | string | Customer's account balance as reported by the bank. Empty when not returned. | | data.tds | string | Tax deducted at source on the agent's commission (INR). | | data.commission | string | Commission earned by the agent on this transaction (INR). | | data.fee | string | Fee charged for the transaction (INR). May be empty. | | data.service_tax | string | Service tax component on the fee (INR). May be empty. | | data.totalfee | string | Total fee including taxes (INR). May be empty. | | data.shop | string | Agent's shop/merchant name. | | data.shop_address_line1 | string | Agent's shop address. May be empty. | | data.sender_name | string | Name of the agent/sender initiating the transaction. | | data.merchantname | string | Registered merchant name of the agent. | | data.merchant_code | string | Merchant code of the agent. May be empty. | | data.user_code | string | Echo of the agent's user_code from the request. | | data.aadhar | string | Masked Aadhaar number of the customer. | | data.auth_code | string | Bank authorization code. May be empty. | | data.stan | string | System Trace Audit Number assigned by the switch. May be empty. | | data.terminal_id | string | Terminal identifier. May be empty. | | data.tx_status | string | Transaction state within the data block: 0=Success, 1=Fail, 2=Pending. | | data.transaction_date | string | Transaction date (DD-MM-YY HH:MM:SS). | | data.transaction_time | string | Transaction timestamp (DD-MM-YY HH:MM:SS). | | data.reason | string | Failure reason, when the transaction did not complete. Empty on success. | | data.comment | string | Human-readable transaction remark from the provider (e.g. 'Request Completed'). | ## Response types Branch on `response_type_id` to decide the next call: | response_type_id | Meaning | Next step | | --- | --- | --- | | 1463 | Transaction Successful | — | | 1464 | Transaction Fail | — | | 1465 | Transaction Pending — check final status later | [transaction-inquiry](https://eps.eko.in/docs/transaction-inquiry.md) | ## Example request ```json { "initiator_id": "9962981729", "client_ref_id": "2026010100123456789", "user_code": "10000001", "bank_code": "HDFC", "aadhar": "BASE64_ENCRYPTED_AADHAAR", "latlong": "28.6139,77.2090", "piddata": "...", "amount": 1000 } ``` ## Example response `response_type_id` `1463` — Transaction Successful. ```json { "response_status_id": 0, "data": { "tx_status": "0", "tds": "0.00", "shop": "Test User", "sender_name": "Test User", "tid": "0000000000", "bank": "Example Bank", "balance": "0.00", "user_code": "10000001", "merchantname": "Test User", "aadhar": "XXXX XXXX 0000", "customer_balance": "0.00", "transaction_time": "01-01-24 00:00:00", "commission": "0.00", "bank_ref_num": "0000000000", "transaction_date": "01-01-24 00:00:00", "amount": "1000.00", "comment": "Request Completed" }, "response_type_id": 1463, "message": "Transaction Successful", "status": 0 } ``` ## Error scenarios | Status | response_type_id | Scenario | | --- | --- | --- | | 200 | `1464` — Transaction Fail | Transaction Fail — incorrect merchant credentials | | 200 | `1464` — Transaction Fail | Transaction Fail — invalid bank_code (transaction not completed) | | 200 | `1465` — Transaction Pending — check final status later | Transaction Pending — awaiting bank confirmation |