Checkout Components
Checkout components are high-level, pre-built components designed to serve as complete entry points for various payment flows. They encapsulate the entire user experience, from presenting payment options to processing transactions and handling success or error states. This allows you to integrate complex payment scenarios like one-time payments, subscriptions from a pricing table, or donations with minimal setup.
These components act as orchestrators for the payment process, as illustrated below:
This section provides an overview of the primary checkout components. For detailed API references and advanced usage, please refer to the specific documentation for each component.
CheckoutForm#
The CheckoutForm is the core component for processing payments. It is designed to handle transactions initiated from a paymentLink (plink_...) or an existing checkoutSession (cs_...). It manages the entire payment UI, including payment method selection, form inputs, and submission.
It is the final step in most payment flows and is used internally by other checkout components like CheckoutTable and CheckoutDonate.
Key Features:
- Handles both one-time and recurring payments.
- Supports multiple display modes (
inline,standalone). - Manages payment state, including completion and error handling.
Basic Usage:
import { CheckoutForm } from '@blocklet/payment-react';
import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
function MyPaymentPage() {
const checkoutSessionId = 'cs_xxxxxxxxxxxx'; // Or a paymentLink id 'plink_...'
return (
<PaymentProvider endpoint="YOUR_API_ENDPOINT">
<CheckoutForm
id={checkoutSessionId}
mode="inline"
onPaid={(context) => console.log('Payment successful!', context)}
onError={(error) => console.error('Payment failed:', error)}
/>
</PaymentProvider>
);
}For a complete guide on its properties and capabilities, see the CheckoutForm documentation.
CheckoutTable#
The CheckoutTable component renders a complete pricing table and manages the subsequent checkout process. When a user selects a pricing plan, the component automatically creates a checkout session and transitions to the CheckoutForm to finalize the payment.
This is the ideal component for integrating subscription-based services with a single, self-contained UI element.
Key Features:
- Fetches and displays pricing table data by ID.
- Handles plan and currency selection.
- Seamlessly integrates
PricingTableandCheckoutFormfor a full subscription workflow.
Basic Usage:
import { CheckoutTable } from '@blocklet/payment-react';
import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
function MyPricingPage() {
const pricingTableId = 'prctbl_xxxxxxxxxxxx';
return (
<PaymentProvider endpoint="YOUR_API_ENDPOINT">
<CheckoutTable
id={pricingTableId}
onPaid={(context) => console.log('Subscription started!', context)}
/>
</PaymentProvider>
);
}To learn more about configuration and customization, visit the CheckoutTable documentation.
CheckoutDonate#
The CheckoutDonate component provides a flexible way to implement donation functionality. It supports various display modes, from a simple button to a fully customized UI, and handles creating the donation link, displaying supporter history, and opening a payment dialog.
Key Features:
- Multiple rendering modes:
default(button and supporter list),inline(popover), andcustom(render prop). - Automatically fetches and displays donation history (supporters).
- Manages donation settings such as preset amounts, title, and description.
- Uses
CheckoutFormwithin a modal for the payment process.
Basic Usage:
import { CheckoutDonate } from '@blocklet/payment-react';
import { PaymentProvider } from '@blocklet/payment-react/lib/contexts/payment';
import { DonateProvider } from '@blocklet/payment-react/lib/contexts/donate';
function SupportOurProject() {
const donationSettings = {
target: 'project_alpha',
title: 'Support Project Alpha',
description: 'Your contribution helps us build great things.',
beneficiaries: [{ did: 'z2qa...', weight: 100 }],
amount: {
presets: ['5', '10', '25'],
custom: true,
},
};
return (
<PaymentProvider endpoint="YOUR_API_ENDPOINT">
<DonateProvider>
<CheckoutDonate
settings={donationSettings}
onPaid={() => console.log('Donation received!')}
/>
</DonateProvider>
</PaymentProvider>
);
}For advanced customization and render prop usage, please see the CheckoutDonate documentation.
These components provide powerful, out-of-the-box solutions for common payment scenarios. To build more customized payment experiences, you can explore the lower-level UI Components.