Skip to main content
Instead of redirecting customers to a Razorpay-hosted page, the SDK renders natively on your site, providing a seamless, single-click payment experience with no extra page loads or redirects.

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:
  1. Your Checkout page loads the Checkout Blocks SDK script.
  2. The SDK dynamically loads only the wallet adapters you need (for example, Apple Pay, Google Pay).
  3. You check wallet eligibility on the customer’s device using isSupported().
  4. If eligible, render the payment button and call initiatePayment() on user click.
  5. The SDK handles merchant validation, payment authorisation, DCC (if applicable) and completion.
  6. Your page receives payment events (onPaymentComplete, onError) via callbacks.
No redirect to 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_id to 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 Status

1.1 Load the Checkout Blocks SDK

Add the Checkout Blocks SDK script to the “ section of your Checkout page. The SDK exposes a global RazorpayCheckoutBlocks 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 resulting order_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 an order_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
The web component automatically checks device eligibility and renders the appropriate payment button. If the wallet is not supported on the customer’s device, nothing is rendered.

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
Watch Out!initiatePayment() can only be called once per transaction. Calling it again will not start a new payment unless the current transaction has ended (completed, failed or cancelled).

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, the onPaymentComplete event contains the following fields:
  • razorpay_payment_id
  • razorpay_order_id
  • razorpay_signature
Send these values to your server for signature verification.

Error Callback

If the payment fails, the onError 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. The razorpay_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:
  1. Log in to the Razorpay Dashboard and navigate to TransactionsPayments.
  2. Check if a Payment Id has been generated and note the status. In case of a successful payment, the status is marked as Captured.
You can use Razorpay webhooks to configure and receive notifications when a specific event occurs. When one of these events is triggered, we send an HTTP POST payload in JSON to the webhook’s configured URL. Know how to set up webhooks.

Example

If you have subscribed to the order.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

  1. Log in to your Razorpay Dashboard.
  2. Navigate to the Apple Pay settings section and download the domain association file provided by Razorpay.
  3. Host the file on your server at the following path: https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
  4. Ensure the file is publicly accessible over HTTPS.
  5. Razorpay will use its own Apple Merchant ID. Your domain is whitelisted automatically once onboarding is complete.
Watch Out!The domain association file must be served with Content-Type: application/octet-stream or text/plain. Ensure your server does not block or redirect requests to the .well-known directory.

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?

The isSupported() 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.

3. Can the customer retry a failed payment?

Yes. On payment failure, the customer can attempt payment again without refreshing the page.