@blocklet/payment-react 1.20.4 → 1.20.6

package/docs/components-checkout-checkout-form.md

@@ -1,185 +1,164 @@
 # 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 (starting with `plink_`) or a `checkoutSession` ID (starting with `cs_`) to initialize.
+The `CheckoutForm` component is the primary entry point for handling payment links and checkout sessions. It acts as a high-level wrapper that fetches all necessary data based on a provided ID and renders the appropriate payment or donation interface. This component is the simplest way to integrate a complete checkout flow into your application.
 
-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.
+It's essential to wrap `CheckoutForm` or any of its parent components with the `PaymentProvider` to ensure it has access to the necessary context, such as session information and API configuration. For more details, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
 
 ## 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 user interaction.
+The component orchestrates the entire checkout process:
 
-```d2
+1.  **Initialization**: It's mounted with a `paymentLink` ID (prefixed with `plink_`) or a `checkoutSession` ID (prefixed with `cs_`).
+2.  **Data Fetching**: It communicates with the payment backend to retrieve all necessary context, including payment methods, line items, and customer details.
+3.  **UI Rendering**: Based on the `formType` prop, it internally renders either the standard `Payment` component or the specialized `DonationForm` component.
+4.  **State Management**: It handles the entire lifecycle of the payment, including loading states, completion status, and error handling.
+
+```d2 Basic Flow of CheckoutForm icon=lucide:workflow
 direction: down
+shape: sequence_diagram
 
-A: "CheckoutForm Component Mounted"
-B: "Analyze 'id' prop prefix"
-C: "Call startFromPaymentLink API"
-D: "Call fetchCheckoutSession API"
-E: "Receive CheckoutContext"
-F: "Check 'formType' prop"
-G: "Render <Payment /> component"
-H: "Render <DonationForm /> component"
-I: "User completes payment flow"
-J: "Payment successful?"
-K: "Execute onPaid callback"
-L: "Execute onError callback"
-
-A -> B
-B -> C: "'plink_...'"
-B -> D: "'cs_...'"
-C -> E
-D -> E
-E -> F
-F -> G: "'payment' (default)"
-F -> H: "'donation'"
-G -> I
-H -> I
-I -> J
-J -> K: "Yes"
-J -> L: "No"
-```
+User-Action: {
+  shape: c4-person
+  label: "User"
+}
 
-## Props
+Application: {
+  label: "Your React Application"
 
-The `CheckoutForm` accepts the following props to customize its behavior and appearance.
-
-| Prop          | Type                                                                        | Description                                                                                                                                      |
-|---------------|-----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
-| `id`          | `string`                                                                    | **Required.** The unique identifier for the checkout. Must start with `plink_` for a Payment Link or `cs_` for a Checkout Session.               |
-| `mode`        | `'standalone' \| 'inline' \| 'popup' \| 'inline-minimal' \| 'popup-minimal'` | The display mode. Defaults to `'inline'`.                                                                                                          |
-| `formType`    | `'payment' \| 'donation'`                                                | The type of form to render. Use `'donation'` for a donation-specific UI. Defaults to `'payment'`.                                              |
-| `onPaid`      | `(res: CheckoutContext) => void`                                            | Callback function executed upon successful payment. It receives the final checkout context.                                                      |
-| `onError`     | `(err: Error) => void`                                                      | Callback function executed when an error occurs during the process.                                                                              |
-| `onChange`    | `(data: CheckoutFormData) => void`                                          | Optional. Callback executed when form data (e.g., selected currency) changes.                                                                  |
-| `goBack`      | `() => void`                                                                | Optional. A function to handle a "back" button action, useful in multi-step flows.                                                               |
-| `extraParams` | `Record<string, any>`                                                       | Optional. An object of extra parameters to be sent when initializing a session from a Payment Link.                                              |
-| `action`      | `string`                                                                    | Optional. A string to customize button text or other UI elements based on the action being performed (e.g., 'subscribe', 'donate').                |
-| `theme`       | `'default' \| 'inherit' \| object`                                          | The theme to apply. `'default'` uses the built-in theme, `'inherit'` uses the parent theme, and an object allows for custom Material-UI theme options. |
-| `formRender`  | `Record<string, any>`                                                       | Optional. Used with `formType='donation'` to inject custom render elements or callbacks, such as a custom cancel button.                         |
+  CheckoutForm-Component: {
+    label: "CheckoutForm"
+  }
 
-## Usage
+  Payment-Component: {
+    label: "Payment Component"
+  }
 
-### Prerequisite: Wrapping with PaymentProvider
+  Donation-Component: {
+    label: "DonationForm Component"
+  }
+}
 
-To use `CheckoutForm`, your application must be wrapped with the `PaymentProvider`. This provider is essential as it supplies the necessary context, including API configuration and session information, to all nested payment components.
+Payment-API: {
+  label: "Payment Backend API"
+  shape: cylinder
+}
 
-A common pattern is to integrate `PaymentProvider` with your application's existing session management. In the example below, `useSessionContext` is a placeholder for your own custom hook that provides the user session. This setup ensures that `CheckoutForm` has access to user data when needed.
+User-Action -> Application.CheckoutForm-Component: "1. Mounts with 'id' prop"
+Application.CheckoutForm-Component -> Payment-API: "2. Fetch session data"
+Payment-API -> Application.CheckoutForm-Component: "3. Return checkout context"
 
-For a complete guide on setting up the `PaymentProvider` and creating your `useSessionContext` hook, please refer to the [PaymentProvider documentation](./providers-payment-provider.md).
+alt "if formType is 'payment'" {
+  Application.CheckoutForm-Component -> Application.Payment-Component: "4. Renders Payment UI"
+}
 
-```tsx
-import { PaymentProvider } from '@blocklet/payment-react';
-import { CheckoutForm } from '@blocklet/payment-react';
-// This is a placeholder for your application's session context hook.
-// See the PaymentProvider documentation for implementation details.
-import { useSessionContext } from '../hooks/session-context';
+alt "if formType is 'donation'" {
+  Application.CheckoutForm-Component -> Application.Donation-Component: "5. Renders Donation UI"
+}
 
-// Your main application component
-function App() {
-  const { session, connectDid, disconnectDid } = useSessionContext();
+User-Action -> Application.Payment-Component: "6. Completes payment"
+User-Action -> Application.Donation-Component: "7. Completes donation"
 
-  return (
-    <PaymentProvider
-      apiHost="https://your-api-host"
-      // Pass session and connection handlers from your local context
-      session={session}
-      connect={connectDid}
-      disconnectDid={disconnectDid}>
-      <MyCheckoutPage />
-    </PaymentProvider>
-  );
-}
+```
 
-// A component that renders the checkout form
-function MyCheckoutPage() {
-  const { session } = useSessionContext();
-  const paymentLinkId = 'plink_xxxxxxxxxxxx';
+## Props
 
-  // Conditionally render based on user login status
-  if (!session?.user) {
-    return <p>Please log in to proceed with the payment.</p>;
-  }
+The `CheckoutForm` component accepts the following props:
+
+| Prop          | Type                                                                       | Required | Default       | Description                                                                                             |
+|---------------|----------------------------------------------------------------------------|----------|---------------|-------------------------------------------------------------------------------------------------------------------------|
+| `id`          | `string`                                                                   | Yes      | -             | The unique identifier for the payment link (`plink_...`) or checkout session (`cs_...`).                                |
+| `mode`        | `'standalone'` \| `'inline'` \| `'popup'` \| `'inline-minimal'` \| `'popup-minimal'` | No       | `'inline'`    | Defines the rendering mode. `'standalone'` for a full-page view, `'inline'` to embed in a container.                  |
+| `formType`    | `'payment'` \| `'donation'`                                                 | No       | `'payment'`   | Determines the type of form to render. Use `'donation'` for the specialized donation flow.                          |
+| `onPaid`      | `(res: CheckoutContext) => void`                                           | No       | -             | Callback function executed upon successful payment. Receives the final checkout context as an argument.               |
+| `onError`     | `(err: Error) => void`                                                     | No       | `console.error` | Callback function executed when an error occurs during the process.                                                   |
+| `onChange`    | `(data: CheckoutFormData) => void`                                         | No       | -             | Callback function that fires when any form field value changes.                                                         |
+| `goBack`      | `() => void`                                                               | No       | -             | If provided, renders a back button and calls this function when clicked.                                                |
+| `extraParams` | `Record<string, any>`                                                      | No       | `{}`          | An object of extra parameters to be passed in the URL when initiating a session from a payment link.                  |
+| `theme`       | `'default'` \| `'inherit'` \| `PaymentThemeOptions`                            | No       | `'default'`   | Controls the component's theme. `'inherit'` uses the parent theme, or you can pass a custom theme object.             |
+| `action`      | `string`                                                                   | No       | `''`          | A string identifier used for customizing UI elements like button text or tracking specific flows.                   |
 
-  return (
-    <CheckoutForm
-      id={paymentLinkId}
-      onPaid={() => console.log('Payment successful!')}
-      onError={(err) => console.error('Payment failed:', err)}
-    />
-  );
-}
-```
+## Usage
 
-### Standard Inline Payment
+### Basic Inline Payment Form
 
-This is the default behavior. The component renders directly where it's placed in the DOM, which is suitable for embedding the payment form within a product or pricing page.
+This is the most common use case for embedding a payment form directly within your application's UI. The component handles all the logic internally.
 
-```tsx
-import { CheckoutForm } from '@blocklet/payment-react';
+```tsx MyStorePage.tsx icon=lucide:shopping-cart
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session-context'; // Your app's session hook
+
+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.');
+  };
 
-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);
-        }}
-        onError={(err) => console.error('Payment failed:', err)}
-      />
-    </div>
+    <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 Checkout Page
+### Standalone Full-Page Checkout
 
-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.
+Use `mode="standalone"` to render a dedicated, full-page checkout experience. This is ideal for scenarios where you redirect the user to a separate page to complete their payment.
 
-```tsx
-import { CheckoutForm } from '@blocklet/payment-react';
+```tsx CheckoutPage.tsx icon=lucide:layout-template
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session-context';
+
+export default function CheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+  const paymentLinkId = 'plink_xxxxxxxxxxxxxx'; // Can be retrieved from URL params
 
-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}`;
-      }}
-      onError={(err) => console.error('Payment failed:', err)}
-    />
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <CheckoutForm id={paymentLinkId} mode="standalone" />
+    </PaymentProvider>
   );
 }
 ```
 
 ### Donation Form
 
-To render a UI optimized for donations, set `formType='donation'`. This changes the layout and terminology to better suit a donation flow.
+By setting `formType="donation"`, the component renders a specialized UI tailored for donation campaigns, including features like amount presets and benefit displays.
 
-```tsx
-import { CheckoutForm } from '@blocklet/payment-react';
+```tsx DonationPage.tsx icon=lucide:gift
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session-context';
 
 export default function DonationPage() {
+  const { session, connectApi } = useSessionContext();
+
   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>
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <div style={{ padding: '2rem' }}>
+        <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>
   );
 }
 ```
 
-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](./components-ui-payment-summary.md) component.

package/docs/components-checkout-checkout-table.md

@@ -1,152 +1,93 @@
 # CheckoutTable
 
-The `CheckoutTable` component provides a complete, out-of-the-box solution for displaying a pricing table and handling the entire checkout flow. It fetches pricing table data by ID, allows users to select a plan, and then either redirects them to a checkout page or renders an inline payment form.
+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.
 
-This component is a high-level abstraction that internally uses [`PricingTable`](./components-ui-pricing-table.md) for display and [`CheckoutForm`](./components-checkout-checkout-form.md) for payment processing, simplifying the integration of subscription or one-time payment flows.
+It internally uses the [`PricingTable`](./components-ui-pricing-table.md) component to display the plans and the [`CheckoutForm`](./components-checkout-checkout-form.md) component to process the payment.
 
-## How It Works
+## How it Works
 
-The component follows a clear, logical flow to guide the user from plan selection to payment completion.
+The checkout flow managed by `CheckoutTable` is straightforward:
 
-```d2
-direction: down
+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.
 
-CheckoutTable: {
-  label: "CheckoutTable Mounted with 'id'"
-  shape: step
-}
+```d2 CheckoutTable Flow Diagram
+direction: down
 
-FetchData: {
-  label: "Fetch Pricing Table Data"
-  shape: step
+User: {
+  shape: c4-person
 }
 
-DisplayPricing: {
-  label: "Display PricingTable"
-  shape: step
-}
+CheckoutTable-Component: {
+  label: "CheckoutTable Component"
+  shape: rectangle
 
-DisplayError: {
-  label: "Display Error Message"
-  shape: step
-  style: {
-    stroke: "#d32f2f"
+  Pricing-Table-View: {
+    label: "Pricing Table View"
   }
-}
-
-HandleSelect: {
-  label: "User selects a plan (handleSelect)"
-  shape: step
-}
 
-CreateSession: {
-  label: "Create Checkout Session via API"
-  shape: step
-}
-
-ModeCheck: {
-  label: "mode === 'standalone'?"
-  shape: diamond
-}
-
-Redirect: {
-  label: "Redirect to Checkout URL"
-  shape: step
-  style: {
-    fill: "#e8f5e9"
+  Checkout-Form-View: {
+    label: "Checkout Form View"
   }
 }
 
-UpdateHash: {
-  label: "Update URL hash with Session ID"
-  shape: step
+Payment-API: {
+  label: "Payment API"
+  shape: cylinder
 }
 
-RenderForm: {
-  label: "Render CheckoutForm"
-  shape: step
-}
+User -> CheckoutTable-Component.Pricing-Table-View: "1. Views plans"
+CheckoutTable-Component.Pricing-Table-View -> User: " "
+User -> CheckoutTable-Component.Pricing-Table-View: "2. Selects a plan"
+CheckoutTable-Component.Pricing-Table-View -> Payment-API: "3. Create checkout session"
+Payment-API -> CheckoutTable-Component.Pricing-Table-View: "4. Return session ID"
+CheckoutTable-Component.Pricing-Table-View -> CheckoutTable-Component.Checkout-Form-View: "5. Transition with session ID"
+User -> CheckoutTable-Component.Checkout-Form-View: "6. Fills payment details & pays"
+CheckoutTable-Component.Checkout-Form-View -> User: ""
 
-OnPaid: {
-  label: "onPaid() callback"
-  shape: step
-  style: {
-    fill: "#e8f5e9"
-  }
-}
-
-OnError: {
-  label: "onError() callback"
-  shape: step
-  style: {
-    stroke: "#d32f2f"
-  }
-}
-
-ToastError: {
-  label: "Show Toast Error"
-  shape: step
-  style: {
-    stroke: "#d32f2f"
-  }
-}
-
-CheckoutTable -> FetchData
-FetchData -> DisplayPricing: "Success"
-FetchData -> DisplayError: "Error"
-DisplayPricing -> HandleSelect
-HandleSelect -> CreateSession
-CreateSession -> ModeCheck: "Success"
-CreateSession -> ToastError: "Error"
-ModeCheck -> Redirect: "Yes"
-ModeCheck -> UpdateHash: "No (Embedded)"
-UpdateHash -> RenderForm
-RenderForm -> OnPaid: "Payment Success"
-RenderForm -> OnError: "Payment Error"
 ```
 
 ## Props
 
-The `CheckoutTable` component requires a `PaymentProvider` to be present in the component tree. For more details, refer to the [`PaymentProvider`](./providers-payment-provider.md) documentation.
-
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `id` | `string` | Yes | The ID of the pricing table to display. This must start with `prctbl_`. |
-| `mode` | `'standalone' \| 'embedded'` | No | Determines the checkout behavior. In `'standalone'` mode, the user is redirected to a separate checkout page. In `'embedded'` mode (default), the `CheckoutForm` is rendered inline, replacing the pricing table. |
-| `onPaid` | `(data: TCheckout) => void` | No | Callback function executed when the payment is successfully completed. It receives the final checkout session data. |
-| `onError` | `(err: Error) => void` | No | Callback function executed if an error occurs during the payment process. |
-| `onChange` | `(session: TCheckout) => void` | No | Callback function executed whenever the checkout session state changes (e.g., from `pending` to `processing`). |
-| `extraParams` | `object` | No | An object containing extra query parameters to be sent when creating the checkout session. |
-| `goBack` | `() => void` | No | A function that is called when the user clicks the "back" button on the `CheckoutForm`. This enables navigation back to the pricing table view in embedded mode. |
-| `theme` | `object \| 'inherit'` | No | A custom Material-UI theme object to style the component. Set to `'inherit'` to use the ambient theme without an additional `ThemeProvider`. |
-
-## Usage Scenarios
-
-`CheckoutTable` can be configured for two primary user experiences: a full-page redirect or a seamless embedded flow.
-
-> **Note on Context:** The following examples assume you have set up a session context in your application. The `PaymentProvider` relies on this context to get authentication and API details. For a complete guide on this setup, please see the [`PaymentProvider`](./providers-payment-provider.md) documentation.
+| 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](./guides-theming.md).                        |
 
-### Standalone Mode
+## Usage
 
-In `standalone` mode, the component handles plan selection and then redirects the user to a dedicated, hosted checkout page. This is the simplest way to integrate.
+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.
 
-```jsx
-import { CheckoutTable, PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from '../contexts/session'; // Path to your custom session context hook
+```javascript Basic CheckoutTable Example icon=logos:react
+import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
+import { useSessionContext } from './path-to-your-session-context'; // Centralize this context as per guidelines
 
-function MyPaymentPage() {
+export default function MyCheckoutPage() {
   const { session, connectApi } = useSessionContext();
 
-  if (!session.user) {
-    return <p>Please log in to see pricing.</p>;
+  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} connect={connectApi}>
-      <div style={{ height: '600px', width: '100%' }}>
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <div style={{ height: '700px', width: '100%' }}>
         <CheckoutTable
-          id="prctbl_xxxxxxxxxxxx" // Replace with your actual pricing table ID
-          mode="standalone"
+          id="prctbl_xxxxxxxxxxxxxxxx" // Replace with your actual pricing table ID
+          onPaid={handlePaymentSuccess}
         />
       </div>
     </PaymentProvider>
@@ -154,75 +95,54 @@ function MyPaymentPage() {
 }
 ```
 
-When a user clicks a subscription button in the pricing table, `window.location.replace` is called to navigate them to the checkout URL provided by the payment service API.
+## Modes of Operation
 
-### Embedded Mode
+### Embedded Mode (Default)
 
-In `embedded` mode (the default behavior), the entire checkout process happens within your application. After a plan is selected, the pricing table is replaced by the `CheckoutForm` component.
+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.
 
-This mode relies on the URL hash (`#`) to store and retrieve the checkout session ID, enabling a smooth, single-page application experience.
-
-```jsx
-import { CheckoutTable, PaymentProvider } from '@blocklet/payment-react';
-import { useSessionContext } from '../contexts/session'; // Path to your custom session context hook
-import type { TCheckout } from '@blocklet/payment-types';
-
-function MyEmbeddedCheckout() {
-  const { session, connectApi } = useSessionContext();
-
-  const handlePaymentSuccess = (checkoutData: TCheckout) => {
-    console.log('Payment successful!', checkoutData);
-    alert('Thank you for your payment!');
-  };
-
-  const handlePaymentError = (error: Error) => {
-    console.error('Payment failed:', error);
-    alert('There was an issue with your payment.');
-  };
-
-  const handleGoBack = () => {
-    // The component handles clearing the URL hash internally.
-    // You can add custom logic here if needed.
-    console.log('User returned to the pricing table view.');
-  };
+### Standalone Mode
 
-  if (!session.user) {
-    return <p>Please log in to see pricing.</p>;
-  }
+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.
 
-  return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <div style={{ height: '800px', width: '100%' }}>
-        <CheckoutTable
-          id="prctbl_xxxxxxxxxxxx" // Replace with your actual pricing table ID
-          onPaid={handlePaymentSuccess}
-          onError={handlePaymentError}
-          goBack={handleGoBack}
-        />
-      </div>
-    </PaymentProvider>
-  );
-}
+```javascript Standalone Mode icon=logos:react
+<CheckoutTable
+  id="prctbl_xxxxxxxxxxxxxxxx"
+  mode="standalone"
+/>
 ```
 
-In this example:
-- The `onPaid` and `onError` callbacks are used to handle the final state of the transaction.
-- The `goBack` prop enables a back button on the payment form, allowing users to return to the plan selection screen without losing context.
+## Advanced Usage
 
-## `CheckoutTable` vs. `PricingTable`
+### Handling Back Navigation
 
-It's important to understand the difference between `CheckoutTable` and the lower-level `PricingTable` component to choose the right one for your needs.
+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.
 
-#### CheckoutTable
+```javascript goBack Prop Example icon=logos:react
+const handleGoBack = () => {
+  console.log('User returned to the pricing table.');
+  // You can add custom logic here, like updating your app's state.
+};
 
-A high-level, all-in-one component that manages the entire checkout flow. It handles data fetching, plan selection, and payment form rendering.
+<CheckoutTable
+  id="prctbl_xxxxxxxxxxxxxxxx"
+  onPaid={handlePaymentSuccess}
+  goBack={handleGoBack}
+/>
+```
 
-**Use when:** You need a complete, ready-to-use pricing and checkout solution with minimal configuration.
+### Passing Extra Parameters
 
-#### PricingTable
+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.
 
-A low-level, presentational component that only displays pricing data passed to it. It does not manage state or handle the checkout process.
+```javascript extraParams Example icon=logos:react
+<CheckoutTable
+  id="prctbl_xxxxxxxxxxxxxxxx"
+  onPaid={handlePaymentSuccess}
+  extraParams={{ userId: 'user_123', source: 'marketing_campaign' }}
+/>
+```
 
-**Use when:** You need to build a custom checkout flow or display pricing plans in a non-checkout context.
+## Customization
 
-For most use cases, **`CheckoutTable` is the recommended starting point** as it provides a complete and integrated experience. If you find you need more granular control over the user flow, you can then use `PricingTable` and `CheckoutForm` as separate building blocks.
+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`](./components-ui-pricing-table.md) component to display plans and then manually trigger a checkout session that renders in a [`CheckoutForm`](./components-checkout-checkout-form.md).