razorpay-react-sdk/dist/index.d.ts

A simple Razorpay integration package for React & Next.js with TypeScript support.

import React from 'react';

/**
 * Parameters that enable configuration of checkout display language and payment methods.
 */
type Config = {
    /**
     * Child parameter that enables configuration of checkout display language.
     */
    display: {
        /**
         * The language in which checkout should be displayed.
         * Possible values:
         * - `en`: English
         * - `ben`: Bengali
         * - `hi`: Hindi
         * - `mar`: Marathi
         * - `guj`: Gujarati
         * - `tam`: Tamil
         * - `tel`: Telugu
         */
        language?: "en" | "ben" | "hi" | "mar" | "guj" | "tam" | "tel";
        /**
         * Configuration for payment method blocks.
         * Allows grouping and customizing payment methods.
         */
        blocks?: {
            [key: string]: {
                name: string;
                instruments: Array<{
                    method: string;
                    issuers?: string[];
                    banks?: string[];
                    wallets?: string[];
                }>;
            };
        };
        /**
         * Sequence of blocks to display in the checkout.
         * Defines the order of blocks during checkout.
         */
        sequence?: string[];
        /**
         * Preferences for displaying payment methods.
         * Provides control over the visibility of default blocks.
         */
        preferences?: {
            show_default_blocks?: boolean;
        };
        /**
         * List of payment methods to hide in the checkout.
         * Allows exclusion of specific payment methods.
         */
        hide?: Array<{
            method: string;
            issuers?: string[];
            banks?: string[];
        }>;
    };
};

type HiddenFields = {
    /**
     * Used to set the contact field as hidden.
     *
     * - `true`: Customer will not be able to view the contact field.
     * - `false` (default): Customer will be able to view the contact field.
     */
    contact?: boolean;
    /**
     * Used to set the email field as hidden.
     *
     * - `true`: Customer will not be able to view the email field.
     * - `false` (default): Customer will be able to view the email field.
     */
    email?: boolean;
};

type ModalOptions = {
    /**
     * Indicates whether clicking the translucent blank space outside the Checkout form should close the form.
     *
     * - `true`: Closes the form when the customer clicks outside the checkout form.
     * - `false` (default): Does not close the form when the customer clicks outside the checkout form.
     */
    backdropclose?: boolean;
    /**
     * Indicates whether pressing the escape key should close the Checkout form.
     *
     * - `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.
     */
    escape?: boolean;
    /**
     * Determines whether Checkout must behave similarly to the browser when the back button is pressed.
     *
     * - `true` (default): Checkout behaves similarly to the browser. When the browser's back button is pressed, the Checkout also simulates a back press as long as the Checkout modal is open.
     * - `false`: Checkout does not simulate a back press when the browser's back button is pressed.
     */
    handleback?: boolean;
    /**
     * Determines whether a confirmation dialog box should be shown if the customer attempts to close the Checkout.
     *
     * - `true`: A confirmation dialog box is shown.
     * - `false` (default): No confirmation dialog box is shown.
     */
    confirm_close?: boolean;
    /**
     * Used to track the status of Checkout. This function is called when the modal is closed by the user.
     * You can pass a modal object with `ondismiss: function() {}` as options. The function is triggered when Checkout closes, even after a failure if `retry` is false.
     */
    ondismiss?: () => void;
    /**
     * Shows an animation before loading the Checkout.
     *
     * - `true` (default): Animation appears.
     * - `false`: No animation appears.
     */
    animation?: boolean;
};

/**
 * A successful payment returns the following fields to the Checkout form.
 * You need to store these fields in your server.
 * You can confirm the authenticity of these details by verifying the signature in the next step.
 */
type PaymentResponse = {
    /**
     * Unique identifier for the payment returned by Checkout only for successful payments.
     */
    razorpay_payment_id: string;
    /**
     * Unique identifier for the order returned by Checkout.
     */
    razorpay_order_id: string;
    /**
     * Signature returned by Checkout. This is used to verify the payment.
     */
    razorpay_signature: string;
};

type Prefill = {
    /**
     * Cardholder's name.
     */
    name?: string;
    /**
     * Customers's email address.
     */
    email?: string;
    /**
     * Represents a customer's phone number.
     *
     * The phone number should be in the format: `+{country code}{phone number}`.
     * If the country code is not specified, `+91` (India) will be used as the default country code.
     *
     * Examples:
     * - `+14155552671` (a valid non-Indian number)
     * - `+919977665544` (a valid Indian number)
     *
     * If only the phone number is provided without a country code (e.g., `9977665544`),
     * the default country code `+91` will be prepended, resulting in `+919977665544`.
     */
    contact?: string;
    /**
     * Represents the pre-selection of a payment method for the customer.
     *
     * This will only work if both the `contact ` and `email` are also pre-filled.
     * The payment method can be one of the following possible values:
     *
     * - `card`: Payment via credit or debit card
     * - `netbanking`: Payment via internet banking
     * - `wallet`: Payment via a digital wallet
     * - `emi`: Payment via equated monthly installments (EMI)
     * - `upi`: Payment via Unified Payments Interface (UPI)
     *
     * Note: Pre-selection will only occur when both the contact and email fields are populated.
     */
    method?: "card" | "netbanking" | "wallet" | "emi" | "upi";
};

type ReadonlyFields = {
    /**
     * Used to set the contact field as read-only.
     *
     * - `true`: Customer will not be able to edit the contact field.
     * - `false` (default): Customer will be able to edit the contact field.
     */
    contact?: boolean;
    /**
     * Used to set the email field as read-only.
     *
     * - `true`: Customer will not be able to edit the email field.
     * - `false` (default): Customer will be able to edit the email field.
     */
    email?: boolean;
    /**
     * Used to set the name field as read-only.
     *
     * - `true`: Customer will not be able to edit the name field.
     * - `false` (default): Customer will be able to edit the name field.
     */
    name?: boolean;
};

type Retry = {
    /**
     * 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.
     */
    enabled: boolean;
    /**
     * 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.
     *
     * Web Integration does not support the `max_count` parameter.
     * It is applicable only in Android and iOS SDKs.
     */
    max_count?: number;
};

type Theme = {
    /**
     * Used to display or hide the top bar on the Checkout form.
     *
     * This bar shows the selected payment method, phone number and gives the customer the option to navigate back to the start of the Checkout form.
     *
     * - `true`: Hides the top bar
     * - `false` (default): Displays the top bar
     */
    hide_topbar?: boolean;
    /**
     * Enter your brand color's HEX code to alter the text, payment method icons, and CTA button color of the Checkout form.
     */
    color?: string;
    /**
     * Enter a HEX code to change the Checkout's backdrop color.
     */
    backdrop_color?: string;
};

/**
 * Options to configure the Razorpay payment instance.
 */
interface RazorpayOptions {
    /**
     * Your API Key ID generated from the Razorpay Dashboard.
     */
    key: string;
    /**
     * Payment amount in the smallest currency sub-unit (e.g., 10000 = ₹100).
     *
     * For example:
     * - If the amount to be charged is ₹299.00, then pass 29900 in this field.
     * - In the case of three decimal currencies, such as KWD, BHD, and OMR:
     *   - To accept a payment of 295.991, pass the value as 295990.
     * - In the case of zero decimal currencies, such as JPY:
     *   - To accept a payment of 295, pass the value as 295.
     *
     * This approach ensures proper handling of different currency precision requirements
     * by passing the corresponding value in the smallest sub-unit (e.g., paise, fils, etc.).
     */
    amount: number;
    /**
     * The currency in which the payment should be made by the customer.
     *
     * See the list of supported currencies here:
     * [Razorpay Supported Currencies](https://razorpay.com/docs/payments/international-payments/#supported-currencies)
     */
    currency: string;
    /**
     * Your Business/Enterprise name shown on the Checkout form.
     *
     * For example, **Acme Corp**.
     */
    name: string;
    /**
     * Description of the purchase item shown on the Checkout form. It should start with an alphanumeric character.
     */
    description?: string;
    /**
     * Link to an image (usually your business logo) shown on the Checkout form. Can also be a **base64** string if you are not loading the image from a network.
     */
    image?: string;
    /**
     * Order ID generate via [Orders API](https://razorpay.com/docs/api/orders/)
     */
    order_id?: string;
    /**
     * Prefilled user details for faster checkout.
     */
    prefill?: Prefill;
    /**
     * Represents additional information that can be stored about the payment.
     *
     * This is an optional property and allows you to store a set of key-value pairs.
     *
     * The object can hold a maximum of 15 key-value pairs, with each key or value being
     * a string with a maximum length of 256 characters.
     *
     * Example:
     * ```typescript
     * notes: {
     *   "address": "Razorpay Corporate Office",
     *   "customerNote": "Please deliver by end of the day"
     * }
     * ```
     *
     */
    notes?: {
        [key: string]: string;
    };
    /**
     * Optional thematic options to modify the appearance of the Checkout form.
     */
    theme?: Theme;
    /**
     * Represents options to handle the Checkout modal.
     */
    modal?: ModalOptions;
    /**
     * Represents the subscription ID for recurring payments via Razorpay Checkout.
     *
     * This is an optional string parameter. If you are accepting recurring payments using Razorpay Checkout,
     * you should pass the relevant `subscription_id` to the Checkout.
     *
     * For more information on subscription integration with Razorpay Checkout, refer to:
     * [Subscriptions on Checkout](https://razorpay.com/docs/api/payments/subscriptions/#checkout-integration)
     */
    subscription_id?: string;
    /**
     * Represents the option to permit or restrict the customer from changing the card linked to the subscription.
     *
     * This is an optional boolean parameter. You can control whether customers are allowed to change the card
     * linked to their subscription via the Checkout page. You can also manage this through the [hosted page](https://razorpay.com/docs/payments/subscriptions/payment-retries/#update-the-payment-method-via-our-hosted-page).
     *
     * Possible values:
     * - `true`: Allows the customer to change the card from the Checkout page.
     * - `false` (default): Does not allow the customer to change the card from the Checkout page.
     */
    subscription_card_change?: boolean;
    /**
     * Represents whether recurring payments are accepted on Checkout via instruments such as emandate, paper NACH, and others.
     *
     * This is an optional boolean parameter. It determines if the Checkout allows [recurring (charge-at-will) payments](https://razorpay.com/docs/api/payments/recurring-payments/).
     *
     * Possible values:
     * - `true`: You are accepting recurring payments via instruments like emandate, paper NACH, etc.
     * - `false` (default): You are not accepting recurring payments.
     */
    recurring?: boolean;
    /**
     * Represents the URL to which customers will be redirected upon successful payment.
     *
     * This is an optional string parameter. After a successful payment, the customer will be redirected to the specified `callback_url`.
     *
     * Ensure that the domain of the `callback_url` is allowlisted to avoid any issues with the redirection.
     */
    callback_url?: string;
    /**
     * Determines whether to post a response to the event handler or redirect to the Callback URL after payment completion.
     *
     * This is an optional boolean parameter. If the `redirect` option is enabled, the customer will be redirected to the
     * `callback_url` specified after a payment, even in the case of payment failure. The `callback_url` must be provided
     * when using this parameter.
     *
     * Possible values:
     * - `true`: The customer is redirected to the specified `callback_url` in case of payment failure.
     * - `false` (default): The customer is shown the Checkout popup to retry the payment with the suggested next best option.
     */
    redirect?: boolean;
    /**
     * Represents a unique identifier for the customer.
     *
     * This is an optional string parameter. The `customer_id` is used for:
     * - [Local saved cards feature](https://razorpay.com/docs/payments/payment-methods/cards/features/saved-cards/#manage-saved-cards), allowing the customer to use previously saved payment methods.
     * - Displaying static bank account details on Checkout in case the [Bank Transfer payment method](https://razorpay.com/docs/payments/payment-methods/bank-transfer/) is used.
     *
     * Ensure that the `customer_id` is unique to avoid any conflicts.
     */
    customer_id?: string;
    /**
     * Determines whether to allow the saving of cards for future payments.
     *
     * This is an optional boolean parameter that specifies if the card-saving feature should be enabled for the customer.
     * It can also be configured via the Dashboard.
     *
     * Possible values:
     * - `true`: Enables the card saving feature, allowing customers to save their card details for future use.
     * - `false` (default): Disables the card saving feature, meaning the customer’s card details will not be saved.
     */
    remember_customer?: boolean;
    /**
     * Sets a timeout on Checkout, in seconds.
     *
     * This is an optional integer parameter. After the specified time limit (in seconds), the customer will no longer be able to use the Checkout.
     *
     * Example:
     * - `timeout: 300` will set a 5-minute timeout for the Checkout session.
     */
    timeout?: number;
    /**
     * Represents fields that are marked as read-only, preventing customers from editing them.
     *
     * This is an optional object containing settings for making specific fields (contact, email, and name) read-only.
     * Each field can be set to either `true` (read-only) or `false` (default, editable).
     */
    readonly?: ReadonlyFields;
    /**
     * Represents fields that are hidden from the customer.
     *
     * This is an optional object that allows you to hide specific fields (contact and email). When a field is set as hidden, the customer will not be able to view it.
     *
     * Each field can be set to either `true` (hidden) or `false` (default, visible).
     */
    hidden?: HiddenFields;
    /**
     * Determines whether the OTP for cards and net banking pages is auto-read.
     *
     * This is an optional boolean parameter, and it is applicable from Android SDK version 1.5.9 and above.
     *
     * Possible values:
     * - `true`: OTP is auto-read, allowing the system to automatically read the OTP from the SMS.
     * - `false` (default): OTP is not auto-read, and the customer will need to enter the OTP manually.
     */
    send_sms_hash?: boolean;
    /**
     * A boolean value that determines whether the payment page can be rotated according to the screen orientation.
     * This field is applicable from Android SDK version 1.6.4 and above.
     *
     * Possible values:
     * - `true`: The payment page can be rotated.
     * - `false` (default): The payment page cannot be rotated.
     *
     * @since 1.6.4 (Android SDK version)
     */
    allow_rotation?: boolean;
    /**
     * Parameters that enable retry of payment on the checkout.
     */
    retry?: Retry;
    /**
     * Parameters that enable configuration of checkout display language and payment methods.
     */
    config?: Config;
    /**
     * Success Callback function for handling the payment response.
     * The function will alert the payment ID, order ID, and signature upon a successful payment.
     *
     * @param response - The response object returned by Razorpay Checkout.
     */
    handler?: (response: PaymentResponse) => void;
}

/**
 * Type for global Razorpay configuration options.
 * These options are set once and apply to all payments.
 */
type RazorpayGlobalOptions = Omit<RazorpayOptions, "order_id" | "amount" | "currency" | "name" | "subscription_id" | "handler" | "callback_url"> & {
    key: string;
};

/**
 * Type for payment-specific options that change per transaction.
 */
type RazorpayPaymentOptions = Pick<RazorpayOptions, "order_id" | "amount" | "currency" | "name" | "subscription_id" | "handler" | "callback_url">;

/**
 * Custom hook to open a Razorpay payment modal without requiring a provider.
 * @param {RazorpayGlobalOptions} globalOptions - Global configuration options (e.g., key, theme, config)
 * @returns A function that accepts payment-specific fields and triggers the payment flow.
 */
declare function useRazorpay(globalOptions: RazorpayGlobalOptions): (paymentOptions: RazorpayPaymentOptions) => Promise<void>;

/**
 * Provides Razorpay configuration to child components.
 * @param options - Default payment options for Razorpay.
 * @param children - React child components.
 */
declare function RazorpayProvider({ options, children, }: Readonly<{
    options: RazorpayGlobalOptions;
    children: React.ReactNode;
}>): React.JSX.Element;
/**
 * Hook to trigger a Razorpay payment with optional global configuration overrides.
 * @param overrideConfig - Optional global overrides (e.g., theme, config)
 * @returns A function that accepts payment-specific fields and opens Razorpay Checkout.
 */
declare function useRazorpayFromProvider(overrideConfig?: Partial<RazorpayGlobalOptions>): (paymentOptions: RazorpayPaymentOptions) => Promise<void>;

/**
 * Utility class for handling Razorpay payments.
 */
declare class RazorpayClient {
    private static scriptLoaded;
    /**
     * Loads the Razorpay checkout script dynamically.
     * @returns A promise that resolves when the script is successfully loaded.
     */
    static loadScript(): Promise<boolean>;
    /**
     * Opens the Razorpay checkout modal with the provided options.
     * @param {RazorpayOptions} options - Configuration options for the Razorpay payment.
     */
    static openPayment(options: RazorpayOptions): Promise<void>;
}

export { type Config, type HiddenFields, type ModalOptions, type PaymentResponse, type Prefill, RazorpayClient, type RazorpayGlobalOptions, type RazorpayOptions, type RazorpayPaymentOptions, RazorpayProvider, type ReadonlyFields, type Retry, type Theme, useRazorpay, useRazorpayFromProvider };