VibeFox 2C2P for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

2C2P 账户：您需要 2C2P 商户账户的 Merchant ID 和 Secret Key。这些信息会在您开通商户账户时由 2C2P 提供。沙盒（sandbox）账户和正式账户使用不同的密钥。开发者文档和沙盒测试卡位于 developer.2c2p.com。

货币：结账货币必须受本扩展支持，并已在您的 2C2P 账户中启用。受支持的货币包括 THB、SGD、MYR、PHP、IDR、VND、MMK、KHR、LAK、CNY、HKD、TWD、JPY、KRW、INR、AUD、NZD、USD、EUR 和 GBP 等。如果顾客的货币不受支持，结账时将隐藏该付款方式。

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

安装

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

OpenCart 3

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

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

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

4. 输入您的沙盒 Merchant ID 和 Secret Key，开启 Enable/Disable，点击 Save，然后下一笔测试订单。

5. 准备就绪后，输入正式账户的凭据并关闭 Sandbox Mode。

OpenCart 4

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

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

3. 进入 Extensions > Extensions，选择扩展类型 Payments。找到 VibeFox 2C2P Payment，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。

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

新安装默认关闭付款方式，并开启沙盒模式。每次付款时都会发送返回和通知 URL。无需在 2C2P 后台进行任何配置。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox 2C2P Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在沙盒模式开启时，设置上方会显示 Sandbox mode is active. No real transactions will be processed.。如果网关已启用，但当前模式的 Merchant ID 或 Secret Key 为空，或者店铺的默认货币不受支持，页面会发出警告。在这两种情况下，结账时都会隐藏该付款方式。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

关闭 Sandbox Mode 后保存时，如果某个正式字段为空，页面会显示 Please enter your live Merchant ID. 或 Please enter your live Secret Key.。设置仍会被保存。Sort Order 必须为整数，Total 必须为 0 或更大的数字，Title 最多 128 个字符，并且地理区域和订单状态必须存在；否则不会保存任何内容，页面会指出具体字段。

2C2P

Enable/Disable：Enable 2C2P Payment Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也会作为付款方式名称保存在订单中，因此最多 128 个字符。如果为空，则使用默认值。默认：2C2P Payment。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P。沙盒模式下会在末尾添加 (TEST MODE)。

Sort Order：2C2P 在结账付款方式中的排列位置。留空或输入整数。

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

Total：订单需要达到的结账金额（以店铺默认货币计算），达到后才会提供 2C2P。留空则对任何金额都提供 2C2P。

测试模式（沙盒）

Sandbox Mode：使用下方的沙盒凭据，将付款发送到 2C2P 沙盒（demo2.2c2p.com）。默认：开启。关闭后可接受真实付款。

Sandbox Merchant ID：您的 2C2P 沙盒 Merchant ID。

Sandbox Secret Key：您的 2C2P 沙盒 Secret Key。

正式 API 凭据

在沙盒模式关闭时使用。

Merchant ID：您的 2C2P 正式 Merchant ID。

Secret Key：您的 2C2P 正式 Secret Key。该密钥将按输入原样保存，包括引号和反斜杠。

已保存的 Secret Key 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it.。只有需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

付款页面

Result URLs：仅供参考，显示 Frontend return URL 和 Backend notification URL。它们的形式如 https://your-store/index.php?route=extension/payment/wcp_2c2p_payment/back 和 https://your-store/index.php?route=extension/payment/wcp_2c2p_payment/notify（OpenCart 3），在 OpenCart 4 中则为 https://your-store/index.php?route=extension/wcp_2c2p_payment/payment/wcp_2c_2p_payment.back 和 https://your-store/index.php?route=extension/wcp_2c2p_payment/payment/wcp_2c_2p_payment.notify，根据您 OpenCart 安装的前台地址生成。它们会随每笔付款自动发送。结果始终使用付款时所用模式的 Merchant ID 和 Secret Key 进行验证：在沙盒中发起的付款，即使切换到正式模式后，仍会使用沙盒密钥进行验证；使用另一模式密钥签名的结果会被拒绝。

Payment Page Language：2C2P 付款页面的语言。默认：English。

Redirect API version：保持 8.5，除非 2C2P 告知您的账户仍在使用旧版 7.0（SHA-1 签名）。切换之前发起的付款，其结果仍会被验证。

Order ID prefix：可选，仅限字母和数字（最多 10 个），例如 SHOP1。2C2P 会拒绝已经收到过的订单 ID。当多家店铺共用一个 2C2P 账户时，以及在沙盒中（测试商户账户是共享的）时，请设置唯一的前缀。2C2P 订单 ID 由前缀、OpenCart 订单号和尝试次数组成，例如 SHOP1123A1。保存时会删除其他字符并给出警告。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（缺失订单）。只有在 2C2P 以有效签名确认结果后，订单才会获得状态。下面每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款成功（2C2P 状态 000）。默认：处理中。

Awaiting Payment Status：付款待处理（状态 001），例如顾客尚未完成的现金或银行付款。默认：待付款。

On Hold (Review) Status：2C2P 报告的金额或币种与订单总额不同。默认：待付款，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Cancelled Payment Status：待处理的付款随后被拒绝、取消或失败（状态 002、003、999）。默认：已取消。

高级设置

Enable Logging：将 2C2P 事件写入 OpenCart 日志文件夹（storage/logs）中的 tc2p_p_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动为 tc2p_p_debug.old.log.php。不会记录银行卡数据、Secret Key、顾客邮箱或付款令牌。默认：关闭。关闭时不会写入任何内容，包括错误信息。

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

Delete Data on Uninstall：开启后，卸载扩展时会删除网关设置和日志。2C2P 交易记录始终保留，因此即使重新安装，旧付款的延迟结果仍会被处理。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 2C2P Payment）。在 Confirm Order 步骤，顾客会看到您的描述。OpenCart 在此步骤创建订单，但仍没有状态。顾客点击 Confirm Order 后，页面会显示 Thank you for your order. You will be redirected to 2C2P to complete your payment.，并在片刻之后将顾客转到 2C2P 付款页面。如果没有自动跳转，顾客可以点击 Pay via 2C2P。

在 2C2P 页面，顾客可以使用您 2C2P 账户中启用的任何方式付款，例如银行卡、电子钱包、二维码支付、网上银行或现金付款。扩展会传递订单币种下的订单总额、顾客邮箱以及订单中的商品名称。付款可在 24 小时内完成。每次点击 Confirm Order 都会以新的 2C2P 订单 ID 开始一次新的尝试，因为 2C2P 从不接受两次相同的订单 ID。

2C2P 会报告两次结果：顾客的浏览器返回店铺，同时 2C2P 发送服务器到服务器的通知。两者的处理方式相同。只有在 2C2P 以有效签名确认后，订单才会被标记为已付款。结果还必须属于此次付款：2C2P 订单 ID 必须是您的店铺发出的，并且会核对商户 ID 和此次尝试的随机令牌。没有有效签名的结果会被拒绝。即使店铺处于维护模式，通知仍然有效，因为 OpenCart 允许付款扩展的请求通过。在 OpenCart 4 中，扩展为此添加一个启动动作，用于放行带有效签名的 2C2P 结果。

付款成功后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面，并显示 Your 2C2P payment has been received.。对于待处理的付款，页面会显示 Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment.。对于待审核的订单，页面会显示 Your payment was received and is being reviewed by the shop.

如果付款未在 2C2P 页面完成或被取消，订单将保持无状态。顾客会回到结账页面，并看到 Payment was not completed. Please try again or choose a different payment method.。购物车会保留，顾客可以重新付款或选择其他付款方式。如果无法确认付款结果，顾客会看到 We could not confirm the payment result. If your account was charged, please contact us before paying again.。如果付款无法发起，例如订单币种不受支持或订单总额为零，顾客会停留在 Confirm Order 步骤，并看到 This payment method is currently unavailable for this order. Please contact us or choose another payment method.

如果订单已经有状态（已付款或等待待处理的付款），则不会生成第二个付款表单。顾客会被转到订单成功页面。

在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。与未完成或无法确认付款相关的提示会显示在结账页面上方。OpenCart 4 会为结账保留一个订单并更新它：付款失败后，顾客会以新的尝试（新的 2C2P 订单 ID，例如 SHOP1123A2）为同一订单付款。如果该订单期间已在未付款的情况下关闭（例如待处理的付款被取消，或您取消了该订单），顾客会被带回结账页面，并看到 Payment was not completed. Please try again or choose a different payment method.，下一次点击 Confirm Order 将为一个新订单付款。如果订单在付款后被关闭，或者它已带有来自其他购物车付款的状态，提示为 This order can no longer be paid. Please confirm your order again.。已付款的订单绝不会在其他购物车中显示为已付款。购物车的任何变动（包括新的数量）都会被视为需要单独付款的新购物车。

该扩展不支持通过 OpenCart 退款、不支持保存银行卡、不支持定期付款或订阅、不在您的网站上提供银行卡输入字段，也不支持 2C2P PGW 4.x API。

订单

订单状态

No status (missing order)：顾客已被转到 2C2P，但尚未收到任何结果，或付款失败。在 Sales > Orders 中，此类订单只会在 Order Status 筛选器设为 Missing Orders 时显示。

Order Status After Payment (default Processing)：2C2P 报告付款成功。备注中会显示 2C2P 交易、授权码、日期和付款渠道。

Awaiting Payment Status (default Pending)：付款在 2C2P 处于待处理状态，例如顾客尚未支付的现金付款。当 2C2P 报告付款后，订单会转为 Order Status After Payment。OpenCart 会将此变更通知顾客。

On Hold (Review) Status (default Pending)：2C2P 报告的金额或币种与订单总额不同。备注会显示收到的值和预期的值。请在 2C2P 后台检查订单和交易。

Cancelled Payment Status (default Canceled)：待处理的付款随后被拒绝、取消或失败。备注会显示状态和原因。较早尝试的失败结果不会取消正在等待另一次尝试的订单。

已付款的订单不会因后续结果而改变，重复的旧结果也不会重新打开已取消的订单。如果已付款的订单又收到第二笔付款，订单不会被更改。备注会提醒您检查，并在 2C2P 商户后台退还重复付款。OpenCart 3 每当顾客到达 Confirm Order 步骤时都会创建一个新订单，因此同一购物车可能有多个订单（OpenCart 4 为结账保留一个订单，但较早的订单或第二个浏览器标签页仍可能占用同一购物车）。其中一个订单一旦已付款或等待待处理的付款，同一购物车就不会再发起新的付款；如果同一购物车的其他订单仍收到付款，也不会改变它。已付款的订单会附带备注，提示退还重复付款。

在 OpenCart 4 中，未付款的结账订单可能会获得 Voided 状态，该状态会在顾客返回 Confirm Order 步骤时由 OpenCart 4 设置。扩展会将这类订单视为无状态订单，之后的付款仍会确认它。

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

VibeFox 2C2P Payment 选项卡

在 Sales > Orders 中打开一个通过 2C2P 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox 2C2P Payment 选项卡会显示 2C2P 订单 ID（沙盒付款会带有 Sandbox 标签）、交易、付款状态、收到的金额、渠道、授权码、遮蔽的银行卡号、日期、渠道响应、API 版本，以及该订单的 2C2P notes。该选项卡对有权访问此扩展的用户显示。

退款

不支持通过 OpenCart 退款。请在 2C2P 商户后台退还付款，然后在 OpenCart 中手动记录退款，例如更改订单状态。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox 2C2P Payment 是 Extensions > Extensions > Payments > VibeFox 2C2P Payment > Edit 中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺删除密钥）。它们下方有一行 Product: opencart-payment-2c2p，以及打开您 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 账户中释放名额。

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

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

故障排除

结账时未显示 2C2P：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否已填写 Merchant ID 和 Secret Key：沙盒模式下填写沙盒字段，正式模式下填写正式字段。检查顾客的货币是否受支持。当凭据缺失或默认货币不受支持时，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：没有有效结果到达您的店铺。请检查付款时所用模式的 Merchant ID 和 Secret Key 是否与 2C2P 账户一致，并检查 Redirect API version 是否与您的账户匹配。签名错误或属于其他 Merchant ID 的结果会被拒绝。请开启 Enable Logging，并在 Log 字段中查找 hash 或 Merchant ID 相关信息。另外请检查您的服务器是否接受来自 2C2P 的后端通知 URL 请求。

后端通知返回 400 FAIL：结果缺少字段、签名错误、Merchant ID 不一致或令牌错误。404 FAIL 表示该 2C2P 订单 ID 不是由本店铺发出的。503 RETRY 表示订单正被另一个请求同时确认，或处理失败；2C2P 稍后会重试。请开启 Enable Logging 查看原因。

通知 URL 在浏览器中显示 FAIL：这是正常的。该 URL 只接受来自 2C2P 的 POST 请求。

2C2P 提示订单 ID 已存在：2C2P 不接受两次相同的订单 ID。当多家店铺共用一个 2C2P 账户，或在沙盒中（许多开发者共享演示商户账户）时，会出现此情况。请设置唯一的 Order ID prefix。

已付款，但订单处于待付款或审核状态：要么付款在 2C2P 仍处于待处理状态（例如顾客尚未支付的现金付款），要么已付金额或币种与订单不符。请检查 VibeFox 2C2P Payment 选项卡中的备注，并在 2C2P 后台查看交易。

顾客看到 This payment method is currently unavailable for this order：订单币种不受支持、当前模式的 Merchant ID 或 Secret Key 为空，或订单总额为零。

顾客看到 This payment method is not available. Please reload the checkout page.:结账会话已与订单不匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。

保存时出现 Please enter your live Merchant ID 或 Please enter your live Secret Key：沙盒模式已关闭，且某个正式字段为空。请输入正式凭据，或保持 Sandbox Mode 开启。

面向开发者：在付款表单签名之前，扩展会触发 OpenCart 事件 tc2p_p_payment_fields，并附带表单字段和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox 2C2P Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件以及在维护模式下放行 2C2P 结果的启动动作）。如果 Delete Data on Uninstall 已开启，则其他网关设置（标题、描述、沙盒模式、凭据、付款页面设置、日志记录）和日志都会被删除。如果已关闭，这些设置会保留，供以后重新安装时使用。2C2P 交易记录始终保留，因此即使重新安装，旧付款的延迟结果仍会被处理。现有订单会保留其付款备注。

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

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