Integrate Razorpay Magic Checkout on Website

Follow these steps to integrate the Razorpay Magic Checkout on your website.

Prerequisites

Create a Razorpay account
.
Generate
API Keys
from the Razorpay Dashboard.

Integration Steps

Follow the steps given below:

1.1 Enable/Disable Magic Checkout and Cash on Delivery

Raise a request with your Razorpay SPOC to get this feature enabled on your account. Once this feature is enabled, the customer address saving and coupon features are enabled.

Handy Tips

If you do not want to use Magic Checkout, raise a request with our

Support team

to disable this feature on the Razorpay Dashboard.

1.2 Create Promotions and Shipping Info API Endpoints

Follow the steps given below to create promotions and shipping info API endpoints:

Watch Out!

Ensure that the URLs are publicly accessible, require no authentication, and are hosted on your server.

Log in to the
Razorpay Dashboard
and navigate to Magic Checkout.
In the Platform Setup, select Custom E-Commerce Platfrom from the drop-down list and click Next.
Navigate to Setup & Settings → Checkout Settings.
In the Coupon Settings section, enter the following:
1. URL for get promotions: The API URL should return a list of promotions applicable to the specified order_id and customer. Magic Checkout uses this endpoint to fetch these promotions from your server and display them to your customers in the checkout modal.
2. URL for apply promotions: The API URL validates the promotion code applied by the customer and should return the discount amount. Magic Checkout uses this endpoint to apply promotions via your server.
Click Save settings.
Navigate to Shipping Setup.
Select API as the Shipping Service type from the drop-down list.
Enter the URL for shipping info. The API URL should return shipping serviceability, COD serviceability, shipping fees, and COD fees for a given list of customer addresses. Magic Checkout uses this endpoint to retrieve shipping information from your server.
Click Save Settings.

1.3 Create an Order

You can create an order using the following API and send the additional information required for Magic Checkout. Pass the order_id received in response to the checkout code.

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/orders \
-H "content-type: application/json" \
-d '{
  "amount": 500000, // in paise. Here 50000 = 50000 paise, which equals to ₹500
  "currency": "INR",
  "receipt": "receipt#1",
  "notes": {},
  "line_items_total": 500000, // in paise.
  "line_items": [
    {
      "sku": "1g234",
      "variant_id": "12r34",
      "other_product_codes": {
        "upc": "12r34",
        "ean": "123r4",
        "unspsc": "123s4"
      },
      "price": 500000, // in paise.
      "offer_price": 500000, // in paise.
      "tax_amount": 0,
      "quantity": 1,
      "name": "TEST",
      "description": "TEST",
      "weight": 1700, // in grams
      "dimensions": {
        "length": 1700,
        "width": 1700,
        "height": 1700
      },
      "image_url": "url",
      "product_url": "url",
      "notes": {}
    }
  ]
}'

1.3.1 Request Parameters

amount

mandatory

integer The transaction amount, expressed in the currency subunit, such as paise (in case of INR). For example, for an actual amount of ₹299.35, the value of this field should be 29935.

currency

mandatory

string The currency in which the transaction should be made. See the

list of supported currencies

. Default is INR. Length must be of 3 characters.

receipt

mandatory

string Your receipt id for this order should be passed here. Maximum length of 40 characters.

notes

optional

object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

line_items_total

mandatory

integer Total of offer_price for all line items added to the cart, in paise. For example, if a shoe worth ₹8,000 and a shirt worth ₹10,000 are added, the line_item_total will be 1800000. This amount is post-tax.

Watch Out!

To ensure the order is considered as a Magic Checkout order, you must pass this parameter. Otherwise, it will default to Standard Checkout order, and customers will view the Standard Checkout UI instead of Magic Checkout. Know more about

Razorpay Standard Checkout

line_items

mandatory

object This will have the details about the specific items added to the cart.

sku

mandatory

string Alphanumeric. Unique product id defined by you.

variant_id

mandatory

string Alphanumeric. Unique variant_id defined by you.

other_product_codes

optional

object Array to collect different codes that can identify the item type. Possible values: upc: string Universal Product Code (UPC; redundantly: UPC code) is a barcode symbology used worldwide to track trade items in stores. UPC consists of 12 numeric digits that are uniquely assigned to each trade item

ean: string European Article Numbers (EAN) is a type of barcode that encodes an article number. Contains 8 (EAN-8) or 13 (EAN-13) numerical digits.
unspsc: string The United Nations Standard Products and Services Code (UNSPSC) is a taxonomy of products and services used in ecommerce. It is a four-level hierarchy coded as an eight-digit number, with an optional fifth level adding two more digits.

price

mandatory

integer Price of the product in paise.

offer_price

mandatory

integer Final price charged to the customer in paise, after applying any adjustments, such as product discounts.

Handy Tips

If no discount is applied, price and offer_price will be the same.

tax_amount

mandatory

integer The tax levied on the product.

quantity

mandatory

integer Number of units added in the cart.

name

mandatory

string Name of the product.

description

mandatory

string Description of the product.

weight

optional

integer Weight of the product in grams.

dimensions

optional

object The dimensions of the product.

length

optional

string The length of the product in centimeters.

width

optional

string The width of the product in centimeters.

height

optional

string The height of the product in centimeters.

product_url

optional

string URL of the product's listing page.

image_url

optional

string The URL of the product image. This parameter is mandatory if you want to display product images on our iframe.

notes

optional

object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

1.3.2 Response Parameters

Descriptions for the response parameters are present in the

Orders Entity

parameters table.

1.3.3 Error Response Parameters

The error response parameters are available in the

API Reference Guide

1.4 Interact with Shipping Info API

This API should return shipping serviceability, COD serviceability, shipping fees, and COD fees for a given list of customer addresses.

POST

/your-server-url/shipping-info-api-path

{
   "order_id": "SomeReceiptValue", // This is the receipt field set in the Razorpay order
   "razorpay_order_id": "EKwxwAgItmmXdp", // This is the RZP order created without the `order_` prefix
   "email": "gaurav.kumar@example.com", // Email field will be set if the customer enters an email
   "contact": "+919900000000", // Customer phone number with country code
   "addresses": [{
     "id": "0", 
     "zipcode": "560060",
     "state_code": "KA",
     "country": "IN"
   }]
}

1.4.1 Request Parameters

order_id

mandatory

string Unique identifier of the order created

previously

razorpay_order_id

mandatory

string Unique identifier for the order returned by Checkout.

mandatory

string Customer's email address.

contact

mandatory

string Customer's phone number.

addresses

mandatory

array Customer's address details.

mandatory

string Unique identifier of the customer's address.

zipcode

mandatory

string Customer's ZIP code.

state_code

optional

string The code of the state where the customer resides.

country

mandatory

string Country where the customer resides. The length cannot exceed 2 characters.

1.4.2 Response Parameters

addresses

mandatory

array Customer's address details.

mandatory

string Unique identifier of the customer's address.

zipcode

mandatory

string Customer's ZIP code.

country

mandatory

string Country where the customer resides. The length cannot exceed 2 characters.

shipping_methods

mandatory

array Details regarding the shipping methods.

mandatory

string Unique identifier of the shipping method.

description

integer Brief description of the shipping method.

name

mandatory

string Name of the shipping method.

serviceable

mandatory

boolean Indicates whether you deliver orders to the zipcode entered by the customer. This is based on the zipcodes you have added in the serviceability setting on the Razorpay Dashboard. Possible values:

true: Orders can be delivered to the added zipcodes.
false: Orders cannot be delivered to the added zipcodes.

shipping_fee

mandatory

integer Shipping charge applicable to be paid by the customer.

cod

mandatory

boolean Indicates whether you support cash on delivery on this order.

true: COD payment method is supported.
false: COD payment method is not supported.

cod_fee

mandatory

integer Additional amount charged by for you COD. This is based on the amount you have added to the COD setting on the Razorpay Dashboard.

Handy Tips

If the cod field is false, set the cod_fee field to 0.

1.5 Interact with Get Promotions API

This API should return the list of promotions applicable for the given order_id and customer.

POST

/your-server-url/create-promotions-api-path

{
  "order_id": "SomeReceiptValue", // this is the receipt field set in Razorpay order
  "contact": "+919000090000", 
  "email": "gaurav.kumar@example.com"
}'

1.5.1 Request Parameters

order_id

mandatory

string Unique identifier of the order created

previously

contact

optional

string Customer's phone number.

optional

string Customer's email address.

1.5.2 Response Parameters

promotions

mandatory

array Details of the promotions created.

code

mandatory

string Unique identifier of the promotion.

summary

mandatory

string Summary about the promotion. For example, 10% off on total cart value.

description

optional

string Brief description of the promotion. For example, 10% on total cart value upto ₹300.

1.5.3 Interact with Apply Promotions API

This API should validate the promotion code applied by the customer and return the discount amount.

POST

/your-server-url/create-promotions-api-path

{
  "order_id": "SomeReceiptValue", // this is the receipt field set in Razorpay order
  "contact": "+919000090000",
  "email": "gaurav.kumar@example.com",
  "code": "500OFF"
  }'

1.5.3.1 Request Parameters

order_id

mandatory

string Unique identifier of the order created

previously

contact

optional

string Customer's phone number.

optional

string Customer's email address.

code

mandatory

string Promotion code used to avail discount on checkout.

1.5.3.2 Response Parameters

promotion

mandatory

object Used to pass all offer or discount-related information, including promotion code discount, method discount and so on.

reference_id

mandatory

string Id of the offer you create.

code

optional

string Promotion code used to avail discount on checkout.

type

optional

string Type of offer. Possible values:

coupon: A discount applied by customers during checkout. For example, customers can use a coupon like Diwali Sale 500 Off to get ₹500 off the total cart value.
offer: A promotion you create for your customers. For example, you create an offer Buy 4 t-shirts and get 2 free. In this case, when customers add 4 t-shirts to their cart, the 2 additional t-shirts will be automatically added for free.

value

optional

integer The offer value that needs to be applied in paise. For example, if you want to offer a discount of ₹500, enter 50000.

value_type

optional

string The type of value like:

fixed_amount: A fixed amount discount value in the currency of the order. For example, ₹500.
percentage: A percentage discount value. For example, 10%.
BXGY: Buy X and Get Y. For example, if you buy 2 tshirts, you a get a cap for free or at a discounted value.

Handy Tips

Regardless of the value_type, the amount specified in the value parameter is applied as-is. For example, if value_type is percentage and the value is 5000, 5000 is considered in currency subunits (paise).

description

optional

string Description of the promotion applied. For example, New Year Sale Offer.

1.5.3.3 Error Code, Description and Next Steps

1.6 Integrate with Magic Checkout on Client-Side

Add the Pay button on your web page using the handler function or callback URL.

Handy Tips

If your website is running on WooCommerce or Shopify, please integrate with the Razorpay

WooCommerce

Shopify

plugin based on your requirement.

1.6.1 Handler Function and Callback URL

1.6.2 Code to Add Pay Button

Copy-paste the parameters as options in your code:

<button id="rzp-button1">Pay</button>
<script src="https://checkout.razorpay.com/v1/magic-checkout.js"></script>
<script>
var options = {
    "key": "YOUR_KEY_ID", // Enter the Key ID generated from the Dashboard
    "one_click_checkout": true,
    "name": "Acme Corp", // your business name
    "order_id": "order_EKwxwAgItmmXdp", // This is a sample Order ID. Pass the `id` obtained in the response of Step 1; mandatory
    "show_coupons": true, // default true; false if coupon widget should be hidden
    "callback_url": "https://eneqd3r9zrjok.x.pipedream.net/",
    "redirect": "true",
    "prefill": { // We recommend using the prefill parameter to auto-fill customer's contact information especially their phone number
        "name": "Gaurav Kumar", // your customer's name
        "email": "gaurav.kumar@example.com",
        "contact": "9000090000", // Provide the customer's phone number for better conversion rates
        "coupon_code": "500OFF" // any valid coupon code that gets auto-applied once magic opens
    },
    "notes": {
        "address": "ABC Office"
    }
};
var rzp1 = new Razorpay(options);
document.getElementById('rzp-button1').onclick = function(e){
    rzp1.open();
    e.preventDefault();
}
</script>

1.6.3 Checkout Options

key

mandatory

string API Key ID generated from the Razorpay Dashboard.

one_click_checkout

mandatory

boolean Specifies whether to initiate Magic Checkout or Standard Checkout. Possible values:

true: Initiates Magic Checkout.
false (default): Initiates Standard Checkout.

name

mandatory

string Your Business/Enterprise name shown on the Checkout form. For example, Acme Corp.

order_id

mandatory

string Order ID generated via

Orders API

show_coupons

optional

boolean Determines whether to show the coupons to customer on the checkout. Possible values:

true (default): Enables the Coupon feature.
false: Disables the Coupon feature.

prefill

optional

object You can prefill the following details at Checkout.

Boost Conversions and Minimise Drop-offs

Autofill customer contact details, especially phone number to ease form completion. Include customer’s phone number in the contact parameter of the JSON request's prefill object. Format: +(country code)(phone number). Example: “contact": "+919000090000").
This is not applicable if you do not collect customer contact details on your website before checkout, have Shopify stores or use any of the no-code apps.

name

optional

string Cardholder's name to be pre-filled if customer is to make card payments on Checkout. For example, Gaurav Kumar.

optional

string Email address of the customer.

contact

optional

string Phone number of the customer. The expected format of the phone number is + {country code}{phone number}. If the country code is not specified, 91 will be used as the default value. This is particularly important while prefilling contact of customers with phone numbers issued outside India. Examples:

+14155552671 (a valid non-Indian number)
+919977665544 (a valid Indian number).
If 9977665544 is entered, +91 is added to it as +919977665544.

coupon_code

optional

string Automatically applies relevant coupon as soon as the checkout modal opens.

notes

optional

object Set of key-value pairs that can be used to store additional information about the payment. It can hold a maximum of 15 key-value pairs, each 256 characters long (maximum).

theme

optional

object Thematic options to modify the appearance of Checkout.

color

optional

string Enter your brand colour's HEX code to alter the text, payment method icons and CTA (call-to-action) button colour of the Checkout form.

Handy Tips

This is an on-demand feature. Please raise a request with your SPOC or our

Support team

to get it activated on your Razorpay account.

backdrop_color

optional

string Enter a HEX code to change the Checkout's backdrop colour.

modal

optional

object Options to handle the Checkout modal.

backdropclose

optional

boolean Indicates whether clicking the translucent blank space outside the Checkout form should close the form. Possible values:

true: Closes the form when your customer clicks outside the checkout form.
false (default): Does not close the form when customer clicks outside the checkout form.

escape

optional

boolean Indicates whether pressing the escape key should close the Checkout form. Possible values:

true (default): Closes the form when the customer presses the escape key.
false: Does not close the form when the customer presses the escape key.

handleback

optional

boolean Determines whether Checkout must behave similar to the browser when back button is pressed. Possible values:

true (default): Checkout behaves similarly to the browser. That is, when the browser's back button is pressed, the Checkout also simulates a back press. This happens as long as the Checkout modal is open.
false: Checkout does not simulate a back press when browser's back button is pressed.

confirm_close

optional

boolean Determines whether a confirmation dialog box should be shown if customers attempts to close Checkout. Possible values:

true: Confirmation dialog box is shown.
false (default): Confirmation dialog box is not shown.

ondismiss

optional

function Used to track the status of Checkout. You can pass a modal object with ondismiss: function()\{\} as options. This function is called when the modal is closed by the user.

animation

optional

boolean Shows an animation before loading of Checkout. Possible values:

true(default): Animation appears.
false: Animation does not appear.

callback_url

optional

string Customers will be redirected to this URL on successful payment. Ensure that the domain of the Callback URL is allowlisted (also known as whitelisted).

redirect

optional

boolean Determines whether to post a response to the event handler post payment completion or redirect to Callback URL. callback_url must be passed while using this parameter. Possible values:

true: Customer is redirected to the specified callback URL in case of payment failure.
false (default): Customer is shown the Checkout popup to retry the payment.

timeout

optional

integer Sets a timeout on Checkout, in seconds. After the specified time limit, the customer will not be able to use Checkout.

readonly

optional

object Marks fields as read-only.

contact

optional

boolean Used to set the contact field as readonly. Possible values:

true: Customer will not be able to edit this field.
false (default): Customer will be able to edit this field.

optional

boolean Used to set the email field as readonly. Possible values:

true: Customer will not be able to edit this field.
false (default): Customer will be able to edit this field.

name

optional

boolean Used to set the name field as readonly. Possible values:

true: Customer will not be able to edit this field.
false (default): Customer will be able to edit this field.

send_sms_hash

optional

boolean Used to auto-read OTP for cards and net banking pages. Applicable from Android SDK version 1.5.9 and above. Possible values:

true: OTP is auto-read.
false (default): OTP is not auto-read.

retry

optional

object Parameters that enable retry of payment on the checkout.

enabled

boolean Determines whether the customers can retry payments on the checkout. Possible values:

true (default): Enables customers to retry payments.
false: Disables customers from retrying the payment.

max_count

integer The number of times the customer can retry the payment. We recommend you to set this to 4. Having a larger number here can cause loops to occur.

Watch Out!

Web Integration does not support the max_count parameter. It is applicable only in Android and iOS SDKs.

config

optional

object Parameters that enable configuration of checkout display language.

display

object Child parameter that enables configuration of checkout display language.

language

string The language in which checkout should be displayed. Possible values:

en: English
ben: Bengali
hi: Hindi
mar: Marathi
guj: Gujarati
tam: Tamil
tel: Telugu

1.7 Verify Payment Signature

This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.

To verify the razorpay_signature returned to you by the Checkout form:

Create a signature in your server using the following attributes:
- order_id: Retrieve the order_id from your server. Do not use the razorpay_order_id returned by Checkout.
- razorpay_payment_id: Returned by Checkout.
- key_secret: Available in your server. The key_secret that was generated from the
  Razorpay Dashboard
  .

Use the SHA256 algorithm, the razorpay_payment_id and the order_id to construct a HMAC hex digest as shown below:

generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret);

  if (generated_signature == razorpay_signature) {
    payment is successful
  }

If the signature you generate on your server matches the razorpay_signature returned to you by the Checkout form, the payment received is from an authentic source.

Generate Signature on Your Server

Given below is the sample code for payment signature verification:

RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");


String secret = "EnLs21M47BllR3X8PSFtjtbd";


JSONObject options = new JSONObject();
options.put("razorpay_order_id", "order_IEIaMR65cu6nz3");
options.put("razorpay_payment_id", "pay_IH4NVgf4Dreq1l");
options.put("razorpay_signature", "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f");


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

Post Signature Verification

After you have completed the integration, you can

set up webhooks

, make test payments, replace the test key with the live key and integrate with other

APIs

Here are the links to our

SDKs

for the supported platforms.

1.8 Verify Payment Status

Verify the payment status using the APIs and webhooks.

You can fetch the payment details using the

Fetch Payments API

The different payment states are given below:

1.9 Perform Post Payment Processing

Based on the order response, you can handle post-payment processing on your end. Use the Fetch Orders API to retrieve order details, including customer information, address, shipping method, and promotions.

Use the following endpoint to retrieve the details of a particular order:

GET

/orders/:id

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]\
-X GET https://api.razorpay.com/v1/orders/order_EKwxwAgItmmXdp \

Know more about the

Orders API.

Order Status

Prepaid orders: paid.
COD orders: placed.

1.8.1 Path Parameter

mandatory

string Unique identifier of the order to be retrieved.

Troubleshoot and FAQs

Integrate Magic Checkout on Website

Prerequisites

Integration Steps

1.1 Enable/Disable Magic Checkout and Cash on Delivery

1.2 Create Promotions and Shipping Info API Endpoints

1.3 Create an Order

1.3.1 Request Parameters

1.3.2 Response Parameters

1.3.3 Error Response Parameters

1.4 Interact with Shipping Info API

1.4.1 Request Parameters

1.4.2 Response Parameters

1.5 Interact with Get Promotions API

1.5.1 Request Parameters

1.5.2 Response Parameters

1.5.3 Interact with Apply Promotions API

1.5.3.1 Request Parameters

1.5.3.2 Response Parameters

1.5.3.3 Error Code, Description and Next Steps

1.6 Integrate with Magic Checkout on Client-Side

1.6.1 Handler Function and Callback URL

1.6.2 Code to Add Pay Button

1.6.3 Checkout Options

1.7 Verify Payment Signature

Generate Signature on Your Server

Post Signature Verification

1.8 Verify Payment Status

1.9 Perform Post Payment Processing

1.8.1 Path Parameter

Related Information