Sethara Pay API: integration guide

Integration guide and API reference for Sethara Pay. Start with "Getting started", then create a payment and handle callbacks.

Getting started

Environments

Create API keys in the merchant cabinet (https://admin.setharapay.io, Settings). Every request carries the key in Authorization: Bearer <key> or X-Api-Key: <key>. Requests are accepted only from the IP addresses allow-listed for the key. Keys can be rotated in the cabinet at any time; the previous key keeps working until you revoke it.

All amounts are strings with two decimals in INR. Timestamps are ISO 8601 in UTC.

Create a payment

Call POST /intake or POST /release with the order amount, your own order reference and the webhook URL that will receive status updates.

{
  "book_sum": "1250.00",
  "book_ccy": "INR",
  "trace_key": "order-2026-000123",
  "ping_url": "https://merchant.example/hooks/payments",
  "leg_type": "p2p_leg"
}

• trace_key makes the call idempotent: repeating a request with the same value returns the original payment instead of creating a second one. Use your order id.
• ping_url is required. It must be an HTTPS URL reachable from the internet.
• The response contains book_id (store it), book_state and page_url: redirect the payer to that page. It shows the payment details, opens the payer's UPI app and collects the confirmation. You do not need to render anything yourself.

Payment lifecycle

A payment moves through the states below. Poll GET /{id}/status (no more often than every 5 seconds) or, better, rely on the callback and use polling only as a fallback.

Only final states are stable. Never treat an intermediate state as paid. clear_sum is the amount actually received and clear_at the time the funds were confirmed.

Callbacks

Every state change is delivered with POST to the ping_url of the payment. The body has the same shape as the status response.

Each delivery carries X-Webhook-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of the string <t>.<raw request body> computed with the webhook secret issued to you at onboarding (keep it out of your client-side code). Recompute it over the raw body exactly as received, compare in constant time and reject deliveries whose t is older than five minutes. If no webhook secret was issued for your account, the header is absent and you must fetch the payment state with the status endpoint before acting on a callback.

Respond with any 2xx status within 10 seconds. Any other response or a timeout is retried with increasing delays for about 32 hours, so your handler must be idempotent: the same event can arrive more than once. Process by book_id and the state, not by delivery order.

Payer confirmation and receipts

On the hosted payment page the payer completes the transfer in a UPI app or by bank transfer and then confirms it either with the 12-digit bank reference (UTR) or by uploading a receipt. Sethara Pay matches the confirmation against the incoming funds; the payment stays in an intermediate state until the match is complete and then moves to a final state, which you receive through the callback.

If you collect the bank reference yourself, submit it with POST /confirm-leg together with book_id. A reference that does not match, was already used or belongs to a different amount ends the payment with a final failure state and halt_note explaining why; the payer is offered to upload a receipt or to contact support on the page.

Errors

Errors are returned with an HTTP status and a stable code. Use the code, not the message, in your logic.

Validation problems (missing fields, wrong types) come back as 400 with a list of fields. 401 means the key or the source IP is not accepted. 5xx responses are safe to retry with the same trace_key.

Sandbox and testing

Use the sandbox base URL with sandbox keys from https://beta-admin.setharapay.io. Payments there never move real money: the payment page lets you complete or fail a payment on demand, so you can test every state, the callback signature and your retry handling. Check that your endpoint answers 2xx and that repeated deliveries do not create duplicate orders.

Reconciliation

The merchant cabinet provides a settlement report (CSV or XLSX) for any period with the bank reference of every payment, gross amount, fees and net amount. Match the report against your bank statement by the bank reference. Payouts show the same breakdown per settlement.

API reference

Machine-readable OpenAPI: openapi.json next to this guide. Endpoints: /intake, /release, /{id}/status, /confirm-leg.