@blocklet/payment-react 1.20.5 → 1.20.7

package/docs/providers-donate-provider.md

@@ -1,78 +1,74 @@
 # DonateProvider
 
-The `DonateProvider` is a context provider that manages the state and settings for donation-related components, such as `CheckoutDonate`. It handles fetching donation configurations, updating settings, and providing this data to its children components. To function correctly, `DonateProvider` must be placed within a [`PaymentProvider`](./providers-payment-provider.md).
+The `DonateProvider` is a crucial context provider that manages the state and settings for all donation-related components within your application. It handles fetching configuration from the backend, caching it for performance, and providing it to components like `CheckoutDonate`.
 
-```d2
-direction: down
+To use any donation features, you must wrap your components with `DonateProvider`. This provider must also be nested within a [`PaymentProvider`](./providers-payment-provider.md) to ensure access to the necessary payment context and session information.
 
-"PaymentProvider": {
-  shape: package
+## How It Works
 
-  "DonateProvider": {
-    shape: package
+The `DonateProvider` performs several key functions:
 
-    "CheckoutDonate": {
-      shape: document
-      label: "CheckoutDonate Component"
-    }
-  }
-}
-
-"PaymentProvider" -> "DonateProvider" -> "CheckoutDonate": "Provides Context"
-```
-
-This structure ensures that donation components have access to both the general payment context and the specific donation settings.
+1.  **Fetches Settings**: On mount, it calls an API endpoint to retrieve the donation settings associated with the unique `mountLocation` prop. These settings determine the behavior of child donation components.
+2.  **Caches Data**: To improve performance and reduce network requests, the fetched settings are stored in `localStorage`. The cache is automatically used on subsequent loads and can be manually cleared if needed.
+3.  **Provides Context**: It uses React's Context API to pass down the settings and control functions (`refresh`, `updateSettings`) to any descendant component that needs them.
+4.  **Enables Donations**: For administrative users ('owner' or 'admin'), if the donation instance is inactive but the `enableDonate` prop is set, the provider will render a UI to activate it.
 
 ## Props
 
 The `DonateProvider` accepts the following props to configure its behavior:
 
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `mountLocation` | `string` | Yes | A unique identifier for this specific donation instance. It's used to fetch and store settings, ensuring that different donation points in your application have their own configurations. |
-| `description` | `string` | Yes | A description to help identify this donation instance in logs or admin interfaces. |
-| `defaultSettings` | `DonateConfigSettings` | No | An object with default settings for the donation component. These settings are used when no configuration has been saved for the given `mountLocation`. |
-| `children` | `any` | Yes | The child components that will be rendered within the provider. Typically, this will include one or more `CheckoutDonate` components. |
-| `active` | `boolean` | No | A flag to control whether the donation functionality is active. Defaults to `true`. |
-| `enableDonate` | `boolean` | No | If set to `true`, it allows administrators to enable a disabled donation instance directly from the UI. Defaults to `false`. |
-
-### DonateConfigSettings
-
-The `defaultSettings` prop accepts an object with the following structure:
-
-| Key | Type | Description |
-|---|---|---|
-| `amount` | `object` | Configuration for donation amounts. Contains `presets` (array of strings), `preset` (string), `custom` (boolean), `minimum` (string), and `maximum` (string). |
-| `btnText` | `string` | Custom text for the main donation button (e.g., "Like", "Support"). |
-| `historyType` | `'table' \| 'avatar'` | Defines the display style for the donation history. |
+| Prop              | Type                               | Required | Description                                                                                                                              |
+| ----------------- | ---------------------------------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `mountLocation`   | `string`                           |   Yes    | A unique string identifier for this specific donation instance. This is used as the key for fetching, caching, and updating settings.        |
+| `description`     | `string`                           |   Yes    | A human-readable description to help identify this donation instance in the system backend or logs.                                      |
+| `children`        | `ReactNode`                        |   Yes    | The child components that will render inside the provider, typically including `CheckoutDonate`.                                       |
+| `defaultSettings` | `DonateConfigSettings`             |    No    | An object with default settings to apply if no settings are found on the backend. See the type definition below for available options. |
+| `active`          | `boolean`                          |    No    | Sets the initial active state for the donation instance when it's first created. Defaults to `true`.                                   |
+| `enableDonate`    | `boolean`                          |    No    | If `true`, allows admin users to enable this donation instance from the UI if it's currently inactive. Defaults to `false`.               |
+
+### DonateConfigSettings Type
+
+This is the shape of the `defaultSettings` object:
+
+```typescript DonateConfigSettings type
+export interface DonateConfigSettings {
+  amount?: {
+    presets?: string[]; // e.g., ['1', '5', '10']
+    preset?: string; // Default selected preset amount
+    custom: boolean; // Allow users to enter a custom amount
+    minimum?: string; // Minimum custom amount
+    maximum?: string; // Maximum custom amount
+  };
+  btnText?: string; // Text for the main donation button, e.g., "Donate"
+  historyType?: 'table' | 'avatar'; // How to display the list of supporters
+}
+```
 
 ## Usage Example
 
-Here is a complete example of how to set up `DonateProvider` to wrap a `CheckoutDonate` component. This setup ensures that the donation button has access to the necessary context from both providers.
+Here is a complete example of setting up a donation section on a page. It shows how to wrap `CheckoutDonate` with both `DonateProvider` and `PaymentProvider`.
 
-```tsx
+```tsx App.tsx icon=logos:react
 import {
   PaymentProvider,
   DonateProvider,
   CheckoutDonate,
 } from '@blocklet/payment-react';
-// This is a custom hook to get session context from your application.
-// See the PaymentProvider documentation for more on session setup.
-import { useSessionContext } from '../hooks/use-session-context';
+import { useSessionContext } from './hooks/use-session'; // Your custom session hook
 
 function DonationSection() {
   const { session, connectApi } = useSessionContext();
 
-  // Render a loading state or null until the session is available
-  if (!session) {
-    return <div>Loading session...</div>;
+  // Render nothing or a login prompt if the user is not authenticated
+  if (!session?.user) {
+    return <div>Please log in to make a donation.</div>;
   }
 
   return (
     <PaymentProvider session={session} connect={connectApi}>
       <DonateProvider
-        mountLocation="unique-blog-post-123"
-        description="Donation button for the blog post about React Hooks"
+        mountLocation="support-our-blog-post-123"
+        description="Donation for the article 'Getting Started with React'"
         defaultSettings={{
           btnText: 'Support the Author',
           amount: {
@@ -83,13 +79,13 @@ function DonationSection() {
         }}>
         <CheckoutDonate
           settings={{
-            target: 'post-123',
-            title: 'Support Author',
-            description: 'If you find this article helpful, feel free to buy me a coffee',
+            target: 'post-123', // A unique identifier for the donation target
+            title: 'Support the Author',
+            description: 'If you found this article helpful, feel free to buy me a coffee.',
             reference: 'https://your-site.com/posts/123',
             beneficiaries: [
               {
-                address: 'user-did-address',
+                address: 'z8iZ75n8fWJ2aL1c9a9f4c3b2e1a0d9f8e7d6c5b4a392817',
                 share: '100',
               },
             ],
@@ -101,75 +97,57 @@ function DonationSection() {
 }
 ```
 
-## Using the Context
-
-You can access the donation context's state and functions using the `useDonateContext` hook. This is useful for building custom UI or logic that interacts with the donation settings.
-
-### Context Values
+## Hooks and Utilities
 
-The `useDonateContext` hook returns an object with the following properties:
+The library also exports several helper functions for advanced control over the donation context and cache.
 
-| Key | Type | Description |
-|---|---|---|
-| `settings` | `TSetting` | An object containing the current settings for the donation instance, including its active status and configuration. |
-| `refresh` | `(forceRefresh?: boolean) => void` | A function to manually trigger a refresh of the donation settings from the server. Pass `true` to bypass the cache. |
-| `updateSettings` | `(newSettings: DonateConfigSettings) => Promise<void>` | An async function to update and persist new settings for the donation instance. |
-| `api` | `Axios` | An Axios instance configured for making requests to the payment API. |
+### `useDonateContext`
 
-### Example
+A React hook to access the donation context directly from any child component of `DonateProvider`.
 
 ```tsx
 import { useDonateContext } from '@blocklet/payment-react';
-import { Button, Typography } from '@mui/material';
-
-function CustomDonateUI() {
-  const { settings, refresh, updateSettings } = useDonateContext();
-
-  const handleUpdateBtnText = async () => {
-    try {
-      await updateSettings({ btnText: 'New Button Text!' });
-      // The settings will be automatically refreshed after update.
-    } catch (error) {
-      console.error('Failed to update settings:', error);
-    }
-  };
+
+function CustomDonationInfo() {
+  const { settings, refresh } = useDonateContext();
 
   return (
     <div>
-      <Typography>Current Button Text: {settings.settings?.btnText}</Typography>
-      <Button onClick={handleUpdateBtnText}>Change Text</Button>
-      <Button onClick={() => refresh(true)}>Force Refresh</Button>
+      <p>Donations are currently {settings.active ? 'enabled' : 'disabled'}.</p>
+      <button onClick={() => refresh(true)}>Refresh Settings</button>
     </div>
   );
 }
 ```
 
-## Utility Functions
-
-The library also exports utility functions to manage the donation settings cache outside of the React component lifecycle.
+### `clearDonateCache`
 
-### clearDonateCache
+This function manually removes the cached settings for a specific `mountLocation` from `localStorage`. This is useful when you know the settings have changed on the server and you want to force a fresh fetch on the next component render.
 
-Removes the cached settings for a specific `mountLocation` from `localStorage`.
-
-```tsx
+```javascript
 import { clearDonateCache } from '@blocklet/payment-react';
 
-// Call this when you know the settings are stale, for example after a user logs out.
-clearDonateCache('unique-blog-post-123');
+// Call this function when you need to invalidate the cache
+clearDonateCache('support-our-blog-post-123');
 ```
 
-### clearDonateSettings
+### `clearDonateSettings`
 
-Sends a `DELETE` request to the server to completely remove the settings for a `mountLocation` and also clears the local cache.
+This function sends a `DELETE` request to the backend API to permanently remove the settings for a given `mountLocation`. It also clears the local cache for that location.
 
-```tsx
+```javascript
 import { clearDonateSettings } from '@blocklet/payment-react';
 
-// Use this to reset a donation instance to its default state.
-async function resetDonationSettings() {
-  await clearDonateSettings('unique-blog-post-123');
+async function deleteDonationInstance() {
+  try {
+    await clearDonateSettings('support-our-blog-post-123');
+    console.log('Donation settings have been deleted.');
+  } catch (error) {
+    console.error('Failed to delete settings:', error);
+  }
 }
 ```
 
-After setting up the provider, the next step is to implement the donation UI using the [`CheckoutDonate`](./components-checkout-checkout-donate.md) component to render the donation widget and display donation history.
+With `DonateProvider` configured, you can now implement various donation features. The next step is to explore the main component for displaying the donation UI.
+
+➡️ Next, learn how to use the [`CheckoutDonate`](./components-checkout-checkout-donate.md) component to render the donation widget.

package/docs/providers-payment-provider.md

@@ -1,245 +1,191 @@
 # 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 from the Payment Kit, and makes payment functions and data available to all its child components.
+The `PaymentProvider` is the cornerstone of the `@blocklet/payment-react` library. It functions as a context provider that must wrap your application or the relevant payment-related components. It handles fetching essential settings, managing application state, and providing helper functions and an API client to all its children.
 
-Any component from this library, such as `CheckoutForm` or `CustomerInvoiceList`, must be nested within a `PaymentProvider` to function correctly.
+Nearly every component and hook in this library requires being nested within a `PaymentProvider` to function correctly.
+
+## How It Works
+
+The provider initializes and fetches configuration data from the Payment Kit backend when it mounts. This data, along with the user's session and other utilities, is then made available to any descendant component via the `usePaymentContext` hook. This pattern ensures that your payment components always have access to the necessary context without prop drilling.
 
 ```d2
 direction: down
 
-"Your React App": {
-  "PaymentProvider": {
-    shape: package
+Your-Application: {
+  label: "Your Application"
+  shape: rectangle
 
-    "Payment Components": {
-      grid-columns: 3
-
-      "CheckoutForm": {shape: document}
-      "CustomerInvoiceList": {shape: document}
-      "Custom Component (usePaymentContext)": {shape: document}
-    }
+  PaymentProvider: {
+    label: "PaymentProvider"
+    style.fill: "#d1e7dd"
+  }
 
+  Payment-Components: {
+    label: "Payment Components\n(e.g., CheckoutForm)"
+    shape: rectangle
+    style.fill: "#cfe2ff"
   }
 }
 
-"PaymentProvider" -> "Payment Components": "Provides context"
+Payment-Kit-API: {
+  label: "Payment Kit API"
+  shape: cylinder
+}
 
-```
+Your-Application.PaymentProvider -> Payment-Kit-API: "1. Fetches settings & methods"
+Your-Application.PaymentProvider -> Your-Application.Payment-Components: "2. Provides context (session, settings, API client)"
+Your-Application.Payment-Components -> Payment-Kit-API: "3. Makes API calls (e.g., create checkout)"
 
-## Prerequisite: Setting Up the Session Context
+```
 
-The `PaymentProvider` requires `session` and `connect` props, which are typically managed by `@arcblock/did-connect-react`. To streamline their use across your application, it's best practice to create a dedicated session context.
+## Setup and Usage
 
-Create a file, for example, at `src/contexts/session.tsx`, with the following content. This will create a `SessionProvider` to wrap your app and a `useSessionContext` hook to access session data easily.
+To use `PaymentProvider`, you need to supply it with `session` and `connect` objects from your application's authentication context. Throughout this documentation, we'll use a custom hook `useSessionContext` to represent your app's authentication logic. Here is a typical implementation of such a hook:
 
-```tsx
-// src/contexts/session.tsx
-import { createAuthServiceSessionContext } from '@arcblock/did-connect-react/lib/Session';
-import { useContext } from 'react';
+```typescript SessionContext.tsx icon=logos:react
+import React, { createContext, useContext } from 'react';
+import { SessionProvider, useSessionContext as useDidSessionContext } from '@arcblock/did-connect-react';
 
-const { SessionProvider, SessionContext, SessionConsumer, withSession } = createAuthServiceSessionContext();
+// You can create your own context or use an existing one
+const AppContext = createContext({});
 
-function useSessionContext() {
-  const info = useContext(SessionContext);
-  return info;
+export function AppProvider({ children }) {
+  return (
+    <SessionProvider>
+      <AppContext.Provider value={{}}>
+        {children}
+      </AppContext.Provider>
+    </SessionProvider>
+  );
 }
 
-export { SessionProvider, SessionContext, SessionConsumer, useSessionContext, withSession };
+// This custom hook provides the session and connectApi to PaymentProvider
+export function useSessionContext() {
+  const { session, connect } = useDidSessionContext();
+  return { session, connectApi: connect };
+}
 ```
 
-Then, wrap your application's root component with the `SessionProvider` you just created:
+Once you have your session management in place, wrap your main application component with `PaymentProvider`.
 
-```tsx
-// src/App.tsx
-import { SessionProvider } from './contexts/session';
+```tsx App.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext'; // Your session context hook
+import MyPaymentPage from './MyPaymentPage';
 
 function App() {
+  const { session, connectApi } = useSessionContext();
+
   return (
-    <SessionProvider>
-      {/* Your application components */}
-    </SessionProvider>
+    <PaymentProvider session={session} connect={connectApi}>
+      <MyPaymentPage />
+    </PaymentProvider>
   );
 }
+
+export default App;
 ```
 
 ## Props
 
-The `PaymentProvider` accepts the following props to configure the payment environment.
+The `PaymentProvider` component accepts the following props:
 
 | Prop | Type | Required | Description |
-|---|---|---|---|
-| `session` | `SessionContext['session']` | Yes | The user session object obtained from `useSessionContext()`. It contains essential user data like their DID. |
-| `connect` | `SessionContext['connectApi']` | Yes | The connect API instance from `useSessionContext()`, used for handling DID Connect interactions. |
-| `children`| `React.ReactNode` | 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. |
+| --- | --- | --- | --- |
+| `session` | `Session` | Yes | The user session object from your authentication context (e.g., `@arcblock/did-connect-react`). |
+| `connect` | `Connect` | Yes | The `connect` API function from your authentication context, used for DID Connect operations. |
+| `children` | `React.ReactNode` | Yes | The child components that will have access to the payment context. |
+| `baseUrl` | `string` | No | The base URL of the Payment Kit blocklet. Required only when integrating payment components from a different origin (cross-origin). |
+| `authToken` | `string` | No | A specific authentication token for API requests. If provided, it will be used instead of the session-based authentication. |
 
-## Basic Integration
 
-To get started, wrap your main application component or the relevant layout with `PaymentProvider`. The required `session` and `connectApi` props are obtained from the `useSessionContext` hook you created earlier.
+## Context Values
 
-```tsx
-import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
-import { useSessionContext } from './contexts/session'; // Adjust path as needed
+Components within `PaymentProvider` can access the following values using the `usePaymentContext` hook.
 
-function App() {
-  const { session, connectApi } = useSessionContext();
+```typescript MyComponent.tsx icon=logos:react
+import { usePaymentContext } from '@blocklet/payment-react';
 
-  if (!session.user) {
-    // Render a login button or a loading state
-    return <button onClick={() => connectApi.open()}>Login</button>;
-  }
+function MyComponent() {
+  const { settings, livemode, setLivemode } = usePaymentContext();
 
   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>
+    <div>
+      <p>Base Currency: {settings.baseCurrency?.name}</p>
+      <p>Mode: {livemode ? 'Live' : 'Test'}</p>
+      <button onClick={() => setLivemode(!livemode)}>Toggle Mode</button>
+    </div>
   );
 }
 ```
 
-## Advanced Usage
-
-### Cross-Origin Communication with `baseUrl`
+Here is a complete list of available context values:
 
-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 and fetch necessary blocklet information for seamless cross-origin communication.
-
-```tsx
-import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';
-import { useSessionContext } from './contexts/session';
-
-function MyAccountPage() {
-  const { session, connectApi } = useSessionContext();
-  const paymentKitBaseUrl = 'https://your-payment-blocklet-domain.com';
+| Key | Type | Description |
+| --- | --- | --- |
+| `session` | `object` | The authenticated user session, including user details. |
+| `connect` | `function` | The `connect` function for initiating DID Wallet interactions. |
+| `livemode` | `boolean` | Indicates if the context is in live (`true`) or test (`false`) mode. |
+| `setLivemode` | `(livemode: boolean) => void` | A function to toggle between live and test modes. This will trigger a refetch of settings. |
+| `settings` | `Settings` | An object containing `paymentMethods` and `baseCurrency` configuration fetched from the backend. |
+| `refresh` | `(forceRefresh?: boolean) => void` | A function to manually trigger a refetch of the settings data. |
+| `getCurrency` | `(id: string) => TPaymentCurrency` | A helper function to retrieve a specific currency's details by its ID. |
+| `getMethod` | `(id: string) => TPaymentMethodExpanded` | A helper function to retrieve a specific payment method's details by its ID. |
+| `api` | `AxiosInstance` | A pre-configured Axios instance for making authenticated API calls to the Payment Kit backend. |
+| `prefix` | `string` | The URL prefix of the blocklet. |
+| `payable` | `boolean` | A state that can be used to control the availability of payment actions. |
+| `setPayable` | `(status: boolean) => void` | A function to update the `payable` status. |
 
-  if (!session.user) {
-    return <button onClick={() => connectApi.open()}>Login</button>;
-  }
 
-  return (
-    <PaymentProvider 
-      session={session} 
-      connect={connectApi} 
-      baseUrl={paymentKitBaseUrl}
-    >
-      <h2>My Invoice History</h2>
-      <CustomerInvoiceList />
-    </PaymentProvider>
-  );
-}
-```
+## Advanced Scenarios
 
-### Using a Custom `authToken`
+### Cross-Origin Integration
 
-In scenarios where you need to use a specific API token instead of relying on the user's session—for example, in a backend-for-frontend pattern or when using a service account token—you can pass the `authToken` prop. This token will be used for all subsequent API requests made by the components within the provider.
+If your application and the Payment Kit blocklet are hosted on different domains, you must use the `baseUrl` prop. This allows `PaymentProvider` to correctly locate and communicate with the Payment Kit API.
 
-```tsx
-import { PaymentProvider, ResumeSubscription } from '@blocklet/payment-react';
-import { useSessionContext } from './contexts/session';
+```tsx CrossOriginApp.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext';
 
-function SubscriptionManager({ temporaryAuthToken }) {
+function CrossOriginApp() {
   const { session, connectApi } = useSessionContext();
 
-  if (!session.user) {
-    return <button onClick={() => connectApi.open()}>Login</button>;
-  }
-
   return (
     <PaymentProvider 
       session={session} 
-      connect={connectApi} 
-      authToken={temporaryAuthToken}
+      connect={connectApi}
+      baseUrl="https://payment-kit.another-domain.com"
     >
-      <ResumeSubscription subscriptionId="sub_xxx" />
+      {/* Your payment components */}
     </PaymentProvider>
   );
 }
 ```
 
-## Accessing Context Data with `usePaymentContext`
-
-Child components can access the data and functions provided by `PaymentProvider` using the `usePaymentContext` hook. This hook provides access to settings, the current operational mode, a pre-configured API client, and more.
-
-### Context Values
-
-Here are the key values returned by the `usePaymentContext` hook:
-
-| Key | Type | Description |
-|---|---|---|
-| `settings` | `object` | An object containing available `paymentMethods` and the `baseCurrency`. |
-| `livemode` | `boolean` | Returns `true` for live mode and `false` for test mode. This state is persisted in local storage. |
-| `setLivemode` | `(livemode: boolean) => void` | A function to toggle between live and test mode. |
-| `api` | `AxiosInstance` | A pre-configured Axios instance for making authenticated requests to the Payment Kit API. |
-| `refresh` | `(forceRefresh?: boolean) => void` | A function to manually trigger a refresh of the settings data. |
-| `getCurrency` | `(id: string) => TPaymentCurrency` | A helper function to find a currency object by its ID from the settings. |
-| `getMethod` | `(id: string) => TPaymentMethodExpanded` | A helper function to find a payment method object by its ID from the settings. |
-| `session` | `object` | The currently active user session object that was passed to the provider. |
-
-### Example: Custom Payment Info Component
-
-This example shows a component that uses the `usePaymentContext` hook to display the current mode and a list of available payment methods.
-
-```tsx
-import { usePaymentContext } from '@blocklet/payment-react';
-import { useSessionContext } from './contexts/session';
-import { Chip, List, ListItem, ListItemText, Typography, Button } from '@mui/material';
+### Custom Authentication Token
 
-function PaymentInfo() {
-  const { settings, livemode, refresh, setLivemode } = usePaymentContext();
+In scenarios where you need to use a specific API token instead of the default session-based authentication (e.g., for server-to-server communication or specific access grants), you can pass the `authToken` prop.
 
-  return (
-    <div>
-      <Typography variant="h6" component="h2" gutterBottom>
-        Payment Status 
-        {livemode ? 
-          <Chip label="Live Mode" color="success" size="small" sx={{ ml: 1 }} /> : 
-          <Chip label="Test Mode" color="warning" size="small" sx={{ ml: 1 }} />
-        }
-      </Typography>
-      
-      <Typography>Available Payment Methods:</Typography>
-      <List dense>
-        {settings.paymentMethods.map(method => (
-          <ListItem key={method.id}>
-            <ListItemText primary={method.name} />
-          </ListItem>
-        ))}
-      </List>
-      
-      <Button variant="outlined" onClick={() => setLivemode(!livemode)} sx={{ mr: 1 }}>
-        Toggle Mode
-      </Button>
-      <Button variant="outlined" onClick={() => refresh(true)}>
-        Refresh Settings
-      </Button>
-    </div>
-  );
-}
+```tsx TokenAuthApp.tsx icon=logos:react
+import { PaymentProvider } from '@blocklet/payment-react';
+import { useSessionContext } from './SessionContext';
 
-// This component must be rendered inside a <PaymentProvider>
-function AppWithPaymentInfo() {
+function TokenAuthApp() {
   const { session, connectApi } = useSessionContext();
-
-  if (!session.user) {
-    return <button onClick={() => connectApi.open()}>Login</button>;
-  }
+  const myCustomAuthToken = 'sk_xxxxxx'; // Your secret token
 
   return (
-    <PaymentProvider session={session} connect={connectApi}>
-      <PaymentInfo />
+    <PaymentProvider 
+      session={session} 
+      connect={connectApi}
+      authToken={myCustomAuthToken}
+    >
+      {/* Components will use the provided authToken for API calls */}
     </PaymentProvider>
   );
 }
 ```
 
-## Next Steps
-
-With `PaymentProvider` set up, you are ready to integrate other components. A good next step is to implement a donation flow or build a checkout page.
+---
 
-- **[DonateProvider](./providers-donate-provider.md)**: Learn how to configure the context for donation-related components.
-- **[CheckoutForm](./components-checkout-checkout-form.md)**: Dive into the primary component for handling payments and checkout sessions.
+With `PaymentProvider` set up, you are now ready to start integrating payment components into your application. A good next step is to explore how to create a payment flow using the [CheckoutForm](./components-checkout-checkout-form.md) component.