@blocklet/payment-react/docs/getting-started.md

Reusable react components for payment kit v2

# Getting Started

This guide will walk you through the essential steps to install `@blocklet/payment-react` and integrate a basic, functional payment form into your application. In just a few minutes, you'll have a working checkout experience.

## Step 1: Installation

First, add the library to your project using npm or your preferred package manager.

```bash Installation Command icon=lucide:terminal
npm install @blocklet/payment-react
```

## Step 2: Set Up the PaymentProvider

Most components in this library require access to a shared payment context. The `PaymentProvider` component provides this context and must be placed at the root of your application or component tree where payments will be handled.

It requires a `session` object and a `connect` API function from your application's authentication context to work correctly.

```tsx App.tsx icon=logos:react
import { PaymentProvider } from '@blocklet/payment-react';
// This is a placeholder for your app's authentication context hook.
// It should return the current user session and an API connector.
import { useSessionContext } from './contexts/session'; 

function App({ children }) {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connect={connectApi}>
      {/* Your payment components will go here */}
      {children}
    </PaymentProvider>
  );
}
```

> For detailed information on setting up your session context and for advanced `PaymentProvider` configurations, please see the [PaymentProvider documentation](./providers-payment-provider.md).

## Step 3: Add a CheckoutForm

The `CheckoutForm` is the primary component for rendering a payment flow. It can handle both one-time payments and subscriptions initiated from a Payment Link.

To use it, simply place it inside the `PaymentProvider` and pass the required `id` of a Payment Link (`plink_...`) or a Checkout Session (`cs_...`).

## Complete Example

Here is a complete, minimal example that combines the steps above. You can use this code as a starting point for your integration.

```tsx PaymentPage.tsx icon=logos:react
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
// This is a placeholder for your app's authentication context hook.
import { useSessionContext } from './contexts/session'; 

function PaymentPage() {
  const { session, connectApi } = useSessionContext();

  // A Payment Link ID is generated from your Payment Kit dashboard.
  const paymentLinkId = 'plink_xxx'; 

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm 
        id={paymentLinkId}
        mode="inline" // Embeds the form directly into your page
        showCheckoutSummary={true}
        onChange={(state) => console.log('Checkout State Changed:', state)}
        onPaid={(result) => console.log('Payment Successful:', result)}
      />
    </PaymentProvider>
  );
}

export default PaymentPage;
```

With this setup, the `CheckoutForm` will render a complete payment UI, handle user input, and process the transaction seamlessly.

## Next Steps

Congratulations! You've successfully integrated your first payment form. Now you're ready to explore more advanced features and components.

- **[CheckoutForm](./components-checkout-checkout-form.md)**: Dive deeper into the `CheckoutForm` props and customization options.
- **[Providers](./providers.md)**: Learn more about the context providers that power the library.
- **[Components](./components.md)**: Discover the full range of UI and business logic components available.