VibeFox Adyen for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x まで。

PHP: 8.0 以降。モジュールは、これより古い PHP バージョンではインストールできません。

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 です。テスト用と本番用のキーは別々です。支払いページは Adyen がホストするため、クライアントキーは不要です。

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

インストール

1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックします。後で探す場合は、モジュール一覧から VibeFox Adyen Gateway を見つけて Configure をクリックします。

3. モジュールの設定ページ上部のライセンスブロックで、VibeFox ライセンスキーを License key に入力し、Activate をクリックします（「ライセンスキー」を参照）。

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

5. Adyen Customer Area（テストと本番）で、モジュールの Webhook セクションに表示された URL を指定して Standard webhook を追加します（設定を参照）。

6. Enable/Disable を有効にして Save をクリックします。Test mode を有効にして支払いをテストし、その後無効にします。

インストール時に、モジュールは注文ステータス Adyen payment on hold を作成します。PrestaShop は、その時点で有効な通貨、国、顧客グループについて新しい支払いモジュールを提供します。Payment > Preferences で確認して変更してください。後から追加する国は、そこでチェックを入れる必要があります。

設定

すべての設定はモジュールのページにあります。Modules > Module Manager > VibeFox Adyen Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体が保存されます。現在のモードの設定が不完全な間、ページには Adyen is hidden at checkout until the test settings are complete（または live settings）と表示され、不足している項目が一覧されます。項目は Merchant account、API キー、HMAC キー、本番モードでは Live URL prefix です。テストモードが有効な場合、ページには Test mode is on: payment links and refunds go to the Adyen test environment, no real money. と表示されます。保存時、16 進数ではない HMAC キーや、英字・数字・ハイフン以外の文字を含む本番 URL プレフィックスは保存されません。警告でフィールド名が示され、以前の値が残ります。

Adyen

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: Adyen のテスト環境を使用します（実際の金銭は発生しません）。有効にすると、支払いリンクと返金はテスト用 API キーを使って checkout-test.adyen.com に送られます。デフォルト: 有効。実際の支払いを受け付けるには無効にしてください。有効な間、購入者には支払い方法の下に Test mode: no real payment is taken. と表示されます。

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 全体を貼り付けることもできます。保存時にそこからプレフィックスが取り出されます。

保存された API キーと HMAC キーは、二度と表示されません。フィールドは空のままで、そのヒントは Saved — leave empty to keep it. で終わります。変更する場合にのみ、新しい値を入力してください。

Clear saved secrets: キーにチェックを入れて Save をクリックすると削除されます。空のフィールドでは、保存済みの値が維持されます。

Webhook

注文は Adyen のウェブフックによってのみ作成されます。Customer Area（テストと本番）で Developers > Webhooks を開き、このセクションの Webhook URL に表示された URL を指定して Standard webhook を追加してください。フレンドリー URL を使用している場合、URL は https://your-shop/module/wcp_adyen_gateway/webhook のような形になり、/en/ のような言語コードが付くこともあります。Adyen はリダイレクトに従わないため、URL は設定に表示されたとおりに正確にコピーしてください。形式として JSON を選択し、Generate HMAC key を有効にして、キーを Test HMAC key または Live HMAC key にコピーします。

各通知の環境によって使用する HMAC キーが決まります。また、通知は同じ環境と同じ加盟店アカウントで作成された支払いリンクにだけ適用されます。テスト用の通知が本番の支払いを確認することはありません。有効な署名がないウェブフックは HTTP 401 で拒否され、Adyen は後で再送します。ウェブフックがなければ、注文は作成されません。

モジュールは次のイベントを処理します。

その他のイベントは注文メモに追加されます。Customer Area のテストボタンなど、このショップのカートに関係しない通知は受け付けられ、無視されます。ウェブフックは、ショップがメンテナンスモードの間も動作し、ショップの国別制限によってブロックされることはありません。

詳細設定

Order status after payment: 成功した AUTHORISATION ウェブフックによって設定される注文ステータスです。

金額または通貨の不一致と、キャプチャの失敗は、常に Adyen payment on hold になります。

Debug log: API の呼び出しとウェブフックのイベントを、モジュールフォルダ内の logs/adyg_debug.log.php に書き込みます。このファイルは Web からは開けません。スイッチがオフでも、エラーは常に記録されます。ログには API キーや HMAC キー、購入者の個人情報は含まれません。デフォルト: 無効。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログが空になります。

Delete data on uninstall: 有効にすると、モジュールのアンインストール時に、モジュールの設定、Adyen の支払い記録（PSP リファレンス、ウェブフックイベント、返金）、ログが削除されます。注文ステータス Adyen payment on hold と注文は残ります。デフォルト: 無効。

チェックアウト

支払いの段階で、購入者は支払い方法（デフォルトは Adyen）を選択し、You will be redirected to Adyen to complete the payment securely. という注記を見ます。確定すると、モジュールはカートの合計額について、カートの通貨で Adyen の支払いリンクを作成し、購入者を Adyen の支払いページに送ります。そこで購入者は、Adyen アカウントで有効になっている任意の方法で支払います。購入者のメールアドレス、氏名、請求先の国、およびストアの言語が Adyen に渡され、支払いは Cart # とカート番号で表示されます。この時点ではまだ注文は存在しません。

支払い後、購入者はストアに戻ります。戻っただけでは、注文は作成されず、支払いも行われません。注文が支払い済みになるのは、Adyen が署名付きの AUTHORISATION ウェブフックで確認し、金額と通貨がカートと一致した場合だけです。ウェブフックが既に届いていれば、購入者には標準の注文確認ページが表示され、Your payment with Adyen has been received. と書かれています（保留中の注文の場合は Your payment with Adyen has been received and is being reviewed by the store.）。それより前に Adyen が支払いをキャンセルしていた場合、ページには Your Adyen payment was not completed. Please contact us about this order. と表示されます。ウェブフックがまだ届いていなければ、Payment confirmation ページに Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. と表示され、支払いを完了していない購入者向けに Check again と Back to checkout のボタンが付きます。

支払いが拒否された場合は注文は作成されず、購入者は再試行できます。購入者が同じカートで新しい支払いを開始すると、前の支払いリンクは期限切れになるため、そのリンクから支払うこともできなくなります。カートに既に注文がある場合、購入者は新しい支払いではなく、その注文の確認ページに移動します。

支払いリンクを作成できない場合、購入者はチェックアウトに残り、Payment could not be initiated. Please try again or choose another payment method. と表示されます。理由はログに書き込まれます。設定が不完全な場合、メッセージは Payment gateway is not configured properly. Please contact the store administrator. になります。

開発者は、フック actionAdygPaymentLinkRequest で支払いリンクのリクエストを変更できます。

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

注文と返金

注文ステータス

No order yet: 購入者は Adyen に移動しましたが、支払っていない、支払いが拒否された、または Adyen がまだ支払いを確認していません。カートだけが存在します。

Payment accepted, Delivered or Adyen payment on hold: 支払いが承認されました。ステータスは Order status after payment に従います。支払いは、Adyen PSP リファレンスをトランザクション ID として記録され、メモには金額、PSP リファレンス、支払い方法が表示されます。

Adyen payment on hold after payment: Adyen がカートの合計額と異なる金額または通貨を確認した（例: 支払いの開始後にカートが変更された）、キャプチャに失敗した、または注文のキャンセル後に支払いが届いた場合です。メモにその理由が書かれています。Customer Area で支払いを確認してから、注文を処理するか、支払いを返金してください。

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

Refunded: 支払いは、モジュールを通じて全額返金されました。

既に支払い済みの注文に、古い支払いリンクなどから 2 回目の支払い成功が届いても、注文は変更されません。メモが表示され、Customer Area で二重請求がないか確認し、必要であればそこで返金するよう求められます。

Adyen 支払いブロック

注文ページには Adyen payment ブロックが表示され、PSP リファレンス、支払いリンク、加盟店アカウントと環境、支払いステータス、支払い済み金額と返金済み金額、テスト支払い用の Test mode バッジ、返金履歴、Adyen notes が含まれます。Adyen notes には、モジュールが注文に追加するメモ（支払いの承認、金額の不一致、二重支払い、キャプチャ、キャンセル、返金結果）が新しいものから順に表示されます。これらのメモは注文の非公開メッセージであり、PrestaShop 8.2 と 9 では注文ページの他の場所には表示されません。

返金

Adyen payment ブロックで金額を入力します（まだ返金されていない金額が自動で入ります）。必要に応じて理由を入力し、Refund via Adyen をクリックします。確認の質問 Refund this amount through Adyen? This cannot be undone. に同意してください。全額返金と一部返金に対応しています。注文を編集する権限が必要です。返金は Adyen が承認した金額と通貨で行われます。そのため、金額または通貨の不一致の後は、注文合計額ではなく、購入者が実際に支払った金額まで返金できます。返金は支払いを行った環境と加盟店アカウントに送られるため、その環境の API キーが設定されている必要があります。Adyen がリクエストを受け付けない場合、ブロックにエラーが表示され、返金は記録されません。

Adyen は返金を非同期で処理します。リクエストは received ステータスで返金履歴とメモに追加され、最終的な結果は REFUND または REFUND_FAILED ウェブフックで届きます。失敗した返金は返金済みとして扱われません。送信された返金が支払い済み金額に達すると、注文は Refunded になります。一部返金ではステータスは変わりません。Adyen で手動キャプチャを使用している場合、キャプチャ済みの支払いだけを返金できます。

モジュールはクレジットスリップを作成しません。注文ページの標準の PrestaShop 返金ボタンは、Adyen を通じてお金を返金しません。Adyen Customer Area で行われた返金はウェブフックで届き、メモに追加されます。注文ステータスとクレジットスリップは自動では変更されません。

ライセンスキー

モジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Adyen Gateway は、Modules > Module Manager > VibeFox Adyen Gateway > Configure の設定の上にある最初のブロックです。キーを License key に入力し、Activate をクリックします。その後、ブロックにはキーがマスク表示され、ステータス（ライセンスの有効期限日や使用中のドメインなど）と、次のボタンが表示されます。Check now はステータスを再確認、Change key は別のキーを入力、Remove key はこのショップからキーを削除します。その下には Product: presta-payment-adyen の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントが開きます。キーを変更できるのは、このモジュールの Configure 権限を持つスタッフだけです。ブロックのテキストはバックオフィスの言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックに理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on。ショップのアドレスを変更した後や、アカウントでドメインの枠を解放した後は、Check now をクリックします。ライセンスサーバーに接続できない場合、モジュールは最後に確認できた状態で動作を続けます。

1 つのキーは 1 つのドメインで利用できます。メインショップのドメインです（マルチストア構成でも同じ）。ショップからキーを削除しても、ドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがないと、チェックアウトで購入者に Adyen は表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、バックオフィスにログインしていることを認識しないため、あなたにも支払い方法が表示されません。購入前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も機能します。

ライセンスの有効期限が切れた場合も、モジュールは動作し続けますが、アップデートとサポートには更新が必要です。バックオフィスで作業している間、ステータスは自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは必要ありません。モジュールのアンインストールやリセットを行うと、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Adyen が表示されない: ライセンスが有効であること、Enable/Disable が有効であること、現在のモードの設定が完了していることを確認してください。設定は Merchant account、そのモードの API キーと HMAC キー、本番モードでは Live URL prefix です。設定ページには不足している項目が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。

支払いは完了したが、注文が作成されない: ウェブフックが機能していません。使用している環境（テストまたは本番）の Customer Area で、Standard webhook が存在すること、その URL が Webhook URL に表示されたものと完全に一致すること、方式が JSON であることを確認してください。そのウェブフックの HMAC キーが対応するフィールド（Test HMAC key または Live HMAC key）に入っていることを確認してください。HMAC キーが無効または未入力の場合、モジュールは HTTP 401 を返し、Adyen は後で配信を再試行します。そのため、キーを修正すれば注文は自動的に作成されます。ログには Webhook rejected: invalid HMAC signature、または HMAC キーが設定されていないことが表示されます。

ウェブフックが [rejected] HMAC key not configured と応答する: 通知の環境の HMAC キーが空です。設定に貼り付けてください。

ウェブフックが [rejected] busy, retry later と応答する: 同じ時刻に別の配信がカートを処理していたか、注文を作成できませんでした（たとえばモジュールが無効になっている場合）。Adyen はウェブフックを自動的に再試行します。理由はログにあります。

ブラウザでウェブフック URL に [rejected] POST required in the browser と表示される: これは正常です。この URL は Adyen からの通知だけを受け付けます。

保存時の HMAC キーの警告: フィールドには、Customer Area の 16 進数の HMAC キーが入っている必要があります。以前の値が保持されました。

購入者に Payment could not be initiated と表示される: モジュールのページにある Log フィールドを確認してください（エラーは常に記録されます）。API キー、加盟店アカウント、本番モードの場合は本番 URL プレフィックスを確認してください。

支払い後に注文が Adyen payment on hold になる: 注文のメモを読んでください。Adyen が確認した金額または通貨がカートと一致しなかった、キャプチャに失敗した、またはキャンセル後に支払いが届いた、といった理由が考えられます。Order status after payment の設定が原因の場合もあります。

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

アンインストール

Modules > Module Manager を開き、VibeFox Adyen Gateway の横のメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall が有効な場合、モジュールの設定、Adyen の支払い記録（PSP リファレンス、ウェブフックイベント、返金）、ログが削除されます。無効な場合は、後で再インストールできるようにすべて残されるため、以前に支払われた注文を引き続き返金できます。注文ステータス Adyen payment on hold は常に残ります。既存の注文は、支払いのメモとトランザクション ID を保持します。

Adyen は、各所有者の商標です。このモジュールは Adyen と提携しておらず、Adyen による推奨も受けていません。