クライアント側の統合

クライアント側の統合は、 regular と express の両方の支払い方法を登録するための API で構成されています。

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

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

エクスプレス・ペイメント

エクスプレス決済とは、Stripe、ApplePay、GooglePay など、買い物客がワンボタンで決済を開始できる決済方法である。

登録

エクスプレス支払い方法を登録するには、ブロックレジストリのregisterExpressPaymentMethod関数を使用します。

const { registerExpressPaymentMethod } = window.wc.wcBlocksRegistry;

@woocommerce/blocks-registryのエイリアス・インポートを使っている場合は、このように関数をインポートできる：

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

レジストリ関数は、支払い方法に固有のオプションを持つ JavaScript オブジェクトを期待します：

registerExpressPaymentMethod( options );

コンフィギュレーション・インスタンスに与えるオプションは、この形のオブジェクトでなければなりません（ExpressPaymentMethodConfiguration typedef参照）：

const options = {
    name: 'my_payment_method',
    title: 'My Mayment Method',
    description: 'A setence or two about your payment method',
    gatewayId: 'gateway-id',
    label: <ReactNode />,
    content: <ReactNode />,
    edit: <ReactNode />,
    canMakePayment: () => true,
    paymentMethodId: 'my_payment_method',
    supports: {
        features: [],
        style: [],
    },
};

ExpressPaymentMethodConfiguration

canMakePayment オプション

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

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

canMakePayment はブール値を返します。ゲートウェイが可用性を決定するために非同期の初期化を実行する必要がある場合、（boolean に解決する）プロミスを返すことができます。これにより、カートに物理的/発送可能な商品がある場合など、カートに基づいて支払い方法を非表示にすることができます (例: Cash on delivery); または、他の条件によって利用可能かどうかを制御する支払い方法。

canMakePayment はストアのフロントエンドでのみ実行されます。エディタコンテキストでは、canMakePayment を使用する代わりに、エディタは支払い方法が利用可能（true）であるとみなし、定義されたeditコンポーネントがマーチャントに表示されます。

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

エクスプレス決済のボタン属性

この API は、一貫したショッパーエクスペリエンスのために、エクスプレスペイメントボタンのルックアンドフィールを同期する方法を提供します。エクスプレス・ペイメント・メソッドは、buttonAttributesで指定された値を優先し、カートまたはチェックアウト・ブロック以外の場所にボタンが表示される場合は、バックアップとして独自のコンフィギュレーション設定を使用する必要があります。

例えば、ボタン・コンポーネントでは次のようにする：

// Get your extension specific settings and set defaults if not available
let {
    borderRadius = '4',
    height = '48',
} = getButtonSettingsFromConfig();

// In a cart & checkout block context, we receive `buttonAttributes` as a prop which overwrite the extension specific settings
if ( typeof buttonAttributes !== 'undefined' ) {
    height = buttonAttributes.height;
    borderRadius = buttonAttributes.borderRadius;
}
...

return <button style={height: `${height}px`, borderRadius: `${borderRadius}px`} />

支払方法

支払い方法は、チェックアウトブロックに表示される支払い方法のオプションです。例としては、cheque、PayPal Standard、Stripe Credit Card などがあります。

登録

支払い方法を登録するには、ブロック・レジストリの registerPaymentMethod 関数を使用する。

const { registerPaymentMethod } = window.wc.wcBlocksRegistry;

@woocommerce/blocks-registryのエイリアス・インポートを使っている場合は、このように関数をインポートできる：

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

レジストリ関数は、支払い方法に固有のオプションを持つ JavaScript オブジェクトを期待します：

registerPaymentMethod( options );

コンフィギュレーション・インスタンスに与えるオプションは、この形のオブジェクトでなければなりません（PaymentMethodRegistrationOptions typedef参照）。コンフィギュレーション・インスタンスに与えるオプションは、エクスプレス・ペイメント・メソッドのものと同じですが、以下のものが追加されます：

| プロパティ｜タイプ｜説明
| — | — | — |
| savedTokenComponent | ReactNode｜保存された支払い方法を処理するためのロジックを含むReactノード。この支払い方法のために顧客の保存されたトークンが選択されたときにレンダリングされます。|
| label | ReactNode｜支払い方法オプションのラベルを出力するためのReactノード。テキストでも画像でもかまいません。|
| ariaLabel | string｜支払い方法が選択されたときにスクリーンリーダーによって読み取られるラベル。|
| placeOrderButtonLabel | string | この支払い方法が選択されたときに、デフォルトの “注文する “ボタンのテキストを変更するオプションのラベル。placeOrderButtonと排他的です。|
| placeOrderButton | Reactコンポーネント｜この支払い方法が選択されたときに、デフォルトの「注文する」ボタンを置き換えるReactコンポーネントを指定します。placeOrderButtonLabelと排他的です。このコンポーネントは PaymentMethodInterface プロップを受け取ります。|
| supports｜オブジェクト｜サポートされる機能に関する情報を含みます：|
| supports.showSavedCards｜boolean｜この支払い方法で保存されたカードが顧客に表示されるかどうかを決定します。|
| supports.showSaveOption｜boolean｜将来の使用のために支払い方法を保存するチェックボックスを表示するかどうかを制御します。|

カスタム発注ボタンの使用

placeOrderButtonプロパティを使用すると、デフォルトの「注文する」ボタンをカスタムコンポーネントで置き換えることができます。これは、カスタムボタンのスタイルを必要とする支払い方法（Google Pay や Apple Pay など）や、注文を送信する前に支払い UI を表示する必要がある場合に便利です。あなたの支払い方法に適用されない場合は、このプロパティを省略し、デフォルトのボタンを使用することをお勧めします。

カスタムボタンコンポーネントは、PaymentMethodInterfaceを介して、支払いメソッドcontentコンポーネントと同じプロップをすべて受け取り、さらにボタン固有のプロップも受け取ります：

• waitingForProcessing – チェックアウト処理中かどうか。
• waitingForRedirect – チェックアウトが成功した後にリダイレクトされるのを待っているかどうか。
• disabled – ボタンを無効にするかどうか
• isEditor – ブロックエディタでボタンがレンダリングされているかどうか
• isPreview – ボタンがプレビューモードでレンダリングされるかどうか

簡単な例を挙げよう：

const CustomButton = ( props ) => {
    const { validate, onSubmit, disabled, isEditor, isPreview, eventRegistration: { onPaymentSetup }, emitResponse } = props;

    const [
        isShowingInternalPaymentSheet,
        setIsShowingInternalPaymentSheet,
    ] = React.useState( false );
  
  const paymentResultRef = React.useRef( false );

    const handleClick = async () => {
        // 1. Validate the checkout form
        const validationResult = await validate();

        if ( validationResult.hasError ) {
            return; // WooCommerce automatically displays validation errors
        }

        // 2. Show your payment UI (e.g., Google Pay sheet, Apple Pay sheet)
        // setIsShowingInternalPaymentSheet( true );
        // const paymentResult = await showPaymentSheet( billing.cartTotal.value );
    // paymentResultRef.current = paymentResult.success;
        // if ( ! paymentResult.success ) {
        //     setIsShowingInternalPaymentSheet( false );
        //     return;
        // }

        // 3. Submit the checkout to the server once all payment information has been collected.
        onSubmit();
    };

  React.useEffect(
    () =>
      onPaymentSetup( () => {
        return ({
          type: paymentResultRef.current ? emitResponse.responseTypes.SUCCESS : emitResponse.responseTypes.ERROR,
          meta: {
            paymentMethodData: {
              payment_method: 'your-payment-method',
            },
          },
        });
      } ),
    [ onPaymentSetup, emitResponse.responseTypes.SUCCESS, emitResponse.responseTypes.ERROR ]
  );

    // In editor/preview mode, show a placeholder or preview version
    if ( isEditor || isPreview ) {
        return (
            <button type="button" disabled>
                Pay with Custom Method (Preview)
            </button>
        );
    }

    return (
        <button
          type="button"
            onClick={ handleClick }
            disabled={ disabled || isShowingInternalPaymentSheet }
        >
            { disabled || isShowingInternalPaymentSheet
                ? 'Processing...'
                : 'Pay with Custom Method' }
        </button>
    );
};

registerPaymentMethod( {
    name: 'my-custom-payment',
    label: <div>My Custom Payment</div>,
    content: <div>Payment method description</div>,
    edit: <div>Payment method description</div>,
    placeOrderButton: CustomButton,
    canMakePayment: () => true,
    supports: {
        features: [ 'products' ],
    },
} );

** カスタムボタンは、支払い方法がリストから選択された場合にのみ表示されます。保存された支払いトークンが選択された場合、代わりにデフォルトの「注文する」ボタンが使用されます。

支払い方法ノードへの小道具の提供

ペイメントメソッド統合の大部分は、提供されたノードがクローンされ、ブロックマウント上でレンダリングされるときに、ペイメントメソッドがpropsを介して使用するために公開されるインタフェースです。すべてのpropsは以下にリストされていますが、このファイルに記述されているtypedefsを介して、propsが参照するもの、それらの型などの詳細を見つけることができます。

登録された savedTokenComponent ノードは token プロップも受け取ります。しかし、これはあくまでデータベース内のトークンを表す id (およびショッパーがチェックしたラジオ入力の値) であり、実際の顧客の支払いトークンではないことに注意してください (通常、トークンを使用した処理はセキュリティのためにサーバで行われるため)。

サーバーサイドの統合

サーバー側の統合には、Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodTypeクラスを継承したクラスを作成する必要があります。

このクラスは、支払い方法をサーバーサイドで表現します。このクラスは、Store APIとCheckoutブロックへの支払い方法アセットの登録を適切なタイミングで処理するために使用されます。決済処理のために別途実装する必要があるPayment Gateway APIとは異なります。

支払方法統合クラスの例

<?php
namespace MyPlugin\MyPaymentMethod;

use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;

final class MyPaymentMethodType extends AbstractPaymentMethodType {
    /**
     * This property is a string used to reference your payment method. It is important to use the same name as in your
     * client-side JavaScript payment method registration.
     *
     * @var string
     */
    protected $name = 'my_payment_method';

    /**
     * Initializes the payment method.
     * 
     * This function will get called during the server side initialization process and is a good place to put any settings
     * population etc. Basically anything you need to do to initialize your gateway. 
     * 
     * Note, this will be called on every request so don't put anything expensive here.
     */
    public function initialize() {
        $this->settings = get_option( 'woocommerce_my_payment_method_settings', [] );
    }

    /**
     * This should return whether the payment method is active or not. 
     * 
     * If false, the scripts will not be enqueued.
     *
     * @return boolean
     */
    public function is_active() {
        return filter_var( $this->get_setting( 'enabled', false ), FILTER_VALIDATE_BOOLEAN );
    }

    /**
     * Returns an array of scripts/handles to be registered for this payment method.
     * 
     * In this function you should register your payment method scripts (using `wp_register_script`) and then return the 
     * script handles you registered with. This will be used to add your payment method as a dependency of the checkout script 
     * and thus take sure of loading it correctly. 
     * 
     * Note that you should still make sure any other asset dependencies your script has are registered properly here, if 
     * you're using Webpack to build your assets, you may want to use the WooCommerce Webpack Dependency Extraction Plugin
     * (https://www.npmjs.com/package/@woocommerce/dependency-extraction-webpack-plugin) to make this easier for you.
     *
     * @return array
     */
    public function get_payment_method_script_handles() {
        wp_register_script(
            'my-payment-method',
            'path/to/your/script/my-payment-method.js',
            [],
            '1.0.0',
            true
        );
        return [ 'my-payment-method' ];
    }

    /**
     * Returns an array of script handles to be enqueued for the admin.
     * 
     * Include this if your payment method has a script you _only_ want to load in the editor context for the checkout block. 
     * Include here any script from `get_payment_method_script_handles` that is also needed in the admin.
     */
    public function get_payment_method_script_handles_for_admin() {
        return $this->get_payment_method_script_handles();
    }

    /**
     * Returns an array of key=>value pairs of data made available to the payment methods script client side.
     * 
     * This data will be available client side via `wc.wcSettings.getSetting`. So for instance if you assigned `stripe` as the 
     * value of the `name` property for this class, client side you can access any data via: 
     * `wc.wcSettings.getSetting( 'stripe_data' )`. That would return an object matching the shape of the associative array 
     * you returned from this function.
     *
     * @return array
     */
    public function get_payment_method_data() {
        return [
            'title'       => $this->get_setting( 'title' ),
            'description' => $this->get_setting( 'description' ),
            'supports'    => $this->get_supported_features(),
        ];
    }
}

支払方法の統合登録

Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodTypeを継承したクラスを作成したら、サーバー側で処理する支払いメソッドに登録する必要があります。

これは、PaymentMethodRegistry クラスの register メソッドを使うことで可能です。

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

add_action(
    'woocommerce_blocks_payment_method_type_registration',
    function( PaymentMethodRegistry $payment_method_registry ) {
        $payment_method_registry->register( new MyPaymentMethodType() );
    }
);

支払処理（レガシーサポート）

支払いは引き続きPayment Gateway APIを介して処理されます。これは、上記の支払い方法の統合に使用されるものとは別のAPIです。

チェックアウトブロックは、クライアントサイドスクリプトによって提供された payment_data を $_POST に変換し、ペイメントゲートウェイの process_payment メソッドを呼び出します。

もしあなたが既に WooCommerce Payment method extension をショートコードのチェックアウトフローに統合している場合、レガシーハンドリングがサーバーサイドであなたの代わりに支払いを処理します。

ストアAPIによる支払い処理

前述したレガシーな支払い処理が、既存の支払い方法との統合で機能しないような、より高度なケースも考えられます。このような場合、Store API に特化した、より多くのコンテキストを提供する、注文のサーバー側処理を処理するために使用できるアクションフックもあります。

このフックは、支払い処理をフックする場所として推奨されます：

do_action_ref_array( 'woocommerce_rest_checkout_process_payment_with_context', [ $context, &$result ] );

注：このフックにコールバックを登録するのに適した場所は、先に作成した支払い方法タイプクラスの initialize メソッド内である。

このフックのコールバックが受け取る：

• 選択された payment_method（支払い方法の登録時に定義された paymentMethodId と同じです）、設置される order、および支払い方法のクライアントが提供する追加の payment_data を含む PaymentContext オブジェクト。
• PaymentResult オブジェクトを使用して、ステータス、リダイレクトURL、追加の支払い詳細をStore API経由でクライアントに返します。

提供された PaymentResult オブジェクトにステータスを設定すると、レガシーな支払い処理は無視されます。エラーが発生した場合、コールバックはStore APIによって処理される例外を投げることができます。

以下はコールバックの例である：

add_action(
    'woocommerce_rest_checkout_process_payment_with_context',
    function( $context, $result ) {
        if ( $context->payment_method === 'my_payment_method' ) {
            // Order processing would happen here!
            // $context->order contains the order object if needed
            // ...

            // If the logic above was successful, we can set the status to success.
            $result->set_status( 'success' );
            $result->set_payment_details(
                array_merge(
                    $result->payment_details,
                    [
                        'custom-data' => '12345',
                    ]
                )
            );
            $result->set_redirect_url( 'some/url/to/redirect/to' );
        }
    },
  10,
  2
);

クライアントからサーバー側の支払い処理に値を渡す

この例では、BACS 支払い方法からサーバーにデータを渡します。BACS の登録は次のようになります：

// Get our settings that were provided when the payment method was registered
const settings = window.wc.wcSettings.getSetting( 'bacs_data' );

// This is a component that would be rendered in the checkout block when the BACS payment method is selected
const Content = () => {
    return decodeEntities( settings?.description || '' );
};

// This is the label for the payment method
const Label = ( props ) => {
    const { PaymentMethodLabel } = props.components;
    return <PaymentMethodLabel text={ decodeEntities( settings?.title || 'BACS' ) } />;
};

// Register the payment method
const bankTransferPaymentMethod = {
    name: 'BACS',
    label: <Label />,
    content: <Content />,
    edit: <Content />,
    canMakePayment: () => true,
    supports: {
        features: settings?.supports ?? [],
    },
};

支払い方法ノードは、usePaymentMethodInterface フックからすべてを渡されます。そのため、<Content />コンポーネントでは、次のようにこれを使用することができます：

const Content = ( props ) => {
    const { eventRegistration, emitResponse } = props;
    const { onPaymentProcessing } = eventRegistration;
    useEffect( () => {
        const unsubscribe = onPaymentProcessing( async () => {
            // Here we can do any processing we need, and then emit a response.
            // For example, we might validate a custom field, or perform an AJAX request, and then emit a response indicating it is valid or not.
            const myGatewayCustomData = '12345';
            const customDataIsValid = !! myGatewayCustomData.length;

            if ( customDataIsValid ) {
                return {
                    type: emitResponse.responseTypes.SUCCESS,
                    meta: {
                        paymentMethodData: {
                            myGatewayCustomData,
                        },
                    },
                };
            }

            return {
                type: emitResponse.responseTypes.ERROR,
                message: 'There was an error',
            };
        } );
        // Unsubscribes when this component is unmounted.
        return () => {
            unsubscribe();
        };
    }, [
        emitResponse.responseTypes.ERROR,
        emitResponse.responseTypes.SUCCESS,
        onPaymentProcessing,
    ] );
    return decodeEntities( settings.description || '' );
};

注文が発注されたとき、API リクエストのペイロードを見ると、以下の JSON を見ることができる：

{
    "shipping_address": {},
    "billing_address": {},
    "customer_note": "",
    "create_account": false,
    "payment_method": "bacs",
    "payment_data": [
        {
            "key": "myGatewayCustomData",
            "value": "12345"
        }
    ],
    "extensions": {}
}

その後、woocommerce_rest_checkout_process_payment_with_context のコールバックがこのデータにアクセスし、支払い処理に使用することができる。

add_action( 'woocommerce_rest_checkout_process_payment_with_context', function( $context, $result ) { )
  if ( $context->payment_method === 'bacs' ) { { $myGatewayCustoms
    myGatewayCustomData = $context->payment_data['myGatewayCustomData']；
    // ここでは、$myGatewayCustomData を使用して支払いを処理します。