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.

Raw SMS / bank notification (no UTR typing)

An Android SMS forwarder or bank webhook can POST the raw message. MyHSRSP extracts the amount, UTR/RRN and VPA automatically, so the customer never types a UTR:

curl -X POST "https://your-domain.com/bank-feed/acc_01J8..." \
  -H "Content-Type: text/plain" \
  -H "X-Bank-Secret: bfeed_..." \
  --data 'Rs.1.00 credited to a/c XX1234 via UPI. UTR 615372849102 from 9634560515@mbk'

The response includes parsed_from_sms: true plus the extracted amount, utr and vpa. Exact-amount matching then confirms the pending order and queues the webhook. If no credit arrives before the Money Check expiry, the check is marked failed automatically.

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.