VibeFox PayFast for OpenCart — ヘルプ
要件
OpenCart: 3.0.x（3.0.5.0 で動作確認済み）または 4.0.2 以降（4.1.0.3 で動作確認済み）。
PHP: 8.0 以降。
Currency: 南アフリカ・ランド（ZAR）。PayFast はランドでのみ決済するため、注文は ZAR で行う必要があります。ストアにまだ通貨がない場合は、System > Localisation > Currencies で追加してください。注文の最低金額は R5.00 です。
PayFast account: PayFast アカウントの Merchant ID と Merchant Key です。PayFast の管理画面の Settings > Developer Settings で確認できます。パスフレーズを強く推奨します。PayFast でパスフレーズを設定している場合は、同じパスフレーズを拡張機能にも入力する必要があります。テストには PayFast サンドボックスの認証情報が必要です。
Reachable store: 支払い通知の URL は、ベーシック認証やファイアウォールによる遮断なしに、インターネットからアクセスできる必要があります。
VibeFox license key: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。
インストール
このダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。中には README.txt、OpenCart 3 用パッケージ wcp_payfast_pay-oc3-(version).ocmod.zip、OpenCart 4 用パッケージ wcp_payfast_pay.ocmod.zip が含まれています。お使いの OpenCart のバージョンに合ったパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。
OpenCart 3
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_payfast_pay-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更が含まれていないため、Extensions > Modifications を更新する必要はありません。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。
2. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox PayFast Pay Gateway を見つけて、Install（緑色の + ボタン）をクリックします。
3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（「ライセンスキー」の節を参照）。
4. Merchant ID、Merchant Key、パスフレーズを入力します。テストする場合は Test mode をオンのままにして、サンドボックスの認証情報を入力します。
5. Enable/Disable をオンにして Save をクリックします。テスト決済を行い、実際の決済を受け付ける準備ができたら Test mode をオフにします。
OpenCart 4
1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_payfast_pay.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 はファイル名から拡張機能のコードを取得するため、名前を変更したパッケージは動作しません。
2. インストール済み拡張機能の一覧に、同じページでパッケージが表示されます。その横にある Install（緑色の + ボタン）をクリックします。
3. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox PayFast Pay Gateway を探して Install（緑色の + ボタン）をクリックし、次に Edit（鉛筆のボタン）をクリックします。
4. ライセンスキーと PayFast の認証情報を入力し、OpenCart 3 の手順 3〜5 と同じようにテスト決済を行います。設定ページとそのフィールドは両方のバージョンで同じです。異なるのは通知 URL だけです（Notification URL を参照）。通知 URL も、すべての支払いとともに PayFast に送信されます。
新規インストールでは、支払い方法はオフ、テストモードはオンの状態で始まります。
設定
すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit。セクションは左側に並んでいます。一覧の下にある Save ボタンで、ページ全体が保存されます。設定の上には、現在のモードの認証情報が空の場合（その場合、PayFast はチェックアウトで非表示になります）、ストアの既定の通貨が ZAR でない場合、本番モードで公開サンドボックスの Merchant ID 10000100 を使用している場合、パスフレーズが設定されていない場合に警告が表示されます。テストモードがオンの間は、Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. と表示されます。
保存時、Title は空にできません（128 文字まで）。Sort Order は整数である必要があります（負の数も使用できます）。Total は 0 以上の数値である必要があります。選択したジオゾーンと注文ステータスも存在している必要があります。条件を満たさない場合は何も保存されず、ページに該当の項目が表示されます。現在のモードの認証情報がないまま支払い方法を有効にした場合は、警告付きで保存されます。
PayFast
Enable/Disable: Enable PayFast で支払い方法をオンまたはオフにします。既定値：オフ。
Title: チェックアウトで顧客に表示される支払い方法の名前です。注文にも支払い方法の名前として保存されます。既定値：PayFast。必須。
Description: Confirm Order のステップで、確認ボタンの上に顧客に表示される文章です。既定値：Pay securely by card, Instant EFT and other methods on the PayFast payment page.
Sort Order: チェックアウトの支払い方法の中で PayFast が表示される位置です。空欄のままにするか、整数を入力してください。
Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ PayFast を提供します。既定値：All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。OpenCart 4 では、ストアで支払い先住所が求められない場合、配送先住所が使用されます。
Total: PayFast を提供するために注文が達している必要があるチェックアウト金額です（ストアの既定の通貨で指定）。空欄にすると、どの金額でも PayFast を提供します。PayFast 自体は常に最低 R5.00 を必要とします。
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 にある salt パスフレーズです。強く推奨します。支払いと通知に署名するために使用されます。
サンドボックス（テストモード）
テストモードでは、支払いは PayFast のサンドボックスに送られ、実際の料金は請求されません。サンドボックスの認証情報は、PayFast サンドボックスにログインすると表示されます（公開テスト用の加盟店は 10000100 / 46f0cd694581a です）。
Test mode: Use the PayFast sandbox and the sandbox credentials below。オンの間、顧客は Confirm Order のステップで TEST MODE: payments go to the PayFast sandbox, no real money is charged. と表示されるのを確認できます。既定値：オン。
Sandbox Merchant ID: サンドボックスアカウントの Merchant ID です。
Sandbox Merchant Key: サンドボックスアカウントの Merchant Key です。
Sandbox Passphrase: サンドボックスアカウントにパスフレーズが設定されている場合のみ入力します。
保存済みのパスフレーズは再表示されません。欄は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。保存済みのパスフレーズを削除するには、欄の下にある Clear the saved passphrase on save にチェックを入れ、Save をクリックします。
支払い通知（ITN）
Notification URL: PayFast は、ここに表示される URL へのサーバー間通知によって、すべての支払いを確認します。形式は、OpenCart 3 では https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn、OpenCart 4 では https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn のようなもので、OpenCart をインストールしたストアのアドレスから作られます。このアドレスはすべての支払いとともに送信されるため、PayFast 側で設定する必要はありませんが、インターネットからアクセスできる必要があります。注文のステータスは、この検証済みの通知によってのみ設定されます。顧客がストアに戻っても注文は変わりません。
Source check: 本番の通知は PayFast のサーバーからのものだけを受け付けます。アドレスは PayFast の DNS レコード（6 時間キャッシュされ、設定を保存するとキャッシュがリセットされます）と PayFast が公開しているアドレス範囲から取得されます。ストアが訪問者のアドレスを隠すプロキシや CDN の背後にある場合にのみオフにしてください。署名とサーバーでの確認は常にチェックされます。サンドボックスの通知はアドレスではチェックされません。既定値：オン。
注文
OpenCart は、Confirm Order のステップで注文をステータスなし（注文が欠落した状態）で作成します。注文がステータスを得るのは、検証済みの PayFast 通知からのみです。キャンセル、失敗、または途中で放棄された支払いは、注文をステータスなしのままにし、顧客は再度支払うことができます。以下の各欄には、お使いの OpenCart の注文ステータスが表示されます。
Order Status (paid): PayFast が支払いを確認し、金額と通貨が一致した後のステータスです。既定値：処理中。
Awaiting PayFast payment: PayFast が支払いを保留中として報告した場合（例：Instant EFT）。PayFast が支払いを完了すると、支払い済みのステータスに変わります。既定値：保留中。
PayFast payment on hold: 管理者による確認が必要な支払いです（「注文ステータス」の節を参照）。このような注文は支払い済みとしてマークされません。理由はメモに記載されます。既定値：保留中。OpenCart には On hold ステータスがないためです。System > Localisation > Order Statuses で独自のステータスを作成し、ここで選択できます。
Payment failed: 保留中の支払いが失敗しました。PayFast がその後支払いを完了した場合、注文は支払い済みのステータスに変わります。既定値：失敗。
詳細設定
Debug log: 支払いの各ステップを、OpenCart のログフォルダ（storage/logs）にある payfast_p_debug.log.php に記録します。このファイルは Web から開くことはできません。5 MB に達すると payfast_p_debug.old.log.php に移動されます。エラーと警告は、スイッチがオフでも常に記録されます。パスフレーズ、キー、顧客の情報は書き込まれません。既定値：オフ。
Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると空になります。
Uninstall: Delete the gateway settings when the extension is uninstalled（設定、キャッシュされた PayFast のアドレス、ログ）。PayFast の支払い記録と注文は常に保持されます。既定値：オフ。
インポート / エクスポート
Export: Download JSON で設定を JSON ファイルとして保存します。パスフレーズはエクスポートされません。
Import: 以前にエクスポートした JSON を貼り付けて Import をクリックすると、設定が復元されます。保存済みのパスフレーズは保持されます。
チェックアウト
Payment Method のステップで、顧客は支払い方法を選択します（既定では PayFast）。Confirm Order のステップでは、顧客にあなたの説明と、Thank you for your order. You will be redirected to PayFast to complete the payment. という案内が表示されます。OpenCart はこのステップで注文を作成しますが、まだステータスはありません。OpenCart 4 では、顧客は支払い方法ブロックの Choose ボタンを押して Payment method options ウィンドウで支払い方法を選択し、チェックアウトページ下部の Confirm Order をクリックします。顧客が Confirm Order をクリックすると、拡張機能が署名済みの支払いフォームを PayFast に送信します。このフォームには、ZAR 建ての注文金額、注文番号を示す Order #、顧客の氏名とメールアドレス、支払い参照（注文番号と試行回数）、および試行ごとのランダムなトークンが含まれます。新しい試行ごとに、新しい参照とトークンが付与されます。
PayFast のページで、顧客はカード、Instant EFT、またはお使いの PayFast アカウントの他の方法で支払います。その後、PayFast が支払い通知（ITN）をストアに送信します。注文は、すべての検証に合格した通知によって PayFast が支払いを確認した後にのみ、支払い済みとしてマークされます。
その後、注文は OpenCart の標準的な方法でステータスを得て、通常の注文メールが送信され、在庫が更新されます。同じカートの通知は一件ずつ処理されます。同じカートの別の通知が処理中の場合、PayFast にはエラー応答が返され、PayFast は通知を再送します。ストアがメンテナンスモードでも通知 URL は機能します。OpenCart 3 では支払い拡張機能のリクエストが OpenCart によって通過させられ、OpenCart 4 では拡張機能が追加するスタートアップアクションによって、通知と PayFast からの顧客の戻りが通過させられます。
顧客が戻ってきて注文にステータスがある場合、OpenCart の注文完了ページが表示されます。PayFast が支払いを保留中と報告していた場合は、PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. も表示されます。注文が保留中の場合は、Your payment is being reviewed. We will contact you if anything else is needed. と表示されます。保留中の支払いがその後失敗した場合は、Your PayFast payment was not completed. Please contact us about this order. と表示されます（OpenCart 4 では、代わりに顧客はチェックアウトに戻されます。下記を参照）。通知がまだ届いていない場合は、Payment confirmation のページに、PayFast が支払いを確認中であることが表示され、Check again と Back to checkout のボタンが表示されます。
顧客が PayFast のページでキャンセルすると、The PayFast payment was cancelled. You can try again or choose another payment method. というメッセージとともにチェックアウトに戻ります。PayFast が支払いを失敗と報告した場合は、The payment was not completed. You can try again or choose another payment method. と表示されます。カートは保持され、再度支払うことができます。OpenCart 4 では、これらのメッセージはチェックアウトページの上部に表示されます。OpenCart 3 では Confirm Order のステップが表示されるたびに新しい注文が作成されますが、OpenCart 4 はチェックアウトの注文を 1 つ保持して更新するため、キャンセルまたは失敗の後、顧客は同じ注文を新しい試行で支払います。同じカートの別の注文がすでに PayFast によって処理されている場合（例：別のブラウザタブで）、顧客は再度支払う代わりに成功ページに移動します。
OpenCart 4 では、成功ページが表示されるまで注文はチェックアウト内に保持されます。その間に支払いなしで注文が閉じられた場合（例：保留中の支払いが失敗した場合、または貴店が注文をキャンセルした場合）、顧客は Your previous order was cancelled or its payment failed. Please confirm the order again. というメッセージとともにチェックアウトに戻され、次の Confirm Order で新しい注文が支払われます。その注文にすでにステータスがあり、カートに別の商品や数量がある場合、メッセージは Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. になります。
現在のモードの認証情報がない場合、チェックアウトの通貨が ZAR でない場合、または合計金額が R5.00 未満の場合は、支払い方法は非表示になります。それでも顧客が支払いに進んだ場合は、ボタンの上に短いメッセージが表示され、その理由が説明されます。例：PayFast accepts payments from R5.00. Please choose another payment method.
この拡張機能が受け付けるのは、ZAR 建ての一回限りの支払いのみです。注文ページからの返金、サブスクリプション、保存された（トークン化された）カード、分割払いには対応していません。
注文
注文ステータス
No status (missing order): 顧客は PayFast に送られましたが、支払い通知がまだ届いていないか、PayFast が支払いを失敗と報告しています。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。
OpenCart 4 では、チェックアウトの未払いの注文に Voided ステータスが設定される場合があります。これは、顧客が Confirm Order のステップに戻ったときに OpenCart 4 が設定するものです。拡張機能はこのような注文をステータスのない注文として扱い、後から届いた支払いによって引き続き確認します。
Order Status (paid) (default Processing): PayFast が支払いを確認しました。メモには PayFast の支払い ID が表示されます。サンドボックスの支払いには、実際の料金は請求されなかったという内容のメモが付きます。
Awaiting PayFast payment (default Pending): PayFast が支払いを保留中と報告しました。PayFast が支払いを完了すると注文は支払い済みのステータスに移り、支払いが失敗すると Payment failed に移ります。顧客は、これらの変更をメールで通知されます。
Payment failed (default Failed): 保留中の支払いが失敗しました。PayFast がその後支払いを完了した場合、注文は支払い済みのステータスに変わります。
PayFast payment on hold (default Pending): 支払われた金額が注文金額と異なる、または注文が ZAR ではない場合。ステータスをその間に変更した（例：キャンセルした）注文、または支払い方法がもう PayFast ではない注文に対して支払いが届いた場合。またはゲートウェイが本番モードの間にサンドボックスの支払いが届いた場合。メモに理由が記載されます。注文と PayFast の管理画面を確認してから、注文を支払い済みのステータスに設定するか、注文をキャンセルして PayFast で支払いを返金してください。
同じ支払いに対する繰り返しの通知では、何も変わりません。遅れて届いた失敗や保留中の通知が、支払い済みの注文を変更することはありません。すでに支払い済みの注文や、すでに支払い済みのカートの 2 件目の注文に対して、別の完了した支払いが届いた場合は、支払い済みの注文にメモが付き、重複分を PayFast で返金するよう促されます。
メモは、顧客には表示されない注文の History のエントリです。
VibeFox PayFast Pay Gateway タブ
Sales > Orders で、PayFast で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox PayFast Pay Gateway タブには、Payment reference (m_payment_id)、PayFast payment ID、Environment（本番またはサンドボックス）、要求された金額、ステータス、ZAR 建ての総額・手数料・純額、PayFast notes が表示されます。保留中の注文の場合は、支払いを確認するよう促すリマインダーが表示されます。このタブは、拡張機能へのアクセス権があるユーザーに表示されます。
返金
注文ページからの返金には対応していません。PayFast の管理画面で支払いを返金してから、OpenCart で注文を手動で更新してください。
ライセンスキー
この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox PayFast Pay Gateway は、Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit の最初のブロックで、設定の上にあります。License key にキーを貼り付け、Activate をクリックします。その後、ブロックにはキーがマスクされた状態で表示され、ステータス（ライセンスの有効期限日、お使いのドメインなど）と、ボタンが表示されます。Check now でステータスを再確認、Change key で別のキーを入力、Remove key でこのストアからキーを削除できます。その下には、Product: opencart-payment-payfast の行と、vibefox.net のアカウントを開くリンク Manage licenses and domains in your account があります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーのみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語が含まれています）。
キーが受け付けられない場合は、ブロックに理由が表示されます。例：Key not found、This key belongs to another product、Domain limit reached、または License expired on と日付。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、拡張機能は最後に確認されたステータスのまま動作を続けます。
1 つのキーは 1 つのドメインで使用できます。ドメインとは、OpenCart の設定にあるストアのアドレスのことです。キーをストアから削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。
有効なキーがない場合、PayFast はチェックアウトで顧客に表示されません。それでも支払いが開始された場合、顧客には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストアで支払い方法が (unlicensed — visible to admins only) と表示された状態で引き続き見えるので、キーを購入する前に拡張機能を設定・テストできます。OpenCart 4 では、このプレビューは利用できません。ストアは管理画面へのログインを認識しないため、有効なキーがない場合は、すべての人に対して支払い方法が非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると 7 日間非表示になります。既存の注文には影響しません。すでに開始された支払いは引き続き確認されます。
ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。ステータスは、管理画面の Dashboard または Edit ページを開くと自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日 1 回、その後は週 1 回です。cron ジョブは不要です。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは必ず削除されます。
トラブルシューティング
PayFast does not appear at checkout: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの Merchant ID と Merchant Key が入力されていること、チェックアウトの通貨が ZAR であること、注文金額が R5.00 以上であることを確認してください。何かが不足している場合、設定ページに警告が表示されます。支払い先の住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。
The payment went through, but the order stays without a status: PayFast が支払い通知を届けられなかったか、通知が拒否されました。拡張機能ページの Log 欄を確認してください。エラーと拒否された通知は常に記録され、Debug log はすべての手順を記録します。よくある原因は次のとおりです。ストアがインターネットから到達できない（ベーシック認証、ファイアウォール）、PayFast と拡張機能でパスフレーズが異なる、または本番モードでプロキシや CDN の背後にあるため送信元チェックに失敗している。その場合は Source check をオフにしてください。
The notification answers Invalid signature: 拡張機能のパスフレーズが、支払いが行われたモードについて PayFast に設定されているものと一致していません。
The notification answers Invalid source: 通知が PayFast のアドレスから届いていないか、プロキシや CDN が実際のアドレスを隠しています。ストアがプロキシや CDN の背後にある場合は、Source check をオフにしてください。
The notification answers Merchant mismatch or Order mismatch: 支払いは別の PayFast アカウントに対して行われたか、この支払い試行に属していません。何も変更されません。
The notification answers Order not found: この支払い参照は、このストアには存在しません。何も変更されません。
The notification answers Confirmation unavailable, Busy or Temporary error: サーバー確認のために PayFast に接続できなかった、同じカートの別の通知がちょうど処理中だった、または注文ステータスを設定できなかった。PayFast は通知を再試行します。ログに理由が表示されます。
The notification answers Not configured: 支払いを開始したモードの認証情報がありません。テスト支払いの場合はサンドボックスの認証情報など、もう一度入力してください。
The customer sees PayFast accepts payments in South African rand (ZAR) only: 注文が別の通貨になっています。顧客がランドで支払うか、別の支払い方法を選ぶようにしてください。
The customer sees This payment method is not available. Please reload the checkout page. チェックアウトのセッションが注文と一致しなくなったか、その間に支払い方法がオフにされました。顧客はチェックアウトのページを再読み込みしてください。
Order is in the on-hold status: VibeFox PayFast Pay Gateway タブのメモ（「注文ステータス」の節を参照）と PayFast の管理画面を確認し、その後、支払い済みのステータスを設定するか、支払いを返金してください。
A sandbox payment did not pay the order: ゲートウェイが本番モードになっています。本番モードでは、サンドボックスの支払いで注文が支払われることはありません。注文のメモにその旨が記載されます。
開発者向け：支払いフォームに署名する前に、拡張機能はフォームのフィールドと注文を伴う OpenCart イベント payfast_p_payment_data を発行します。このイベントによって、加盟店の認証情報、URL、支払い参照、金額、トークンを変更することはできません。
アンインストール
Extensions > Extensions に移動し、種類 Payments を選択して、VibeFox PayFast Pay Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は、拡張機能自身の設定を常に削除します。Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションの注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、そのイベントとスタートアップアクションも削除されます。このスタートアップアクションは、メンテナンスモードでも通知と顧客の戻りを通過させます）。Delete the gateway settings when the extension is uninstalled がオンの場合、その他のゲートウェイ設定（タイトル、説明、認証情報、パスフレーズ、テストモード、送信元チェック、ログ記録）、キャッシュされた PayFast のアドレス、ログが削除されます。オフの場合は、後日の再インストールのために保持されます。PayFast の支払い記録と注文は常に保持されます。既存の注文は支払いのメモを保持します。
OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧にある VibeFox PayFast Pay Gateway の横の Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱のボタン）をクリックしてください。
PayFast は、それぞれの所有者の商標です。この拡張機能は PayFast とは提携しておらず、PayFast による推奨も受けていません。