Frequently asked questions

EPS (Eko Platform Services) is the technology arm of Eko — the developer tools, AI tooling and APIs that power modern fintech integration, from money transfer and AePS to identity verification.

Three paths, pick whichever suits your stack:

• Call the REST APIs directly.
• Use our official Node.js, Python, PHP, Go or Java SDKs to skip request-signing boilerplate.
• Let an AI coding agent build it via our MCP server and agent skills.

For multi-step flows (onboard a sender, then transfer) start from a transaction-flow recipe rather than wiring single endpoints together yourself.

Each request carries your static developer_key header plus a per-request secret-key header — an HMAC-SHA256 signature of the current timestamp, keyed by your access key. The access key itself is never sent over the wire. You receive UAT keys on signup and production keys after KYC.

The How Authentication Works guide has the full signing recipe in five languages plus an in-browser playground that generates and verifies a real secret-key against your own access key.

Authentication failed. For the known causes, the response body's status names the check that failed:

• 2483 — The developer_key is wrong.
• 2484 — The secret-key (signature) is wrong.
• 2485 — The secret-key-timestamp is more than 2 minutes older or newer than the server clock, or was reused from an earlier request.
• 2486 — The secret-key-timestamp is not in milliseconds (13 digits) — often seconds (10 digits).
• 2487 — The secret-key or secret-key-timestamp header is missing.

If your signature checks out in the secret-key playground and you still get a 401, make sure the base URL matches your keys (UAT vs production) and, in production, that your server's IP is whitelisted.

Yes. A full sandbox is available immediately on signup — test your integration end-to-end before going live, no commitment required. For offline work you can also run our mock server (npx -y @ekoindia/eps-mock-server) and get canned responses with no network calls at all.

Sandbox and production share the same paths and differ only by base URL:

• UAT / Sandbox — https://staging.eko.in/ekoapi/v3
• Production — https://api.eko.in/ekoicici/v3

A common cause of failures is calling the sandbox URL with live credentials, or vice-versa — make sure the base URL matches the keys you are using.

It's optional. IP whitelisting is available for production access as an extra layer of security — share your static public (server) IP with us and we'll whitelist it.

Yes — that is the fastest path. Point your agent (Claude Code, Codex, Cursor, Copilot, …) at our MCP server and it can look up any endpoint, generate correctly-signed requests, and scaffold the integration in your own stack. Install it in one step from the AI hub, or start from a ready-made prompt.

We also publish an OpenAPI 3.1 spec, a Postman collection and per-agent context packs (AGENTS.md, CLAUDE.md, .cursorrules) so an agent has the ground truth instead of guessing.

Most verification APIs return in real time with sub-second responses, and 99th-percentile latency stays under two seconds across verification endpoints. Transaction APIs (DMT, AePS, BBPS) respond within seconds.

Yes. The API is designed to handle large-scale volumes reliably without performance degradation.

Usage is billed per successful API call with no minimum commitment. Volume-based pricing tiers are available — see the pricing calculator for indicative rates, or contact our team for a custom quote.

Every response carries a status code (0 = success), a human-readable message, and a response_status_id (a UI display hint only — never use it for business logic). A 200 OK with a non-zero status is a business failure, not a transport success — always check both before treating a call as done. The Status & Error Codes reference lists every code and what to do about it.

Eko APIs are versioned in the base path (currently v3). Sandbox and production share the same paths and differ only by base URL, so promoting an integration from UAT to live is a base-URL and credentials change — not a code change.

Through a UIDAI registered device (RDService) — the scanner returns a signed, encrypted PID block that you pass straight through to the API. Never capture or store raw biometrics yourself.

The Aadhaar Biometric Auth (RDService) guide covers both the Windows/Web and Android capture paths, and includes an in-browser device tester — plug in your scanner and confirm it works before writing any code.

Most real use cases are multi-step — onboard a customer, verify them, then transact. Rather than stitching endpoints together from the reference, start from a transaction flow recipe: each one is an ordered runbook showing which endpoint to call at each step and how to branch on status and response_type_id.

The same recipes are available to AI agents through our MCP server, so an agent can execute a whole flow end to end.

Only in India. The platform runs on Microsoft Azure, with a primary data centre in Central India (Pune) and a disaster-recovery site in South India (Chennai), in line with RBI's data-localisation requirements.

No. Aadhaar numbers are never stored, and biometric data (fingerprints / PID blocks) is passed straight through for authentication and never retained. We retain no data that UIDAI, RBI or other applicable regulations prohibit us from storing.

Yes. RBI-empanelled auditors audit our information-security controls every year against ISO/IEC 27001. The platform complies with RBI regulations for payment services and Business Correspondent operations, and with KYC and AML/CFT norms. Aadhaar-based KYC is performed only with explicit customer consent.

Every request is HMAC-SHA256 signed with a private key issued to your account, all traffic uses TLS 1.2+, and our SDKs are backend-only so keys never reach client apps. Sandbox and production are separate, and IP whitelisting is available as an optional extra layer for production.

• Money transfers (DMT): Senders complete a one-time biometric Aadhaar eKYC. Every transfer after that requires a fresh OTP sent to the sender's registered mobile. Transfers are capped at ₹5,000 per transaction, and sender-level monthly limits apply.
• AePS: Agents complete a one-time eKYC plus a biometric authentication each day before transacting. Customer withdrawals are authorised by fingerprint through UIDAI-certified RD-service devices, and withdrawals above ₹5,000 also need an SMS OTP.
• Bill payments (BBPS): Bill amounts are fetched live from the biller. Whenever a biller supports bill-fetch, the amount paid can never exceed the fetched bill amount.

Send a unique client_ref_id (10–20 characters) with every transaction. If a call is pending or times out, don't treat it as failed — confirm its status with the Transaction Inquiry API using that reference before retrying.

Yes. Full transaction logs, reconciliation data and settlement reports are maintained for audit and reporting, and reconciliation and settlement reports are shared over email on request.

Share the complete request and response so we can debug in one round trip:

• The full curl (including headers)
• The response body, verbatim
• The timestamp of the call
• Your initiator_id, user_code and client_ref_id

Issues raised with these details are resolved much faster than "the API is failing".

Three frequent ones:

• client_ref_id must be 10–20 characters and unique per request.
• Calling the sandbox base URL with live credentials (or vice-versa) fails auth — see How Authentication Works.
• The JSESSIONID cookie Postman adds automatically is harmless — it has no effect on the API and can be ignored.

Inside the API docs: Integration FAQs collects the credential, signing, environment, error-handling and support questions in one place, right next to the endpoint reference and guides.