VibeFox Redsys for PrestaShop — 帮助
要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。
Redsys 商户账户：您的银行（为您提供 Redsys 虚拟 POS 的收单机构）会提供商户代码（FUC）、终端号，以及可以在 Redsys 管理面板中查看的各环境 SHA-256 密钥。测试环境的密钥与正式环境不同。您的终端必须启用在线通知（HTTP）。如果不确定，请咨询您的银行。
店铺货币：必须是模块支持的货币之一（参见 Configuration），并且您的 Redsys 终端必须已由银行为该货币启用。大多数终端只接受 EUR。
可访问的店铺：Redsys 必须能够从互联网访问您的店铺，不需要登录，也不能被防火墙拦截，才能送达付款通知。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Redsys Gateway，然后点击 Configure。
3. 将您的 VibeFox 许可证密钥输入 Configure 页面顶部许可证区块中的 License key，然后点击 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。该文件无法通过网页打开。即使此选项关闭，错误也始终会被记录。密钥、签名和银行卡数据从不记录。默认：关闭。
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 订单号，而且通过其中任何一次尝试（例如从第二个浏览器标签页）完成的付款仍会被识别。
如果付款无法发送到 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。如果同一购物车已有订单，又收到第二笔不同的付款，订单不会被修改。备注会请您在 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 一行，以及 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。如果无法连接许可证服务器，模块将继续使用上次已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Redsys。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台不知道您已登录后台，因此付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 的 Alerts 标签页中会显示提醒。已有订单不受影响：已发起的付款仍会被确认，退款也仍然有效。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您操作后台时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 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 的认可。