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.

Installation Command

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.

App.tsx

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.

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.

PaymentPage.tsx

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.