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.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):
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.