Standard Checkout Integration Guide

Customer            Your Frontend           Your Server            Razorpay
   |                     |                       |                      |
   | 1. Start checkout   |                       |                      |
   |-------------------->| 2. Create order       |                      |
   |                     |---------------------->| 3. POST /v1/orders   |
   |                     |                       |--------------------->|
   |                     |                       |   order_id           |
   |                     |<----------------------|<---------------------|
   | 4. Pay (modal)      |                       |                      |
   |-------------------->| 5. checkout.js opens  |                      |
   |                     |------------------------------------------------>|
   |                     |         OTP / bank redirect / UPI approval      |
   |<------------------------------------------------------------------->|
   |                     | 6. success (handler / callback_url)           |
   |                     |    (payment_id, order_id, signature)          |
   |                     |---------------------->| 7. Verify signature  |
   |                     |                       | 8. Capture + fulfil  |
   |                     |                       |--------------------->|
   |                     |                       | 9. Webhook: captured |
   |                     |                       |<---------------------|

POST https://api.razorpay.com/v1/orders
Authentication: HTTP Basic Auth
Username: YOUR_KEY_ID
Password: YOUR_KEY_SECRET

curl -X POST https://api.razorpay.com/v1/orders \
 -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
 -H 'content-type:application/json' \
 -d '{
 "amount": 50000,
 "currency": "INR",
 "receipt": "rcpt_001",
 "notes": {
 "customer_id": "cust_abc123",
 "plan": "gold",
 "source": "web_checkout"
 },
 "partial_payment": true,
 "first_payment_min_amount": 23000,
 "capture": "automatic"
 }'

{
 "error": {
 "code": "BAD_REQUEST_ERROR",
 "description": "Order amount less than minimum amount allowed",
 "source": "business",
 "step": "payment_initiation",
 "reason": "input_validation_failed",
 "metadata": {},
 "field": "amount"
 }
}

<script src="https://checkout.razorpay.com/v1/checkout.js"></script>
<!-- Load this on every page where the Pay button appears. -->
<!-- Never self-host this script. Always load it from the Razorpay CDN. -->

<button id="rzp-button1">Pay</button>
<script src="https://checkout.razorpay.com/v1/checkout.js"></script>
<script>
var options = {
 "key": "YOUR_KEY_ID",
 "amount": "50000",
 "currency": "INR",
 "name": "Acme Corp",
 "description": "Gold Plan - Monthly Subscription",
 "image": "https://example.com/your_logo.png",
 "order_id": "order_9A33XWu170gUtm", // from Step 1
 "callback_url": "https://yourserver.com/payment/callback",
 "prefill": {
 "name": "Customer Name",
 "email": "customer@example.com",
 "contact": "+919876543210"
 },
 "notes": { "address": "Your Office" },
 "theme": { "color": "#3399cc" },
 "modal": {
 "confirm_close": true,
 "escape": false,
 "backdropclose": false,
 "animation": true
 },
 "retry": { "enabled": true, "max_count": 4 }
};
var rzp1 = new Razorpay(options);
document.getElementById("rzp-button1").onclick = function(e) {
 rzp1.open();
 e.preventDefault();
}
</script>

{
 "razorpay_payment_id": "pay_29QQoUBi66xm2f",
 "razorpay_order_id": "order_IluGWxBm9U8zJ8",
 "razorpay_signature": "9ef4dffbfd84f1318..."
}

// Algorithm: HMAC-SHA256
// Input: order_id + "|" + razorpay_payment_id
// Key:   YOUR_KEY_SECRET
// Compare: generated_signature == razorpay_signature

generated_signature = HMAC_SHA256(
 key  = YOUR_KEY_SECRET,
 data = razorpay_order_id + "|" + razorpay_payment_id
)

if generated_signature == razorpay_signature:
 # Payment is authentic -> fulfil order
else:
 # Signature mismatch -> reject, do NOT fulfil

import hmac, hashlib, os

def verify_signature(order_id, payment_id, received_sig, key_secret):
 body = f'{order_id}|{payment_id}'
 expected_sig = hmac.new(
 key_secret.encode(), body.encode(), hashlib.sha256
 ).hexdigest()
 # hmac.compare_digest prevents timing attacks
 return hmac.compare_digest(expected_sig, received_sig)

# In your Flask/Django view:
payment_id = request.json["razorpay_payment_id"]
received_sig = request.json["razorpay_signature"]

# CRITICAL: get order_id from YOUR database using the real Razorpay callback field
order = Order.objects.get(razorpay_order_id=request.json["razorpay_order_id"])

KEY_SECRET = os.environ.get('RAZORPAY_KEY_SECRET')
if verify_signature(order.razorpay_order_id, payment_id, received_sig, KEY_SECRET):
 order.mark_paid()
else:
 return JsonResponse({"error": "Signature mismatch"}, status=400)

String secret = "YOUR_KEY_SECRET";

JSONObject options = new JSONObject();
options.put("razorpay_order_id", order.getRazorpayOrderId());
options.put("razorpay_payment_id", razorpayPaymentId);
options.put("razorpay_signature", razorpaySignature);

boolean status = Utils.verifyPaymentSignature(options, secret);

/* Java SDK: https://github.com/razorpay/razorpay-java */
Utils.verifyWebhookSignature(webhookBody, webhookSignature, webhookSecret);

// Express middleware: raw body required for HMAC
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
 const secret = process.env.WEBHOOK_SECRET;
 const received = req.headers['x-razorpay-signature'];

 // 1. Verify signature FIRST (fast, synchronous)
 try {
 Razorpay.validateWebhookSignature(req.body.toString(), received, secret);
 } catch (err) {
 return res.status(400).send('Invalid signature');
 }

 const event = JSON.parse(req.body.toString());

 // 2. Replay-attack guard: reject stale events
 const eventAge = Date.now() / 1000 - event.created_at;
 if (eventAge > 300) { // older than 5 minutes
 return res.status(200).send('Stale event ignored'); // still return 200
 }

 // 3. Return 200 IMMEDIATELY, before any heavy processing
 res.status(200).json({ received: true });

 // 4. Enqueue for background processing (fire-and-forget with error logging).
 // Do NOT await here: the response is already committed, so an unhandled throw
 // would make Express attempt a second response write (headers already sent).
 jobQueue.enqueue('process_razorpay_event', event).catch(err => {
 console.error('Failed to enqueue webhook event, manual replay required', {
 eventId: event.id,
 error: err.message,
 });
 // Alert ops: Razorpay will NOT retry (200 was returned), so this event is lost.
 });
});

// Background worker (runs outside the request)
async function processRazorpayEvent(event) {
 const paymentId = event.payload.payment?.entity?.id;

 // Idempotency: atomic insert-if-not-exists, relies on a unique constraint on event.id.
 // A single operation leaves no window for a race between the check and the insert.
 try {
 await db.processedEvents.insert(event.id);
 } catch (err) {
 // A unique constraint violation means another worker already claimed this event.
 if (err.code === 'UNIQUE_VIOLATION' || err.code === '23505') return;
 throw err; // unexpected error, re-throw
 }

 switch (event.event) {
 case 'payment.captured':
 await db.orders.markPaid(paymentId);
 await emailService.sendConfirmation(paymentId);
 break;
 case 'payment.failed':
 await db.orders.markFailed(paymentId);
 await emailService.sendFailureAlert(paymentId);
 break;
 case 'refund.failed':
 await alertOpsTeam(paymentId, 'refund_failed');
 break;
 case 'payment.dispute.created':
 await db.orders.flagDisputed(paymentId);
 await alertOpsTeam(paymentId, 'dispute_raised');
 break;
 }
}

// When you receive payment.authorized for an "expired" order:
async function handleLateAuth(event) {
 const payment = event.payload.payment.entity;
 const orderId = payment.order_id;

 const order = await db.orders.findByRazorpayId(orderId);

 if (!order) {
 // Unknown order - refund immediately
 await razorpay.payments.refund(payment.id, { amount: payment.amount });
 await alertOpsTeam('late_auth_unknown_order', payment.id);
 return;
 }

 if (order.status === 'expired' || order.status === 'cancelled') {
 // Order is expired - refund and notify customer
 await razorpay.payments.refund(payment.id, { amount: payment.amount });
 await emailService.sendLateAuthRefundNotice(order.customerEmail, payment.id);
 await db.orders.markLateAuthRefunded(orderId, payment.id);
 return;
 }

 if (order.status === 'created' || order.status === 'pending') {
 // Order still valid - fulfil normally
 await db.orders.markPaid(orderId, payment.id);
 await emailService.sendConfirmation(order.customerEmail);
 }
}

logger.info({
 event: "payment_verified",
 order_id: order.razorpayOrderId,
 payment_id: razorpay_payment_id,
 result: "success",
 duration_ms: Date.now() - startTime
 // DO NOT include: signature, key_secret, card_number, cvv
});