VibeFox Paystack for PrestaShop — ヘルプ

動作環境

PrestaShop：8.0 から 9.x。

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

通貨：カートは Paystack が受け付ける通貨（NGN、USD、GHS、ZAR、KES、XOF、EGP、RWF のいずれか、Paystack アカウントで有効になっているもの）である必要があります。その他の通貨では決済方法が非表示になります。XOF と RWF では、Paystack は整数の金額のみを受け付けます。

Paystack アカウント：Paystack アカウントのシークレットキーが必要です：テスト用シークレットキー（sk_test_...）および/または本番用シークレットキー（sk_live_...）。支払いは Paystack のホスト型ページで行われるため、公開キー（pk_...）は不要です。また、Paystack のダッシュボードで、ショップの Webhook URL も設定します（設定を参照）。Webhook を受信するため、ショップはインターネットからアクセス可能である必要があります。

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

インストール

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

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

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

4. Paystack のダッシュボードからシークレットキーを貼り付け、Paystack のダッシュボードで Webhook URL を設定します（設定を参照）。

5. Enable/Disable をオンにして Save をクリックします。テスト支払いを行うまでは Test Mode をオンのままにし、その後オフにして実際の支払いを受け付けます。

インストール時に、モジュールは2つの注文ステータス Awaiting Paystack payment と Paystack payment on hold を作成します。PrestaShop は、すべての通貨、国、顧客グループに対して新しい決済モジュールを提供します。これらは Payment > Preferences で制限できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Paystack Payment > Configure。フィールドのある各セクションには独自の Save ボタンがあり、ページ全体が保存されます。フィールドの上には、モードを示すステータスボックスが表示されます：テストモード：実際の料金は請求されません。 または 本番モード：実際の支払いを受け付けます。 また、現在のモードのシークレットキーが空の場合、シークレットキーのフィールドに公開キー（pk_...）が入力された場合、本番モードにテストキー（sk_test_...）がある場合またはテストモードに本番キー（sk_live_...）がある場合、Paystack がショップのデフォルト通貨を受け付けない場合に警告します。キーの問題がある間は、チェックアウトで決済方法が非表示になります。

Paystack

最初のセクションは Paystack という名前で、現在のモードの TEST または LIVE バッジが付いています。

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

Title：お客様がチェックアウトで目にする決済方法の名前です。注文にも決済方法の名前として保存されます。デフォルト：Paystack。必須。

Description：チェックアウトで決済方法の下に表示されるテキストです。デフォルト：Pay securely using your debit card, credit card, or bank account via Paystack.

API キー

Paystack のダッシュボードの Settings > API Keys & Webhooks ページからシークレットキーをコピーします。このセクションにはそのページへのリンクがあります。

Test Mode：新しい支払いにはテスト用シークレットキーを使用し、実際の料金は請求されません。オフにすると、本番用シークレットキーで実際の支払いを受け付けます。もう一方のモードで行われた支払いは、検証と返金に引き続き自身のモードのキーを使用します。デフォルト：オン。オンの間、お客様には決済方法の下に テストモードが有効です。実際の請求は行われません。 と表示されます。

Test Secret Key：Paystack のテスト用シークレットキーです。sk_test_ で始まります。

Live Secret Key：Paystack の本番用シークレットキーです。sk_live_ で始まります。

保存されたキーは二度と表示されません。フィールドは空のままになり、保存済み — 保持するには空のままにしてください。 と表示されます。変更する場合にのみ新しい値を入力してください。

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

Webhook

Webhook は、お客様がショップに戻らなくても、支払いが行われたことをショップに通知します。Paystack のダッシュボードの Settings > API Keys & Webhooks ページで、このセクションの Webhook URL に表示される URL を、Test Webhook URL と Live Webhook URL の両方に設定します。フレンドリー URL を使用している場合、次のような形式になります：https://your-shop/module/wcp_paystack_payment/webhook。/en/ のような言語コードが付く場合もあります。設定に表示されたとおりに URL をコピーしてください。

Paystack は、すべての Webhook をお使いのシークレットキーで署名するため、他に設定する必要はありません。有効な署名がない Webhook は拒否されます。モジュールは charge.success イベントを使用します：

charge.success：支払いが行われました。モジュールは、支払いが開始されたモードのシークレットキーを使用して Paystack API からトランザクションを読み取り、すべてが一致すれば注文を支払い済みとしてマークします。

その他のイベントには OK と応答され、無視されます。Webhook がない場合、注文は、お客様が支払い後にショップに戻ったときにのみ確認されます。後で完了する銀行振込や USSD の支払いは、Webhook によってのみ確認されます。

注文

Autocomplete Order：オンにすると、支払い済みの注文は Payment accepted ではなく Delivered ステータスになり、ステータス変更は1回だけ行われます。デフォルト：オフ。

詳細設定

Debug log：Paystack のイベントと API 呼び出しを、モジュールフォルダー内の logs/paystack_p_debug.log.php に記録します。このファイルはウェブから開くことはできません。エラーと警告は常に記録されます。キーとお客様のデータは記録されません。デフォルト：オフ。

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

Delete data on uninstall：オンにすると、モジュールをアンインストールしたときにモジュールの設定とログが削除されます。注文に保存された支払いデータは常に保持されます。デフォルト：オフ。

チェックアウト

決済のステップで、お客様は決済方法（デフォルトは Paystack）を選択し、注文を確定します。モジュールは、カートの通貨でカート合計金額について、お客様のメールアドレスを使用して Paystack のトランザクションを開始し、お客様を Paystack のホスト型決済ページに移動させます。そこでお客様は、Paystack アカウントで有効になっているチャネルのいずれかで支払います。支払い画面には、カート番号とお客様の名前が表示されます。この時点ではまだ注文は存在しません。

支払い後、お客様はショップに戻ります。注文は、Paystack が確認した後にのみ支払い済みとしてマークされます。お客様が戻ったときと Webhook が届いたときの両方で、モジュールは Paystack API からトランザクションを読み取り、参照、ステータス、金額、通貨を照合します。その後、注文が作成され、お客様には標準の注文確認ページが表示されます。

銀行振込など、支払いがまだ処理中の場合、お客様が戻った時点で注文は Awaiting Paystack payment として作成され、確認ページには お支払いは Paystack により確認中です。確認が完了次第、メールでお知らせします。 と表示されます。注文は後で Webhook によって完了します。お客様が戻った時点で Paystack に接続できない場合、Payment confirmation ページでお客様に再度支払わないよう伝え、Check again と Back to checkout を提示します。Webhook が届いた時点で注文が作成されます。保留中の注文の場合、確認ページには お支払いを受け付けました。ご注文は確認中です。必要があればご連絡いたします。 と表示されます。

お客様が Paystack のページでキャンセルしたり、支払わずに離脱したりした場合、注文は作成されず、カートは保持されます。お客様は、たとえば 支払いがキャンセルされました。もう一度お試しいただくか、別の決済方法をお選びください。、支払いが完了しませんでした。もう一度お試しいただくか、別の決済方法をお選びください。、お支払いが拒否されました。もう一度お試しいただくか、別の決済方法をお選びください。 といったメッセージとともにチェックアウトに戻ります。新しい試行のたびに、新しい Paystack トランザクションが開始されます。カートの以前の支払いページは引き続き有効です。後で支払われた場合でも、支払いは受け付けられます。

注文確認ページは、お客様自身のブラウザーでのみ開きます。戻りリンクが別の場所で開かれた場合、支払いは引き続き確認されますが、注文は表示されません。訪問者にはチェックアウトで中立的なメッセージが表示されます。

Paystack が支払いを開始できない場合、お客様は、たとえば Paystack で支払いを開始できませんでした： に続けて Paystack からの理由、または Paystack は一時的に利用できません。しばらくしてから再度お試しいただくか、別の決済方法をお選びください。 という短いメッセージとともにチェックアウトに留まります。カートの合計金額はゼロより大きい必要があり、お客様には有効なメールアドレスが必要です。

Webhook は、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることもありません。

このモジュールには、PrestaShop において、埋め込み型またはポップアップの決済フォーム、保存済みカード、サブスクリプション、分割払い、サブアカウント、決済チャネルの選択はありません。

注文と返金

注文ステータス

まだ注文はありません：お客様は Paystack に移動しましたが、まだ支払っていないか、Paystack のページを離れたか、Paystack がまだ支払いを確認していません。存在するのはカートのみです。

Awaiting Paystack payment：Paystack がまだ支払いを処理している間にお客様が戻りました。たとえば銀行振込や USSD です。Paystack が支払いを確認すると、注文は支払い済みのステータスに移行します。そのような支払いが完了しなかった場合、注文はあなたが変更するまでこのステータスのままになります。

Payment accepted または Delivered：支払いが確認されました。Autocomplete Order がオンの場合、ステータスは配達済みになります。支払いは、トランザクション ID として Paystack の参照（pscart_...）とともに記録されます。メモには、金額、参照、トランザクション番号、モード（テストまたは本番）、支払いチャネル、カードの種類、カード支払いの場合は下4桁、およびお客様が負担した Paystack の手数料（ある場合）が表示されます。

Paystack payment on hold：支払われた金額または通貨が注文と一致しません（メモ Paystack 金額または通貨の不一致）。たとえば、支払いの開始後にカートが変更された場合、または注文がキャンセルされた後に支払いが届いた場合です。メモには確認すべき内容が記載されています。注文を処理するか、支払いを返金してください。

支払いエラー：Paystack は、Awaiting Paystack payment の注文の最新の支払い試行が失敗または取り消されたと報告します。以前の試行の失敗は、注文を変更しません。

注文がすでに支払い済みのカートについて2回目の支払いが届いた場合、注文は変更されません。メモで、重複した支払いを Paystack のダッシュボードから返金するよう求められます。別のステータス（たとえば発送済み）の注文に届いた支払いは、注文にメモとして記録されるだけです。

Paystack payment ブロック

注文ページには Paystack payment ブロックが表示され、参照、トランザクション ID、テスト支払い用の Test mode バッジ付きのモード、支払いステータス、チャネルとカード、支払日、支払い済み金額と返金済み金額、返金履歴、注文の Payment notes が含まれます。

返金

Paystack payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Paystack をクリックします。確認の質問 この金額を Paystack 経由で返金しますか？この操作は取り消せません。 に応答してください。全額と一部の返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は注文を支払ったトランザクションに対して、返金時のモード（テストまたは本番）のシークレットキーを使用して行われるため、そのキーが設定されている必要があります。返金は、Paystack が請求した金額と通貨で行われます。そのため、金額または通貨の不一致の後に保留中の注文については、注文合計ではなく、お客様が実際に支払った金額までを返金できます。XOF と RWF では、返金は整数の金額である必要があります。Paystack は返金をキューに入れます。メモと返金履歴には、Paystack が返した（たとえば pending などの）ステータスと返金 ID が表示されます。Paystack が返金を受け付けない場合、ブロックには Paystack の返金に失敗しました： と理由が表示され、返金は記録されません。全額返金を行うと、注文のステータスは Refunded になります。一部の返金ではステータスは変わりません。返金は、Paystack が支払いを確認した後に利用できます。

このモジュールはクレジットノートを作成しません。注文ページにある PrestaShop の標準の返金ボタンでは、Paystack を通じて返金されることはありません。

Paystack のダッシュボードで行われた返金や、Paystack がキューに入れた返金の最終ステータスは、PrestaShop に同期されません。必要に応じて手動で記録してください。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Paystack が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、現在のモードに正しいシークレットキーがあること（テストモードでは sk_test_... の Test Secret Key、本番モードでは sk_live_... の Live Secret Key）、そしてカートの通貨が Paystack で受け付けられる通貨であることを確認してください。設定の上部にあるステータスボックスに問題が表示されます。Payment > Preferences で、カートの通貨、お客様の国、お客様のグループに対してモジュールが許可されているかを確認してください。

支払いは完了したが、注文が作成されなかった：Webhook がショップに届かず、お客様も戻りませんでした。Paystack のダッシュボードで、Test Webhook URL と Live Webhook URL が Webhook URL に表示されている URL と完全に一致していること、およびファイアウォールやパスワード保護によってブロックされていないことを確認してください。Debug log をオンにして、Log フィールドで拒否された Webhook を確認してください。

Webhook が Invalid signature と応答する：Webhook が、設定に入力されたテストまたは本番のシークレットキーで署名されていません。たとえば、キーが別の Paystack アカウントのものである場合です。Webhook を送信するアカウントのキーを入力してください。

Webhook が Secret key not configured と応答する：どちらのシークレットキーも設定されていません。設定でシークレットキーを入力してください。

Webhook が Verification failed、Busy、retry later、または Order could not be created, retry later と応答する：その時点でトランザクションを Paystack API から読み取れなかった、お客様の戻りによってカートが同時に処理されていた、または注文を作成できなかった（たとえばモジュールが無効になっている）などです。Paystack は Webhook を再送します。ログに理由が表示されます。

Webhook が OK - unknown reference と応答する：その支払いは、このショップのカートに対して行われたものではありません。たとえば、同じアカウント上の Paystack の支払いページや別の連携です。無視されます。

Webhook の URL をブラウザーで開くと Empty body と表示される：これは正常です。この URL は Paystack からのリクエストのみを受け付けます。

お客様に「決済ゲートウェイが正しく設定されていません」と表示される：現在のモードのシークレットキーが欠けているか、間違っています。設定の上部にあるステータスボックスの指示に従って修正してください。

支払い後に注文が Paystack payment on hold になる：Paystack payment ブロックの支払いメモを確認し（注文ステータスを参照）、その後で注文を処理するか、支払いを返金してください。

注文が Awaiting Paystack payment のまま：Paystack がまだ支払いを確認していません。Paystack のダッシュボードでトランザクションと Webhook の設定を確認してください。お客様が支払いを一度も完了しなかった場合は、手動でステータスを変更してください。

返金がモードに関するメッセージで失敗する：支払いはテストまたは本番モードで行われましたが、そのモードのシークレットキーが設定されていません。キーを入力して、もう一度お試しください。

開発者は、モジュールのフック actionWcpPaystackPaymentRequest、actionWcpPaystackSupportedCurrencies、actionWcpPaystackCurrencyDecimals を使用して、トランザクションのリクエストと通貨の一覧を変更できます。

アンインストール

Modules > Module Manager に進み、VibeFox Paystack Payment の横にあるメニューを開いて、Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後で再インストールするためにすべての設定が保持されます。注文の Paystack 支払いデータ、返金、および Awaiting Paystack payment と Paystack payment on hold の注文ステータスは常に保持されるため、以前に支払われた注文は再インストール後も返金できます。既存の注文は、支払いメモとトランザクション ID を保持します。

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