UPI — Not Available On Behalf of Merchants (Yet)

Unlike AEPS and DMT, a vendor credential cannot drive UPI Collection, SMS Pay, Dynamic QR generation, status checks, refunds, or VPA verification for a managed merchant today. This page exists to document that constraint clearly rather than leave it to be discovered as a confusing rejected call.

QR Generation — request/response reference

The endpoint, for integration-testing purposes and for whenever this opens up server-side (see Why below):

POST https://api.bucksbox.in/gateway/process/upi/txn/v1/GenerateQR      (production)
POST https://api.bucksbox.in/gateway-stage/process/upi/txn/v1/GenerateQR (staging)
X-Client-Id: <your apiKey>

Plaintext body — encrypt with AES-256-GCM using your SaltAESKey (64-char hex or 44-char base64, both decode to 32 bytes) before sending as { "payload": "..." } (see Authentication & Security):

{ "merchantId": "MERCHANT123", "amount": 250, "order_id": "ORD-12345" }

amount present/truthy → Dynamic QR (fixed amount); omitted or 0 → Static QR. order_id optional, auto-generated if omitted.

What you actually get today:

{ "statusCode": "01", "message": "Access denied" }

returned with HTTP 403 — paymentSystem rejects this before your merchantId/amount/order_id are even read (see Why).

What a merchant's own direct call gets (for comparison — this is the shape a partner call would return too, if the role gate below were widened):

{
  "statusCode": "00",
  "message": "success",
  "data": {
    "qrString": "upi://pay?pa=merchant@bucksbox&am=250...",
    "qr_image": "data:image/png;base64,...",
    "txn_ref_no": "...",
    "order_id": "ORD-12345"
  }
}

Why

Every route in Merchant UPI and QR is guarded with checkRole("merchant") only — there is no "vendor" entry the way AEPS's and DMT's route guards have. A vendor is rejected at the role check itself, before any merchant-resolution logic even runs — and this holds whether the vendor calls directly with a JWT (which would fail checkRole regardless) or through fintech-gateway's /process/* proxy with an apiKey (the gateway forwards the call with X-Api-Key, paymentSystem resolves role: "vendor" from it exactly as it would from a JWT, and checkRole("merchant") rejects it the same way).

Vendor (JWT or gateway apiKey) → checkRole("merchant") → ❌ rejected, vendor is not "merchant"

versus AEPS/DMT's:

Vendor (JWT or gateway apiKey) → checkRole("merchant", "vendor") → ✔ allowed
                                → check_merchant() reads req.body.merchantId → ✔ resolves target merchant

The two UPI route groups differ slightly in why a vendor call would still fail even if checkRole were relaxed, which matters if you're the one fixing this server-side:

  • /upi/txn/v1/GenerateQR (isg.txt.js) has its own local check_merchant() that already reads req.body?.merchantId as a fallback — the only blocker today is the route-level checkRole("merchant") itself. Widening that one line to checkRole("merchant", "vendor") would be enough.
  • /Collection, /SMSpay, /UpiStatus, /SMSStatus, /RefundUPI, /RefundSMS, /verifyVPA (payments.routes.js) resolve identity via checkMerchant() (src/utils/checkMerchant.js), which reads req.merchantId off your authenticated identity only — there's no req.body.merchantId fallback at all here, unlike AEPS/DMT's check_merchant(). Fixing these would need both the checkRole widening and a fallback added to checkMerchant() itself.

What to do instead

  • If you operate the merchant's terminal directly (e.g. you're white-labeling and the merchant's storefront is really your integration), provision that merchant with their own credentials and call Merchant UPI with a merchant-scoped JWT, not your vendor JWT.
  • If you need vendor-driven UPI as a product requirement, this is a paymentSystem change — see the per-route breakdown above for exactly what each route group needs — raise it with your integration contact rather than working around it client-side. Don't attempt to spoof req.merchantId by any means outside an actual role change; there's nothing here to configure around it today.

What vendor UPI visibility does exist

You can still see UPI transaction history (not initiate new UPI transactions) for your managed merchants through the generic Vendor Transactions endpoint, filtering type=QR or by paymentMethod. That's read-only reporting, not the ability to generate a QR, push a Collection request, or issue a refund on a merchant's behalf.