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.

  • CheckoutForm: Dive deeper into the CheckoutForm props and customization options.
  • Providers: Learn more about the context providers that power the library.
  • Components: Discover the full range of UI and business logic components available.
Overview
Providers