CheckoutForm | ArcBlock

The CheckoutForm component is the primary entry point for handling payment links and checkout sessions. It serves as a high-level wrapper that automatically fetches the necessary data based on a provided ID and renders the appropriate payment or donation interface. This component provides the most straightforward method for integrating a complete checkout flow into your application.

For the CheckoutForm to function correctly, it must be nested within a PaymentProvider. This provider supplies the necessary context, such as session information and API configuration. For detailed setup instructions, please refer to the PaymentProvider documentation.

How It Works

The component manages the entire checkout process through a clear, sequential flow:

Initialization
The component is mounted with an id prop, which must be either a paymentLink ID (prefixed with plink_) or a checkoutSession ID (prefixed with cs_).
Data Fetching
It sends a request to the payment backend to retrieve the complete checkout context, which includes available payment methods, line items, and customer details.
UI Rendering
Based on the formType prop, it internally renders either the standard Payment component for purchases or the specialized DonationForm for contributions.
State Management
It handles the full lifecycle of the transaction, managing loading states, completion status, and any potential errors.

Props

The CheckoutForm component is configured using the following properties.

id string (required) — The unique identifier for the payment link (plink_...) or checkout session (cs_...).
mode 'standalone' | 'inline' | 'popup' | 'inline-minimal' | 'popup-minimal' (default: inline) — Defines the rendering mode. 'standalone' creates a full-page view, while 'inline' embeds the form within an existing container. The -minimal variants hide the order summary.
formType 'payment' | 'donation' (default: payment) — Specifies the type of form to render. Use 'donation' to activate the specialized donation user interface.
onPaid (res: CheckoutContext) => void — A callback function that is executed upon successful payment completion. It receives the final checkout context as an argument.
onError (err: Error) => void (default: console.error) — A callback function that is executed if an error occurs during the checkout process.
onChange (data: CheckoutFormData) => void — A callback function that fires whenever a value in the payment form changes.
goBack () => void — If provided, a back button is rendered. This function is called when the button is clicked.
extraParams Record<string, any> (default: {}) — An object containing extra parameters to be appended to the URL when initiating a checkout session from a payment link.
theme 'default' | 'inherit' | PaymentThemeOptions (default: default) — Controls the component's theme. 'inherit' uses the parent theme, while 'default' applies the library's standard theme. A custom theme object can also be provided.
action string (default: '') — A string identifier used for customizing UI elements, such as button text, or for tracking specific analytics events.

Usage Examples

Basic Inline Payment Form

This is the most common use case, where the payment form is embedded directly into a page of your application. The component handles all data fetching and state management internally.

MyStorePage.jsx

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context'; // This is an example hook from your application

export default function MyStorePage() {
  const { session, connectApi } = useSessionContext();

  const handlePaymentSuccess = (result) => {
    console.log('Payment successful!', result);
    alert('Thank you for your purchase!');
  };

  const handlePaymentError = (error) => {
    console.error('Payment failed:', error);
    alert('Sorry, your payment could not be processed.');
  };

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ maxWidth: '960px', margin: '0 auto' }}>
        <h1>Checkout</h1>
        <CheckoutForm
          id="plink_xxxxxxxxxxxxxx" // Replace with your Payment Link ID
          mode="inline"
          onPaid={handlePaymentSuccess}
          onError={handlePaymentError}
        />
      </div>
    </PaymentProvider>
  );
}

Standalone Full-Page Checkout

Use mode="standalone" to render a dedicated, full-page checkout experience. This mode is ideal for redirecting the user to a separate URL to complete their payment without distractions.

CheckoutPage.jsx

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';

export default function CheckoutPage() {
  const { session, connectApi } = useSessionContext();

  // In a real application, you would get this ID from the URL parameters
  const paymentLinkId = 'plink_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <CheckoutForm
        id={paymentLinkId}
        mode="standalone"
        onPaid={() => {
          // Redirect to a success page
          window.location.href = '/payment-success';
        }}
      />
    </PaymentProvider>
  );
}

Donation Form

By setting formType="donation", the component renders a specialized UI tailored for donation campaigns. This form includes features such as amount presets and can display information about the benefits of donating.

DonationPage.jsx

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';

export default function DonationPage() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ padding: '2rem', textAlign: 'center' }}>
        <h2>Support Our Cause</h2>
        <CheckoutForm
          id="plink_yyyyyyyyyyyyyy" // Replace with your Donation Link ID
          formType="donation"
          onPaid={() => alert('Thank you for your generous donation!')}
        />
      </div>
    </PaymentProvider>
  );
}