--- title: "Integration FAQs" description: "Common integration questions — credentials, request signing, environments, error handling and support." canonical: "https://eps.eko.in/docs/faqs" --- > **Canonical URL:** https://eps.eko.in/docs/faqs > 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. # Integration FAQs The questions developers ask most while wiring up an Eko API — credentials, request signing, environments, error handling and where to get unstuck. Each answer links to the guide or tool that goes deeper. > In a hurry? Point an AI coding agent at our [MCP server](/ai#install) and ask > it to build the integration for you — it can look up any endpoint, sign > requests correctly, and scaffold the code in your own stack. ## Getting started #### How do I get started? Four steps: **sign up** at the [developer console page](/console), verify your identity with PAN and address details, load your wallet to test the APIs live, then integrate and go live. Sandbox credentials are issued immediately — you can call your first endpoint before any paperwork clears. Also see: [Developer docs](https://eps.eko.in/docs) · [Sign up](https://eps.eko.in/console) #### What is EPS? **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. Also see: [About Eko](https://eps.eko.in/about) ## Authentication & keys #### How does API authentication work? 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](/docs/how-auth-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. Also see: [How auth works](https://eps.eko.in/docs/how-auth-works) · [Set up auth with AI](https://eps.eko.in/ai#install) #### Why does my API call return 401 Unauthorized? 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](/docs/how-auth-works#try-it-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. Also see: [Authentication errors](https://eps.eko.in/docs/error-codes#authentication-errors-http-401) · [Troubleshooting a 401](https://eps.eko.in/docs/how-auth-works#troubleshooting-a-401) The [How Authentication Works](/docs/how-auth-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. ## Environments & testing #### Is there a sandbox environment for testing? 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](/ai#artifacts) (`npx -y @ekoindia/eps-mock-server`) and get canned responses with no network calls at all. Also see: [Get started](https://eps.eko.in/docs) #### What are the sandbox and production base URLs? 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**. Also see: [Get started](https://eps.eko.in/docs) · [How auth works](https://eps.eko.in/docs/how-auth-works) ## Integration & errors #### What are the different ways to integrate with Eko EPS? 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](/ai#install). For multi-step flows (onboard a sender, *then* transfer) start from a [transaction-flow recipe](/recipe) rather than wiring single endpoints together yourself. Also see: [SDK guides](https://eps.eko.in/docs/sdk) · [Developer docs](https://eps.eko.in/docs) · [Integrate with AI](https://eps.eko.in/ai) #### Do I need to whitelist my server IP? 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. Also see: [Security & data protection](https://eps.eko.in/security#api-security) #### What response times can I expect? 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. #### Can the API handle high volumes? Yes. The API is designed to handle **large-scale volumes** reliably without performance degradation. #### How are errors and failures reported? 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](/docs/error-codes) reference lists every code and what to do about it. Also see: [Error codes reference](https://eps.eko.in/docs/error-codes) #### How does API versioning work? 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. Also see: [Developer docs](https://eps.eko.in/docs) #### How do I capture an Aadhaar fingerprint or biometric? 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)](/docs/aadhaar-biometric-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. Also see: [RDService guide & device tester](https://eps.eko.in/docs/aadhaar-biometric-rdservice) #### How do I chain multiple API calls into one flow? 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**](/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](/ai#install), so an agent can execute a whole flow end to end. Also see: [Transaction flows (recipes)](https://eps.eko.in/recipe) #### Are there any common integration gotchas to know? 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](/docs/how-auth-works). - The `JSESSIONID` cookie Postman adds automatically is **harmless** — it has no effect on the API and can be ignored. Also see: [Error codes reference](https://eps.eko.in/docs/error-codes) ## Building with AI #### Can an AI coding agent build the integration for me? 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](/ai#install), or start from a [ready-made prompt](/ai#quick-start). 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. Also see: [AI tools & MCP server](https://eps.eko.in/ai) · [Quick start prompt](https://eps.eko.in/ai#quick-start) ## Security & compliance #### Where is my data stored and processed? 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. Also see: [Infrastructure & data residency](https://eps.eko.in/security#infrastructure) #### Does Eko store Aadhaar numbers or biometric data? 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. Also see: [Infrastructure & data residency](https://eps.eko.in/security#infrastructure) #### Is the platform independently audited? Which regulations does it follow? 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. Also see: [Audit & compliance](https://eps.eko.in/security#compliance) #### What API security controls are in place? 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. Also see: [API & access security](https://eps.eko.in/security#api-security) #### How are money transfers, AePS and bill payments authenticated? - **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**. Also see: [Transaction security](https://eps.eko.in/security#transactions) #### How do I avoid duplicate transactions after a timeout? 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](/docs/transaction-inquiry) using that reference before retrying. Also see: [Transaction security](https://eps.eko.in/security#transactions) #### Can I get transaction logs and reconciliation reports for audits? 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**. Also see: [Audit trail & reconciliation](https://eps.eko.in/security#audit-trail) The [Security & data protection](/security) page covers infrastructure, data residency, audits and transaction safeguards in one place. ## Support #### How do I report an integration issue? 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". #### Where can I find the developer integration FAQ? Inside the API docs: [**Integration FAQs**](/docs/faqs) collects the credential, signing, environment, error-handling and support questions in one place, right next to the endpoint reference and guides. Also see: [Integration FAQs](https://eps.eko.in/docs/faqs) > This page covers the developer-facing questions. Commercial questions — > pricing and billing — live on the [main FAQ page](/faq).