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.
Overview
Every integration follows the same three-step loop:
- Create an order on your server with an amount and your own
order_id. - Redirect the customer to the returned
payment_url(hosted checkout with QR + UPI intent). - Verify server-side using
check-statusand/or the signed webhook, then deliver the goods.
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:
| Header | Value |
|---|---|
X-API-Key | Public key, e.g. pk_live_… |
X-API-Secret | Secret, e.g. sk_live_… — server-side only |
Content-Type | application/json |
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:
| Mode | Credentials | How confirmation works |
|---|---|---|
| Manual UPI VPA | Your UPI ID + payee name (e.g. store@okhdfcbank) | Dynamic QR/intent, customer submits UTR, bank feed or merchant marks it paid |
| Merchant API | Official MID + merchant key / token (Paytm Business, BharatPe, PhonePe, Freecharge, MobiKwik, Binance Pay) | Provider server-to-server callback, verified with your secret |
| Sandbox | Nothing — a demo VPA is generated | Simulated success/failure from the checkout page |
Connect from the dashboard
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
Returns the same connected / live_verification contract, or 502 with status: "error" if the credential is invalid.
Provider callback endpoint
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.
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"
}
}
payment.success webhook.Dashboard reconciliation endpoints (session auth):
Pass / fail contract
One field decides the outcome: data.payment_status. It is always one of:
| payment_status | Meaning | What you should do |
|---|---|---|
pending | Checkout created, no confirmed credit yet. | Show “waiting”, keep polling or wait for webhook. Do not deliver. |
success | Confirmed by provider callback or matched UTR. utr and paid_at are set. | Fulfil the order, store the UTR, make fulfilment idempotent. |
failed | Declined, cancelled or provider failure. | Do not deliver. Ask for a new checkout. |
expired | Checkout timed out before payment. | Create a fresh order. |
refunded | A 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
| Field | Type | Required | Notes |
|---|---|---|---|
amount | number | yes | INR, minimum ₹1, maximum ₹2,00,000 |
order_id | string | yes | 3–64 chars: letters, numbers, ._:-. Unique per merchant. |
customer_name | string | yes | Shown on the checkout |
customer_mobile | string | no | 10–15 digits |
customer_email | string | no | Stored for reconciliation |
callback_url | string | no | Absolute URL shown as “Return to merchant” after success |
description | string | no | Checkout remark / product name |
is_reusable | boolean | no | Reserved for reusable checkouts |
account_id | string | no | Force 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
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
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)
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
| Header | Value |
|---|---|
X-Signature | t=<unix>,v1=<hex hmac> |
X-Event | payment.success, payment.failed, payment.expired |
X-Delivery-Id | Unique attempt id (for deduplication) |
X-Timestamp | Unix 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
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_JSON | Body is not a JSON object |
| 401 | MISSING_API_CREDENTIALS | Key or secret header missing |
| 401 | INVALID_API_KEY / INVALID_API_SECRET | Key revoked or secret wrong |
| 402 | TRIAL_EXPIRED / PLAN_LIMIT_REACHED | Subscription or quota block |
| 402 | SUBSCRIPTION_PAST_DUE | Invoice overdue |
| 403 | MERCHANT_SUSPENDED | Workspace suspended by admin |
| 404 | ORDER_NOT_FOUND | No matching order_id |
| 409 | UTR_ALREADY_USED | UTR linked to another order |
| 422 | VALIDATION_ERROR / INVALID_AMOUNT | Field validation failed; see details[] |
| 429 | RATE_LIMITED | Slow down; honour Retry-After |
| 503 | NO_GATEWAY_CONNECTED | No active collection account |
| 503 | GATEWAY_LIMIT_REACHED | All 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
- Keep secrets server-side and rotate on any suspicion of leakage.
- Validate amounts server-side; never trust a client-supplied price.
- Verify webhook signatures with constant-time comparison and a timestamp window.
- Deliver goods idempotently: an order can receive replayed webhooks.
- Log UTRs and gateway transaction ids for dispute resolution.
- Complete KYC (PAN + DigiLocker Aadhaar + video KYC where required) before live commercial collection.
- Operating a payment aggregator in India requires RBI authorisation and NPCI PA-PG compliance. This platform is orchestration software: use your own authorised merchant accounts unless you hold those licences.