Providers

PaymentProvider

The PaymentProvider is the cornerstone of the @blocklet/payment-react library. It's a context provider that must wrap your application or the specific sections that utilize payment components. It initializes the payment context, fetches necessary settings, and makes payment functions and data available to all its child components.
Any component from this library, such as CheckoutForm or CustomerInvoiceList, needs to be nested within a PaymentProvider to function correctly.
Your React App
PaymentProvider
CheckoutForm
CustomerInvoiceList
Component with usePaymentContext()

Props#The PaymentProvider accepts the following props to configure the payment environment.
Prop
Type
Required
Description
session
SessionContext['session']
Yes
The user session object from your authentication system (e.g., @arcblock/did-connect-react). It contains essential user data like their DID.
connect
SessionContext['connectApi']
Yes
The connect API instance from your authentication system, used for handling DID Connect interactions.
children
any
Yes
The React components or part of your application tree that needs access to the payment context.
baseUrl
string
No
The base URL of the Payment Kit blocklet. This is only necessary if your application and the Payment Kit are running on different origins. The provider uses this URL to fetch configuration for cross-origin API requests.
authToken
string
No
An optional authentication token. If provided, it will be used for API requests, overriding the default token from the session.
Basic Integration#To get started, wrap your main application component or the relevant layout with PaymentProvider, passing the required session and connect props.
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';

// Assume `session` and `connectApi` are obtained from your app's authentication context

function App({ session, connectApi }) {
  if (!session.user) {
    // Render a login button or a loading state
    return <button onClick={() => connectApi.open()}>Login</button>;
  }

  return (
    <PaymentProvider session={session} connect={connectApi}>
      {/* All child components now have access to the payment context */}
      <h1>My Store</h1>
      <CheckoutForm 
        id="plink_xxx" // A valid Payment Link ID
        mode="inline"
      />
    </PaymentProvider>
  );
}Advanced Usage#Cross-Origin Communication with baseUrl#If your payment blocklet is hosted on a different domain than your main application (e.g., payments.example.com vs app.example.com), you must provide the baseUrl prop. The PaymentProvider will use this URL to correctly resolve API endpoints.
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function MyAccountPage({ session, connectApi }) {
  const paymentKitBaseUrl = 'https://your-payment-blocklet-domain.com';

  return (
    <PaymentProvider 
      session={session} 
      connect={connectApi} 
      baseUrl={paymentKitBaseUrl}
    >
      <h2>My Invoice History</h2>
      <CustomerInvoiceList />
    </PaymentProvider>
  );
}Using a Custom authToken#In scenarios where you need to use a specific API token instead of relying on the user's session, you can pass the authToken prop.
import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';

function SubscriptionManager({ session, connectApi, temporaryAuthToken }) {
  return (
    <PaymentProvider 
      session={session} 
      connect={connectApi} 
      authToken={temporaryAuthToken}
    >
      <ResumeSubscription subscriptionId="sub_xxx" />
    </PaymentProvider>
  );
}Accessing Context Data#Child components can access the data and functions provided by PaymentProvider using the usePaymentContext hook.
The context provides access to:
settings: Contains available paymentMethods and the baseCurrency.
livemode: A boolean indicating if the environment is in live or test mode.
api: A pre-configured Axios instance for making authenticated requests to the Payment Kit API.
refresh: A function to manually trigger a refresh of the settings data.
And more...
Example: Using usePaymentContext#Here is an example of a component that uses the hook to display the current mode and a list of available payment methods.
import { usePaymentContext } from '@blocklet/payment-react';
import { Chip, List, ListItem, ListItemText, Typography } from '@mui/material';

function PaymentInfo() {
  const { settings, livemode, refresh } = usePaymentContext();

  return (
    <div>
      <Typography variant="h6">
        Payment Status {
          livemode ? 
          <Chip label="Live Mode" color="success" size="small" /> : 
          <Chip label="Test Mode" color="warning" size="small" />
        }
      </Typography>
      
      <Typography>Available Payment Methods:</Typography>
      <List>
        {settings.paymentMethods.map(method => (
          <ListItem key={method.id}>
            <ListItemText primary={method.name} />
          </ListItem>
        ))}
      </List>
      
      <button onClick={() => refresh()}>Refresh Settings</button>
    </div>
  );
}

// This component must be rendered inside a <PaymentProvider>
function App({ session, connectApi }) {
  return (
    <PaymentProvider session={session} connect={connectApi}>
      <PaymentInfo />
    </PaymentProvider>
  );
}With PaymentProvider set up, you are ready to integrate other components. A good next step is to implement a donation flow using the DonateProvider.

Overview

Getting Started

Providers

Components

Guides

Hooks

PaymentProvider

Props#

Basic Integration#

Advanced Usage#

Cross-Origin Communication with `baseUrl`#

Using a Custom `authToken`#

Accessing Context Data#

Example: Using `usePaymentContext`#

Providers

DonateProvider

Prop	Type	Required	Description
`session`	`SessionContext['session']`	Yes	The user session object from your authentication system (e.g., `@arcblock/did-connect-react`). It contains essential user data like their DID.
`connect`	`SessionContext['connectApi']`	Yes	The connect API instance from your authentication system, used for handling DID Connect interactions.
`children`	`any`	Yes	The React components or part of your application tree that needs access to the payment context.
`baseUrl`	`string`	No	The base URL of the Payment Kit blocklet. This is only necessary if your application and the Payment Kit are running on different origins. The provider uses this URL to fetch configuration for cross-origin API requests.
`authToken`	`string`	No	An optional authentication token. If provided, it will be used for API requests, overriding the default token from the session.