CheckoutForm
The CheckoutForm component is the primary entry point for rendering a complete payment or donation flow. It orchestrates the entire checkout process by fetching session details and rendering the appropriate user interface based on the provided configuration. It requires a paymentLink ID or a checkoutSession ID to initialize.
This component is highly flexible and can be rendered in several modes, including as an inline element, a standalone full-page experience, or a popup modal.
How It Works#
The CheckoutForm component follows a clear internal logic to manage the checkout process. It starts by identifying the type of ID provided, fetches the necessary data, and then renders the appropriate form (Payment or DonationForm) to handle the user interaction.
Props#
The CheckoutForm accepts the following props to customize its behavior and appearance.
Prop | Type | Description |
|---|---|---|
|
| Required. The unique identifier for the checkout. Must start with |
|
| The display mode. Can be |
|
| The type of form to render. Use |
|
| Callback function executed upon successful payment. It receives the final checkout context. |
|
| Callback function executed when an error occurs during the process. |
|
| Optional. Callback executed when form data (e.g., selected currency) changes. |
|
| Optional. A function to handle a "back" button action, useful in multi-step flows. |
|
| Optional. An object of extra parameters to be sent when initializing a session from a Payment Link. |
|
| Optional. A string to customize button text or other UI elements based on the action being performed (e.g., 'subscribe', 'donate'). |
|
| The theme to apply. |
Usage#
Prerequisite: Wrapping with PaymentProvider#
To use CheckoutForm, your application must be wrapped with the PaymentProvider. This provider supplies the necessary context, including session information and configuration.
import { PaymentProvider } from '@blocklet/payment-react';
import CheckoutForm from '@blocklet/payment-react/lib/CheckoutForm';
function App() {
return (
<PaymentProvider apiHost="https://your-api-host">
<MyCheckoutPage />
</PaymentProvider>
);
}
function MyCheckoutPage() {
const paymentLinkId = 'plink_xxxxxxxxxxxx';
return (
<CheckoutForm
id={paymentLinkId}
onPaid={() => console.log('Payment successful!')}
onError={(err) => console.error('Payment failed:', err)}
/>
);
}Standard Inline Payment#
This is the default behavior. The component renders directly where it's placed in the DOM. This is suitable for embedding the payment form within a product or pricing page.
import { CheckoutForm } from '@blocklet/payment-react';
export default function InlinePayment() {
return (
<div>
<h2>Complete Your Purchase</h2>
<CheckoutForm
id="plink_xxxxxxxxxxxx"
mode="inline"
onPaid={(data) => {
console.log('Payment successful:', data.checkoutSession.id);
}}
/>
</div>
);
}Standalone Checkout Page#
By setting mode='standalone', the component will render a full-page checkout experience, including a header and footer. This is ideal for redirecting users to a dedicated payment page.
import { CheckoutForm } from '@blocklet/payment-react';
export default function StandaloneCheckoutPage() {
return (
<CheckoutForm
id="cs_xxxxxxxxxxxx"
mode="standalone"
onPaid={(data) => {
// Redirect to a success page
window.location.href = `/payment-success?session_id=${data.checkoutSession.id}`;
}}
/>
);
}Donation Form#
To render a UI optimized for donations, set formType='donation'. This changes the layout and terminology to better suit a donation flow.
import { CheckoutForm } from '@blocklet/payment-react';
export default function DonationPage() {
return (
<div>
<h2>Support Our Cause</h2>
<CheckoutForm
id="plink_donation_xxxxxxxx"
formType="donation"
onPaid={(data) => {
console.log(`Thank you for your donation! Invoice ID: ${data.checkoutSession.invoice_id}`);
}}
onError={(err) => {
console.error('Donation failed:', err);
}}
/>
</div>
);
}After integrating the checkout form, you may want to display a summary of the items being purchased. To learn more, see the documentation for the PaymentSummary component.