VibeFox Peach Payments for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

PHP：OpenSSL 拡張機能を備えた 8.0 以降（ウェブフックの復号に使用します）。これらがない場合、モジュールはインストールできません。

通貨：カートの通貨は ZAR、KES、MUR のいずれかである必要があります。それ以外の通貨のカートでは、決済方法が表示されません。ショップのデフォルト通貨がこれらのいずれでもない場合、設定ページに警告が表示されます。

Peach Payments アカウント：Peach Payments アカウントの Card API 認証情報、つまり Entity ID と Access Token が必要です。テスト用の認証情報は Peach Payments のサンドボックスダッシュボードから、本番用の認証情報は Peach Payments のダッシュボードから取得します。両者は異なります。ウェブフックには、Peach Payments がショップの Card ウェブフックを有効にする際に送付するウェブフック復号キーも必要です（設定を参照してください）。ウェブフックを受信するには、ショップがインターネットからアクセスできる必要があります。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。または、後でモジュール一覧から VibeFox Peach Payments Pay Gateway を探し、Configure をクリックします。

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

4. Peach Payments のサンドボックスダッシュボードからテスト用の Entity ID と Access Token を入力し、設定ページに表示されるウェブフック URL に対して Card ウェブフックを有効にするよう Peach Payments に依頼します（設定を参照してください）。

5. Enable/Disable をオンにして Save をクリックします。Test mode はオンのままにして、Peach Payments のサンドボックステストカードで決済を行います。その後 Test mode をオフにし、本番の認証情報と本番のウェブフックキーを入力して、Save をクリックします。

インストール時に、モジュールは 2 つの注文ステータスを作成します：Awaiting Peach Payments payment と Peach Payments payment on hold。PrestaShop は、その時点で有効な通貨、国、顧客グループに対して新しい決済モジュールを提供します。後から追加した国は、Payment > Preferences でこのモジュールに対して有効にする必要があります。同じ画面で国を制限することもできます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上にはページのお知らせが表示されます：Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.。現在のモードの Entity ID または Access Token がない場合はエラーになります（それまでは決済画面に決済方法が表示されません）。現在のモードのウェブフック復号キーがない場合は警告になります（この場合、購入者がショップに戻ったときにのみ決済が確認されます）。ショップのデフォルト通貨がサポートされていない場合はエラーになります。保存時には認証情報から空白が削除されます。また、64 文字の 16 進数ではないウェブフックキーは警告で通知されます。

Peach Payments

Enable/Disable：Enable Peach Payments で決済方法のオン／オフを切り替えます。デフォルト：オフ。

Title：決済画面で購入者に表示される決済方法の名前です。注文にも決済方法の名前として保存されます。デフォルト：Credit / Debit Card (Peach Payments)。必須です。

Description：決済画面で決済方法の下に表示されるテキストです。デフォルト：Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

API credentials

Card API の Access Token と Entity ID は、Peach Payments のダッシュボードに表示されます（テスト用の認証情報はサンドボックスダッシュボードにあります）。このセクションには両方のダッシュボードと Peach Payments の開発者向けドキュメントへのリンクがあります。

Test mode：テスト用の認証情報を使って、新しい決済を Peach Payments のサンドボックスに送信します。実際の料金は請求されません。オフにすると、本番の認証情報で実際の決済を受け付けます。あるモードで開始された決済は、切り替えた後も必ずそのモードで確認されます。デフォルト：オン。

Test Entity ID：サンドボックスアカウントの Entity ID（3-D Secure チャネル）です。

Test Access Token：サンドボックスアカウントの bearer アクセストークンです。

Test Webhook Decryption Key：サンドボックスの Card ウェブフックを復号するための 64 文字の 16 進数キーです。

Live Entity ID：本番アカウントの Entity ID（3-D Secure チャネル）です。

Live Access Token：本番アカウントの bearer アクセストークンです。

Live Webhook Decryption Key：本番アカウントの Card ウェブフックを復号するための 64 文字の 16 進数キーです。

保存済みのアクセストークンとウェブフックキーは、二度と表示されません。フィールドは空のままになり、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。

Clear saved secrets：アクセストークンまたはウェブフックキーにチェックを入れ、Save をクリックすると削除されます。フィールドが空の場合は保存済みの値が保持されます。

Webhook

ウェブフックは、購入者がショップに戻る前にブラウザーを閉じた場合でも決済を確認します。Webhook URL フィールドには、ショップのウェブフック URL が表示されます。フレンドリー URL を使用している場合は、https://your-shop/module/wcp_peach_pay/webhook のような形式になり、/en/ のような言語コードが含まれることもあります。設定に表示されたとおりに URL をコピーしてください。この URL で、アカウントの Card ウェブフックを有効にするよう Peach Payments（support@peachpayments.com）に依頼し、受け取った復号キーを同じモードの Webhook Decryption Key フィールドに入力してください。

Peach Payments はすべてのウェブフックを暗号化します（AES-256-GCM）。テスト用キーまたは本番用キーのいずれでも復号できないウェブフックは拒否されるため、注文を変更できるのは Peach Payments だけです。あるモードのキーで復号されたウェブフックは、そのモードで開始された決済にのみ適用されます。モジュールは次の決済通知を使用します：

その他の通知（ウェブフックを有効にしたときに送信されるテスト通知など）には ignored と応答されます。ウェブフックキーがない場合、購入者が決済後にショップへ戻ったときにのみ注文が作成されます。

Payment form

Card brands：Peach Payments のフォームに表示されるブランドです：Visa、Mastercard、American Express、Diners Club。Entity ID で有効になっているブランドのみを選択してください。デフォルト：Visa と Mastercard。ブランドが 1 つも選択されていない場合、保存時に警告が表示され、フォームには Visa と Mastercard が表示されます。

Advanced

Logging：API リクエストと決済結果を、モジュールフォルダー内の logs/peach_p_debug.log.php に記録します。このファイルはウェブから読み取ることはできません。エラーと警告は常に記録されます。ログにはカード情報、キー、購入者データは含まれません。デフォルト：オフ。

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

Delete data on uninstall：オンの場合、モジュールをアンインストールすると、モジュールの設定とログが削除されます。注文に関する Peach Payments のデータ（決済の試行、決済 ID）と注文ステータスは注文に属するため、保持されます。デフォルト：オフ。

チェックアウト

購入者は決済方法（デフォルトは Credit / Debit Card (Peach Payments)）を選択し、注文を確定します。テストモードでは、決済方法に Test mode: no real payment will be made. と表示されます。モジュールは、カートの金額をカートの通貨で Peach Payments のチェックアウトとして準備し、ショップの Peach Payments payment ページに、Peach Payments のカードフォームと選択されたカードブランドを表示します。Peach Payments が対応している場合は、購入者の言語で表示されます。テストモードでは、このページに Test mode: use a Peach Payments test card, no real payment will be made. と表示されます。カード情報は Peach Payments のフォームに入力され、フォームのスクリプトは Subresource Integrity ハッシュ付きで読み込まれます。Choose another payment method のリンクでチェックアウトに戻ります。この時点ではまだ注文は存在しません。ページを再読み込みした場合、カートが変更されていなければ、同じチェックアウトが最大 25 分間再利用されます。

決済後、購入者はショップに戻ります。注文は Peach Payments が確認してから初めて支払い済みになります。ショップは、チェックアウトを作成したモードで、Peach Payments API からこのカートのチェックアウト結果を取得し、決済がこのカートに属していることを確認します。ウェブフックも独立して同じ処理を行うため、先に届いた方が注文を作成し、もう一方は何も変更しません。その後、購入者には標準の注文確認ページが表示されます。

決済が完了しなかった場合、購入者はメッセージとともにチェックアウトに戻り、再度試すことができます：Payment failed: の後に Peach Payments から通知された理由が続き、Please try again or use another card.、または The payment was not completed. Please try again. と表示されます。カートは保持されます。結果をまだ確認できない場合（たとえば Peach Payments が応答しなかった、またはウェブフックがちょうど同じカートを処理している場合）は、We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. と表示されます。決済のモードにウェブフックキーが設定されていない場合は、代わりにショップへの問い合わせを促すメッセージが表示されます。

決済フォームを準備できない場合、購入者はチェックアウトに留まり、短いメッセージが表示されます：The payment form is not available right now (payment configuration error). Please contact us or choose another payment method.（認証情報がない、または誤っている場合）、一部の請求情報が決済プロバイダーに受け付けられなかったというメッセージ、または The payment form could not be loaded. Please try again in a moment. のいずれかです。技術的な理由はログに記録されます。

ウェブフックは、ショップがメンテナンスモードの間も動作し、ショップの国別制限にはブロックされません。

モジュールには、チェックアウトのステップ自体にカードフォームはなく、保存済みカード、定期購入、事前承認とキャプチャ、EFT、BNPL、QR その他カード以外の決済方法にも対応していません。

注文

注文ステータス

No order yet：購入者が支払っていない、決済が拒否または未完了になった、または Peach Payments がまだ確認していない状態です。カートだけが存在し、購入者は再度決済できます。

Payment accepted：決済が確認され、金額と通貨がカートと一致した状態です。決済は Peach Payments の決済 ID をトランザクション ID として記録され、メモには Peach Payments の結果コード、説明、決済 ID が表示されます。Peach Payments が決済を手動確認対象としてマークした場合、メモで出荷前に Peach Payments ダッシュボードで確認するよう求められます。

Awaiting Peach Payments payment：Peach Payments が確認待ちの決済を報告した状態です。その後ウェブフックにより、注文は Payment accepted に移行するか、失敗としてマークされます。

Peach Payments payment on hold：支払われた金額または通貨がカートと異なる状態（メモ：amount/currency mismatch — manual review required）、または注文がキャンセルされた後に決済が届いた状態です。メモには確認すべき内容が説明されています。Peach Payments ダッシュボードで決済を確認してから、注文を処理するか、決済を返金してください。

Payment error：Peach Payments が、確認待ちの注文が待っていた決済を拒否した状態です。拒否された試行によって、支払い済み、保留中、またはキャンセル済みの注文が変更されることはありません。

支払い済みの注文に対する 2 回目の決済が成功しても、注文は変更されません。メモには重複決済であることが示され、Peach Payments ダッシュボードで返金するよう求められます。返金済みの注文に届いた決済は、注文にメモとして記録されるだけです。

Peach Payments 決済ブロック

注文ページには Peach Payments payment ブロックが表示されます。決済 ID、チェックアウト ID、加盟店トランザクション ID、Peach Payments に送信された金額、結果と結果コード、テスト決済の Test mode バッジ、そして注文の Peach Payments notes が含まれます。

返金

PrestaShop の注文ページからの返金はできません。Peach Payments ダッシュボードで決済を返金し、必要に応じて PrestaShop にも記録してください（部分返金またはクレジットスリップ）。ウェブフックを設定している場合、Peach Payments で行われた返金、取り消し、チャージバックは、金額と ID とともに注文メモに追加されます。注文ステータスは変わりません。

ライセンスキー

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

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

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

有効なキーがない場合、決済画面で購入者に Peach Payments は表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. が表示されます。PrestaShop のショップフロント画面は、管理画面にログインしていることを認識しないため、決済方法はあなたに対しても非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された決済は、購入者の帰還とウェブフックによって引き続き確認されます。

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

トラブルシューティング

チェックアウトに Peach Payments が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの Entity ID と Access Token が入力されていること（テストモードでは Test Entity ID と Test Access Token、本番モードでは Live Entity ID と Live Access Token）、カートの通貨が ZAR、KES、MUR のいずれかであることを確認してください。設定の上部の通知が問題を示しています。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループについてモジュールが許可されていることも確認してください。

決済は完了したが、注文が作成されなかった：購入者がショップに戻らず、ウェブフックも届いていません。Peach Payments が設定に表示された URL に対して Card ウェブフックを有効にしていること、決済を行ったモードの Webhook Decryption Key が入力されていること、そしてファイアウォールやパスワード保護がこの URL をブロックしていないことを確認してください。Logging をオンにして、Log フィールドで拒否されたウェブフックを確認してください。

ウェブフックが Decryption failed と応答する：テスト用キーでも本番用キーでも、ウェブフックを復号できませんでした。キーが誤っているか、別のアカウントまたはモードのものです。この Webhook URL に対して Peach Payments から送られたキーを入力してください。

ウェブフックが Webhook key not configured と応答する：テスト用と本番用のウェブフックキーがいずれも設定されていない、または有効ではありません。64 文字のキーを入力してください。Peach Payments は後で再送します。

ウェブフックが Busy, retry later と応答する：同じタイミングで購入者の帰還によってカートが処理されていた、または注文を作成できなかった（たとえばモジュールが無効になっている）ことを意味します。何も変更されず、Peach Payments はウェブフックを再送します。理由はログに表示されます。

ウェブフックが Missing or malformed data と応答する：リクエストに暗号化された本文、または X-Initialization-Vector / X-Authentication-Tag ヘッダーがありませんでした（たとえばプロキシがリクエストを変更した場合）。何も変更されていません。

ウェブフックが ignored と応答する：通知は正規のものですが、このショップのチェックアウトに属していない（同じ Entity ID を使う別のショップ、削除されたカート）か、決済とは別のモードから届いています。何も変更されていません。

ブラウザーでウェブフック URL に Method not allowed と表示される：これは正常です。この URL は Peach Payments からのリクエストのみを受け付けます。

購入者に The payment form is not available right now と表示される：現在のモードの Access Token または Entity ID が誤っています。認証情報とモードを確認し、Peach Payments のコードをログで確認してください。

決済後に注文が Peach Payments payment on hold になる：Peach Payments payment ブロックのメモを確認してください。支払われた金額または通貨がカートと異なっていたか、注文がキャンセルされた後に決済が届いています。Peach Payments ダッシュボードで決済を確認してから、注文を処理するか、決済を返金してください。

保存時に、ウェブフックキーは 64 文字の 16 進数キーである必要があると表示される：入力された値は Peach Payments から提供されたキーではありません。修正されるまで、ウェブフックは復号できません。

アンインストール

Modules > Module Manager に移動し、VibeFox Peach Payments Pay Gateway の横にあるメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。決済の試行、決済 ID、Awaiting Peach Payments payment と Peach Payments payment on hold の注文ステータスは、常に保持されます。既存の注文は、決済メモ、トランザクション ID、Peach Payments のチェックアウトデータを保持します。

Peach Payments は、各所有者の商標です。本モジュールは Peach Payments との提携や承認を受けたものではありません。