VibeFox Adyen for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 7.0 以降がインストールされ、有効になっていること。これがないと、プラグインは有効化できません。

PHP: 8.0 以降。

Adyen アカウント: 使用する環境（テストと本番）ごとに、Adyen の加盟店アカウント名、API キー、HMAC キーが必要です。本番の支払いには、本番 URL プレフィックスも必要です。API キーは、Checkout webservice と Merchant PAL webservice のロールを持つ API 認証情報に属している必要があります。HMAC キーは Standard webhook 用に生成されます（「設定」の項を参照）。テスト用の Customer Area は ca-test.adyen.com、本番用は ca-live.adyen.com です。テストと本番のキーは別々です。

VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

1. WordPress で Plugins > Add New > Upload Plugin に進み、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_adyen_gateway フォルダーを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。

3. 設定を開きます: WooCommerce > Settings > Payments > Adyen > Manage。または、プラグインページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンス欄に VibeFox ライセンスキーを入力し、Activate をクリックします。

5. 加盟店アカウント、テストの API キーと HMAC キーを入力します。本番の API キー、本番の HMAC キー、本番 URL プレフィックスは、後で入力します。

6. Adyen の Customer Area（テストと本番の両方）で、プラグイン設定に表示された URL を使って Standard webhook を追加します（「設定」の項を参照）。

7. Enable/Disable をオンにします。Test mode をオンにした状態で支払いをテストし、その後チェックを外します。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Adyen。現在のモードの設定が未完了の間、ページには Adyen is hidden at checkout until the test settings are complete（本番の場合は live settings）と表示され、不足している項目が一覧表示されます。項目は Merchant account、API キー、HMAC キー、本番モードでは Live URL prefix です。保存時に、16 進数ではない HMAC キーや、英字、数字、ハイフン以外の文字を含む本番 URL プレフィックスはエラーとともに拒否され、以前の値が保持されます。

一般

Enable/Disable: Enable Adyen payment gateway で支払い方法をオンまたはオフにします。既定値はオフです。

Title: 購入者がチェックアウトで見る支払い方法の名前。既定値: Adyen。

Description: チェックアウトで支払い方法の下に表示される説明文。既定値: Pay securely via Adyen.

Adyen アカウント

API キーは Adyen の Customer Area の Developers > API credentials で作成します。両方のキーのセットを入力してください。Test mode のスイッチで、どちらを使用するかを選択します。

Test mode: Use the Adyen test environment (no real money)。オンの場合、支払いリンクと返金は、テスト API キーを使って checkout-test.adyen.com に送られます。既定値はオンです。実際の支払いを受け付けるには、チェックを外してください。

Merchant account: Adyen の加盟店アカウント名（会社のアカウントではありません）。例: MyShopECOM。通常、テストと本番の Customer Area で同じ名前です。

テスト用の認証情報

Test mode が有効な間に使用されます。

Test API key: テスト用の Customer Area から取得: Developers > API credentials > お使いの認証情報 > API key。

Test HMAC key: テスト用の Customer Area から取得: Developers > Webhooks > お使いの Standard webhook > HMAC key（16 進数）。必須です。有効な署名のないウェブフックは拒否されます。

本番用の認証情報

Test mode がオフの場合に使用されます。

Live API key: 本番用の Customer Area から取得: Developers > API credentials > お使いの認証情報 > API key。

Live HMAC key: 本番用の Customer Area から取得: Developers > Webhooks > お使いの Standard webhook > HMAC key（16 進数）。

Live URL prefix: 本番用の Customer Area から取得: Developers > API URLs。例: https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com からの 1797a841fbb37ca7-AdyenDemo。URL 全体を貼り付けることもできます。保存時に、URL からプレフィックスが取り出されます。

ウェブフック

注文が支払い済みになるのは、Adyen のウェブフックによる場合だけです。Customer Area（テストと本番の両方）で Developers > Webhooks に移動し、この設定ページの本項に表示された URL を使って Standard webhook を追加します。URL は https://your-site/wc-api/adyg_adyen_webhook/ のような形式です。メソッドとして JSON を選択し、Generate HMAC key をオンにして、キーを Test HMAC key または Live HMAC key にコピーします。各通知の環境によって、使用される HMAC キーが決まります。有効な署名のないウェブフックは拒否され、Adyen は後で再送します。ウェブフックがないと、注文は支払い待ちのままになります。

プラグインは次のイベントを処理します:

その他のイベントは、注文メモに追加されます。Customer Area のテストボタンなど、このストアの注文に関係のない通知は受け付けられ、無視されます。

詳細設定

Order status after payment: 支払い成功後に、1 回のステータス変更で設定される注文ステータス。

Debug log: Log API calls and webhook events を、WooCommerce > Status > Logs のソース wcp_adyen_gateway に記録します。エラーは常に記録されます。ログに API キー、HMAC キー、購入者の個人情報が含まれることはありません。既定値はオフです。

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted。既定値はオフです。

チェックアウト

購入者は支払い方法（既定では Adyen）を選び、注文を確定します。プラグインは、注文の通貨で注文合計額の Adyen 支払いリンクを作成し、購入者を Adyen の決済ページに移動させます。そこで購入者は、Adyen アカウントで有効になっている任意の方法で支払います。購入者の請求先メールアドレス、氏名、国、ストアの言語が Adyen に渡され、支払いには Order # と注文番号が表示されます。

支払い後、購入者はストアの注文受付ページに戻ります。この戻りだけでは注文は支払い済みになりません。注文が支払い済みになるのは、Adyen が署名付きの AUTHORISATION ウェブフックで確認し、金額と通貨が注文と一致した後だけです。

支払いが拒否された場合、注文は失敗になり、購入者は再試行できます。購入者が同じ注文で新しい支払いを開始すると（例えば Pay for order ページから）、前の支払いリンクは期限切れになるため、そちらで支払うこともできません。

支払いリンクを作成できない場合、購入者には Payment could not be initiated. Please try again or choose another payment method. と表示されます。理由は注文メモに追加されます。設定が未完了の場合、購入者には Payment gateway is not configured properly. Please contact the store administrator. と表示されます。

JPY、KRW、IDR、VND など小数点のない通貨では、WooCommerce > Settings > General > Number of decimals を 0 に設定してください。そうしないと、合計額が整数単位に丸められます。

この支払い方法は、クラシックチェックアウトとチェックアウトブロックの両方で動作します。WooCommerce の高性能注文ストレージ（HPOS）に対応しています。

このプラグインには、サブスクリプションや定期払い、カードの保存、サイト上のカード入力欄（Drop-in または Components）、WooCommerce のキャプチャやキャンセルのボタン、ウェブフックのベーシック認証はありません。

注文と返金

注文ステータス

Pending payment: 支払いリンクが作成されましたが、Adyen はまだ支払いを確認していません。注文メモには、支払いリンク、金額、環境が表示されます。

Processing, Completed or On Hold: 支払いが承認されました。ステータスは Order status after payment に従います。注文メモには、金額、PSP リファレンス、支払い方法が表示されます。トランザクション ID は Adyen の PSP リファレンスです。

On hold after payment: Adyen が注文合計と異なる金額または通貨を確認しました。注文メモには両方の値が表示され、注文は支払い済みにはなりません。キャプチャに失敗した場合も、お金が回収されていないため、支払い済みの注文は保留になります。Customer Area で支払いを確認してください。

Failed: 支払いが拒否されました。支払い済み、保留、キャンセルの注文は、拒否された支払いによって変更されません。

Cancelled: この注文の支払いが Adyen でキャンセルされました。

すでに支払い済みの注文に対して 2 回目の支払いが成功した場合（例えば古い支払いリンクから）、その注文は再び変更されません。注文メモには、Customer Area で二重の請求がないか確認し、必要に応じてそこで返金するよう表示されます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Adyen をクリックします。全額返金と一部返金に対応しています。返金は、支払いを行った環境と加盟店アカウントに送られるため、その環境の API キーが設定されている必要があります。Adyen は返金を非同期で処理します。リクエストは注文に記録され、最終結果は REFUND または REFUND_FAILED のウェブフックによって注文メモとして追加されます。Adyen がリクエストを受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。Adyen で手動キャプチャを使用している場合、キャプチャ済みの支払いのみ返金できます。

Adyen の Customer Area で行われた返金は、ウェブフックによって届き、注文メモに追加されます。WooCommerce の返金として自動的に記録されることはありません。

ライセンスキー

このプラグインは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンス欄は WooCommerce > Settings > Payments > Adyen の上部にあります。キーを License key に貼り付け、Activate をクリックします。ライセンス欄には、ステータス（例: ライセンスが有効な期限の日付）とドメインが表示されます。Check now でステータスを再確認、Change key で別のキーを入力、Remove key でこのサイトからキーを削除できます。リンク Manage licenses and domains in your account から vibefox.net のアカウントを開けます。

1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、チェックアウトで Adyen は購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログインしているストア管理者には、(unlicensed — visible to admins only) と表記された支払い方法が引き続き表示されるため、キーを購入する前にプラグインを設定してテストできます。プラグインのページと WooCommerce のページにはリマインダーが表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も動作します。

ライセンスの期限が切れてもプラグインは動作し続けますが、アップデートとサポートには更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに Adyen が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの設定が完了していることを確認してください。具体的には、Merchant account、そのモードの API キーと HMAC キー、本番モードでは Live URL prefix です。設定ページに不足している項目が表示されます。

支払いは完了したが、注文が Pending payment のまま: ウェブフックが機能していません。使用している環境（テストまたは本番）の Customer Area で、Standard webhook が存在すること、その URL が設定に表示されたものと正確に一致すること、メソッドが JSON であることを確認してください。そのウェブフックの HMAC キーが、対応する欄（Test HMAC key または Live HMAC key）に入っているか確認します。HMAC キーが無効または未入力の場合、プラグインは HTTP 401 で応答し、Adyen はキーを修正した後に再送するため、注文は自動的に更新されます。ログには Webhook rejected: invalid HMAC signature、または HMAC キーが設定されていないことが表示されます。

ウェブフックが busy, retry later と応答する: 同じ時刻に別の通知で注文が処理されていました。Adyen がウェブフックを自動的に再送します。

保存時に HMAC キーのエラーが出る: この欄には、Customer Area の 16 進数の HMAC キーを入力する必要があります。以前の値が保持されました。

購入者に Payment could not be initiated と表示される: 注文メモを開くか、Debug log をオンにして WooCommerce > Status > Logs をソース wcp_adyen_gateway で確認してください。API キー、加盟店アカウント、本番モードでは本番 URL プレフィックスを確認します。

支払い後に注文が On hold になっている: 注文メモを読んでください。Adyen が確認した金額または通貨が注文と一致しなかったか、キャプチャに失敗しました。Order status after payment の設定が原因の場合もあります。

返金が失敗する: 注文には Adyen の PSP リファレンスが必要で、これは AUTHORISATION ウェブフックで届きます。支払いが行われた環境の認証情報が設定されている必要があります。手動キャプチャの場合、キャプチャ済みの支払いのみ返金できます。

ライセンス欄にエラーが表示される: ライセンス欄のメッセージに従ってください。例えば、キーが別のドメインですでに使用されている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスを変更した場合は、Check now をクリックして新しいドメインでキーを有効化します。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作し続けます。

アンインストール

プラグインを無効化してもすべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは常に削除されます。ゲートウェイの設定と、注文に保存された Adyen のデータ（PSP リファレンス、支払いリンク、処理済みイベント）は、Delete data on uninstall がオンだった場合にのみ削除されます。それ以外の場合は、再インストールのために残ります。既存の注文は、支払いメモとトランザクション ID を保持します。

Adyen は、それぞれの所有者の商標です。このプラグインは Adyen と提携しておらず、Adyen による推奨も受けていません。