Advantages
- Offer single-click express checkout with digital wallet. No redirects, no extra page loads.
- Support multiple wallet (Apple Pay, Google Pay and more) through a single, unified SDK.
How It Works
The Checkout Blocks SDK manages the full payment lifecycle for each supported wallet. At a high level:- Your Checkout page loads the Checkout Blocks SDK script.
- The SDK dynamically loads only the wallet adapters you need (for example, Apple Pay, Google Pay).
- You check wallet eligibility on the customer’s device using
isSupported(). - If eligible, render the payment button and call
initiatePayment()on user click. - The SDK handles merchant validation, payment authorisation, DCC (if applicable) and completion.
- Your page receives payment events (
onPaymentComplete,onError) via callbacks.
api.razorpay.com is required, the entire flow happens on your domain.
Prerequisites
Before you begin the integration, ensure you have:- Active Razorpay Account: A Razorpay account with payments enabled.
- Order Creation via Backend: Your server must be able to create orders using the Orders API and pass the
order_idto the frontend. - HTTPS Protocol: Your website must be served over HTTPS for security compliance. Digital wallet require a secure context.
Handy TipsRazorpay manages all Apple Pay certificates and business verification on your behalf. You only need to host the domain association file.
Integration Steps
Follow the steps given below to integrate Checkout Blocks and accept express checkout payments on your website. 1.1 Load the Checkout Blocks SDK 1.2 Create an Order 1.3 Initialise SDK and Check Wallet Eligibility 1.4 Handle Payment Events 1.5 Verify Payment Signature 1.6 Integrate Payments Rainy Day Kit 1.7 Verify Payment Status1.1 Load the Checkout Blocks SDK
Add the Checkout Blocks SDK script to the “ section of your Checkout page. The SDK exposes a globalRazorpayCheckoutBlocks object that you use to interact with wallet.
Script Setup
Add the following to your HTML “:HTML
Handy TipsAdding
preconnect and dns-prefetch hints can reduce script load time by up to 75%. We strongly recommend including these in your “ tag.The SDK core is under 10 KB (gzipped). Wallet-specific adapters are loaded dynamically only when needed:- Core SDK —
https://checkout.razorpay.com/checkout-blocks/checkout-blocks.js - Apple Pay Adapter —
https://checkout.razorpay.com/checkout-blocks/rzp-apple-pay.js - Google Pay Adapter —
https://checkout.razorpay.com/checkout-blocks/rzp-google-pay.js
1.2 Create an Order
Before initiating a payment, create an order on your backend using the Razorpay Orders API. Pass the resultingorder_id to your frontend to initialise the SDK.
The SDK flow requires your site to call Create Order (amount, currency) on the Razorpay backend and receive an order_id in response. Use this order_id when initialising the SDK in step 1.3.
Refer to the Orders API documentation for detailed request and response parameters.
1.3 Initialise SDK and Check Wallet Eligibility
Once the SDK is loaded and you have anorder_id, you can initialise Checkout Blocks and check whether the customer’s device supports a given wallet.
Integration Option 1: Razorpay-Managed Web Component
Use this approach if you want Razorpay to handle button rendering and payment initiation automatically. Simply place the “ web component on your page.JavaScript
Integration Option 2: Business-Controlled
Use this approach if you want full control over button rendering and payment initiation. You use the SDK’s JavaScript API to check eligibility and trigger payments programmatically.JavaScript
1.4 Handle Payment Events
Subscribe to payment lifecycle events to track the payment status and update your UI accordingly.Available Events
Event | Description
onPaymentComplete | Fired when payment is complete. Resolves to either success or failure.
onPaymentCancel | Fired when payment is cancelled by the user.
onError | Indicates any error that happens within the payment cycle. Could be vendor-specific or Razorpay-specific.
Success Callback
If the payment is successful, theonPaymentComplete event contains the following fields:
razorpay_payment_idrazorpay_order_idrazorpay_signature
Error Callback
If the payment fails, theonError event contains details about the failure. Common error codes:
Error Code | Description | Retryable
BAD_REQUEST_ERROR | Invalid request parameters or payment failure. | No
GATEWAY_ERROR | Payment gateway error during processing. | Yes
SERVER_ERROR | Internal server error. | Yes
INVALID_MERCHANT_ERROR | Invalid merchant configuration. | No
PAYMENT_ALREADY_PROCESSED | Payment already authorised/captured. | No
INSUFFICIENT_FUNDS | Card has insufficient balance. | No
CARD_DECLINED | Card declined by issuer. | No
AUTHENTICATION_FAILED | 3DS authentication failed. | No
On retryable errors, the SDK automatically re-renders the payment buttons so the customer can attempt payment again.
1.5 Verify Payment Signature
Signature verification is a mandatory step to ensure that the payment callback is authentic and sent by Razorpay. Therazorpay_signature contained in the success callback can be regenerated by your system and verified as follows.
Create a string to be hashed using the razorpay_payment_id contained in the callback and the order_id generated in step 1.2, separated by a |. Hash this string using SHA256 and your API Secret.
Generate Signature on your Server
Sample code
Java
1.6 Integrate Payments Rainy Day Kit
Use Payments Rainy Day kit to overcome payments exceptions such as:1.7 Verify Payment Status
Handy TipsOn the Razorpay Dashboard, ensure that the payment status is
captured. Refer to the payment capture settings page to know how to capture payments automatically.You can track the payment status in three ways:
To verify the payment status from the Razorpay Dashboard:- Log in to the Razorpay Dashboard and navigate to Transactions → Payments.
- Check if a Payment Id has been generated and note the status. In case of a successful payment, the status is marked as Captured.
Example
If you have subscribed to theorder.paid webhook event, you will receive a notification every time a customer pays you for an order.
Poll Payment APIs to check the payment status.
Apple Pay - Domain Verification
To accept Apple Pay payments, your domain must be verified with Apple via Razorpay. Follow the steps below:Steps to Verify Your Domain
- Log in to your Razorpay Dashboard.
- Navigate to the Apple Pay settings section and download the domain association file provided by Razorpay.
- Host the file on your server at the following path:
https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association - Ensure the file is publicly accessible over HTTPS.
- Razorpay will use its own Apple Merchant ID. Your domain is whitelisted automatically once onboarding is complete.
Frequently Asked Questions
1. Can I integrate multiple wallet using a single SDK?
Yes. Checkout Blocks is designed to support multiple digital wallet through a single integration. You load the SDK once and specify which wallet to enable. Each wallet adapter is loaded dynamically, keeping the core bundle lightweight.2. What happens if the customer’s device does not support the wallet?
TheisSupported() method returns false for unsupported wallet. In the Web Component approach, the element simply does not render. You should always check eligibility before displaying a payment button.