Custom Checkout Integration Guide

Customer            Your Frontend           Your Server            Razorpay
   |                     |                       |                      |
   | 1. Start checkout   |                       |                      |
   |-------------------->| 2. Create order       |                      |
   |                     |---------------------->| 3. POST /v1/orders   |
   |                     |                       |--------------------->|
   |                     |                       |   order_id           |
   |                     |<----------------------|<---------------------|
   | 4. Enter details    |                       |                      |
   |-------------------->| 5. createPayment(data)|                      |
   |                     |------------------------------------------------>|
   |                     |         OTP / bank redirect / UPI approval      |
   |<------------------------------------------------------------------->|
   |                     | 6. payment.success                            |
   |                     |    (payment_id, order_id, signature)          |
   |                     |---------------------->| 7. Verify signature  |
   |                     |                       |    (HMAC-SHA256)     |
   |                     |                       | 8. Capture + fulfil  |
   |                     |                       |--------------------->|
   |                     |                       | 9. Webhook: captured |
   |                     |                       |<---------------------|

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": "rcptid_11",
 "notes": { "customer_id": "cust_abc123" }
 }'

var razorpay = new Razorpay({
 key: '<YOUR_KEY_ID>',
 image: 'https://i.imgur.com/n5tjHFD.jpg', // logo shown in the popup
});
razorpay.once('ready', function(response) {
 console.log(response.methods); // render only these methods in your UI
})

var razorpay = new Razorpay({ key: '<YOUR_KEY_ID>' });

var methodsRendered = false;
var FALLBACK_METHODS = { card: true, upi: true, netbanking: true }; // safe minimum

// 1. If the fetch has not returned in 5s, render the fallback set.
var timer = setTimeout(function () {
 if (!methodsRendered) {
 methodsRendered = true;
 renderPaymentMethods(FALLBACK_METHODS);
 showRetryNotice(); // let the customer refresh to load all methods
 }
}, 5000);

// 2. When methods arrive, cancel the timer and render the real list.
razorpay.once('ready', function (response) {
 clearTimeout(timer);
 if (!methodsRendered) {
 methodsRendered = true;
 renderPaymentMethods(response.methods);
 }
});

<script type="text/javascript" src="https://checkout.razorpay.com/v1/razorpay.js"></script>

var razorpay = new Razorpay({
 key: '<YOUR_KEY_ID>',
 image: 'https://i.imgur.com/n5tjHFD.jpg', // logo shown in the payment popup
 redirect: true
});

var data = {
 amount: 1000, // in currency subunits
 currency: "INR",
 email: 'gaurav.kumar@example.com',
 contact: '+919876543210',
 notes: {
 address: 'Ground Floor, SJR Cyber, Laskar Hosur Road, Bengaluru',
 },
 order_id: 'order_DBJOWzybf0sJbb', // Order ID from Step 1
 method: 'netbanking',
 bank: 'HDFC' // method-specific field
};

var btn = document.querySelector('#btn');
btn.addEventListener('click', function(){
 // must be inside a user-initiated event so the popup is not blocked
 razorpay.createPayment(data);

 razorpay.on('payment.success', function(resp) {
 // send these three fields to your server for verification (Step 3)
 alert(resp.razorpay_payment_id);
 alert(resp.razorpay_order_id);
 alert(resp.razorpay_signature);
 });

 razorpay.on('payment.error', function(resp){
 // Read the full error object, not just the description (see Error handling below)
 console.error({
 code: resp.error.code, // e.g. BAD_REQUEST_ERROR, GATEWAY_ERROR
 description: resp.error.description, // human-readable message to show the customer
 source: resp.error.source, // where it failed, e.g. customer, business, bank
 step: resp.error.step, // e.g. payment_authentication
 reason: resp.error.reason, // machine-readable cause, e.g. payment_failed
 order_id: resp.error.metadata && resp.error.metadata.order_id,
 payment_id: resp.error.metadata && resp.error.metadata.payment_id
 });
 });
})

razorpay.createPayment({
 amount: 5000,
 email: 'gaurav.kumar@example.com',
 contact: '9123456780',
 order_id: 'order_DBJOWzybf0sJbb',
 method: 'card',
 'card[name]': 'Gaurav Kumar',
 'card[number]': '4111111111111111',
 'card[cvv]': '123',
 'card[expiry_month]': '10',
 'card[expiry_year]': '30'
});

{
 "error": {
 "code": "BAD_REQUEST_ERROR",
 "description": "Payment failed because of a temporary issue at the bank.",
 "source": "bank",
 "step": "payment_authentication",
 "reason": "payment_failed",
 "metadata": {
 "order_id": "order_DBJOWzybf0sJbb",
 "payment_id": "pay_DBJP1H5nubc"
 }
 }
}

const crypto = require('crypto');

function verifyPaymentSignature(orderId, paymentId, receivedSig, keySecret) {
 const body = orderId + '|' + paymentId;
 const expectedSig = crypto
 .createHmac('sha256', keySecret)
 .update(body)
 .digest('hex');
 return crypto.timingSafeEqual(
 Buffer.from(expectedSig, 'hex'),
 Buffer.from(receivedSig, 'hex')
 );
}

// CRITICAL: retrieve order_id from YOUR database, not from the client.
const order = await db.orders.findByInternalId(internalOrderId);

const isValid = verifyPaymentSignature(
 order.razorpayOrderId,
 razorpay_payment_id,
 razorpay_signature,
 process.env.RAZORPAY_KEY_SECRET
);

if (isValid) {
 // Update order status to PAID and trigger fulfilment
} else {
 // Signature mismatch -> reject, do NOT fulfil
}

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);

const crypto = require('crypto');

// Use the RAW request body, not the parsed JSON, or the signature will not match.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
 const received = req.headers['x-razorpay-signature'];
 const expected = crypto
 .createHmac('sha256', process.env.RAZORPAY_WEBHOOK_SECRET)
 .update(req.body) // raw Buffer
 .digest('hex');

 if (received !== expected) return res.status(400).send('invalid signature');

 res.status(200).send('ok'); // acknowledge fast
 // Then process asynchronously (idempotent on razorpay_payment_id).
 const event = JSON.parse(req.body);
 // switch (event.event) { case 'payment.captured': ... }
});