setu-client

Production-grade TypeScript SDK for the Setu API platform.

This SDK provides:

• Typed configuration management
• Automatic OAuth token management with caching
• Retry + exponential backoff handling
• Built-in client-side rate limiting
• Structured error handling
• Telemetry hooks for observability
• Webhook dispatch utilities
• Validation helpers
• UPI, BBPS, KYC, AA, and eSign integrations

---

Features

Core Infrastructure

Configuration

Located in config/index.ts

• Environment-aware URL resolution
• Immutable validated SDK configuration
• Sandbox and production support
• Request timeout and retry configuration
• Built-in rate limiting configuration

Token Management

Located in token/index.ts

• Automatic access token fetching
• In-memory token caching
• Token refresh buffering
• Singleflight refresh deduplication
• Cache invalidation helpers

HTTP Client

Located in http/index.ts

• Typed request wrappers
• Automatic retries
• Full-jitter exponential backoff
• Timeout handling
• Structured API error decoding
• Integrated telemetry and rate limiting

Rate Limiting

Located in ratelimit/index.ts

• Token bucket implementation
• Per-client/environment buckets
• Configurable burst limits
• Request throttling with timeout support

Telemetry

Located in telemetry/index.ts

Event-based observability layer using Node.js EventEmitter.

Supported events:

• request:start
• request:stop
• request:exception
• token:refresh
• ratelimit:wait

---

Installation

npm install setu-client

---

Quick Start

import { createConfig } from "setu-client";
import { createDqr } from "setu-client/payments/upi";

const cfg = createConfig({
  clientId: process.env.SETU_CLIENT_ID!,
  clientSecret: process.env.SETU_CLIENT_SECRET!,
  environment: "sandbox",
});

const result = await createDqr(cfg, "merchant-id", {
  merchantVpa: "shop@upi",
  amount: 10_000,
});

if (result.ok) {
  console.log(result.data);
} else {
  console.error(result.error);
}

---

Project Structure

setu-client/
├── config/
├── data/
│   ├── aa.ts
│   ├── esign.ts
│   └── kyc/
├── error/
├── http/
├── payments/
│   ├── bbps.ts
│   └── upi.ts
├── ratelimit/
├── telemetry/
├── token/
├── validation/
├── webhook/
└── index.ts

---

Configuration

Creating a Config

import { createConfig } from "setu-client";

const cfg = createConfig({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  environment: "sandbox",
});

Configuration Options

Option	Description	Default
clientId	Setu client ID	Required
clientSecret	Setu client secret	Required
productInstanceId	Product instance ID	Optional
environment	sandbox or production	sandbox
timeoutMs	Request timeout	30000
maxRetries	Maximum retry attempts	3
retryBaseDelayMs	Base retry delay	500
retryMaxDelayMs	Max retry delay	10000
rateLimitRps	Requests per second	100
rateLimitBurst	Burst capacity	20

---

Error Handling

Located in error/index.ts

All SDK operations return:

type SetuResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: SetuError };

Error Types

Type	Description
api	Non-2xx API response
auth	Authentication failure
rate_limit	HTTP 429 response
network	Network or timeout issue
validation	Local validation failure
decode	JSON decoding failure

Example

if (!result.ok) {
  console.error(result.error.type);
  console.error(result.error.message);
}

---

Validation Utilities

Located in validation/index.ts

Available helpers:

• requireParam()
• requirePositive()
• requireId()
• requireMerchant()
• chain()

Example

const validation = chain(
  requireMerchant(merchantId),
  requirePositive(amount, "amount")
);

if (!validation.ok) {
  return validation.error;
}

---

Telemetry

Located in telemetry/index.ts

Listening to Events

import { telemetry } from "setu-client";

telemetry.on("request:start", (event) => {
  console.log(event.method, event.url);
});

Request Lifecycle Events

request:start

{
  method: string;
  url: string;
  attempt: number;
  startTimeMs: number;
}

request:stop

{
  method: string;
  url: string;
  attempt: number;
  durationMs: number;
  httpStatus?: number;
}

request:exception

{
  method: string;
  url: string;
  attempt: number;
  durationMs: number;
  error: SetuError;
}

---

Token Management

Located in token/index.ts

Features

• Automatic token refresh
• Token caching
• Refresh buffering
• Concurrent request deduplication

Helpers

import {
  getToken,
  invalidateToken,
  clearTokenCache,
} from "setu-client";

---

Webhook Utilities

Located in webhook/index.ts

Unified webhook dispatcher for all Setu events.

Supported Event Categories

Payments

• payment.initiated
• payment.pending
• payment.success
• payment.failed

Mandates

• mandate.initiated
• mandate.live
• mandate.rejected
• mandate.paused
• mandate.revoked
• Mandate operation lifecycle events

Refunds

• refund.pending
• refund.successful

Disputes

• dispute_created
• dispute_open
• dispute_closed
• dispute_in_review
• dispute_won
• dispute_lost

Account Aggregator Events

• CONSENT_STATUS_UPDATE
• SESSION_STATUS_UPDATE

BBPS Settlement Events

Automatically detected using payload structure.

Example

import { dispatchRaw } from "setu-client/webhook";

await dispatchRaw(rawBody, {
  async handlePayment(event) {
    console.log("Payment event", event);
  },

  async handleConsent(event) {
    console.log("Consent update", event);
  },
});

Helper Functions

• eventType()
• consentId()
• sessionId()
• consentStatus()
• sessionStatus()
• isPaymentSuccessful()
• isConsentActive()
• isSessionCompleted()

---

Payments APIs

Located in payments/

UPI Module

File: payments/upi.ts

Provides helpers for:

• Dynamic QR creation
• Payment link generation
• Transaction retrieval
• UPI collect flows
• Merchant transaction history

BBPS Module

File: payments/bbps.ts

Provides helpers for:

• Bill payment flows
• Settlement history
• BBPS transaction management

---

Data APIs

Located in data/

Account Aggregator

File: data/aa.ts

Features:

• Consent creation
• Session handling
• Financial information retrieval
• Consent status tracking

eSign

File: data/esign.ts

Features:

• Electronic signature workflows
• Document signing integration
• Status retrieval

---

KYC APIs

Located in data/kyc/

Supported integrations:

File	Purpose
bav.ts	Bank account verification
digilocker.ts	DigiLocker integration
ekyc.ts	Electronic KYC workflows
gst.ts	GST verification
namematch.ts	Name matching utilities
pan.ts	PAN verification

---

HTTP Behavior

The SDK automatically handles:

• Retries for retryable status codes
• Retryable network errors
• Exponential backoff
• Rate limiting
• Request timeout handling
• Structured error decoding

Retryable HTTP statuses:

• 429
• 500
• 502
• 503
• 504

---

Design Principles

Functional Error Handling

The SDK avoids throwing for expected operational errors.

Instead:

const result = await someSdkCall();

if (result.ok) {
  // success
} else {
  // handle error
}

Immutable Configuration

createConfig() returns a frozen configuration object.

Safe Concurrency

Token refresh requests are deduplicated to prevent token stampedes.

Production Readiness

The SDK includes:

• Retry strategies
• Rate limiting
• Telemetry hooks
• Timeout handling
• Structured errors
• Validation helpers

---

Environment URLs

Sandbox

• Account Service: https://accountservice.setu.co
• UMAP API: https://umap.setu.co/api
• Data Gateway: https://dg-sandbox.setu.co
• FIU: https://fiu-sandbox.setu.co

Production

• Account Service: https://accountservice.setu.co
• UMAP API: https://umap.setu.co/api
• Data Gateway: https://dg.setu.co
• FIU: https://fiu.setu.co

---

Best Practices

• Reuse a single SetuConfig instance
• Attach telemetry listeners for monitoring
• Handle all SetuResult failures explicitly
• Use sandbox before production rollout
• Tune retry and rate-limit settings based on traffic

---

Example Express Webhook Integration

import express from "express";
import { dispatchRaw } from "setu-client/webhook";

const app = express();

app.post(
  "/webhooks/setu",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const ok = await dispatchRaw(req.body.toString(), {
      async handlePayment(event) {
        console.log("payment", event);
      },
    });

    res.sendStatus(ok ? 200 : 400);
  }
);

---

Exports

The root index.ts re-exports:

• Configuration helpers
• Error utilities
• Telemetry
• Token helpers
• Rate limiter helpers
• Validation helpers
• Webhook helpers
• Payments APIs
• KYC APIs
• AA APIs
• eSign APIs

---

Summary

This SDK is structured as a production-ready foundation for integrating with the Setu ecosystem.

It provides:

• Strong TypeScript ergonomics
• Safe and predictable error handling
• Scalable networking primitives
• Observability support
• Modular API integrations
• Built-in resiliency patterns

Suitable for:

• Payment gateways
• Fintech backends
• KYC pipelines
• Account Aggregator integrations
• BBPS workflows
• Enterprise API platforms