Node.js SDK

@ekoindia/eps-sdk is a thin, dependency-free client for every EPS API. One generic call(slug, params) covers all of them: the endpoint catalog, each endpoint's params and which of them are required are baked into the package from the same surface these docs are built from, so the client validates your input before it signs and sends anything.

Warning

Backend only. accessKey signs every request — it must never reach a browser, a mobile app, or any bundle a user can read. The constructor throws if it detects a window global, but that guard is a safety net, not a strategy.

Install

npm i @ekoindia/eps-sdk

View @ekoindia/eps-sdk on npm

Package: @ekoindia/eps-sdk
Requires: Node.js 18 or newer
Dependencies: None — standard library only (node:crypto, global fetch).
Source: GitHub

Your first call

Set the two keys from your secret store, pick an environment, and call an endpoint by its slug:

import { EpsClient } from "@ekoindia/eps-sdk";

const client = new EpsClient({
  developerKey: process.env.EPS_DEVELOPER_KEY,
  accessKey: process.env.EPS_ACCESS_KEY,
  initiatorId: "9962981729",
  environment: "sandbox",
});

const result = await client.call("pan-lite", {
  "pan_number": "ABCDE1234F",
  "name": "Rajesh Kumar",
  "dob": "1994-08-29"
});
console.log(result);

initiatorId and userCode are near-constant per developer, so set them once on the client. They are injected into every call as the wire params initiator_id and user_code — pass either in params to override it for a single call, or pass null to clear it.

Client options

Option	Type	Required	Notes
`developerKey`	`string`	Yes	Your EPS developer key, sent as the `developer_key` header.
`accessKey`	`string`	Yes	Server-side secret used to sign every request. Never ships to a browser.
`environment`	`"sandbox" \| "production"`	Yes	Selects the base URL from the embedded surface.
`initiatorId`	`string`	No	Default `initiator_id` (registered mobile of the API user) injected into every call.
`userCode`	`string`	No	Default `user_code` (retailer/agent code) injected into every call.
`timeoutMs`	`number`	No	Aborts a request that takes longer. Named for its unit — Python and PHP use seconds. (milliseconds, default 30_000)
`fetch`	`typeof fetch`	No	Inject a custom fetch implementation (proxies, tests).

API surface

The SDK is deliberately small. There is no method per endpoint — call() takes the slug, and the baked surface supplies the method, path, and validation rules.

Member	Signature	What it does
`EpsClient` class	`new EpsClient(options: EpsClientOptions)`	The client. Throws immediately if constructed where `window` exists — `accessKey` must never reach a browser.
`call` method	`client.call<T = unknown>(slug: string, params?: Record<string, unknown>): Promise<T>`	Validates, signs and sends one endpoint call; resolves with the decoded envelope.
`signSecretKey` function	`signSecretKey(accessKey: string, timestamp: string): string`	The raw signing primitive, exported for debugging. `call()` applies it for you.
`MULTIPART_JSON_FIELD` constant	`MULTIPART_JSON_FIELD = "form-data"`	Name of the single form field carrying the JSON envelope on file-upload endpoints.
`EpsClientOptions` type	`interface EpsClientOptions`	The constructor options above.
`SdkEndpoint / SdkParam` type	`interface SdkEndpoint, interface SdkParam`	Shape of one endpoint in the embedded surface (slug, method, path, params).

Authentication

You never compute a signature yourself. On every request the client derives secret-key = base64(HMAC-SHA256(timestamp, base64(accessKey))) and sends it with secret-key-timestamp and developer_key. signSecretKey is exported only so you can reproduce a signature while debugging a 403.

File uploads

A single type: "file" param flips the whole request to multipart/form-data. You still pass every parameter flat; on the wire the SDK packs them the way the API expects — one form field named form-data holding all the non-file params as a single JSON object, plus one part per upload. A null param is dropped (a form field has no null encoding), while a null nested inside an object value is preserved.

File params accept:

A local file path (read from disk; the filename is the basename)
A Blob or File (a File keeps its own name)

Errors and timeouts

A non-2xx response throws — an auth or infrastructure failure is never returned as if it were a result. The decoded envelope is still on the error, so you can read status and message off it.

Type	Raised when	Fields
`EpsHttpError`	Any non-2xx response.	`status`, `url`, `body` (decoded envelope or null), `raw`
`EpsError`	Unknown slug, missing required param, wrong param type, bad option, or a 2xx body that is not JSON. `EpsHttpError` extends it.	—
`TimeoutError (DOMException)`	The request exceeded `timeoutMs`. Surfaced raw, as Node reports it.	—

HTTP status	Meaning
`200`	OK — response returned by our system.
`403`	Forbidden — incorrect secret-key or timestamp.
`404`	Not Found — wrong request URL.
`405`	Method Not Allowed — incorrect HTTP method.
`415`	Unsupported Media Type — wrong Content-Type header.
`500`	Internal Server Error — connectivity or URL misconfiguration.

Environments

Switch with the environment option; there is no base-URL override.

Environment	Base URL	Notes
`sandbox` UAT / Sandbox	`https://staging.eko.in/ekoapi/v3`	Self-serve credentials available immediately on signup.
`production` Production	`https://api.eko.in/ekoicici/v3`	Credentials issued after organizational KYC.

Node-specific notes

ESM only ("type": "module"). Use import, or await import() from CommonJS.
A per-call cancellation signal is not supported yet — timeoutMs is the only abort source.

Every endpoint

call() accepts every slug in the EPS catalog. Each endpoint's reference page shows its parameters, response fields and a ready-to-paste Node.js snippet.

Browse the API reference