このページは Payment Method Integration for the Checkout Block を日本語に2023年1月15日に翻訳したものです。ちなみにこの説明だけでは動きませんので、一番下のテストプラグインの内容も含めて、検討した方がいいです。

購入手続きブロックには、サーバー側とクライアント側の両方の実装で構成される、統合する支払い方法用の API インターフェイスがあります。

クライアント側の統合

クライアント側の統合は、エクスプレス支払い方法 (Stripe、ApplePay、GooglePay など、買い物客が開始するワンボタン支払いプロセスで構成されるもの) と、小切手、PayPal Standard、または stripe のクレジットカードに分かれます。

どちらの場合も、クライアント側の統合は、blocks-registry API で公開される登録メソッドを使用して行われます。 これには、WooCommerce 環境の wc global (wc.wcBlocksRegistry) を介してアクセスできます。

注: ビルドプロセスでは、この API を @woocommerce/blocks-registry の外部としてエイリアスするブロックリポジトリで行われることと同様のことを行うことができます。

エクスプレス支払い方法 – registerExpressPaymentMethod( options )

エクスプレス支払い方法を登録するには、ブロックレジストリの registerExpressPaymentMethod 関数を使用します。 これをインポートして JavaScript ファイルで使用する例は次のとおりです。

エイリアス付きインポート

import { registerExpressPaymentMethod } from '@woocommerce/blocks-registry';

wc global

const { registerExpressPaymentMethod } = window.wc.wcBlocksRegistry;

登録オプション

レジストリ関数は、支払い方法に固有のオプションを備えた JavaScript オブジェクトを想定しています。

registerExpressPaymentMethod( options );

構成インスタンスにフィードするオプションは、次の形式のオブジェクトである必要があります (ExpressPaymentMethodConfiguration typedef を参照)。

const options = {
	name: 'my_payment_method',
	content: <div>A React node</div>,
	edit: <div>A React node</div>,
	canMakePayment: () => true,
	paymentMethodId: 'new_payment_method',
	supports: {
		features: [],
	},
};

構成オプションの詳細は次のとおりです:

name (必須)

これは、ゲートウェイのクライアント側の識別子として使用される一意の文字列である必要があります (別の実装では使用されない、ゲートウェイにとって一意のものを選択することが賢明です)。 PaymentMethodId が指定されていない場合は、paymentMethodId にも name が使用されます。

content (必須)

これは、ブロックがフロントエンドでレンダリングされるときにエクスプレス支払い方法領域に出力される React ノードである必要があります。 レンダリングプロセスでクローンが作成されます。 クローン化されると、この React ノードは、購入手続き支払いメソッド インターフェイスから渡された props を受け取り、コンポーネントが購入手続きデータと対話できるようにします (これらの props については後で詳しく説明します)。

edit (必須)

これは、ブロックがエディターでレンダリングされるときに高速支払い方法領域に出力される React ノードである必要があります。 レンダリングプロセスでクローンが作成されます。 クローン化されると、この React ノードは支払い方法インターフェイスからチェックアウトするためのプロパティを受け取ります (ただし、それらにはプレビュー データが含まれます)。

canMakePayment (必須)

支払い方法を買い物客のオプションとして使用できるかどうかを決定するコールバック。 この関数には、現在の注文に関するデータを含むオブジェクトが渡されます。

canMakePayment( {
	cart: Cart,
	cartTotals: CartTotals,
	cartNeedsShipping: boolean,
	shippingAddress: CartShippingAddress,
	billingAddress: CartBillingAddress,
	selectedShippingMethods: Record<string,unknown>,
	paymentRequirements: string[],
} )

ブール値を返します。支払い方法が使用できる場合は true。 ゲートウェイが可用性を判断するために非同期初期化を実行する必要がある場合は、Promise (ブール値に解決) を返すことができます。 これにより、カートに基づいて支払い方法を非表示にすることができます。 カートに物理的/配送可能な商品がある場合 (例: 代金引換)。 または、支払い方法が他の条件に応じて利用可能かどうかを制御する場合。

canMakePayment はストアのフロントエンドでのみ実行されます。 エディターのコンテキストでは、canMakePayment を使用するのではなく、エディターは支払い方法が利用可能 (true) であると想定し、定義された edit コンポーネントが販売者に表示されます。

この関数はチェックアウトのライフサイクルで複数回呼び出される可能性があるため、このプロパティで提供されるコールバック内の高価なロジックはすべてメモ化する必要があることに注意してください。

paymentMethodId

これは唯一のオプションの構成オブジェクトです。 このプロパティの値は、サーバーへのチェックアウト処理リクエストに付随するもので、支払いを処理するためにどの支払い方法ゲートウェイ クラスをロードするかを識別するために使用されます (買い物客がゲートウェイを選択した場合)。 たとえば、これがストライプの場合、支払いを処理するために WC_Gateway_Stripe::process_payment が呼び出されます。

supports:features

これは、ゲートウェイによってサポートされる一連の支払い機能です。 カートの内容に支払い方法が使用できるかどうかを照合するために使用されます。 デフォルトでは、支払い方法は少なくとも product 機能をサポートする必要があります。 値が指定されていない場合は、['products'] がサポートされていると想定されます。

支払い方法 – registerPaymentMethod( options )

支払い方法を登録するには、ブロック レジストリの registerPaymentMethod 関数を使用します。 これをインポートして JavaScript ファイルで使用する例は次のとおりです。

エイリアス付きインポート

import { registerPaymentMethod } from '@woocommerce/blocks-registry';

wc global

const { registerPaymentMethod } = window.wc.wcBlocksRegistry;

登録オプション

レジストリ関数は、支払い方法に固有のオプションを備えた JavaScript オブジェクトを想定しています。

registerPaymentMethod( options );

構成インスタンスに入力するオプションは、エクスプレス支払い方法のオプションと同じですが、次の点が追加されています。

• SavedTokenComponent: これは、お支払い方法が保存されたお支払い方法をサポートしている場合、お支払い方法が保存されたお支払い方法に対して行う必要がある処理を処理するロジックを含む React ノードである必要があります。 このコンポーネントは、処理に支払い方法を使用して顧客が保存したトークンが購入の際に選択されるたびにレンダリングされます。
• label: これは、支払い方法が存在するオプションのラベルを出力するために使用される React ノードである必要があります。 たとえば、クレジット/デビットカートや画像を出力することができます。
• ariaLabel: これは、支払い方法が選択されたときにスクリーンリーダーを介して読み上げられるラベルです。
• placeOrderButtonLabel: これは、支払い方法が選択されたときにデフォルトの「注文する」ボタンのテキストを別のテキストに変更するオプションのラベルです。 たとえば、PayPal 標準支払い方法は、チェックアウトの支払い方法として選択されると、ボタンのテキストを「PayPal に進む」に変更します。これは、この支払い方法では、買い物客が支払いを完了するためにオフサイトの PayPal に移動するためです。
• support: これは、支払い方法がサポートする機能に関する情報を含むオブジェクトです。 ここでは次のキーが有効です。
  • showSavedCards: この値は、支払い方法に関連付けられた保存済みカードを顧客に表示するかどうかを決定します。
  • showSaveOption: この値は、顧客が将来の支払いのために支払い方法を保存できるようにするチェックボックスを表示するかどうかを制御します。

支払い方法ノードに供給されるプロパティ

支払い方法の統合の大部分は、提供されたノードがブロック マウントで複製およびレンダリングされるときに、小道具を介して使用する支払い方法に公開されるインターフェイスです。 すべての props は以下にリストされていますが、このファイルで説明されている typedef を介して、props が参照するもの、その型などの詳細を見つけることができます。

• isPristine: 現在の支払いステータスが PRISTINE の場合に当てはまります。
• isStarted: 現在の支払いステータスが EXPRESS_STARTED の場合に当てはまります。
• isProcessing: 現在の支払いステータスが PROCESSING の場合、これは true です。
• isFinished: 現在の支払いステータスが ERROR、FAILED、SUCCESS のいずれかの場合に true です。
• hasError: これは、現在の支払いステータスが ERROR の場合に true です。
• hasFailed: 現在の支払いステータスが FAILED の場合、これは true です。
• isSuccessful: 現在の支払いステータスが SUCCESS の場合に true です。

登録済みの SavedTokenComponent ノードは、支払い方法で内部ロジックに使用する必要がある場合に備えて、選択した保存済みトークンの ID を含む token プロパティも受け取ります。 ただし、これはデータベース内のこのトークンを表す ID (および買い物客がチェックした無線入力の値) であり、実際の顧客の支払いトークンではないことに注意してください (これを使用した処理は通常、セキュリティのためにサーバーで行われるため)。

サーバー側の統合

支払いの処理中

購入手続きブロックには現在、支払い処理のための従来の処理があります。 クライアント側の支払い方法によって提供される受信 payment_data を $_POST に変換し、支払いゲートウェイの process_payment 関数を呼び出します。 既存のショートコード チェックアウト フローに統合された WooCommerce Payment メソッド拡張機能がすでにある場合は、チェックアウト ブロックの従来の処理がサーバー側で支払いを処理します。 ただし、支払い方法が何らかの方法でコアチェックアウトの process_checkout 関数にフックされる場合は、この動作を考慮して適切な調整を行う必要があります。 (ストア API を介したチェックアウトプロセスへのフックについては、以下のセクションを参照してください。)

クライアントからサーバー側の支払い処理に値を渡す例を参照してください。

アセットの登録

ブロックの統合では、クライアント側のアセット登録の正しい読み込みを実装するのは困難です。 これは、リクエスト内の依存アセットの読み込み順序に依存関係があるためです。ここで拡張機能の利用者にとっての複雑さを取り除くために、サーバー側の API インターフェイスは、サーバーからクライアント側の支払い方法に渡すアセットとデータを確実に登録できるように支援し、それらのアセットの正しい読み込み順序を処理します。

まず、Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType を拡張するクラスを作成します (または Automattic\WooCommerce\Blocks\Payments\PaymentMethodTypeInterface を実装できますが、抽象クラスを介して一部の機能を無料で入手できます)。

クラスでは:

• name プロパティ (支払い方法を参照するために使用される文字列) を定義します。
• initialize 関数を定義します。 この関数はサーバー側の初期化プロセス中に呼び出され、設定の作成などを行うのに適した場所です。基本的に、ゲートウェイを初期化するために行う必要があるものはすべてあります。 これはリクエストごとに呼び出されるため、ここには高価なものを置かないでください。
• is_active 関数を定義します。 これにより、支払い方法がアクティブかどうかが返されます。
• get_payment_method_script_handles 関数を定義します。 この関数では、支払い方法スクリプトを登録し (wp_register_script を使用)、登録したスクリプト ハンドルを返す必要があります。 これは、支払い方法をチェックアウト スクリプトの依存関係として追加するために使用され、それが正しく読み込まれることを確認します。 注: スクリプトにある他のアセットの依存関係がここで適切に登録されていることを確認する必要があります。Webpack を使用してアセットを構築している場合は、WooCommerce Webpack Dependency Extraction Pluginを使用してこれを簡単に行うことができます。
• get_payment_method_script_handles_for_admin 関数を定義します。 支払い方法に、チェックアウト ブロックのエディター コンテキストにのみロードするスクリプトがある場合は、これを含めます。 ここには、管理者にも必要な get_payment_method_script_handles のスクリプトを含めます。
• get_payment_method_data 関数を定義します。 この関数から、支払い方法のクライアント側に公開したいデータの連想配列を返すことができます。 このデータは、wc.wcSettings.getSetting を介してクライアント側で利用可能になります。 したがって、たとえば、このクラスの name プロパティの値としてストライプを割り当てた場合、クライアント側では、 wc.wcSettings.getSetting( 'stripe_data' ) を介して任意のデータにアクセスできます。 これにより、この関数から返された連想配列の形状に一致するオブジェクトが返されます。

Store API によるチェックアウト処理へのフック

場合によっては、前述の StoreAPI からのチェックアウト リクエストのフォールバック レガシー処理が、既存の支払い方法の統合では機能しない場合があります。 このような場合には、サーバー側の注文処理にフックするために実装できるアクションフックもあります。 注: このフックにコールバックを登録するのに適した場所は、上記の手順で作成した支払いメソッド クラスの initial メソッド内です。

このフックは、支払い処理でフックする場所として推奨されます。提供された PaymentResult オブジェクトにステータスを設定すると、支払い方法では従来の処理が無視されます。 フックのコールバックは以下を受け取ります:

Automattic\WooCommerce\StoreApi\Payments\PaymentContext

これには、チェックアウト処理リクエストから抽出された支払いに関するさまざまな詳細が含まれます。 特に注目すべきは、支払い方法のクライアント側がチェックアウトに提供したデータの連想配列を含むpayment_dataプロパティです。 また、チェックアウト処理中に使用されるアクティブな支払い方法のpaymentMethodId 値を含む payment_method の文字列値も含まれます。 したがって、これを使用して、支払い方法がこのデータを処理するかどうかを判断できます。

Automattic\WooCommerce\StoreApi\Payments\PaymentResult

これには、クライアントに返され、onAfterCheckoutProcessingWithSucces/WithError イベントで公開される支払い結果に関するさまざまな詳細が含まれます。 サーバー側では、支払い方法でこれを次の目的で使用できます。:

• 支払い方法に対して返されるステータス ( success, failure, pending, error のいずれか) を設定します。
• リダイレクト URL を設定します。
• 追加の支払い詳細を設定します (クライアントがさらに処理するために何かを返す必要がある場合)。

すべてを一緒に入れて

Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType を拡張するクラスを作成しましたが、これを支払い方法のサーバー側処理に登録する必要があります。 これを行うには、woocommerce_blocks_payment_method_type_registration アクションにコールバックを登録する必要があります。 コールバックは、作成したクラスのインスタンスを登録するための register メソッドを持つ Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry のインスタンスを受け取ります。 また、woocommerce_blocks_loaded アクションのコールバックのコンテキスト内でこのアクションのコールバックを登録することをお勧めします。

注: 現在、Cart ブロックと Checkout ブロックは WooCommerce Blocks Feature プラグインでのみ利用可能であるため、支払い方法統合サーバー側を登録する前に、Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType クラスが利用可能かどうかを必ず確認してください。 

たとえば、Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType を拡張するクラスの名前が MyPaymentMethod であるとします。 これは拡張機能のブートストラップのどこかにあります。

use MyPlugin\MyPaymentMethod;
use Automattic\WooCommerce\Blocks\Payments\PaymentMethodRegistry;

add_action( 'woocommerce_blocks_loaded', 'my_extension_woocommerce_blocks_support' );

function my_extension_woocommerce_blocks_support() {
  if ( class_exists( 'Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType' ) ) {
    add_action(
      'woocommerce_blocks_payment_method_type_registration',
      function( PaymentMethodRegistry $payment_method_registry ) {
        $payment_method_registry->register( new MyPaymentMethod );
      }
    );
  }
}

例として、このプル リクエストで Stripe 拡張機能がどのように統合を追加するかを確認できます。

上記の表記の内容の一部が古いようです。

新しい説明としては以下の支払いプラグインの例がhttps://github.com/woocommerce/woocommerce-gateway-dummy こちらにありますので、これを参考にした方がいいです。上記では動きません。(T_T)