CheckoutTable

The CheckoutTable component provides a complete, out-of-the-box solution for subscription checkouts. It fetches and renders a pricing table, allows users to select a plan, and then seamlessly transitions them to a payment form to complete the purchase. This high-level component is the fastest way to integrate a plan-based payment flow into your application.

It internally uses the PricingTable component to display the plans and the CheckoutForm component to process the payment.

How it Works#

The checkout flow managed by CheckoutTable is straightforward:

1. Fetch Data: The component fetches the pricing table configuration from the server using the provided id.
2. Display Plans: It renders the subscription plans in a responsive table, allowing users to switch between billing intervals (e.g., monthly/yearly) and currencies.
3. Create Session: When a user selects a plan, the component communicates with the backend to create a secure checkout session.
4. Process Payment: It then displays the CheckoutForm, pre-filled with the session details, allowing the user to enter their payment information and finalize the transaction.

Props#

Prop	Type	Required	Default	Description
id	string	Yes	-	The ID of the pricing table to display (must start with prctbl_).
mode	'standalone' or 'embedded'	No	'embedded'	The display mode. 'standalone' redirects to a separate page, while 'embedded' handles the flow inline within the component.
onPaid	(sessionId: string) => void	No	-	Callback function triggered when the payment is successfully completed.
onError	(error: Error) => void	No	-	Callback function for handling errors during the checkout process.
onChange	(data: any) => void	No	-	Callback for any state change within the checkout form.
extraParams	Record<string, any>	No	{}	An object of extra parameters to be sent when creating the checkout session, useful for passing custom data like a user ID.
goBack	() => void	No	-	A function to handle the back action from the payment form, returning the user to the pricing table view.
theme	object or 'inherit'	No	-	Custom Material-UI theme object to style the component. For more details, see the Theming guide.

Usage#

To use the CheckoutTable component, you must wrap it in a PaymentProvider. Pass the pricing table id and an onPaid callback to handle successful transactions.

import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
import { useSessionContext } from './path-to-your-session-context'; // Centralize this context as per guidelines

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

  const handlePaymentSuccess = (sessionId) => {
    console.log(`Payment successful for session: ${sessionId}`);
    alert('Thank you for your subscription!');
  };

  if (!session) {
    return <div>Loading session...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ height: '700px', width: '100%' }}>
        <CheckoutTable
          id="prctbl_xxxxxxxxxxxxxxxx" // Replace with your actual pricing table ID
          onPaid={handlePaymentSuccess}
        />
      </div>
    </PaymentProvider>
  );

Modes of Operation#

Embedded Mode (Default)#

By default, CheckoutTable operates in 'embedded' mode. The component manages the entire flow inline, transitioning from the pricing table view to the payment form within its own container. This is ideal for single-page applications where you want the checkout to feel like an integrated part of the page.

Standalone Mode#

By setting mode='standalone', the component's behavior changes. When a user selects a plan, they are redirected to a dedicated, hosted checkout page. This mode is useful for simpler integrations that don't require an embedded payment form.

<CheckoutTable
  id="prctbl_xxxxxxxxxxxxxxxx"
  mode="standalone"
/>

Advanced Usage#

Handling Back Navigation#

The goBack prop allows you to define custom logic when the user navigates back from the payment form to the pricing table. The component handles the view transition automatically, but this callback is useful for synchronizing your application's state.

const handleGoBack = () => {
  console.log('User returned to the pricing table.');
  // You can add custom logic here, like updating your app's state.
};

<CheckoutTable
  id="prctbl_xxxxxxxxxxxxxxxx"
  onPaid={handlePaymentSuccess}
  goBack={handleGoBack}
/>

Passing Extra Parameters#

Use the extraParams prop to send additional data when creating the checkout session. This data can be associated with the resulting payment and is useful for tracking and reconciliation on your backend.

<CheckoutTable
  id="prctbl_xxxxxxxxxxxxxxxx"
  onPaid={handlePaymentSuccess}
  extraParams={{ userId: 'user_123', source: 'marketing_campaign' }}
/>

Customization#

While CheckoutTable is a high-level component designed for ease of use, you can achieve more granular control by using its constituent parts. For a fully custom UI, you can use the PricingTable component to display plans and then manually trigger a checkout session that renders in a CheckoutForm.