VibeFox PayFast for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x まで。

PHP：8.0 以降。古いバージョンの PHP ではモジュールをインストールできません。

通貨：南アフリカ・ランド（ZAR）。PayFast はランドでのみ決済されるため、カートは ZAR である必要があります。ストアにまだ通貨がない場合は、International > Localization > Currencies で追加してください。最低注文金額は R5.00 です。

PayFast アカウント：PayFast の Merchant ID と Merchant Key。PayFast のダッシュボードの Settings > Developer Settings で確認できます。パスフレーズの設定を強くお勧めします。PayFast でパスフレーズを設定している場合は、同じパスフレーズをモジュールにも入力する必要があります。テストには PayFast サンドボックスの認証情報が必要です。

アクセス可能なストア：支払い通知の URL は、ベーシック認証やファイアウォールによるブロックなしで、インターネットからアクセスできる必要があります。

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

インストール

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

2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox PayFast Pay Gateway を探し、Configure をクリックすることもできます。

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

4. Merchant ID、Merchant Key、パスフレーズを入力します。テスト時は Test mode をオンのままにし、サンドボックスの認証情報を入力します。

5. Enable/Disable をオンにして Save をクリックします。テスト支払いを行ったあと、実際の支払いを受け付けるために Test mode をオフにします。

インストール時に、モジュールは 2 つの注文ステータスを作成します：Awaiting PayFast payment と PayFast payment on hold。PrestaShop は、すべての通貨・国・顧客グループに対して新しい支払いモジュールを提供します。Payment > Preferences で制限できます。ランドについてモジュールが許可されたままになっていることを確認してください。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。項目の上部では、現在のモードの認証情報が空の場合（その場合、PayFast は決済時に非表示になります）、既定のストア通貨が ZAR でない場合、本番モードで公開サンドボックスの Merchant ID 10000100 が使われている場合、パスフレーズが設定されていない場合に警告が表示されます。テストモードがオンで、モジュールが有効な間は、テストモードがオンです：注文は PayFast サンドボックスで支払われ、実際の料金は請求されません。 と表示されます。Title が空の場合は、支払い方法のタイトルを入力してください。 というメッセージで保存できません。

PayFast

Enable/Disable：Enable PayFast は、この支払い方法を有効または無効にします。既定値：オフ。

Title：決済時に購入者に表示される支払い方法の名称。注文にも支払い方法の名称として保存されます。既定値：PayFast。必須。

Description：決済時に支払い方法の下に表示されるテキスト。既定値：Pay securely by card, Instant EFT and other methods on the PayFast payment page.

PayFast アカウント（本番）

Merchant ID と Merchant Key は、PayFast のダッシュボードの Settings > Developer Settings で確認できます。そこでパスフレーズを設定している場合は、まったく同じものをここに入力してください。

Merchant ID：本番用の PayFast Merchant ID。

Merchant Key：本番用の PayFast Merchant Key。すべての支払いフォームとともに PayFast に送信されるため、通常のテキスト項目です。

Passphrase：PayFast の Settings > Developer Settings にあるソルト用のパスフレーズ。設定を強くお勧めします。支払いと通知に署名します。

サンドボックス（テストモード）

テストモードでは、支払いは PayFast のサンドボックスに送られ、実際の料金は請求されません。サンドボックスの認証情報は、PayFast のサンドボックスにログインすると表示されます（公開テスト用の加盟店は 10000100 / 46f0cd694581a です）。

Test mode：Use the PayFast sandbox and the sandbox credentials below。オンの間、購入者は支払い方法の下に テストモード：支払いは PayFast のサンドボックスに送られ、実際の料金は請求されません。 と表示されます。既定値：オン。

Sandbox Merchant ID：サンドボックスアカウントの Merchant ID。

Sandbox Merchant Key：サンドボックスアカウントの Merchant Key。

Sandbox Passphrase：サンドボックスアカウントにパスフレーズが設定されている場合のみ。

保存されたパスフレーズは再表示されません。項目は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。

Clear saved passphrases：Passphrase または Sandbox Passphrase にチェックを入れて Save をクリックすると削除されます。空の項目では保存済みの値が維持されます。

支払い通知（ITN）

Notification URL：PayFast は、ここに表示される URL へサーバー間通知を送って、すべての支払いを確認します。フレンドリー URL を使う場合は https://your-shop/module/wcp_payfast_pay/itn のような形になり、既定の言語のコードが付くこともあります。このアドレスはすべての支払いとともに送信されるため、PayFast 側で設定する必要はありませんが、インターネットからアクセスできる必要があります。注文は検証済みのこれらの通知によってのみ作成されます。購入者がストアに戻っても、注文は作成されず、支払いも行われません。

Source check：本番の通知は PayFast のサーバーからのものだけを受け入れます。アドレスは PayFast の DNS レコード（6 時間キャッシュ）と、PayFast が公開しているアドレス範囲から取得されます。ストアが訪問者のアドレスを隠すプロキシまたは CDN の背後にある場合にのみ無効にしてください。署名とサーバー確認は常に検証されます。サンドボックスの通知はアドレスでは検証されません。既定値：オン。

詳細設定

Debug log：支払いの各段階をモジュールフォルダー内の logs/payfast_p_debug.log.php に記録します。このファイルは Web から開けません。エラーと警告は、スイッチがオフでも常に記録されます。パスフレーズや購入者の情報は書き込まれません。既定値：オフ。

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

Uninstall：Delete the gateway settings when the module is uninstalled（設定、キャッシュされた PayFast のアドレス、ログ）。PayFast の支払い記録、注文、注文ステータスは常に保持されます。既定値：オフ。

決済

支払いの段階で、購入者は支払い方法（既定では PayFast）を選んで確定します。ご注文ありがとうございます。PayFast の支払いページへ移動しています。 と表示されるページが、署名付きの支払いフォームを自動的に PayFast へ送信します。ブラウザが自動で進まない場合、購入者が Pay with PayFast をクリックします。Cancel をクリックすると決済に戻ります。フォームには、ZAR でのカートの合計額、カート番号を含む Cart #、購入者の氏名とメールアドレス、支払い参照番号（カート番号と試行回数）、そしてその試行のランダムなトークンが含まれます。この時点ではまだ注文は存在しません。新しい試行ごとに、新しい参照番号とトークンが割り当てられます。

PayFast のページで、購入者はカード、Instant EFT、または PayFast アカウントの他の方法で支払います。その後 PayFast は支払い通知（ITN）をストアに送信します。注文は、PayFast がすべての検証を通過した通知によって支払いを確認したあとにのみ、支払い済みとしてマークされます。

同じカートの通知は、1 件ずつ処理されます。同じカートの別の通知が処理中の場合、PayFast はエラー応答を受け取り、通知を再送します。通知 URL は、ストアがメンテナンスモードの間も機能し、ストアの国別制限によってブロックされることはありません。

購入者が戻ってきて注文が存在する場合は、標準の注文確認ページが表示されます。PayFast が支払いを保留と報告した場合は、PayFast が支払いを確認しています。確認が完了次第、メールでお知らせします。再度お支払いいただく必要はありません。 と表示されます。注文が保留中の場合は、お支払いは確認中です。他に必要な情報があればご連絡します。 と表示されます。保留中の支払いが後で失敗した場合は、PayFast でのお支払いは完了しませんでした。この注文についてお問い合わせください。 と表示されます。通知がまだ届いていない場合は、Payment confirmation ページが表示され、PayFast が支払いを確認していること、PayFast が確認した時点で注文が作成されることを伝えます。ボタンは Check again と Back to checkout です。

購入者が PayFast のページでキャンセルすると、決済に戻り、PayFast での支払いはキャンセルされました。もう一度試すか、別の支払い方法を選んでください。 と表示されます。PayFast が支払いを失敗と報告した場合は、お支払いは完了しませんでした。もう一度試すか、別の支払い方法を選んでください。 と表示されます。カートは保持され、再度支払うことができます。

現在のモードの認証情報が不足している場合、カートの通貨が ZAR でない場合やモジュールで許可されていない場合、または合計額が R5.00 未満の場合は、支払い方法が非表示になります。それでも購入者が支払いの段階に進んだ場合は、短いメッセージで説明します（例：PayFast は R5.00 以上の支払いを受け付けます。別の支払い方法を選んでください。）。

このモジュールは ZAR での単発決済のみを受け付けます。注文画面からの返金、サブスクリプション、保存された（トークン化された）カード、分割決済には対応していません。

注文

注文ステータス

No order yet：購入者は PayFast に移動しましたが、支払い通知がまだ届いていないか、PayFast が支払いを失敗と報告しました。カートのみが存在します。

Payment accepted：PayFast が支払いを確認しました。支払いは PayFast の支払い ID をトランザクション ID として記録され、備考には支払い ID が表示されます。サンドボックスの支払いには、実際の料金は請求されていないという備考が付きます。

Awaiting PayFast payment：PayFast が支払いを保留と報告しました。PayFast が支払いを完了すると、注文は Payment accepted に移ります。

Payment error：保留中の支払いが失敗しました。PayFast が後で完了させた場合、注文は Payment accepted になります。

PayFast payment on hold：支払われた金額がカートの合計額と異なる、またはカートが ZAR ではない場合。キャンセルされた注文、または支払い方法がもう PayFast ではない注文に対して支払いが届いた場合。ゲートウェイが本番モードの間にサンドボックスの支払いが届いた場合。PayFast が受け取った金額は注文に記録され（サンドボックスの支払いは除く）、備考に理由が記されます。注文と PayFast のダッシュボードを確認したうえで、注文を Payment accepted に設定するか、注文をキャンセルして PayFast で支払いを返金してください。

同じ支払いに対する繰り返しの通知は、何も変更しません。遅れて届いた失敗または保留の通知は、支払い済みの注文を決して変更しません。すでに支払い済みの注文に対して別の完了した支払いが届いた場合、備考で重複分を PayFast で返金するよう求められます。返金済みの注文に対する支払いは、備考を追加するだけです。

PayFast 支払いブロック

注文ページには PayFast payment ブロックが表示され、支払い参照番号（m_payment_id）、PayFast の支払い ID、環境（本番またはサンドボックス）、ステータス、ZAR での総額・手数料・正味額、およびモジュールの備考が示されます。保留中の注文については、支払いの確認を促すリマインダーが表示されます。

返金

注文ページからの返金には対応していません。PayFast のダッシュボードで支払いを返金し、その後 PrestaShop で注文を手動で更新してください。

ライセンスキー

このモジュールは、vibefox.net で取得した VibeFox ライセンスキーを使用します。ライセンスブロック License — VibeFox PayFast Pay Gateway は、Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure ページの最初のブロックで、設定の上にあります。キーを License key に入力し、Activate をクリックします。その後、このブロックにはキーがマスク表示され、ステータス（例：ライセンスの有効期限の日付とドメイン）と、ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key のボタンが表示されます。その下には Product: presta-payment-payfast の行と、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 のアカウントで枠を解放してください。

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

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

トラブルシューティング

決済時に PayFast が表示されない：ライセンスが有効か、Enable/Disable がオンか、現在のモードの Merchant ID と Merchant Key が入力されているか、カートが ZAR か、注文合計が少なくとも R5.00 あるかを確認してください。不足がある場合、設定ページに警告が表示されます。Payment > Preferences で、ランド、購入者の国、購入者のグループに対してモジュールが許可されているかを確認してください。

支払いは完了したが、注文が作成されなかった：PayFast が支払い通知を届けられなかったか、通知が拒否されました。モジュールページの Log 欄を確認してください。エラーと拒否された通知は常に記録され、Debug log を有効にすると各ステップも記録されます。よくある原因：ストアがインターネットからアクセスできない（ベーシック認証、ファイアウォール）、PayFast とモジュールでパスフレーズが異なる、または本番モードでプロキシや CDN の背後にあるための送信元チェック。その場合は Source check を無効にしてください。

通知が Invalid signature を返す：モジュールのパスフレーズが、支払いを行ったモード用に PayFast で設定されたものと異なります。

通知が Invalid source を返す：通知が PayFast のアドレスから届いていないか、プロキシまたは CDN が実際のアドレスを隠しています。ストアがプロキシまたは CDN の背後にある場合は、Source check を無効にしてください。

通知が Merchant mismatch または Order mismatch を返す：支払いは別の PayFast アカウント宛てか、この支払い試行に属していません。何も変更されません。

通知が Order not found を返す：この支払い参照番号は、このストアには登録されていません。何も変更されません。

通知が Confirmation unavailable、Busy、または Temporary error を返す：サーバー確認のために PayFast に接続できなかった、同じカートの別の通知がちょうど処理中だった、あるいは注文を作成できなかった（たとえばモジュールが無効）。PayFast は通知を再試行します。ログに理由が表示されます。

通知が Not configured を返す：支払いを開始したモードの認証情報が不足しています。テスト支払いの場合はサンドボックスの認証情報など、もう一度入力してください。

購入者に「PayFast は南アフリカ・ランド（ZAR）での支払いのみを受け付けます」と表示される：カートが別の通貨になっています。購入者にランドで支払ってもらうか、別の支払い方法を選んでもらってください。

注文が PayFast payment on hold になっている：PayFast payment ブロックの備考（注文ステータスを参照）と PayFast のダッシュボードを確認し、注文を承認するか、支払いを返金してください。

サンドボックスの支払いで注文が支払われなかった：ゲートウェイが本番モードです。サンドボックスの支払いは、本番モードでは注文を決して支払い済みにしません。注文に備考が付きます。

開発者向け：フック actionPayfastPPaymentData は、署名の前に支払いフォームの項目を変更できます。このフックで変更できないのは、加盟店の認証情報、URL、支払い参照番号、金額、トークンです。

アンインストール

Modules > Module Manager を開き、VibeFox PayFast Pay Gateway の横のメニューを開いて Uninstall を選びます。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete the gateway settings when the module is uninstalled がオンの場合、ゲートウェイの設定、キャッシュされた PayFast のアドレス、ログが削除されます。オフの場合は、後で再インストールできるようすべての設定が保持されます。PayFast の支払い記録、注文、注文ステータス Awaiting PayFast payment と PayFast payment on hold は常に保持されます。既存の注文は、支払いの備考とトランザクション ID を保持します。

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