VibeFox Redsys for OpenCart — 帮助

要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Redsys 商户账户：您的银行（为您提供 Redsys 虚拟 POS 的收单机构）会向您提供商户代码（FUC）、终端号，以及 Redsys 管理面板的访问权限，每个环境的 SHA-256 密钥都在该面板中显示。测试环境的密钥与正式环境的密钥不同。您的终端必须启用在线通知（HTTP）。如果不确定，请咨询您的银行。

货币：扩展支持的货币之一（参见配置），并且您的 Redsys 终端必须已获得银行对该货币的开通。大多数终端仅接受 EUR。

可访问的商店：Redsys 必须能够从互联网访问您的商店，不能有登录要求或防火墙拦截，才能送达付款通知。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_redsys_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_redsys_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_redsys_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Redsys Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。

4. 输入您的商户代码、终端以及每个环境的密钥（参见配置）。

5. 打开 Enable/Disable 并点击 Save。在 Test Mode 开启的状态下进行一次测试付款，然后关闭 Test Mode，即可接受真实付款。

OpenCart 4

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_redsys_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Redsys Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 请按照 OpenCart 3 步骤 3 至 5 输入许可证密钥和 Redsys 数据。两个版本的设置页面及其字段完全相同，只有通知 URL 不同（参见付款通知）。

新安装时，支付方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Redsys Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。如果没有修改扩展的权限，页面仅显示设置而无法保存。

在设置上方，当商户代码缺失或不全是数字、某个密钥不是有效的 Redsys SHA-256 密钥、当前模式的密钥为空（此时结账页面会隐藏该支付方式）、或商店默认货币不受支持时，页面都会发出警告。测试模式开启时，页面会显示 Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged.

保存时，Title 必须为 1 到 128 个字符（Enter a title for the payment method (1 to 128 characters).），Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，且地理区域和每个订单状态都必须存在。否则不会保存任何内容。

Redsys

Enable/Disable：Enable Redsys Gateway 用于开启或关闭该支付方式。默认：关闭。

Title：顾客在结账时看到的支付方式名称，也是订单中保存的支付方式名称。默认：Credit/Debit Card (Redsys)。必填，最多 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with your credit or debit card via Redsys.

Sort Order：Redsys 在结账页面支付方式中的排列位置。可留空或输入整数。

Geo Zone：仅向所选地理区域内的付款地址提供 Redsys。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账金额（以商店默认货币计）才会提供 Redsys：大于或等于 0 的数字。留空则对任何金额都提供 Redsys。

Redsys 账户

您的银行会提供商户代码（FUC）、终端，以及 Redsys 管理面板的访问权限，每个环境的 SHA-256 密钥都在该面板中显示。本节包含 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），并使用测试密钥签名。默认：开启。关闭后即可接受真实付款。开启期间，顾客在 Confirm Order 步骤会看到 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 secret on save，然后点击 Save。

付款页面和订单

Commerce Name：显示在 Redsys 付款页面上的商店名称，最多 25 个字符。默认：您的商店名称，截取为 25 个字符。

Order Status After Payment：已付款订单获得的状态。

金额或货币不一致、网关处于正式模式时的测试付款，以及已取消尝试的付款，始终会获得 On hold (review) status。

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在收到 Redsys 签名通知后，订单才会获得状态。被拒绝或取消的付款会使订单保持无状态；顾客返回结账页面，购物车会被保留。下方每个字段都列出了您的 OpenCart 订单状态。

Processing status：当 Order Status After Payment 为 Processing 时使用。默认：处理中。

Completed status：当 Order Status After Payment 为 Completed 时使用。默认：已完成。

On hold (review) status：用于需要您审核的付款（见上文），或在 Order Status After Payment 为 On hold (review) 时用于每个已付款订单。默认：待处理，因为 OpenCart 没有“保留”状态；订单备注会说明原因。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Refunded status：Redsys 付款通过订单页面全额退款后设置。默认：已退款。

付款通知

Notification URL：Redsys 会将每笔付款报告到您商店的这个地址。它显示在本节中。在 OpenCart 3 中形式类似 https://your-store/index.php?route=extension/payment/wcp_redsys_gateway/notify，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_redsys_gateway/payment/wcp_redsys_gateway.notify，由您 OpenCart 安装的商店地址生成。扩展会在每次付款时将其发送给 Redsys，因此无需在 Redsys 面板中复制任何内容。您的终端必须启用在线通知（HTTP）。如果成功付款后没有订单被确认，请咨询您的银行。没有有效签名的通知会被拒绝。没有通知，订单永远不会获得状态。

高级

Debug log：将付款、通知和退款的详细信息写入 OpenCart 日志文件夹（storage/logs）中的 rdsg_debug.log.php。该文件无法通过网页打开，文件大小达到 5 MB 时会被移入旧副本。即使此选项关闭，错误也始终会被记录。密钥、签名和银行卡数据绝不会被记录。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete Data：开启后，卸载扩展会删除网关设置和日志。订单的 Redsys 付款记录（退款所需）始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥会保留。

支持的货币

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。如果顾客的货币不在此列表中，则会隐藏该支付方式。

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 Credit/Debit Card (Redsys)）。在 Confirm Order 步骤中，顾客会看到您的描述。OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会准备一份已签名的付款表单，顾客会看到 Redirecting to Redsys for payment. Please wait...，并前往您银行的 Redsys 付款页面。如果浏览器没有自动跳转，顾客可点击 Pay via Redsys。在 OpenCart 4 中，顾客通过支付方式区块中的 Choose 按钮，在 Payment method options 窗口中选择支付方式，然后点击结账页面底部的 Confirm Order。

在 Redsys 页面上，顾客可以使用银行卡通过 3-D Secure 付款，也可以使用 Bizum 或您银行为该终端启用的其他方式。页面使用顾客的语言（西班牙语、英语、加泰罗尼亚语、法语、德语、意大利语、葡萄牙语等），其他语言则使用英语。金额为订单货币最小单位下的订单总额，例如 EUR 43.45 以 4345 表示；JPY 和 CLP 没有小数位。付款会以 Order 加订单号和您的商店名称来描述。

付款后，顾客返回您的商店。返回本身不会将任何内容标记为已付款。只有在 Redsys 通过签名通知确认后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单电子邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，并显示 Your payment with Redsys has been received. 如果订单获得了 On hold (review) status，页面会显示 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 confirmed 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 订单号，而通过其中任何一次进行的付款（例如从第二个浏览器标签页付款）仍会被识别。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；如果同一购物车的另一笔订单已经付款，顾客会直接进入成功页面，而另一笔订单的迟到付款不会被应用。

在 OpenCart 4 中，未完成付款的提示显示在结账页面上方。OpenCart 4 会为结账保留一个订单并对其进行更新，因此在取消或付款被拒绝后，顾客会使用新的 Redsys 订单号为同一订单付款。如果该订单在此期间已被关闭，顾客会被带回结账页面，并显示 Your previous order was closed without a payment. Please confirm the order again to pay with a new order.；如果该订单已有 Redsys 付款，则显示 Your order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.。下一次点击 Confirm Order 将为新订单付款。如果结账中的订单已付款，但之后购物车有变化（包括新数量），顾客会被带回结账页面，并使用新订单支付新的购物车。

如果付款无法发送到 Redsys，顾客会停留在 Confirm Order 步骤，并看到简短提示：Redsys payments are not configured correctly. Please choose another payment method or contact us.、该货币的付款不被接受的提示，或 The order total must be greater than zero.

即使商店处于维护模式，通知和顾客的返回也能正常工作：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，扩展会为其添加一个启动操作。

该扩展仅支持一次性付款，在 Redsys 页面上即时授权并扣款。它不支持您自己网站上的银行卡表单（InSite 或 iframe）、已保存的银行卡、一键付款或令牌化、订阅或定期付款、授权后延迟扣款的预授权，以及为管理后台创建的订单提供付款链接。

订单与退款

订单状态

无状态（缺失订单）：顾客已被转到 Redsys 但尚未付款，付款被拒绝或取消，或 Redsys 通知尚未到达。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时才会显示此类订单。

Processing、Completed 或 On hold (review)：付款已确认。状态取决于 Order Status After Payment。备注会显示 Redsys 订单号（Ds_Order）、授权码和响应码，测试付款会标记 [TEST]。

付款后的 On hold (review)：Redsys 报告的金额或货币与订单总额不同；网关处于正式模式时收到了测试付款（未扣除真实款项）；或顾客在 Redsys 页面上取消该付款后又完成了付款。备注会说明原因。请在 Redsys 管理面板中核实该付款，然后处理订单或为付款退款。

Refunded status：付款已通过扩展全额退款。

被拒绝的付款永远不会改变已有状态的订单。对于常见的响应码，日志和备注会给出简短原因，例如 Insufficient funds、Card expired 或 Cancelled by the customer。如果同一订单或已付款的购物车又收到了第二笔不同的付款，订单不会被更改。备注会提示您在 Redsys 管理面板中退还重复付款。如果 Redsys 报告某笔付款仍在处理中，会添加备注，订单将等待最终结果。

备注是订单 History 中顾客看不到的条目。

VibeFox Redsys Gateway 选项卡

在 Sales > Orders 中打开一个通过 Redsys 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox Redsys Gateway 选项卡会显示 Redsys order number (Ds_Order)、Authorisation code / response、Environment（正式或测试，并带有 Test mode 标签）、付款的 Status、Paid / refunded、针对待审核订单的审核提示、退款表单、退款历史、订单的 Redsys notes，以及 Redsys order numbers issued for this cart。该选项卡对有权访问此扩展的用户显示。

退款

在选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Redsys。确认提示 Refund this amount through Redsys? This cannot be undone. 支持全额和部分退款。您需要有修改订单的权限（Sales > Orders，在 System > Users > User Groups 中设置）。退款以 Redsys 扣款的金额和货币进行，因此在金额或货币不一致之后，您最多可以退还顾客实际支付的金额，而不是订单总额。退款会通过 Redsys REST API 发送到付款所在的环境（测试或正式），使用该环境的密钥签名，并会检查响应签名。如果 Redsys 不接受退款，选项卡会显示错误，且不会记录任何退款。成功的退款会连同 Redsys 订单号和原因一起添加到退款历史和备注中。全额退款会将订单设为 Refunded status，且不通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

在 Sales > Returns 中的商品退货不会通过 Redsys 退款。

在 Redsys 管理面板中进行的退款不会被记录为扩展的退款。当 Redsys 为此发送通知时，订单会添加一条备注。订单状态不会自动更改。

许可证密钥

该扩展需要使用在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Redsys Gateway 是 Extensions > Extensions > Payments > VibeFox Redsys Gateway > Edit 中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏部分字符的形式显示密钥、状态（例如许可证有效期的截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中移除该密钥）。其下方是 Product: opencart-payment-redsys 一行，以及打开您 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。如果无法连接许可证服务器，扩展将继续按最后已知的状态运行。

一个密钥只适用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 Redsys。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍然可以在商店中看到该支付方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中没有此预览功能：商店无法看到后台登录状态，因此没有有效密钥时，该支付方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款照常进行。

许可证到期后，扩展仍会继续运行，但更新和支持需要续期。打开后台 Dashboard 或 Edit 页面时，状态会被自动重新检查：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

Redsys 未在结账页面显示：请检查许可证是否有效、Enable/Disable 是否已开启、商户代码和终端是否已填写，以及当前模式是否有有效密钥：测试模式下为 Secret Key (SHA-256) — test，正式模式下为 Secret Key (SHA-256) — live。检查顾客的货币是否在支持的货币列表中。设置页面会针对每个问题显示警告。另外还要检查付款地址是否在所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。

付款已成功，但订单仍无状态：Redsys 通知没有到达您的商店。请让银行检查您终端的在线通知（HTTP）是否已启用。检查 Notification URL 中显示的地址能否在不需要登录、不被防火墙拦截的情况下从互联网访问。开启 Debug log，并查看扩展页面上的 Log 字段。

通知返回 Forbidden：签名与付款发起环境的密钥不匹配，或通知中的商户代码不是您的。请检查设置中的密钥和商户代码是否为您终端的密钥和商户代码。

通知返回 Order not found：通知的签名正确，但本商店没有任何订单使用该 Redsys 订单号。

通知返回 Busy：购物车在同一时刻正被另一条通知处理，或无法设置订单状态。Redsys 会重试该通知。日志会显示原因。

通知返回 Bad request：请求中没有 Redsys 参数，或参数已损坏。它不是以预期格式从 Redsys 发出的。

订单在付款后处于 on hold 状态：请阅读 VibeFox Redsys Gateway 选项卡中的备注（参见订单状态），然后处理订单或为付款退款。

测试付款在正式模式下不会确认订单：当 Test Mode 关闭时，测试付款永远不会支付订单。订单会改为暂停并附带备注。测试付款请使用测试模式和测试密钥。

退款失败：请阅读错误信息。Redsys refund: the merchant code or the TEST secret key is not configured.（或 LIVE）表示付款所在环境的密钥缺失。Redsys 错误码会在消息中说明，例如 SIS0057（金额超过付款剩余额度）、SIS0056（找不到原始付款：环境或终端不同）、SIS0042（签名错误，请检查该环境的密钥）、SIS0026（未知的商户代码或终端）和 SIS0027（终端未配置该货币）。如果无法连接 Redsys，退款不会完成。请稍后再试。

选项卡中没有退款表单：选项卡会说明原因，例如订单没有已确认的 Redsys 付款、已全额退款，或您的用户组没有修改订单的权限。

开发人员须知：扩展会触发 OpenCart 事件 wcp_redsys_gateway/merchant_parameters（付款参数和订单）和 wcp_redsys_gateway/currency_codes（支持的货币列表）。只有在您的银行已为终端开通某种货币时，才应添加该货币。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Redsys Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及四个订单状态（重新安装后恢复默认值）。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还会删除其事件和启动操作，该启动操作用于在维护模式下放行通知和顾客的返回）。如果 Delete Data 已开启，其他网关设置（标题、描述、商户代码、终端、密钥、测试模式、商店名称、付款后订单状态、日志记录）和日志会被删除；如果已关闭，这些设置会保留，供之后重新安装时使用。Redsys 付款记录和退款始终保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Redsys Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

Redsys 是其各自所有者的商标。本扩展与 Redsys 无关联，也未获得 Redsys 的认可。