ゲートウェイテンプレート

ゲートウェイテンプレートは、自分専用のPOS専用決済ゲートウェイを構築するための出発点を提供します。これは、インストールしてニーズに合わせてカスタマイズできる単一のPHPファイルを持つ動作するWordPressプラグインを生成します。

特徴

最小限のコード

必要なものだけを含む単一のPHPファイル — 読みやすく、修正が簡単

POS専用

デフォルトでWebチェックアウトでは無効になっており、WCPOSの設定を通じて有効化される

自動セットアップ

シェルスクリプトがすべてのプレースホルダーの置換を処理します

GitHubリリース

バージョンをプッシュすると、GitHub Actionsがダウンロード可能なZIPをビルドします

始めに

1

テンプレートリポジトリをクローンする

git clone https://github.com/wcpos/woocommerce-gateway-template.git
cd woocommerce-gateway-template

または、GitHubリポジトリのこのテンプレートを使用ボタンをクリックして、自分のコピーを作成します。

2

セットアップスクリプトを実行する

./create-gateway.sh

スクリプトは、ゲートウェイ名、短い説明、およびGitHubユーザー名など、いくつかの詳細を要求し、その後、選択したディレクトリに使用可能なプラグインを生成します。

3

プラグインをインストールする

2つのオプションがあります：

オプションA — フォルダを直接コピー（サーバーアクセスがある場合）： 生成されたゲートウェイフォルダをサイトのwp-content/plugins/ディレクトリにコピーします。

オプションB — ZIPしてアップロード（ほとんどの人にとって簡単）：

1. 生成されたフォルダを.zipファイルに圧縮します
2. WordPressで、プラグイン > 新規追加 > プラグインをアップロードに移動します
3. ZIPファイルを選択し、今すぐインストールをクリックします

4

WCPOSで有効化

1. WP Admin > WCPOS > 設定 > チェックアウトに移動します
2. リストで新しいゲートウェイを見つけて有効にします

ノート

ゲートウェイはデフォルトで通常のWebチェックアウトでは無効です。WCPOSは独自の設定を通じて、POSに表示されるゲートウェイを制御します。

手動セットアップ

スクリプトを使用したくない場合、プレースホルダーを自分で置き換えることができます。テキストエディタで各ファイルを開き、以下を検索して置換します：

プレースホルダー	入力する内容	例
{{GATEWAY_NAME}}	ゲートウェイの表示名	現金決済
{{GATEWAY_SLUG}}	URL安全な識別子（小文字、ハイフン）	cash-payment
{{GATEWAY_DESCRIPTION}}	ゲートウェイの短い説明	WCPOSで現金決済を受け付ける
{{GATEWAY_DEFAULT_DESCRIPTION}}	チェックアウト時にレジ係に表示されるテキスト	売上時に現金で支払う
{{GITHUB_USERNAME}}	GitHubユーザー名	kilbot
{{REPO_NAME}}	リポジトリ名	cash-payment-gateway
{{AUTHOR_NAME}}	自分の名前	kilbot
{{GATEWAY_ID}}	ハイフンの代わりにアンダースコアを使ったスラグ	cash_payment
{{GATEWAY_CLASS_NAME}}	各単語を大文字にし、アンダースコアで繋ぐ	Cash_Payment
{{GATEWAY_FUNCTION_PREFIX}}	ゲートウェイIDと同じ	cash_payment

次に、wcpos-{{GATEWAY_SLUG}}.phpファイル名をスラグに合わせて変更します（例：wcpos-cash-payment.php）。

ヒント

セットアップスクリプトは、名前とスラグからGATEWAY_ID、GATEWAY_CLASS_NAME、GATEWAY_FUNCTION_PREFIXを自動的に導出するため、手動セットアップ時にこれらを考えるだけで済みます。

仕組み

生成されたプラグインは、WooCommerceの決済ゲートウェイクラスを登録します。知っておくべき主な内容は以下の通りです：

• $this->enabled = 'no' — ゲートウェイはWebチェックアウトから隠されています。WCPOSはPOS設定に基づいてそれを有効にします。
• process_payment() — $order->payment_complete()を呼び出し、これにより注文が支払い済みとしてマークされ、在庫の減少を自動的に処理します。
• init_form_fields() — WooCommerceの設定に表示されるタイトルと説明フィールドを定義します。

ゲートウェイのカスタマイズ

支払いフィールドの追加

ゲートウェイがレジ係からの入力を必要とする場合（たとえば、参照番号）、payment_fields()メソッドをオーバーライドします：

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

その後、$_POST['my_gateway_reference']を通じてprocess_payment()内で提出された値を読むことができます。入力は常にsanitize_text_field()を使ってサニタイズすることを忘れないでください。

支払いの動作を変更する

デフォルトのテンプレートでは、注文がすぐに支払い済みとしてマークされます。作業フローが後での支払いを必要とする場合（請求書など）、payment_complete()を状態更新に置き換えます：

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

変更と更新を行う

ゲートウェイをインストールした後、決済のロジックを調整するためにプラグインファイルを編集し続けることができます。更新版をインストールするには：

1. 生成されたフォルダ内のwcpos-your-slug.phpを編集します
2. プラグインヘッダー内のVersion:番号を更新します（例：0.1.0から0.2.0へ）
3. フォルダをZIP圧縮し、再度プラグイン > 新規追加 > プラグインをアップロードを通じてアップロードするか、wp-content/plugins/内で直接フォルダを置き換えます。

ヒント

WordPressは、同じプラグイン名でZIPをアップロードすると、既存のプラグインを置き換えるかどうかを尋ねます — アップロードしたもので現在のものを置き換えるをクリックして更新します。

GitHubによる自動リリース

ゲートウェイをGitHubリポジトリにプッシュすると、テンプレートには自動的にリリースを作成するGitHub Actionsワークフローが含まれます：

1. プラグインヘッダー内のVersion:番号を更新します
2. mainブランチにコミットしてプッシュします
3. GitHub Actionsがバージョンの変更を検出し、ダウンロード可能なZIPを持つ新しいリリースを作成します

他のユーザーは、リポジトリのリリースページからZIPをダウンロードし、通常のWordPressプラグインと同様にインストールできます。

トラブルシューティング

ゲートウェイがPOSに表示されない

• WP Admin > プラグインでプラグインが有効になっていることを確認します
• WP Admin > WCPOS > 設定 > チェックアウトに移動し、ゲートウェイが有効化されていることを確認します
• WooCommerceがインストールされ、有効であることを確認します

ゲートウェイがWebチェックアウトに表示される

• ゲートウェイコンストラクタ内で$this->enabled = 'no';が設定されていることを確認します
• WCPOSはPOSリクエストのためにこの設定をオーバーライドしますので、ゲートウェイはPOSにのみ表示されるべきです

注文が「処理中」のままで「完了」しない

• WooCommerceは商品タイプに基づいて注文ステータスを設定します。物理的な商品を含む注文は「処理中」のままになります — これは通常のWooCommerceの動作です。仮想またはダウンロード可能な商品だけの注文は、自動的に「完了」としてマークされます。

リソース

• GitHub: woocommerce-gateway-template
• WooCommerce決済ゲートウェイAPI: WC_Payment_Gatewayドキュメント

例ゲートウェイ

これらの既存のゲートウェイは、同じアプローチで構築されており、良い参考例です：

• メール請求書 — 顧客が後で支払えるよう請求書のメールを送信
• Webチェックアウト — 支払いのためにWebストアにリダイレクト