Build a checkout in one request.

Authentication

Keep your site API key on your server and send it in the x-prime-pay-key header. Never put it in browser JavaScript.

x-prime-pay-key: pk_primepay_...

Create checkout

POST /api/v1/checkout

{
  "amount": 499,
  "item_name": "520 Diamonds",
  "external_order_id": "ORDER-12345",
  "idempotency_key": "ORDER-12345",
  "success_url": "https://example.com/payment/success",
  "cancel_url": "https://example.com/payment/cancel",
  "webhook_url": "https://example.com/api/payment/webhook",
  "metadata": { "product_id": "diamond_520", "uid": "123456789" }
}

The response contains order, checkout_url, upi_uri and qr_data_url. Redirect the customer to checkout_url.

Order status

GET /api/v1/orders/:orderCode

Returns the order. Status is one of pending_payment, verified, late_paid, expired or refunded. Deliver only on verified (and, at your discretion, late_paid).

QR code

GET /api/v1/orders/:orderCode/qr

Returns an interoperable UPI URI and a QR image for a payable order. Orders that are expired or already paid return 409.

Verify by UTR

POST /api/v1/orders/:orderCode/verify

Used by the checkout page when a customer enters their UTR. Body: { "utr": "123456789012" }. Returns { "success": true } once the payment is found; otherwise an error explaining why.

Sandbox mode

Use the pk_test_… key of a website instead of its live key. The checkout call returns instantly with an order that is already verified, upi_uri and qr_data_url are null, sandbox: true is set, and your webhook fires with is_test: true. Sandbox orders never touch Gmail matching and are excluded from revenue and analytics.

Webhooks

Prime Pay signs the exact raw request body with your site’s webhook secret using HMAC-SHA256 (hex) and sends it in x-prime-pay-signature.

import crypto from "node:crypto";

app.post("/api/payment/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.get("x-prime-pay-signature") || "";
  const expected = crypto.createHmac("sha256", process.env.PRIME_PAY_WEBHOOK_SECRET)
    .update(req.body).digest("hex");
  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body);          // event.event === "payment.verified"
  // mark event.external_order_id as paid, then deliver
  res.sendStatus(200);
});

The body contains event plus the fields selected in the website’s Webhook payload builder (default: order_code, amount, status, utr; optional: metadata, external_order_id, device_info, base_amount, tax_amount, paid_at). Failed deliveries retry with exponential backoff (about 30s, 1m, 2m, 4m… up to 8 attempts).

Handle duplicate deliveries idempotently using your external order ID or the order code.

Tax, short links & invoices

Common errors