MyHSRSP API reference

Create a checkout, send the customer to a hosted UPI page, then verify the result on your server. The API is JSON over HTTPS and works from any backend: PHP, Node, Python, Java, .NET, Go or serverless.

BASE https://your-domain.com/api

Overview

Every integration follows the same three-step loop:

  1. Create an order on your server with an amount and your own order_id.
  2. Redirect the customer to the returned payment_url (hosted checkout with QR + UPI intent).
  3. Verify server-side using check-status and/or the signed webhook, then deliver the goods.
Never mark an order as paid from a browser redirect, a screenshot or a URL query parameter. Only trust payment_status: "success" from your server-side call, or a webhook whose signature verifies.

Idempotency

Posting the same order_id twice does not create a second order. The existing order is returned with duplicate: true, so retries are safe.

Rate limits

240 requests per minute per API key + IP. Rate-limited responses are 429 with Retry-After.

Authentication

Create keys in Dashboard → API keys. Send them as headers on every request from your backend:

HeaderValue
X-API-KeyPublic key, e.g. pk_live_…
X-API-SecretSecret, e.g. sk_live_… — server-side only
Content-Typeapplication/json
Secrets are hashed at rest and shown once. Never bundle a secret into a mobile app, browser bundle or public repository. If a key leaks, rotate it immediately.

Connect your own UPI account (“personal API”)

MyHSRSP is non-custodial. You connect the collection channel you already own, and money moves directly into that account. There are three connection modes:

ModeCredentialsHow confirmation works
Manual UPI VPAYour UPI ID + payee name (e.g. store@okhdfcbank)Dynamic QR/intent, customer submits UTR, bank feed or merchant marks it paid
Merchant APIOfficial MID + merchant key / token (Paytm Business, BharatPe, PhonePe, Freecharge, MobiKwik, Binance Pay)Provider server-to-server callback, verified with your secret
SandboxNothing — a demo VPA is generatedSimulated success/failure from the checkout page
Consumer UPI apps (Google Pay, PhonePe personal, Paytm personal) do not expose a legal public payment API. Connect an official merchant account or your own VPA. Do not scrape apps or automate consumer notifications — it violates provider terms and can be fraudulent.

Connect from the dashboard

POST /api/m/accountsSession auth

Called by the dashboard (cookie session + X-Requested-With). The credential secret is encrypted with AES-256-GCM before storage.

{
  "provider": "manual_vpa",
  "label": "Primary collections",
  "vpa": "rohitstore@upi",
  "payee_name": "Rohit Store",
  "priority": 1,
  "daily_limit": 50000000
}

Successful connection — 201

{
  "status": "success",
  "message": "Manual UPI VPA connected",
  "data": {
    "id": "acc_01J8…",
    "provider": "manual_vpa",
    "provider_name": "Manual UPI VPA",
    "status": "active",
    "vpa": "rohitstore@upi",
    "test": {
      "connected": true,
      "credential_format_valid": true,
      "live_verification": "bank_feed_ready",
      "latency_ms": 12,
      "message": "VPA format verified. Incoming payments reconcile through UTR submissions and the bank feed."
    }
  }
}

Failed connection — 422

{
  "status": "error",
  "code": "INVALID_CREDENTIALS",
  "message": "Please check the connection details.",
  "details": [
    { "field": "vpa", "issue": "Enter a valid UPI ID, for example store@okhdfcbank" }
  ],
  "request_id": "req_3a27f8acd15828c7"
}

A connection test validates credential shape and reachability. For merchant APIs, the first verified provider callback flips live_verification to verified. This is deliberate: we never fabricate a provider-side success.

Test an existing account

POST /api/m/accounts/:id/test

Returns the same connected / live_verification contract, or 502 with status: "error" if the credential is invalid.

Provider callback endpoint

POST /webhooks/provider/:provider/:accountId

Configure this URL in the provider dashboard. Send the raw JSON body and an X-Signature header:

X-Signature: t=1795279286,v1=<hex HMAC-SHA256(secret, "1795279286." + rawBody)>

Body fields we map: order_id (your order ref), status (SUCCESS / FAILED / PENDING), amount, utr, txn_id. Unknown orders return 404 ORDER_NOT_FOUND; amount mismatches return 422 AMOUNT_MISMATCH.

Bank feed — instant verification for personal UPI

A personal VPA has no public payment API. To confirm personal UPI payments in real time, forward the credit notification from your bank (webhook, SMS-forwarder app, or statement automation) to the private bank-feed endpoint shown in Dashboard → Connected accounts → Bank feed setup.

POST /bank-feed/:accountIdBank-feed secret

Headers: X-Bank-Secret: <feed secret> (or a signed X-Bank-Signature). The body contains what your bank already credited — MyHSRSP does not move money.

curl -X POST "https://your-domain.com/bank-feed/acc_01J8..." \
  -H "Content-Type: application/json" \
  -H "X-Bank-Secret: bfeed_..." \
  -d '{
    "utr": "615372849102",
    "amount": 499.00,
    "vpa": "rohitstore@upi",
    "received_at": "2026-11-21T16:40:31Z",
    "payer": "Aarav Sharma"
  }'

If exactly one pending order has the same amount (within 48 hours), it is confirmed immediately:

{
  "status": "success",
  "message": "Credit matched to an order. Payment is confirmed.",
  "data": {
    "event_id": "bnk_01J8…",
    "utr": "615372849102",
    "amount": 499.00,
    "matched": true,
    "reason": "auto_matched",
    "order_id": "ORD-1042",
    "payment_status": "success",
    "duplicate": false,
    "webhook": "queued"
  }
}

If no order matches, or several pending orders share the amount, the credit is stored and the merchant reconciles it in Bank feed:

{
  "status": "success",
  "message": "Credit recorded. No unique pending order matched — reconcile it from the dashboard.",
  "data": {
    "event_id": "bnk_01J8…",
    "matched": false,
    "reason": "multiple_candidates",
    "order_id": null,
    "payment_status": "unmatched"
  }
}
The bank feed is pull-free and non-custodial: it only ingests a notification of money that is already in your bank. UTRs are idempotent, the secret is scoped to one account, and every auto-match queues the normal payment.success webhook.

Dashboard reconciliation endpoints (session auth):

GET /api/m/bank-feed?status=unmatched
GET /api/m/bank-feed/:id/candidates
POST /api/m/bank-feed/:id/match

Pass / fail contract

One field decides the outcome: data.payment_status. It is always one of:

payment_statusMeaningWhat you should do
pendingCheckout created, no confirmed credit yet.Show “waiting”, keep polling or wait for webhook. Do not deliver.
successConfirmed by provider callback or matched UTR. utr and paid_at are set.Fulfil the order, store the UTR, make fulfilment idempotent.
failedDeclined, cancelled or provider failure.Do not deliver. Ask for a new checkout.
expiredCheckout timed out before payment.Create a fresh order.
refundedA refund was recorded by the merchant.Reverse entitlement; refunds settle from the merchant’s bank.

Example — success

{
  "status": "success",
  "data": {
    "order_id": "ORD-1042",
    "gateway_order_id": "ord_0MWQMXM6DDNRB1NJR",
    "amount": 499.00,
    "currency": "INR",
    "payment_status": "success",
    "status": "success",
    "utr": "615372849102",
    "payment_method": "UPI QR",
    "provider": "manual_vpa",
    "gateway_txn_id": "TXN_9201938561",
    "paid_at": "2026-11-21T16:41:25.536Z",
    "failure_reason": null
  }
}

Example — pending

{
  "status": "success",
  "data": {
    "order_id": "ORD-1043",
    "payment_status": "pending",
    "status": "pending",
    "utr": null,
    "paid_at": null,
    "expires_at": "2026-11-21T16:56:25.381Z"
  }
}

Example — failed

{
  "status": "success",
  "data": {
    "order_id": "ORD-1044",
    "payment_status": "failed",
    "status": "failed",
    "utr": null,
    "failure_reason": "Customer cancelled the payment",
    "paid_at": null
  }
}

Create order

POST /api/create-order
FieldTypeRequiredNotes
amountnumberyesINR, minimum ₹1, maximum ₹2,00,000
order_idstringyes3–64 chars: letters, numbers, ._:-. Unique per merchant.
customer_namestringyesShown on the checkout
customer_mobilestringno10–15 digits
customer_emailstringnoStored for reconciliation
callback_urlstringnoAbsolute URL shown as “Return to merchant” after success
descriptionstringnoCheckout remark / product name
is_reusablebooleannoReserved for reusable checkouts
account_idstringnoForce a specific connected account; otherwise smart routing
curl -X POST "https://your-domain.com/api/create-order" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_…" \
  -H "X-API-Secret: sk_live_…" \
  -d '{
    "amount": 499.00,
    "order_id": "ORD-1042",
    "customer_name": "Aarav Sharma",
    "customer_mobile": "9876543210",
    "description": "Premium plan renewal",
    "callback_url": "https://your-site.com/payment/return"
  }'
HTTP/1.1 201 Created

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "payment_url": "https://your-domain.com/pay/EkIV9jMtXsnmHtKm8SX5dmF9Fx4",
    "order_id": "ORD-1042",
    "token": "EkIV9jMtXsnmHtKm8SX5dmF9Fx4",
    "amount": 499.00,
    "currency": "INR",
    "status": "pending",
    "payment_status": "pending",
    "provider": "manual_vpa",
    "expires_at": "2026-11-21T16:56:25.381Z",
    "created_at": "2026-11-21T16:41:25.381Z",
    "duplicate": false
  }
}

Check status

POST /api/check-status
curl -X POST "https://your-domain.com/api/check-status" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_…" \
  -H "X-API-Secret: sk_live_…" \
  -d '{ "order_id": "ORD-1042" }'

Returns 200 for any known order. Unknown orders return 404 ORDER_NOT_FOUND. If a pending order is past its expiry, calling this endpoint transitions it to expired before responding.

Refund

POST /api/refund

Records a refund against a successful order. Because funds settle directly to your bank, the actual bank transfer is performed by you; MyHSRSP records the refund for reporting and optional refund.processed webhooks.

{
  "order_id": "ORD-1042",
  "amount": 499.00,
  "reason": "Customer requested cancellation"
}

Partial refunds are allowed until the successful amount is exhausted. Over-refunding returns 422 INVALID_REFUND_AMOUNT.

UTR submission (public checkout)

POST /api/pay/:token/utr

Used by the hosted checkout when a manual VPA account is connected. If the UTR matches an unclaimed bank-feed event with the exact amount, the order is marked success instantly. Otherwise the UTR is stored and the order stays pending with a “verify against bank” notification for the merchant.

Duplicate UTRs are rejected with 409 UTR_ALREADY_USED.

Webhooks

Add an HTTPS endpoint in Dashboard → Webhooks. We POST a JSON event and retry on failure.

Headers

HeaderValue
X-Signaturet=<unix>,v1=<hex hmac>
X-Eventpayment.success, payment.failed, payment.expired
X-Delivery-IdUnique attempt id (for deduplication)
X-TimestampUnix seconds

Signing algorithm

signed_payload = timestamp + "." + raw_request_body
expected = HMAC_SHA256(webhook_secret, signed_payload)   // hex
compare with the v1= value using a constant-time compare

Reject requests where the timestamp is more than 5 minutes old, and deduplicate on X-Delivery-Id.

Event payload — success

{
  "event": "payment.success",
  "gateway_order_id": "ord_0MWQMXM6DDNRB1NJR",
  "order_id": "ORD-1042",
  "token": "EkIV9jMtXsnmHtKm8SX5dmF9Fx4",
  "amount": 499.00,
  "currency": "INR",
  "status": "success",
  "payment_status": "success",
  "utr": "615372849102",
  "provider": "manual_vpa",
  "payment_method": "UPI QR",
  "gateway_txn_id": "TXN_9201938561",
  "customer_name": "Aarav Sharma",
  "customer_mobile": "9876543210",
  "description": "Premium plan renewal",
  "paid_at": "2026-11-21T16:41:25.536Z",
  "created_at": "2026-11-21T16:41:20.000Z"
}

Event payload — failure

{
  "event": "payment.failed",
  "order_id": "ORD-1044",
  "amount": 199.00,
  "status": "failed",
  "payment_status": "failed",
  "failure_reason": "UPI transaction declined by bank",
  "utr": null
}

Retries

Failed attempts retry after 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, then stop. Every attempt is visible in the delivery log with response code and body. Respond 2xx quickly; do heavy work asynchronously.

Verification example (Node.js)

const crypto = require('crypto');

app.post('/hooks/paysetu', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.headers['x-signature'] || '';
  const [tPart, vPart] = header.split(',');
  const timestamp = tPart.replace('t=', '');
  const raw = req.body.toString('utf8');
  const expected = crypto
    .createHmac('sha256', process.env.SETU_WEBHOOK_SECRET)
    .update(`${timestamp}.${raw}`)
    .digest('hex');
  const ok = vPart.replace('v1=', '').length === expected.length &&
             crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(vPart.replace('v1=', '')));
  if (!ok) return res.status(400).send('invalid signature');
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.status(400).send('stale');

  const event = JSON.parse(raw);
  if (event.event === 'payment.success') {
    // idempotent fulfilment keyed on event.gateway_order_id
  }
  res.json({ received: true });
});

Callbacks

If you provide callback_url, the success screen shows a Return to merchant button pointing to that URL. Browser redirects are not a source of truth — always verify with check-status or the webhook before fulfilment.

Error codes

HTTPCodeMeaning
400INVALID_JSONBody is not a JSON object
401MISSING_API_CREDENTIALSKey or secret header missing
401INVALID_API_KEY / INVALID_API_SECRETKey revoked or secret wrong
402TRIAL_EXPIRED / PLAN_LIMIT_REACHEDSubscription or quota block
402SUBSCRIPTION_PAST_DUEInvoice overdue
403MERCHANT_SUSPENDEDWorkspace suspended by admin
404ORDER_NOT_FOUNDNo matching order_id
409UTR_ALREADY_USEDUTR linked to another order
422VALIDATION_ERROR / INVALID_AMOUNTField validation failed; see details[]
429RATE_LIMITEDSlow down; honour Retry-After
503NO_GATEWAY_CONNECTEDNo active collection account
503GATEWAY_LIMIT_REACHEDAll accounts hit daily caps

Errors always use the same shape:

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "customer_name is required.",
  "details": [{ "field": "customer_name" }],
  "request_id": "req_…"
}

Include request_id when contacting support — it ties the API response to server logs.

Code samples

Node.js (create + verify)

const BASE = process.env.SETU_BASE_URL;
const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': process.env.SETU_API_KEY,
  'X-API-Secret': process.env.SETU_API_SECRET
};

async function createCheckout(order) {
  const res = await fetch(`${BASE}/api/create-order`, {
    method: 'POST', headers,
    body: JSON.stringify({
      amount: order.total,
      order_id: order.id,
      customer_name: order.customerName,
      callback_url: 'https://my-site.com/payment/return'
    })
  });
  if (!res.ok) throw new Error((await res.json()).message);
  return (await res.json()).data;
}

async function verify(orderId) {
  const res = await fetch(`${BASE}/api/check-status`, {
    method: 'POST', headers, body: JSON.stringify({ order_id: orderId })
  });
  const json = await res.json();
  return json.data.payment_status; // success | pending | failed | expired
}

PHP

<?php
$payload = [
  'amount' => 499.00,
  'order_id' => 'ORD-' . time(),
  'customer_name' => 'Aarav Sharma',
  'callback_url' => 'https://my-site.com/payment/return',
];

$ch = curl_init('https://your-domain.com/api/create-order');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-API-Key: ' . getenv('SETU_API_KEY'),
    'X-API-Secret: ' . getenv('SETU_API_SECRET'),
  ],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['status'] ?? '') === 'success') {
  header('Location: ' . $result['data']['payment_url']);
  exit;
}
http_response_code(502);

Webhook receiver (PHP)

<?php
$secret = getenv('SETU_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
[$tPart, $vPart] = array_pad(explode(',', $header), 2, '');
$timestamp = str_replace('t=', '', $tPart);
$expected = hash_hmac('sha256', $timestamp . '.' . $raw, $secret);

if (!hash_equals($expected, str_replace('v1=', '', $vPart))) {
  http_response_code(400); exit('invalid signature');
}
if (abs(time() - (int)$timestamp) > 300) {
  http_response_code(400); exit('stale');
}
$event = json_decode($raw, true);
if (($event['event'] ?? '') === 'payment.success') {
  // Mark order paid, idempotently
}
http_response_code(200);
echo json_encode(['received' => true]);

Security & compliance

MyHSRSP never asks for a customer’s UPI PIN or bank password. The PIN is entered only inside the customer’s UPI app on NPCI infrastructure.