StripeCheckoutModal Documentation

Overview

The StripeCheckoutModal component is designed to render Stripe's Embedded Checkout within a modal overlay in a web application. This component provides a seamless user experience for initiating transactions while ensuring security and efficiency via Stripe's checkout process.

Purpose

The primary purpose of the StripeCheckoutModal is to facilitate the transaction process for users directly within a modal. It allows users to complete their purchases without leaving the current page, which enhances user experience and can lead to higher conversion rates. This component is particularly useful in e-commerce platforms, services with subscription models, or any application that requires secure payment processing.

Settings

The StripeCheckoutModal component accepts several props that allow you to configure its behavior and appearance. Each prop is detailed below:

Props

1. open

   • Input Type: Boolean
   • Description: Determines whether the modal is visible to the user. When set to true, the modal is displayed; when false, it is hidden.
   • Default Value: false (the modal is closed by default).

2. onClose

   • Input Type: Function
   • Description: A callback function that is invoked to close the modal. This is typically called when the user clicks outside the modal or on the close button. It should handle any cleanup or state updates necessary upon modal dismissal.
   • Default Value: None (the user must provide this function).

3. fetchClientSecret

   • Input Type: Async Function
   • Description: An asynchronous function that retrieves a Stripe client_secret string. This is crucial for the payment flow, allowing the modal to initiate the checkout session securely. This function should be implemented to call your backend API that generates the client_secret.
   • Default Value: None (the user must provide this function).

4. onComplete

   • Input Type: Optional Function
   • Description: An optional callback function that is triggered when the checkout process is completed. This can be used to handle subsequent actions after payment, such as updating the user interface or redirecting the user to a confirmation page.
   • Default Value: undefined (if not provided, no action is taken on completion).

How It Works

The StripeCheckoutModal leverages the Stripe Embedded Checkout integration to provide a smooth payment experience. Here's a breakdown of its operation:

1. Initialization: The Stripe Promise is loaded using the public Stripe publishable key specified in the environment variable your Stripe publishable key. This allows the integration to interact with Stripe's API.

2. Modal Display: When the open prop is set to true, the modal renders on the screen. Otherwise, it returns null, rendering nothing.

3. Close Mechanism: The modal can be closed via the close button or by clicking on the modal backdrop, both invoking the onClose callback.

4. Fetching Client Secret: The fetchClientSecret function is called asynchronously to obtain the client secret needed for initiating the payment workflow. It is wrapped in a optimized callbacks to ensure performance optimization by maintaining a stable reference.

5. Embedded Checkout: The modal encapsulates the EmbeddedCheckoutProvider, passing in the necessary options including fetchClientSecret and onComplete. The EmbeddedCheckout component is then rendered within this provider, allowing users to complete their transactions securely in a visual component.

Use Cases & Examples

Use Cases

1. E-Commerce Checkout: An online retail platform wants to implement a seamless checkout experience, allowing customers to purchase items without navigating away from the product page.

2. Subscription Services: A SaaS application requires a billing solution that permits users to subscribe to services on demand, ensuring a user-friendly payment process.

3. Donation Platforms: Non-profit organizations can use the modal for handling donations, making it quick and easy for users to contribute without unnecessary steps.

Example Configuration

Use Case: Implementing an E-commerce Checkout Experience.

Configuration Example:

// Function to fetch the client secret from the server
const fetchClientSecret = async () => {
    const response = await fetch('/api/create-checkout-session', {
        method: 'POST',
    });
    const data = await response.json();
    return data.client_secret;
};

// Function to handle checkout completion
const handleCheckoutComplete = () => {
    alert('Payment completed successfully!');
    // Additional actions like redirect or state update can be done here
};

// Usage in a component
const YourCheckoutComponent = () => {
    const [isModalOpen, setModalOpen] = initState(false);

    return (
        <>
            <button onClick={() => setModalOpen(true)}>Checkout</button>
            <StripeCheckoutModal
                open={isModalOpen}
                onClose={() => setModalOpen(false)}
                fetchClientSecret={fetchClientSecret}
                onComplete={handleCheckoutComplete}
            />
        </>
    );
};

In this example, fetchClientSecret retrieves a client secret from the server when the user initiates a checkout. The modal opens when the "Checkout" button is clicked and closes appropriately, with an alert being displayed once the payment process is finished successfully.