API overview

v2· latest

The UPI Setu API exposes payment collection, mandates, refunds, and QR generation behind a single REST surface. This page is the 30-second tour: how to authenticate, which environment to call, how we handle failures, and where every endpoint lives.

Base URL

https://uat.setu.co

sandbox

Auth

X-Client-* headers

see Authentication

Version

stable

Rate limit

120 req / min

per credential

01Authentication

Every request carries three identifiers issued in The Bridge. Sandbox keys are pre-seeded the moment you create an app.

Header	Purpose
`X-Client-ID`	Identifies your app. Safe to include in any environment.
`X-Client-Secret`	Secret shared with your app. Never expose in the browser.
`X-Setu-Product-Instance-ID`	Routes the request to a specific product instance.

Sandbox credentials are pre-generated and live under Apps → UMAP → Credentials in The Bridge.

02Environments

Environment	Base URL	Behavior
Sandbox	`https://uat.setu.co`	Simulated bank rails. No money moves.
Production	`https://prod.setu.co`	Live rails. Activated after KYC.

03Idempotency

Send an Idempotency-Key header on every POST. Retrying the same key returns the original response without creating a duplicate.

Keys are scoped per credential.
Keys expire after 24 hours.
Editing the body with the same key returns 409 Conflict.

04Errors

Errors follow a consistent shape: code, message, optional details. Status codes map to operational categories so retries can be automated cleanly.

200

Request succeeded.

201

Created

Resource created. Returned for collect / mandate POSTs.

400

Bad Request

Validation failed. See details[].

401

Unauthorized

Missing or invalid credentials.

404

Not Found

Resource id does not exist (or is not yours).

409

Conflict

Idempotency key reused with a different body.

429

Rate limited

Throttled. Retry with backoff.

500

Internal

Setu-side failure. Retry safe; we will not double-charge.

05Pagination

List endpoints return cursors, not page numbers:

{
  "data": [/* … */],
  "page": { "next": "eyJpZCI6ICJwY18xMjMifQ==", "hasMore": true }
}

Pass ?after=<cursor> to get the next page. Cursors are stable for 7 days.

06Webhooks

Subscribe to events in The Bridge. Setu retries failed deliveries with exponential backoff for 24 hours, then quarantines them for manual replay.

Verify the X-Setu-Signature header on every webhook — it's an HMAC-SHA256 of the raw request body with your webhook secret.

07Endpoints

Payments

Initiate, query, and finalize UPI collects.

POST/api/v2/paymentsCreate collectInitiate a UPI collect request for a customer VPA.Open →GET/api/v2/payments/{id}Get collectFetch the status and metadata of a collect by id.Open →POST/api/v2/payments/{id}/expireExpire collectCancel an open collect before the customer pays.Open →POST/api/v2/payments/{id}/transfersInitiate transferMove the collected amount onward after a successful collect.Open →

QR codes

Static and dynamic QR generation for offline collection points.

POST/api/v2/merchants/dqrCreate dynamic QROne-time QR for a specific amount.Open →POST/api/v2/merchants/sqrCreate static QRReusable QR for a merchant terminal.Open →

Mandates

Recurring debit authorization on UPI.

POST/api/v2/mandatesCreate mandateSet up a recurring debit on a customer VPA.Open →GET/api/v2/mandates/{id}Get mandateFetch a mandate's current status and history.Open →POST/api/v2/mandates/{id}/revokeRevoke mandateEnd a customer's standing authorization.Open →

PreviousQuickstart Try itOpen the API playground