VibeFox Redsys for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。モジュールは、それより古い PHP バージョンではインストールできません。

Redsys 加盟店アカウント：貴行（Redsys 仮想 POS を提供したアクワイアラ）から、加盟店コード（FUC）、端末番号、そして各環境の SHA-256 秘密キーが表示される Redsys 管理パネルへのアクセスを受け取ります。テスト環境のキーは本番環境のキーとは異なります。端末でオンライン通知（HTTP）が有効になっている必要があります。不明な場合は貴行にご確認ください。

ストアの通貨：モジュールがサポートする通貨のいずれか（Configuration を参照）であり、Redsys 端末がその通貨について貴行によって有効化されている必要があります。ほとんどの端末は EUR のみを受け付けます。

アクセス可能なストア：支払い通知を届けるため、Redsys がインターネットから貴店にアクセスできる必要があります。ログインを求められたり、ファイアウォールでブロックされたりしないようにしてください。

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

インストール

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

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

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

4. 加盟店コード、端末、および各環境の秘密キーを入力します（Configuration を参照）。

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

インストール時に、モジュールは注文ステータス Redsys payment on hold を作成します。PrestaShop は、その時点で有効な国、およびすべての通貨と顧客グループに対して、新しい支払いモジュールを提供します。これは Payment > Preferences で変更できます。後から有効にした国も、そこでモジュールに対してチェックを入れる必要があります。

Configuration

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Redsys Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。フィールドの上部では、加盟店コードが未入力であるか数字のみで構成されていない場合、秘密キーが有効な Redsys SHA-256 キーでない場合、現在のモードのキーが空の場合（この場合、チェックアウトで支払い方法が非表示になります）、ストアの通貨がサポートされていない場合に警告が表示されます。テストモードがオンの間は、Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. と表示されます。Title が空の場合、ページには Enter a title for the payment method. と表示され、何も保存されません。

Redsys

Enable/Disable：Enable Redsys Gateway は、支払い方法のオン／オフを切り替えます。初期値：オフ。

Title：お客様がチェックアウトで見る支払い方法の名前です。注文に保存される支払い方法名にもなります。初期値：Credit/Debit Card (Redsys)。必須。

Description：チェックアウトで支払い方法の下に表示されるテキストです。初期値：Pay securely with your credit or debit card via Redsys.

Redsys アカウント

貴行から、加盟店コード、端末、そして各環境の SHA-256 秘密キーが表示される Redsys 管理パネルへのアクセスを受け取ります。このセクションには Redsys 管理パネルへのリンクがあります。

Merchant Code (FUC)：Redsys の加盟店コードです。最大 9 桁。数字以外の文字は保存時に削除されます。

Terminal Number：貴行が割り当てた端末番号です。最大 3 桁。初期値：1。空欄の場合は 1 として保存されます。

Secret Key (SHA-256) — live：本番環境の Base64 SHA-256 キーです。通常 32 文字です。テストモードがオフのときに使用されます。

テストモード（SIS-T）

Redsys のテスト環境には、独自の秘密キーがあります。このセクションには、Redsys の公開テストデータが表示されます：加盟店コード 999008881、端末 1、キー sq7HjrUOBfKmC576ILgskD5srU870gJ7、カード番号 4548 8100 0000 0003、有効期限 12/49、CVV 123。テストモードでは実際の料金は請求されません。

Test Mode：支払いと返金は Redsys のテスト環境（SIS-T）に送信され、テストキーで署名されます。初期値：オン。実際の支払いを受け付けるにはオフにします。オンの間、チェックアウトでは支払い方法の下に TEST MODE: Redsys test environment, no real money is charged. と表示されます。

Secret Key (SHA-256) — test：テスト環境の Base64 SHA-256 キーです。独自のテストキー、または上記の公開テストキーを使用してください。

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

Clear saved secrets：キーにチェックを入れて Save をクリックすると削除されます。空欄の場合は保存済みの値が維持されます。

支払いページと注文

Commerce Name：Redsys の支払いページに表示されるストア名です。最大 25 文字。初期値：ストア名を 25 文字に切り詰めたもの。

Order Status After Payment：支払いが成功した後に設定される注文ステータスです。

金額または通貨の不一致、ストアが本番モードの間のテスト支払い、キャンセルされた試行の支払いは、常に Redsys payment on hold になります。

支払い通知

Notification URL：Redsys は、すべての支払いを貴店のこのアドレスに通知します。このセクションに表示され、フレンドリー URL の場合は https://your-shop/module/wcp_redsys_gateway/notify のような形式になります。モジュールは支払いごとにこれを Redsys に送信するため、Redsys パネルにコピーする必要はありません。端末でオンライン通知（HTTP）が有効になっている必要があります。支払いが成功しても注文が作成されない場合は、貴行にご確認ください。有効な署名のない通知は拒否されます。通知がなければ、注文は作成されません。

詳細設定

Debug log：支払い、通知、返金の詳細を、モジュールフォルダー内の logs/rdsg_debug.log.php に書き込みます。このファイルは Web から開くことはできません。このオプションがオフの場合でも、エラーは常に記録されます。キー、署名、カード情報は記録されません。初期値：オフ。

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

Delete Data：オンの場合、モジュールをアンインストールすると、ゲートウェイの設定とログが削除されます。注文の Redsys 支払い記録（返金に必要）と注文ステータス Redsys payment on hold は、常に保持されます。初期値：オフ。

サポートされる通貨

EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD。サポートされていない通貨のカートでは、支払い方法は非表示になります。

チェックアウト

支払いの段階で、お客様は支払い方法（初期値は Credit/Debit Card (Redsys)）を選び、注文を確定します。お客様には Redirecting to Redsys for payment. Please wait... と表示され、貴行の Redsys 決済ページに進みます。ブラウザが自動で先に進まない場合、お客様は Pay via Redsys をクリックするか、Choose another payment method をクリックして戻ることができます。この時点では、まだ注文は存在しません。

Redsys のページで、お客様は 3-D Secure によるカード決済、または Bizum や貴行が端末で有効にしたその他の方法で支払います。ページではカートの言語（スペイン語、英語、カタルーニャ語、フランス語、ドイツ語、イタリア語、ポルトガル語など）が使われ、それ以外の言語の場合は英語が使われます。金額は、カート通貨の最小単位によるカートの合計金額です。たとえば EUR 43.45 は 4345 として送信され、JPY や CLP は小数点を使いません。支払いは Cart に、カート番号とストア名を加えた形で説明されます。

支払い後、お客様は貴店に戻ります。注文は、Redsys が署名付きの通知で確認した後にのみ支払い済みになります。注文を作成するのは通知で、お客様には Your payment with Redsys has been received. を含む標準の注文確認ページが表示されます。注文が Redsys payment on hold になった場合、ページには Your payment with Redsys has been received and is being reviewed by the store. と表示されます。通知がまだ届いていない場合は、Payment confirmation ページに Redsys is confirming your payment. If you completed the payment, your order will be created in a few moments — please do not pay again. と表示され、Check again と Back to checkout のボタンが付きます。

お客様がキャンセルした場合や支払いが拒否された場合、Redsys はお客様を The Redsys payment was not completed. You can try again or choose another payment method. とともにチェックアウトに戻します。カートは保持され、お客様は再度支払うことができます。新しい試行ごとに新しい Redsys 注文番号が割り当てられ、そのいずれかで行われた支払い（たとえば 2 つ目のブラウザータブから行われた支払い）も引き続き認識されます。

支払いを Redsys に送信できない場合、お客様はチェックアウトにとどまり、短いメッセージが表示されます：Redsys payments are not configured correctly. Please choose another payment method or contact us.、通貨が受け付けられないことを示すメッセージ、または The order total must be greater than zero.

通知は、ストアがメンテナンスモードの間も機能し、ストアの国による制限でブロックされることもありません。

モジュールは、Redsys のページで即時に承認・売上確定される一回限りの支払いに対応します。貴店のサイト上のカードフォーム（InSite または iframe）、カードの保存、ワンクリック決済、トークン化、定期購入や継続課金、後日売上確定する事前承認、バックエンドで作成された注文の支払いリンクには対応していません。

注文と返金

注文ステータス

No order yet：お客様は Redsys に移動したものの支払っていない、支払いが拒否またはキャンセルされた、または Redsys の通知がまだ届いていない状態です。存在するのはカートだけです。

Payment accepted, Delivered or Redsys payment on hold：支払いが確認されました。ステータスは Order Status After Payment に従います。支払いは Redsys 注文番号（Ds_Order）を取引 ID として記録され、メモには Redsys 注文番号、承認コード、応答コードが表示されます。テスト支払いの場合は [TEST] と表示されます。

Redsys payment on hold after payment：Redsys がカートの合計と異なる金額または通貨を報告した場合（たとえば、支払いの開始後にカートが別のタブで変更された場合）、ストアが本番モードの間にテスト支払いが届いた場合（実際の料金は請求されず、支払いは記録されません）、またはお客様が Redsys のページでその支払いをキャンセルした後に支払った場合です。メモに理由が説明されます。Redsys 管理パネルで支払いを確認してから、注文を処理するか、支払いを返金してください。

Refunded：支払いはモジュールを通じて全額返金されました。

拒否された支払いによって、既存の注文が変更されることはありません。よくある応答コードについて、ログとメモには Insufficient funds、Card expired、Cancelled by the customer などの短い理由が記載されます。注文がすでにあるカートに、別の 2 回目の支払いが届いた場合、その注文は変更されません。重複した支払いを Redsys 管理パネルで返金するよう、メモで案内されます。Redsys が支払いがまだ処理中であると報告した場合、メモが追加され、注文は最終結果を待ちます。

Redsys 支払いブロック

注文ページには Redsys payment ブロックが表示されます。これには、Redsys 注文番号（Ds_Order）、承認コードと応答、環境（本番またはテスト）、支払い済み金額と返金済み金額、テスト支払い用の Test mode バッジ、保留中の注文の確認のヒント、返金履歴、注文の Redsys notes、そしてそのカートに対して発行されたすべての Redsys 注文番号が含まれます。

返金

Redsys payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Redsys をクリックします。確認のダイアログ Refund this amount through Redsys? This cannot be undone. で確定します。全額返金と一部返金に対応しています。注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。返金は、Redsys が請求した金額と通貨で行われます。そのため、金額または通貨の不一致の後は、注文の合計ではなく、お客様が実際に支払った金額まで返金できます。返金は Redsys REST API を通じて、支払いが行われた環境（テストまたは本番）に送信され、その環境のキーで署名され、応答の署名が検証されます。Redsys が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。返金が成功すると、Redsys 注文番号と理由とともに、返金履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。

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

Redsys 管理パネルで行われた返金は、モジュールの返金としては記録されません。Redsys がそれらについて通知を送信すると、注文にメモが追加されます。注文のステータスは自動的には変更されません。

ライセンスキー

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

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

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

トラブルシューティング

チェックアウトに Redsys が表示されない：ライセンスが有効であること、Enable/Disable がオンであること、加盟店コードと端末が入力されていること、そして現在のモードに有効なキーがあることを確認してください。テストモードでは Secret Key (SHA-256) — test、本番モードでは Secret Key (SHA-256) — live です。カートの通貨がサポートされている通貨の一覧にあることを確認してください。設定ページには、これらの問題ごとに警告が表示されます。Payment > Preferences で、モジュールがカートの通貨、お客様の国、お客様のグループに対して許可されているか確認してください。

支払いは完了したが、注文が作成されなかった：Redsys の通知が貴店に届きませんでした。端末でオンライン通知（HTTP）が有効かどうかを、貴行に確認してもらってください。Notification URL に表示されるアドレスが、ログインやファイアウォールでのブロックなしにインターネットからアクセスできることを確認してください。Debug log をオンにして、モジュールのページの Log フィールドを確認してください。

通知の応答が Forbidden：署名が、支払いを開始した環境の秘密キーと一致していないか、通知内の加盟店コードが貴店のものではありません。設定内の秘密キーと加盟店コードが、貴店の端末のものであるかを確認してください。

通知の応答が Order not found：通知は正しく署名されていましたが、このストアのどのカートも、その Redsys 注文番号を使用していません。

通知の応答が Busy：同じタイミングで、カートが別の通知によって処理されていたか、注文を作成できなかった場合です（たとえば、モジュールが無効になっている場合）。Redsys は通知を再試行します。ログに理由が表示されます。

通知の応答が Bad request：リクエストに Redsys のパラメーターがないか、壊れていました。期待される形式で Redsys から送られたものではありません。

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

本番モードでテスト支払いが注文を確定しない：Test Mode がオフの間は、テスト支払いで注文が支払われることはありません。代わりに、注文はメモ付きで保留になります。テスト支払いには、テストモードとテストキーを使用してください。

返金に失敗する：エラーを確認してください。Redsys refund: the merchant code or the TEST secret key is not configured.（または LIVE）は、支払いの環境のキーが設定されていないことを意味します。Redsys のエラーコードはメッセージに説明されています。たとえば SIS0057（金額が支払いの残額を超えている）、SIS0056（元の支払いが見つからない。別の環境または端末）、SIS0042（署名エラー。この環境のキーを確認）、SIS0026（不明な加盟店コードまたは端末）、SIS0027（端末に通貨が設定されていない）です。Redsys に接続できない場合、返金は行われません。後でもう一度お試しください。

端末がリストにない通貨を受け付けている：開発者は actionRdsgCurrencyCodes フックを使って通貨の一覧を変更できます。通貨を追加するのは、貴行がその通貨を端末に対して有効にしている場合のみにしてください。

アンインストール

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

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