Web JS Integration

Available in🇮🇳 India

The headless JS integration gives you full control over the Apple Pay button and payment flow. You initialise the Razorpay JS object with the amount and currency at start, then check eligibility and trigger the payment yourself. Know more about Apple Pay.

Advantages

Integrating Apple Pay using the headless JS SDK offers you the following advantages:

Full control: Render your own button or let Razorpay render one for you using mount().
Flexible initialisation: Pass amount and currency at init time when the cart total is known upfront.
Device-aware eligibility: Use canMakePayment() to check Apple Pay support before showing the button.
Event-driven results: Handle payment success, failure and errors through event listeners.
No extra script for existing merchants: The SDK ships with the Custom Checkout script you already use.

Prerequisites

Before starting the integration, ensure you have the following:

A Razorpay account with Apple Pay enabled.
An existing Razorpay Custom Checkout integration.
International Payments enabled on your Razorpay 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 Orders API.
Domains verified in the Dashboard for Apple Pay.

Integration Steps

Follow the steps given below.

Step 1: Domain Verification

Verify your checkout domain(s) for Apple Pay before you go live. To find the list of these domains, please log in to the dashboard.

Handy TipOnly domains whitelisted with the accounts service will be visible here. Similar domains are visible as well. Please contact our Support team if you cannot find your Apple Pay showing domain here. You need to whitelist your URL.

Dashboard Configuration and Verification

Log in to the Dashboard and navigate to Account & Settings → International payments (under Payment methods). Click Apple Pay.
ImportantThis will only be visible if the business has International payments activated. If you do not have international payments active, you will not see Apple Pay.
You will see a list of domains associated with your business account:
- Verified domains: Ready for Apple Pay.
- Unverified domains: Need to be verified.
Click Verify domains for any unverified domains.

Step 2: Load the Script

Include the Razorpay Custom Checkout script in your page’s <head> tag.

HTML

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

Handy TipLoad this script on every page where you intend to use the Apple Pay integration. Existing Custom Checkout merchants already load this script.

Running Alongside Standard Checkout

Both razorpay.js (headless Apple Pay) and checkout.js (Standard Checkout) register their constructor on the same window.Razorpay global. If your page uses both, whichever script loads last overwrites the other’s constructor on window.Razorpay. Capture the headless constructor as soon as razorpay.js loads, and let checkout.js load after it so window.Razorpay is restored to Standard Checkout’s constructor for the rest of your page.

HTML

<head>
    <script src="https://checkout.razorpay.com/v1/razorpay.js" onload="window.__rzpApplePay = window.Razorpay;"></script>
    <script src="https://checkout.razorpay.com/v1/checkout.js"></script>
</head>

If you cannot guarantee this load order (for example, scripts injected dynamically or loaded in parallel), queue the captures instead and resolve them once both scripts have loaded:

JavaScript

window.__rzpQueue = window.__rzpQueue || [];

function enqueueRazorpayCtor(name) {
  window.__rzpQueue.push({ name, ctor: window.Razorpay });
  if (window.__rzpQueue.length === 2) {
    // Both scripts have loaded — headless SDK loaded first, Standard Checkout loaded second.
    const [applePay, standard] = window.__rzpQueue;
    window.__rzpApplePay = applePay.ctor;
    window.Razorpay = standard.ctor;
  }
}

Use window.__rzpApplePay (instead of window.Razorpay) to instantiate the headless Apple Pay object in Step 3, and leave window.Razorpay untouched for your existing Standard Checkout code.

JavaScript

const razorpay = new window.__rzpApplePay({ ... });

Step 3: Initialise with Amount and Currency

Pass the amount and currency when you initialise Razorpay. Use the on_payment_initiate_create_order callback to create the order on your server right before the payment sheet opens.

JavaScript

const razorpay = new Razorpay({
  key: 'rzp_test_XXXXXXXXXX',
  prefill: {
    contact: '+919876543210', // This is your customer's contact number.
  },
  amount: 1000,
  currency: 'EUR',
  on_payment_initiate_create_order: async () => {
    // Called right before the payment sheet opens.
    // Create the order on your server here, then:
    razorpay.set('order_id', orderIdFromYourServer);
  },
});

Watch Out!on_payment_initiate_create_order is where you create the Razorpay order. You must call razorpay.set('order_id', ...) inside it before it resolves — the payment cannot be authorised without an order id.

Step 4: Listen for the Result

JavaScript

razorpay.on('payment.success', (response) => {
  // response.paymentData.razorpay_payment_id
  // response.paymentData.razorpay_order_id
  // response.paymentData.razorpay_signature
});

razorpay.on('payment.failure', (response) => {
  // response.error -> { code, description, source, reason }
});

Step 5: Check Availability and Trigger the Payment

Check whether the customer’s device supports Apple Pay using canMakePayment(), then trigger the payment using one of the following options.

Option 1: mount() (Recommended)
Option 2: Your Own Button + createPayment()

Use mount() to have Razorpay render an Apple Pay button into a container element you provide. This is the recommended default — it needs the least code, and the SDK starts the Apple Pay session on click and handles the payment for you.

JavaScript

razorpay.mount({
  method: 'card',
  app: { name: 'apple_pay' },
  container: document.getElementById('apple-pay-container'),
  buttonLabel: 'pay',
  buttonTheme: 'dark',
  buttonWidth: '148px',
  buttonHeight: '32px',
});

mount() creates the button, appends it to the container and wires up the click to payment lifecycle for you. The result still comes via the payment.success / payment.failure events from Step 3.

Watch Out!Call canMakePayment() before mount() if you want to avoid mounting a button the customer cannot actually use (for example, hide the container on available: false).

Use this option only if you need full control over the button’s markup and rendering. Use canMakePayment() to check eligibility, then call createPayment() inside your button’s click handler.

JavaScript

const { available, reason } = await razorpay.canMakePayment({
  method: 'card',
  app: { name: 'apple_pay' },
});

if (!available) {
  // hide your Apple Pay button, show alternatives
} else {
  // show your button
}

myButton.addEventListener('click', () => {
  razorpay.createPayment({
    method: 'card',
    app: { name: 'apple_pay' },
  });
});

Handy TipcreatePayment() is fire-and-forget — the outcome always comes through the payment.success / payment.failure events registered in Step 3.

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 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 and has not been tampered with.

Error Handling Reference

Every failure — from payment.failure events or a caught exception — carries the same shape:

JavaScript

{
  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
}

Code	Meaning	Suggested Handling
`PAYMENT_CANCELLED`	Customer closed the sheet, or you called `abort()`	Return to the product/cart page
`PAYMENT_FAILED`	Payment was attempted but declined/failed	Show description, offer retry or another method
`INTERNAL_ERROR`	Something went wrong on our end (network, script load, etc.)	Show a generic “try again later” message

Quick Checklist

Load https://checkout.razorpay.com/v1/razorpay.js
Initialise new Razorpay({ amount, currency, ... })
Implement order creation inside on_payment_initiate_create_order
Wire up payment.success / payment.failure handling
Test canMakePayment() handling for devices/browsers where Apple Pay is not available
Verify the payment signature on your server before fulfilling the order

​Prerequisites

​Integration Steps

​Error Handling Reference

​Quick Checklist

​Related Information

Prerequisites

Integration Steps

Error Handling Reference

Quick Checklist

Related Information