Magic Checkout Integration Guide

How does the Magic Checkout flow work?

Customer          Magic Checkout            Your Server            Razorpay
   |                    |                        |                     |
   |                    |                        | 1. POST /v1/orders  |
   |                    |                        |-------------------->|
   |                    |                        |     order_id        |
   | 2. Open checkout   |                        |<--------------------|
   |------------------->| 3. get-promotions      |                     |
   |                    |----------------------->| (your API)          |
   |                    | 4. shipping-info       |                     |
   |                    |----------------------->| (your API)          |
   | 5a. Prepaid pay    |                        |                     |
   |------------------->|--------------------------------------------->| authorize
   | 5b. Place COD      |                        |                     |
   |------------------->|--------------------------------------------->| order.placed
   |                    | 6. success response    |                     |
   |                    |----------------------->| 7. Verify signature |
   |                    |                        | 8. Capture (prepaid)|
   |                    |                        |-------------------->|
   |                    |                        | 9. Webhooks:        |
   |                    |                        |   order.paid /      |
   |                    |                        |   payment.pending / |
   |                    |                        |   fulfillment.*     |
   |                    |                        |<--------------------|

1. Set up promotions and shipping APIs on your server and register them in the Dashboard (Step 1).
2. Create an order for every checkout (Step 2).
3. Open Magic Checkout with one_click_checkout: true; it calls your promotions and shipping APIs (Step 3).
4. Verify the signature on your server for prepaid payments (Step 4).
5. Confirm and fulfil via webhooks; capture prepaid payments and process COD orders (Step 5).

When should you use Magic Checkout?

Use Magic Checkout when you run an ecommerce store and want a faster, one-click checkout with prefilled customer details, built-in coupons and COD support. If you only need to accept a payment and do not need addresses, coupons or COD, use

What are the payment states in Magic Checkout?

Magic Checkout supports prepaid and COD orders, so it has an extra pending state for COD. You can fetch the current state with the

What do you need before you start?

• A
  Razorpay account
  with Magic Checkout enabled by your SPOC.

• API Keys

  from the Dashboard. Use Test Mode keys while building and Live Mode keys to go live.
• A server-side backend to call the Orders API, host the promotions and shipping APIs, and verify signatures.
• HTTPS on your website with a valid SSL/TLS certificate.

Step 1: How do you set up the promotions and shipping APIs?

Magic Checkout calls APIs on your server to fetch promotions and shipping information. Build these first and register their URLs in the Dashboard.

1. Log in to the Dashboard and go to Magic Checkout.
2. In Platform Setup, select Custom E-Commerce Platform and select Next.
3. In Setup & Settings → Checkout Settings → Coupon Settings, enter the URL for get promotions and the URL for apply promotions, then save.
4. Go to Shipping Setup, select API as the shipping service type, enter the URL for shipping info and save.

Shipping-info API

This API returns shipping serviceability, COD serviceability, shipping fees and COD fees for a list of customer addresses.

{
 "order_id": "SomeReceiptValue",
 "razorpay_order_id": "EKwxwAgItmXXXX",
 "email": "john.smith@example.com",
 "contact": "+919000090000",
 "addresses": [{ "id": "0", "zipcode": "560060", "state_code": "KA", "country": "IN" }]
}

Fees are in paise. If cod is false, set cod_fee to 0.

Create promotions

Before the promotions APIs can return anything, the promotions themselves must exist. You have two options:

• Create coupons on the Razorpay Dashboard. Go to Magic Checkout → Setup & Settings → Coupon Settings and create coupons with a code, type (fixed_amount, percentage or BXGY), value and conditions such as minimum cart value or customer eligibility. Use this when you want Razorpay to manage coupon storage.
• Manage promotions in your own system. Keep coupons in your commerce backend and have your get-promotions and apply-promotions APIs return them. Use this when your promotion logic (bundles, loyalty, personalised offers) already lives on your server.

Either way, Magic Checkout only ever reads promotions through the two APIs below, so they must always return the correct, current set.

Get-promotions and apply-promotions APIs

The get-promotions API returns the coupons applicable to an order and customer. The apply-promotions API validates a code the customer enters and returns the discount.

{
 "order_id": "SomeReceiptValue",
 "contact": "+919000090000",
 "email": "john.smith@example.com"
}

{
 "order_id": "SomeReceiptValue",
 "contact": "+919000090000",
 "email": "john.smith@example.com",
 "code": "500OFF"
}

The value is always in paise and applied as-is. value_type can be fixed_amount, percentage or BXGY (Buy X Get Y).

Step 2: How do you create an order?

Create an order on your server for every checkout, the same as other Razorpay integrations. Save the id from the response and pass it to Magic Checkout in Step 3. Amounts are in paise, for example, ₹450 = 45000.

curl -X POST https://api.razorpay.com/v1/orders \
 -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
 -H 'content-type:application/json' \
 -d '{
 "amount": 45000,
 "currency": "INR",
 "receipt": "rcptid_11"
 }'

The receipt value you set here is the order_id your promotions and shipping APIs receive. Know more about the

Step 3: How do you open Magic Checkout on the client?

Load magic-checkout.js and open Checkout with one_click_checkout: true. Use the handler function for SPAs or the callback URL for server-rendered apps.

<button id="rzp-button1">Pay</button>
<script src="https://checkout.razorpay.com/v1/magic-checkout.js"></script>
<script>
var options = {
 "key": "YOUR_KEY_ID",
 "one_click_checkout": true,
 "name": "Acme Corp",
 "order_id": "order_EKwxwAgItmXXXX", // from Step 2
 "show_coupons": true, // set false to hide the coupon widget
 "handler": function (response){
 // send these three fields to your server for verification (Step 4)
 alert(response.razorpay_payment_id);
 alert(response.razorpay_order_id);
 alert(response.razorpay_signature);
 },
 "prefill": {
 "name": "John Smith",
 "email": "john.smith@example.com",
 "contact": "9000090000",
 "coupon_code": "500OFF" // auto-applied when Magic opens
 },
 "notes": { "address": "ABC Office" }
};
var rzp1 = new Razorpay(options);
rzp1.on('payment.failed', function (response){
 alert(response.error.code);
 alert(response.error.description);
 alert(response.error.reason);
});
document.getElementById('rzp-button1').onclick = function(e){
 rzp1.open();
 e.preventDefault();
}
</script>

For server-rendered apps, set "callback_url": "https://yourserver.com/callback" and "redirect": "true" instead of the handler function.

Checkout options reference

For the complete list, see the full

Step 4: How do you verify the payment is genuine?

Verify the signature on your server before fulfilling, exactly as in other Razorpay integrations. The signature is an HMAC-SHA256 hash of order_id and payment_id, signed with your Key Secret.

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')
 );
}
// Use the order_id from YOUR database, not the one from the browser.

Step 5: How do you confirm payment and fulfil orders?

Magic Checkout handles prepaid and COD orders, so subscribe to order, payment and fulfilment webhooks.

The confirmation path is different for prepaid and COD orders:

Order events

Payment events

Fulfilment events

For the full async webhook handler pattern, replay-attack guard, idempotency, monitoring metrics, rollback plan and logging strategy, see the shared deep-dives in the

Step 6: How do you test in Test Mode?

Test with Test Mode API keys so no real money moves. Use the mock bank page's Success and Failure buttons to simulate outcomes, and place a COD order to exercise the order.placed and payment.pending webhooks.

Test cards and UPI

Use any random CVV and any future expiry date. For netbanking and wallets, choose any bank or wallet and use the Success or Failure buttons. See the full list of

What to test before going live

• The prepaid flow end to end, including signature verification and capture.
• The COD flow: placing a COD order and receiving order.placed and payment.pending.
• Coupon application through your get-promotions and apply-promotions APIs.
• Shipping-info responses for serviceable, non-serviceable and COD-disabled pincodes.

Step 7: How do you go live?

• If you configured settings in Test Mode, replicate them in Live Mode, including the promotions and shipping URLs.
• Use API keys generated in Live Mode. If you have multiple Razorpay accounts, use the Live key from the account you intend to go live with.
• Verify the signature server-side, fulfil only after capture (for prepaid) or after order.placed (for COD), and handle all subscribed webhooks idempotently.
• Re-test the prepaid flow, the COD flow, coupon application and the shipping-info responses in Test Mode before switching keys.

Frequently asked questions

Related information

• Standard Checkout integration guide

  (shared webhook, monitoring, rollback and logging deep-dives)

• Magic Checkout on Website (full reference)

• Magic Checkout for Shopify

  and

  WooCommerce

• Orders API reference

• Troubleshooting and FAQs