CheckoutForm | ArcBlock

CheckoutFormコンポーネントは、支払いリンクとチェックアウトセッションを処理するための主要なエントリーポイントです。提供されたIDに基づいて必要なすべてのデータを取得し、適切な支払いまたは寄付インターフェースをレンダリングする高レベルのラッパーとして機能します。このコンポーネントは、完全なチェックアウトフローをアプリケーションに統合する最も簡単な方法です。

CheckoutFormまたはその親コンポーネントをPaymentProviderでラップして、セッション情報やAPI設定などの必要なコンテキストにアクセスできるようにすることが不可欠です。詳細については、PaymentProviderのドキュメントを参照してください。

仕組み

コンポーネントは、チェックアウトプロセス全体を調整します：

初期化
paymentLink ID（plink_で始まる）またはcheckoutSession ID（cs_で始まる）でマウントされます。
データ取得
支払いバックエンドと通信して、支払い方法、ラインアイテム、顧客詳細など、必要なすべてのコンテキストを取得します。
UIレンダリング
formType propに基づいて、内部で標準のPaymentコンポーネントまたは特化したDonationFormコンポーネントをレンダリングします。
状態管理
読み込み状態、完了ステータス、エラーハンドリングなど、支払いのライフサイクル全体を処理します。

Basic Flow of CheckoutForm

direction: down
shape: sequence_diagram

User-Action: {
  shape: c4-person
  label: "ユーザー"
}

Application: {
  label: "あなたのReactアプリケーション"

  CheckoutForm-Component: {
    label: "CheckoutForm"
  }

  Payment-Component: {
    label: "Paymentコンポーネント"
  }

  Donation-Component: {
    label: "DonationFormコンポーネント"
  }
}

Payment-API: {
  label: "支払いバックエンドAPI"
  shape: cylinder
}

User-Action -> Application.CheckoutForm-Component: "1. 'id' propでマウント"
Application.CheckoutForm-Component -> Payment-API: "2. セッションデータを取得"
Payment-API -> Application.CheckoutForm-Component: "3. チェックアウトコンテキストを返す"

alt "formTypeが'payment'の場合" {
  Application.CheckoutForm-Component -> Application.Payment-Component: "4. Payment UIをレンダリング"
}

alt "formTypeが'donation'の場合" {
  Application.CheckoutForm-Component -> Application.Donation-Component: "5. Donation UIをレンダリング"
}

User-Action -> Application.Payment-Component: "6. 支払いを完了"
User-Action -> Application.Donation-Component: "7. 寄付を完了"

Props

CheckoutFormコンポーネントは、次のpropsを受け入れます：

Prop	Type	必須	デフォルト	説明
`id`	`string`	はい	-	支払いリンク（`plink_...`）またはチェックアウトセッション（`cs_...`）の一意の識別子。
`mode`	`'standalone'` \| `'inline'` \| `'popup'` \| `'inline-minimal'` \| `'popup-minimal'`	いいえ	`'inline'`	レンダリングモードを定義します。`'standalone'`はフルページビュー用、`'inline'`はコンテナに埋め込む用です。
`formType`	`'payment'` \| `'donation'`	いいえ	`'payment'`	レンダリングするフォームのタイプを決定します。特化した寄付フローには`'donation'`を使用します。
`onPaid`	`(res: CheckoutContext) => void`	いいえ	-	支払いが成功したときに実行されるコールバック関数。最終的なチェックアウトコンテキストを引数として受け取ります。
`onError`	`(err: Error) => void`	いいえ	`console.error`	プロセス中にエラーが発生したときに実行されるコールバック関数。
`onChange`	`(data: CheckoutFormData) => void`	いいえ	-	いずれかのフォームフィールドの値が変更されたときに発行されるコールバック関数。
`goBack`	`() => void`	いいえ	-	提供された場合、戻るボタンをレンダリングし、クリックされたときにこの関数を呼び出します。
`extraParams`	`Record<string, any>`	いいえ	`{}`	支払いリンクからセッションを開始する際にURLで渡される追加パラメータのオブジェクト。
`theme`	`'default'` \| `'inherit'` \| `PaymentThemeOptions`	いいえ	`'default'`	コンポーネントのテーマを制御します。`'inherit'`は親テーマを使用するか、カスタムテーマオブジェクトを渡すことができます。
`action`	`string`	いいえ	`''`	ボタンのテキストなどのUI要素をカスタマイズしたり、特定のフローを追跡したりするために使用される文字列識別子。

使用方法

基本的なインライン支払いフォーム

これは、支払いフォームをアプリケーションのUI内に直接埋め込む最も一般的なユースケースです。コンポーネントが内部ですべてのロジックを処理します。

MyStorePage.tsx

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context'; // アプリのセッションフック

export default function MyStorePage() {
  const { session, connectApi } = useSessionContext();

  const handlePaymentSuccess = (result) => {
    console.log('支払いが成功しました！', result);
    alert('ご購入ありがとうございます！');
  };

  const handlePaymentError = (error) => {
    console.error('支払いが失敗しました:', error);
    alert('申し訳ありませんが、支払いを処理できませんでした。');
  };

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ maxWidth: '960px', margin: '0 auto' }}>
        <h1>Checkout</h1>
        <CheckoutForm
          id="plink_xxxxxxxxxxxxxx" // あなたの支払いリンクIDに置き換えてください
          mode="inline"
          onPaid={handlePaymentSuccess}
          onError={handlePaymentError}
        />
      </div>
    </PaymentProvider>
  );
}

スタンドアロンのフルページチェックアウト

mode="standalone"を使用すると、専用のフルページチェックアウトエクスペリエンスをレンダリングできます。これは、ユーザーを別のページにリダイレクトして支払いを完了させるシナリオに最適です。

CheckoutPage.tsx

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';

export default function CheckoutPage() {
  const { session, connectApi } = useSessionContext();
  const paymentLinkId = 'plink_xxxxxxxxxxxxxx'; // URLパラメータから取得可能

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <CheckoutForm id={paymentLinkId} mode="standalone" />
    </PaymentProvider>
  );
}

寄付フォーム

formType="donation"を設定することで、コンポーネントは寄付キャンペーンに特化したUIをレンダリングします。これには、金額のプリセットや特典の表示などの機能が含まれます。

DonationPage.tsx

import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
import { useSessionContext } from './hooks/session-context';

export default function DonationPage() {
  const { session, connectApi } = useSessionContext();

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ padding: '2rem' }}>
        <h2>Support Our Cause</h2>
        <CheckoutForm
          id="plink_yyyyyyyyyyyyyy" // あなたの寄付リンクIDに置き換えてください
          formType="donation"
          onPaid={() => alert('寛大なご寄付ありがとうございます！')}
        />
      </div>
    </PaymentProvider>
  );
}