VibeFox Ozow for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古いバージョンの PHP では、モジュールはインストールを拒否します。

通貨: 南アフリカ・ランド（ZAR）。決済方法は ZAR のカートにのみ表示されます。Ozow はセント単位の整数で請求するため、通貨は小数点以下 2 桁を使用する必要があります。

Ozow アカウント: Ozow の加盟店ダッシュボードで確認できる、Ozow サイトの Site Code と Private Key を持つ Ozow 加盟店アカウント。API Key は任意ですが、設定を推奨します。Ozow はテスト決済と本番決済で同じ Site Code とキーを使用します。

到達可能なサイト: Ozow の通知が届くように、ショップはインターネットから到達可能である必要があります。パスワード保護や、Ozow をブロックするファイアウォールがあってはなりません。ショップがメンテナンスモードであっても、通知は受け付けられます。

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

インストール

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

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

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

4. Ozow の加盟店ダッシュボードから Site Code と Private Key を入力し、できれば API Key も入力します。

5. Enable/Disable をオンにして Save をクリックします。Test mode をオンにした状態でテスト決済を行い、その後テストモードをオフにして実際の決済を受け付けます。

インストール時に、モジュールは 2 つの注文ステータスを作成します：Awaiting Ozow payment と Ozow payment on hold。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。これらは Payment > Preferences で制限できます。そこで、モジュールに対して ZAR を許可する必要があります。後から有効にした国も、そこでモジュールにチェックを入れる必要があります。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Ozow Pay > Configure。Save ボタンのある各セクションは、ページ全体を保存します。フィールドの上では、Site Code または Private Key が未入力の場合（その場合 Ozow はチェックアウトで非表示になります）、ショップの既定通貨が ZAR でない場合、通貨の小数点以下の桁数が 2 を超える場合（International > Localization > Currencies で 2 に設定してください）に警告が表示され、テストモードがオンの間は Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. が表示されます。

Ozow

Enable/Disable: Enable Ozow payments は決済方法のオン／オフを切り替えます。既定: off。

Title: チェックアウトで購入者に表示される決済方法の名前です。注文にも、この決済方法の名前として保存されます。既定: Instant EFT (Ozow)。

Description: チェックアウトで決済方法の下に表示されるテキストです。既定: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. テストモードでは、その下に TEST MODE: no money will be charged. という行が追加されます（説明が空でない場合のみ）。

Ozow の認証情報

Ozow の加盟店ダッシュボード（Merchant details / Sites）から、Site Code、Private Key、API Key をコピーします。このセクションには、hub.ozow.com にある Ozow の連携ドキュメントへのリンクがあります。

Site Code: 決済を受け取る Ozow サイトの Site Code です。別の Site Code 宛ての応答は拒否されます。

Private Key: すべての決済リクエストに署名し、Ozow からのすべての応答を検証します。秘密にしてください。これがないと、決済方法は非表示になり、Ozow の応答は一切受け付けられません。

API Key (recommended): 任意です。API Key を設定すると、成功したすべての決済は、注文が支払い済みになる前に Ozow GetTransaction API でも確認されます。API は、このカートについて、同じ金額、通貨、Site Code で決済が完了したと報告する必要があります。

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

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

Test mode: Ozow はテストにも同じ Site Code とキーを使用します。決済は IsTest=true で作成され、資金は動きません。テストモードで支払われた注文には注文メッセージが付きます。出荷しないでください。実際の決済を受け付けるには、テストモードをオフにしてください。本番モードでは、テスト決済によって注文が支払い済みになることはありません。既定: on。

決済の通知

通知、成功、キャンセル、エラーの各 URL は、決済のたびに Ozow へ送信されるため、Ozow サイトで固定 URL を設定している場合を除き、Ozow の管理画面で設定する必要はありません。このセクションには 4 つの URL すべてが表示されます：Notification URL、Success URL、Cancel URL、Error URL。これらはショップのモジュールリンク（コントローラー notify と return）です。Ozow サイトで固定 URL を使用している場合は、設定に表示されているとおりに正確にコピーしてください。

詳細設定

Debug log: 決済リクエストと Ozow の応答を、モジュールフォルダー内の logs/ozow_p_debug.log.php に記録します（Web からは読み取れません）。エラーと警告は常に記録されます。キー、ハッシュ、トークン、顧客データは決して記録されません。既定: off。

Log: ログの現在のサイズと末尾を表示します。Clear log ボタンもあります。

Delete data on uninstall: このモジュールのアンインストール時に、設定とログを削除します（注文に保存された Ozow のデータは保持されます）。既定: off。

チェックアウト

支払いの段階で、購入者は決済方法（既定では Instant EFT (Ozow)）を選択し、注文を確定します。モジュールは、ZAR によるカート合計の署名付きリクエストとともに、購入者を Ozow がホストする決済ページに移動させます。銀行明細上の参照は Cart とカート番号です（ラテン文字、数字、スペース、ハイフンで最大 20 文字）。購入者の名前は Ozow に渡されます。この時点では、まだ注文は存在しません。Ozow のページで購入者は南アフリカの銀行を選択し、銀行アプリで支払いを承認します。

その後、Ozow はショップに通知し、購入者を戻します。どちらも同じ署名付きの応答を含み、同じ方法で処理されるため、一方が失われても注文は作成されます。注文は、Ozow が確認した後にのみ支払い済みとしてマークされます。ハッシュが貴店の Private Key で検証でき、Site Code が貴店のものであり、応答がそのカートのこの決済試行に属し、金額と通貨がカートと一致する必要があります。API Key を使用する場合、決済は GetTransaction API でも確認されます。

決済が成功すると、購入者には標準の注文確認ページが表示されます。Ozow または銀行がまだ決済を確認中の場合、そのページには We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. と表示されます。注文が保留中の場合は Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. と表示されます。確認中の決済が後で失敗した場合、または未払いの注文がキャンセルされた場合は、Your Ozow payment was not completed. Please contact us about this order. と表示されます。購入者が戻った時点で Ozow がまだ決済を確認していない場合は、待機メッセージと、Check again および Back to checkout ボタンが表示されるページが表示されます。

購入者が Ozow のページでキャンセルした場合、または決済が失敗した場合、注文は作成されません。購入者は同じカートのままチェックアウトに戻り、The Ozow payment was cancelled. You can try again or choose another payment method. または The Ozow payment was not completed. You can try again or choose another payment method. と表示されます。

カートが ZAR でない場合、購入者には Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method. と表示されます。

モジュールは ZAR による 1 回限りの決済のみに対応しています。PrestaShop からの返金、サブスクリプション、保存済みの銀行口座やトークン化、バックオフィスからの決済リンクの送信には対応していません。

注文と返金

注文ステータス

まだ注文はありません: 購入者は Ozow に移動されましたが、まだ支払っていないか、キャンセルしたか、Ozow がまだ決済を確認していません。存在するのはカートだけです。

Payment accepted: 決済が確認されました。注文メッセージには、金額と Ozow の取引 ID、および決済が GetTransaction API によって確認されたかどうかが表示されます。注文の決済の取引 ID は Ozow の TransactionId です。テスト決済には TEST MODE — no money was received, do not ship this order. というメッセージが付きます。

Awaiting Ozow payment: Ozow または銀行が決済を確認中です。Ozow が最終ステータスを送信すると、注文が更新されます。

Ozow payment on hold: 注文メッセージに理由が表示されます：支払われた金額または通貨がカートと異なる。すでにキャンセルされた注文に対して決済が届いた。または、API Key を使用している場合、GetTransaction API がまだ決済を確認できない、もしくは決済と矛盾している。Ozow の管理画面で決済を確認し、注文ステータスを変更してください。API が応答できなかった場合は、次の Ozow 通知によって注文が完了します。

決済エラー: 確認中だった決済がキャンセル、放棄、または失敗しました。その決済に対して後から届いた Ozow の成功応答は、それでも注文を支払い済みにします。

支払い済みの注文が元に戻されることはなく、キャンセルまたは返金された注文が再開されることもありません。すでに支払い済みの注文に 2 回目の決済が届いた場合、重複分を Ozow の管理画面で返金するようメッセージが表示されます。注文が別の理由で保留になっている場合（たとえばご自身で設定した場合）、後から届いた決済はメッセージを追加するだけで、注文を Payment accepted に設定するのはご自身です。

Ozow 決済ブロック

注文ページには、取引の参照と試行、Ozow の取引 ID、ステータス、リクエストされた金額、Ozow が報告した金額、Ozow のメッセージ、そしてテスト決済の場合は TEST MODE の表示を含む Ozow payment ブロックが表示されます。

返金

PrestaShop からの返金には対応していません。Ozow の加盟店ダッシュボードで決済を返金し、その後 PrestaShop で返金を手動で記録してください。

ライセンスキー

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

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

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

トラブルシューティング

Ozow がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、Site Code と Private Key が入力されていること、カートの通貨が ZAR であることを確認してください。Payment > Preferences で、このモジュールが ZAR、購入者の国、購入者のグループに対して許可されていることを確認してください。設定ページは、何かが不足している場合に警告を表示します。

決済は完了したが、注文が作成されていない: Ozow の通知がショップに届かず、購入者も戻っていません。ショップがインターネットから到達可能であることを確認してください（Ozow をブロックするパスワード保護やファイアウォールがないこと）。Ozow サイトで固定 URL を使用している場合は、Payment notifications に表示されている URL と正確に一致しているか確認してください。Debug log をオンにして、Configure ページでログを確認してください。

通知の応答が Invalid hash: 設定の Private Key は、応答を送信した Ozow サイトのものではありません。Ozow の加盟店ダッシュボードから再度コピーしてください。何も変更されません。

通知の応答が Unknown site: 応答は別の Ozow サイトから届きました。Site Code を確認してください。

通知の応答が Order mismatch または Order not found: その応答は、このショップで開始された決済に属しません。何も変更されません。

通知の応答が Gateway not configured: Site Code または Private Key が不足しています。入力してください。Ozow が再試行する場合があります。

通知の応答が Payment not confirmed yet: その応答はまだ適用できませんでした。API Key を使用する場合、GetTransaction API が決済を確認できなかったことを意味します（注文は保留中で、次の通知によって完了します。保留のままの場合は、API Key と Ozow の管理画面で決済を確認してください）。同じカートについて購入者の戻りが同じタイミングで処理されていた場合や、注文を作成できなかった場合にも、この応答になります。ログを確認してください。

テスト決済で注文が支払われなかった: モジュールは本番モードです。本番モードでは、テスト決済によって注文が支払われることはありません。注文メッセージまたはログにその旨が記載されます。

支払い後に注文が Ozow payment on hold になっている: 注文メッセージを確認し、Ozow の管理画面で決済を確認してから、注文を Payment accepted に設定するか、Ozow で決済を返金してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Ozow Pay の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは、常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールできるように、すべての設定が保持されます。Ozow の決済記録と、注文ステータス Awaiting Ozow payment および Ozow payment on hold は常に保持されるため、再インストール後も古い注文に対する遅延通知は引き続き認識されます。既存の注文は、決済メッセージと取引 ID を保持します。

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