Web Component Integration

The <razorpay-checkout> web component lets you embed an Apple Pay button directly on your checkout page with minimal JavaScript. The component renders its own button, checks Apple Pay eligibility automatically and reports results via DOM events. Know more about

Apple Pay

Advantages

Integrating Apple Pay using the web component offers you the following advantages:

Minimal code: Drop in the HTML tag and wire up event listeners. No JavaScript setup needed for button rendering.
Customisable appearance: Configure the button theme, label, width and height using component attributes.
Device-aware rendering: The component automatically checks device eligibility and only renders the button when Apple Pay is supported.
Seamless event handling: Built-in events for payment success, failure and component errors integrate directly with your existing checkout logic.
No extra script for existing merchants: The component ships with the Custom Checkout script you already use.

Prerequisites

Before starting the integration, ensure you have the following:

A Razorpay Curlec account with Apple Pay enabled.
An existing Razorpay Curlec Custom Checkout integration.
International Payments enabled on your Razorpay Curlec account.
Your API Key Id available. Know how to generate
API Keys from the Dashboard
.
An HTTPS-enabled domain (TLS 1.2 or higher). Apple Pay requires a secure context and will not function over HTTP.
Server-side capability to create orders via the Razorpay Curlec Orders API.
Apple Pay domain verification completed for your checkout domain.

Integration Steps

Follow the steps given below.

Step 1: Domain Registration and Verification

Apple Pay needs you to host a file in your domain.

Watch Out!

The file path must be exactly as specified (case-sensitive).
File hosting is required on websites where Razorpay Curlec Checkout loads as an overlay/iframe. This includes:
- WooCommerce, Magento and other ecommerce platforms where Razorpay Curlec appears as an overlay. Any website where checkout.razorpay.com iframe is embedded.
No file hosting required on:
- Shopify, Mobile SDKs (Flutter, Native iOS, React Native) and Razorpay Curlec no-code solutions, such as
  Payment Links
  ,
  Payment Pages
  and
  Invoices
  .

Domain Verification Process:

Download the
verification file
.
Host the file on your server.
- Upload the file to this exact path on your website:
/.well-known/apple-developer-merchantid-domain-association
- For example, if your domain is https://www.yourstorename.com, the file must be accessible at:
https://www.yourstorename.com/.well-known/apple-developer-merchantid-domain-association
Ensure correct configuration. When setting up Apple Pay domain verification, follow these requirements:

File Path and Response
- The verification file must be accessible at the exact path, /.well-known/apple-developer-merchantid-domain-association.
- The file must return a direct HTTP 200 status code and not a 301, 302 or any 3xx redirects.
- Apple does not support HTTP URL redirects for the domain association file.
Server Configuration
- The file must be served via HTTPS 1.1 protocol.
- The file must have Content-Type: text/plain in the header.
- The file must be externally accessible (not behind authentication).
- The file must not be password protected.
- The file must not be behind a proxy or redirect.
Network Access
- Ensure the file is not behind a firewall or access restrictions.
- If using a firewall, configure it to allow Apple's
  IP addresses
  .
After completing the above steps, please contact the
Support team
to enable Apple Pay.

Step 2: Load the Script

Include the Razorpay Curlec Custom Checkout script in your page's <head> tag. This script registers the <razorpay-checkout> web component and makes it available for use in your HTML.

<head>
    <script src="https://checkout.razorpay.com/v1/razorpay.js"></script>
</head>

Handy Tip

Load this script on every page where you intend to render the Apple Pay button. The script must be loaded before the <razorpay-checkout> component is placed in the DOM. Existing Custom Checkout merchants already load this script and do not need to add a new one.

Step 3: Create an Order on Your Server

You must create a Razorpay Curlec order on your server before rendering the Apple Pay button. The order_id returned from this call is passed directly to the web component.

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": "USD",
     "receipt": "receipt_1"
 }'

The response includes an id field (for example, order_XXXXXXXXXX). Pass this value to your frontend to use as the order-id attribute on the component.

The parameter descriptions and errors are present in the

Create an Order API

Step 4: Drop in the Component Tag

Place the <razorpay-checkout> component in your HTML at the exact location where you want the Apple Pay button to render. The button loads inline at the position of this component.

<razorpay-checkout
    id="checkout"
    key="rzp_test_XXXXXXXXXX"
    order-id="order_XXXXXXXXXX"
    contact="+919876543210"
    method="card"
    app-name="apple_pay"
></razorpay-checkout>

To customise the button appearance, add the optional design attributes:

<razorpay-checkout
    id="checkout"
    key="rzp_test_XXXXXXXXXX"
    order-id="order_XXXXXXXXXX"
    contact="+919876543210"
    method="card"
    app-name="apple_pay"
    button-label="pay"
    button-theme="dark"
    button-width="148px"
    button-height="32px"
></razorpay-checkout>

The component fetches order details as soon as it is attached, checks Apple Pay eligibility and renders the button automatically once ready. No JavaScript setup is needed for that part.

Handy Tip

The component checks device eligibility on mount and renders the Apple Pay button only if the customer's device supports it. If Apple Pay is not available, nothing is rendered — no additional conditional logic is needed on your end.

Step 5: Listen for the Result

Attach event listeners to the component to handle the payment outcome.

const checkoutEl = document.getElementById('checkout');

checkoutEl.addEventListener('payment.success', (e) => {
    // e.detail.paymentData.razorpay_payment_id
    // e.detail.paymentData.razorpay_order_id
    // e.detail.paymentData.razorpay_signature
});

checkoutEl.addEventListener('payment.failure', (e) => {
    // e.detail.error -> { code, description, source, reason }
});

checkoutEl.addEventListener('error', (e) => {
    // init/validation failures (bad key, bad order-id, etc.)
});

That is the whole integration.

Step 6: Verify the Payment Signature on Your Server

After a successful payment (the payment.success event fires), verify the payment signature on your server before fulfilling the order.

Send the following fields to your backend:

razorpay_payment_id
razorpay_order_id
razorpay_signature

Verify them using the standard

Razorpay Curlec signature verification process

Watch Out!

Never fulfil an order based solely on the client-side payment.success event. Signature verification ensures the payment was genuinely processed by Razorpay Curlec and has not been tampered with.

Component Reference

Attributes

Events

payment.success

Fired when the payment completes successfully. The event detail contains:

{
    status: 'success',
    paymentData: {
        razorpay_payment_id: string,
        razorpay_order_id: string,
        razorpay_signature: string
    }
}

Use these three values to verify the payment on your server before fulfilling the order.

payment.failure

Fired when the payment fails or the customer cancels the payment sheet.

{
    status: 'failure',
    error: {
        code: string,
        description: string,
        source: string,
        reason: string
    }
}

error

Fired if the component fails to initialise — for example, due to an invalid attribute or Apple Pay not being enabled for your business account.

{
    errorCode: string,
    message: string
}

Check that key, order-id, method and app-name are all correctly set if you receive this event on load.

Error Handling Reference

Every failure — from payment.failure or the error event — carries the same shape:

{
  code: 'PAYMENT_CANCELLED' | 'PAYMENT_FAILED' | 'INTERNAL_ERROR',
  description: string,  // safe to show to the customer
  source: 'customer' | 'merchant' | 'bank' | 'internal',
  reason: string,        // machine-readable, for logging
}

Quick Checklist

Load https://checkout.razorpay.com/v1/razorpay.js
Create the order on your server before rendering the tag
Add <razorpay-checkout> with required attributes
Wire up payment.success / payment.failure / error listeners
Verify the payment signature on your server before fulfilling the order