VibeFox Redsys for WooCommerce — 帮助

要求

WordPress：6.2 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce，插件无法启用。

PHP：8.0 或更高版本。

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

店铺货币：插件支持的货币之一（参见配置），且您的 Redsys 终端必须已由银行为该货币开通。大多数终端只接受 EUR。

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

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_redsys_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Redsys > Manage，或在插件页面点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

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

6. 开启 Enable/Disable。在开启 Test Mode 的情况下测试一笔付款，然后取消勾选 Test Mode 以接受真实付款。

配置

所有设置都在同一个页面：WooCommerce > Settings > Payments > Redsys。在字段上方，页面会在以下情况发出警告：商户代码缺失或不是纯数字；某个密钥不是有效的 Redsys SHA-256 密钥；当前模式的密钥为空（此时结账时会隐藏该付款方式）；店铺货币不受支持。开启测试模式时，页面会显示 Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. 保存后，警告会立即反映新的设置。在付款方式列表中，Redsys 会被标记为需要设置，直到商户代码、终端以及当前模式的密钥都有效为止。

常规

Enable/Disable: Enable Redsys Gateway 用于启用或禁用该付款方式。默认：关闭。

Title: 顾客在结账时看到的付款方式名称。默认：Credit/Debit Card (Redsys)。

Description: 结账时显示在付款方式下方的文字。默认：Pay securely with your credit or debit card via Redsys。

Redsys 账户

您的银行会向您提供商户代码、终端号，以及可访问 Redsys 管理面板的权限，SHA-256 密钥即显示在该面板中。本节包含指向 Redsys 管理面板的链接。

Merchant Code (FUC): 您的 Redsys 商户代码，最多 9 位数字。保存时会删除所有非数字字符。

Terminal Number: 银行分配的终端号，最多 3 位数字。默认：1。空字段保存为 1。

Secret Key (SHA-256) — live: 正式（生产）环境的 Base64 SHA-256 密钥。测试模式关闭时使用。

测试模式（SIS-T）

Redsys 测试环境有自己的密钥。本节显示 Redsys 公开的测试数据：商户代码 999008881，终端 1，密钥 sq7HjrUOBfKmC576ILgskD5srU870gJ7，卡号 4548 8100 0000 0003，有效期 12/49，CVV 123。测试模式下不会扣除真实款项。

Test Mode: Enable test mode 会将付款和退款发送到 Redsys 测试环境（SIS-T），并使用测试密钥签名。默认：开启。取消勾选即可接受真实付款。开启时，结账页面会在付款方式下方显示 TEST MODE: Redsys test environment, no real money is charged.

Secret Key (SHA-256) — test: 测试环境的 Base64 SHA-256 密钥。可使用您自己的测试密钥，或上方公开的测试密钥。

支付页面和订单

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

Order Status After Payment: 付款成功后设置的订单状态。该状态只设置一次，因此顾客只会收到一封邮件。

付款通知

Redsys 会将每笔付款通知发送到您店铺的通知地址。地址格式为 https://your-site/wc-api/rdsg_redsys/，并显示在本节中。插件会在每笔付款时将其发送给 Redsys，因此无需复制到 Redsys 面板。您的终端必须启用在线通知（HTTP）。如果付款成功后订单仍为待付款，请咨询您的银行。没有有效签名的通知会被拒绝。没有通知，订单不会被标记为已付款。

高级

Debug log: Enable debug logging 会将付款、通知和退款的详细信息写入 WooCommerce > Status > Logs，来源为 wcp_redsys_gateway。即使此选项关闭，错误也始终会被记录。密钥、签名和银行卡数据从不记录。默认：关闭。

Delete Data: Delete the gateway settings when the plugin is deleted。开启后，删除插件时会移除网关设置和插件日志。默认：关闭。

支持的货币

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。其他货币不显示该付款方式。在 Pay for order 页面，以订单的货币为准。

结账

顾客选择付款方式（默认为 Credit/Debit Card (Redsys)）并提交订单。订单会被设为待付款，顾客会看到 Redirecting to Redsys for payment. Please wait...，然后前往您银行的 Redsys 付款页面。如果浏览器没有自动跳转，顾客可点击 Pay via Redsys。在 Redsys 页面上，顾客可通过 3-D Secure 使用银行卡付款，或使用 Bizum 或您的银行为该终端启用的其他方式付款。页面使用您店铺的语言（西班牙语、英语、加泰罗尼亚语、法语、德语、意大利语、葡萄牙语等），其他语言则显示英语。

金额以订单货币的最小单位发送，例如 EUR 43.45 发送为 4345；JPY 或 CLP 没有小数位。付款会以 Order 描述，并附带订单号和您的站点名称。库存在付款确认后才会减少，而不是更早。

付款后，顾客会返回您店铺的订单已收到页面。只有在 Redsys 通过已签名的通知确认后，订单才会被标记为已付款。在通知到达之前，页面会显示 Redsys is confirming your payment. If you completed the payment, your order will be updated in a few moments — please do not pay again.

如果顾客取消或付款被拒绝，Redsys 会将顾客送回您的店铺。对于结账订单，订单会以 WooCommerce 标准方式取消，购物车会保留。对于您在后台创建的订单（付款链接），顾客会带着 The Redsys payment was not completed. You can try again or choose another payment method. 提示返回 Pay for order 页面，订单不会被取消。您店铺的跳转页面还提供 Cancel order & restore cart，或对于后台创建的订单，提供 Choose another payment method。

顾客可以从 Pay for order 页面重新支付未付款的订单。每次尝试都会获得新的 Redsys 订单号，并且从其中任何一个发起的付款（例如来自第二个浏览器标签页的付款）仍会被识别。

如果订单无法发送至 Redsys，顾客会看到简短提示，并可以选择其他付款方式：Redsys payments are not configured correctly. Please choose another payment method or contact us.、提示不接受该货币的消息，或 The order total must be greater than zero.

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

本插件只接受一次性付款，并在 Redsys 页面上立即授权和扣款。它不提供您自己网站上的银行卡表单（InSite 或 iframe），不支持保存银行卡、一键付款或令牌化，不支持订阅或定期付款，不支持预授权后再扣款，也不支持 SOAP 通知。

订单与退款

订单状态

Pending payment: 顾客已被转到 Redsys 但尚未付款，或 Redsys 通知尚未到达。订单备注显示 Awaiting Redsys payment.

Processing, Completed or On Hold: 付款已确认。状态遵循 Order Status After Payment。订单备注显示 Redsys 订单号（Ds_Order）、授权码和响应码；测试付款会标记 [TEST]。订单的交易 ID 即为 Redsys 订单号。

On hold after payment: Redsys 报告的金额或货币与订单总额不同；店铺处于正式模式时收到了测试付款（未扣除真实款项）；或付款是在订单取消之后到达的。订单备注会说明原因。请在 Redsys 管理面板中核实付款，然后发货或退款。

Failed: 付款在 Redsys 被拒绝或取消。订单备注显示响应码，对于常见代码还会附上简短原因，例如 Insufficient funds、Card expired 或 Cancelled by the customer。只有仍在等待付款的订单才会变为失败。已付款或已关闭的订单永远不会因被拒绝的尝试而改变，该尝试仅作记录。

Cancelled: 顾客取消了付款，或订单被您或 WooCommerce 库存保留超时取消。

如果已付款或已退款的订单又收到第二笔不同的付款，订单不会改变。备注会提醒您在 Redsys 管理面板中退还重复付款。如果 Redsys 报告某笔付款仍在处理中，会添加一条备注，订单将等待最终结果。

退款

打开订单，点击 Refund，输入金额，然后通过 Redsys 付款方式点击退款按钮（默认为 Refund via Credit/Debit Card (Redsys)）。支持全额和部分退款。退款通过 Redsys REST API 发送至付款所在的环境（测试或正式），使用该环境的密钥签名，并检查响应签名。如果 Redsys 不接受退款，WooCommerce 会显示错误，且不会记录任何退款。成功的退款会连同 Redsys 订单号和原因一起添加到订单备注中。

在 Redsys 管理面板中进行的退款不会记录为 WooCommerce 退款。Redsys 为这些退款发送通知时，会在订单中添加备注。如有需要，可在 WooCommerce 中创建手动退款，而无需使用 Redsys 退款按钮。

许可证密钥

本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Redsys 页面顶部。将密钥粘贴到 License key，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，顾客在结账时看不到 Redsys。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍能看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也照常进行。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时不显示 Redsys：请检查许可证是否有效、Enable/Disable 是否开启、商户代码和终端是否已填写，以及当前模式是否有有效密钥：测试模式下为 Secret Key (SHA-256) — test，正式模式下为 Secret Key (SHA-256) — live。检查店铺货币（在 Pay for order 页面则为订单货币）是否在支持的货币列表中。设置页面会针对这些问题中的每一项显示警告。

付款已完成，但订单仍为 Pending payment：Redsys 通知未能到达您的店铺。请让银行检查您的终端是否已启用在线通知（HTTP）。检查 付款通知 中显示的地址能否在互联网上访问，无需登录、无维护页面、无防火墙拦截。开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_redsys_gateway。

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

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

通知返回 Busy：订单在同一时刻正被另一条通知处理。Redsys 会重试该通知。

通知返回 Bad request：请求缺少 Redsys 参数或参数已损坏。它不是以预期格式来自 Redsys 的。

订单在付款后处于 On hold：请阅读订单备注。付款金额或货币与订单不符，店铺处于正式模式时收到测试付款，或付款在订单取消后到达。请发货或退款。

正式模式下测试付款不会确认订单：当 Test Mode 关闭时，测试付款永远不会支付订单。相反，订单会被保留并附带备注。测试付款请使用测试模式和测试密钥。

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

您的终端接受列表中没有的货币：开发人员可以使用 rdsg_currency_codes 过滤器更改货币列表。仅当银行已为该终端开通某货币时，才应添加。

从 1.0 版本更新后：您在测试模式下使用的密钥现在位于 Secret Key (SHA-256) — test 中。在取消勾选 Test Mode 之前，请输入正式密钥。使用 1.0 版本创建的订单仍会接收通知和退款。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在另一个域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将沿用最后已知的状态继续工作。

卸载

停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面删除。本插件的许可证密钥和许可证状态始终会被删除。仅当 Delete Data 已开启时，才会删除网关设置和插件日志；否则它们会保留，以便日后重新安装。保存在订单上的 Redsys 数据始终保留，因为它记录了付款信息，并且退款时需要。现有订单会保留其付款备注和交易 ID。

Redsys 是其各自所有者的商标。本插件与 Redsys 无关联，也未获得 Redsys 的认可或背书。