VibeFox Transbank for OpenCart — 帮助

系统要求

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

PHP: 8.0 或更高版本。

货币: 智利比索（CLP）。如果您的商店没有该货币，请在 System > Localisation > Currencies 中添加，小数位设为 0：Webpay Plus 只收取整数比索。对于其他货币的订单，不会显示该付款方式。

Transbank 账户: 要进行真实付款，您需要一个标准的 Webpay Plus 商户（即时扣款），并具备其正式环境的 Commerce Code 和 API Key Secret。Transbank 会在您的签约申请获批后提供 Commerce Code，并在集成验证流程结束后提供 API Key Secret（请参阅 Transbank 开发者文档）。测试时无需凭据。不支持 Webpay Plus Mall、Oneclick 和延迟扣款的商户代码。

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

安装

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

OpenCart 3

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

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

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

4. 开启 Enable / Disable，然后点击 Save。在开启 Integration (test) mode 的情况下，使用 Transbank 开发者文档中的测试卡，以 CLP 测试一笔付款。

5. 要正式上线，请输入您的 Production Commerce Code 和 Production API Key Secret，关闭 Integration (test) mode，然后点击 Save。

OpenCart 4

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

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

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

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

无需在 Transbank 设置返回 URL 或 webhook。扩展会在每笔交易中发送其返回 URL。新安装时，付款方式默认关闭，集成模式默认开启。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在以下情况向您发出警告：选择了正式模式，但正式 Commerce Code 或 API Key 缺失或无效（此时 Webpay 将在结账时隐藏）；商店的默认货币不是 CLP（其他货币下付款方式会被隐藏）；CLP 设置了小数位（金额会四舍五入为整数比索）。在开启集成模式时，页面会显示付款将使用 Transbank 集成环境和公开测试商户代码，并且不会扣除真实款项。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空或超过 128 个字符，Sort Order 必须是整数（允许负值），Total 必须是大于或等于 0 的数字，且订单状态必须存在；否则不会保存任何内容，页面会显示错误信息。

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments 用于开启或关闭该付款方式。默认值：off。

Title: 客户在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认值：Webpay Plus。必填，最多 128 个字符。

Description: 客户在 Confirm Order 步骤中、确认按钮上方看到的文字。默认值：Pay with credit, debit or prepaid card via Webpay。

Sort Order: Webpay 在结账时付款方式中的位置。留空或输入整数（允许负值）。

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

Total: 订单在商店默认货币下需达到的结账总额，达到后才会提供 Webpay。留空则对任何金额都提供 Webpay。

环境与凭据

本部分的文字链接到 Transbank 开发者文档，并说明 Transbank 何时提供正式凭据。

Integration (test) mode: 付款将通过公开的测试商户代码（597055555532）发送到 Transbank 集成环境，并自动使用该代码。下方的正式凭据不会被使用，也不会扣除真实款项。默认值：on。关闭它即可正式上线。开启时，客户在 Confirm Order 步骤会看到 TEST MODE — Integration environment. No real charges. 。

Production Commerce Code: 您的正式商户代码（Tbk-Api-Key-Id）：12 位数字，以 5970 开头。如果您的代码是 8 位，请按原样输入；保存时会自动加上 5970 前缀。空格和其他字符会被去除。Transbank 的公开测试商户代码无法用于正式环境：若使用其中任何一个，Webpay 在结账时仍会隐藏。

Production API Key Secret: 您正式商户的 Tbk-Api-Key-Secret。请妥善保密。保存时会去除空格。已保存的密钥不会再次显示：该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选 Clear saved API key，然后点击 Save。

Integration (test) mode 决定新付款的去向。每笔付款都会记住其所在环境：付款的确认和退款始终使用创建该付款时的环境（集成或正式）和凭据，即使您之后更改了模式。

返回 URL

Return from Webpay: Transbank 将客户送回的地址，仅供参考。OpenCart 3 中其格式类似：https://your-store/index.php?route=extension/payment/wcp_transbank_gateway/back，OpenCart 4 中类似：https://your-store/index.php?route=extension/wcp_transbank_gateway/payment/wcp_transbank_gateway.back。无需在 Transbank 中进行任何设置：扩展会在每笔交易中发送此 URL（Transbank 没有 webhook：客户返回时才会确认付款）。该地址必须可从互联网访问；维护模式不会阻止它（在 OpenCart 4 中，扩展会为此添加一个启动动作）。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（缺失订单）。只有当客户从 Webpay 返回后，商店通过 Transbank 确认交易（commit），订单才会获得状态。以下每个字段都列出您的 OpenCart 订单状态。

Order Status After Payment: Webpay 付款经批准并验证后设置的状态。默认值：Processing。

Transbank Payment On Hold Status: Transbank 授权了一笔与订单不匹配的付款（金额、buy order、session id）：订单会被暂挂以供人工审核，并附带备注说明原因。默认值：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Refunded Status: 在订单页面将付款全额退款后设置。默认值：Refunded。

高级

Debug log: 将 API 请求和返回记录到 OpenCart 日志文件夹（storage/logs）中的 wc_tbk_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误也始终会被记录。不会记录任何银行卡数据、API 密钥或完整令牌。默认值：off。

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

Delete data on uninstall: 开启后，卸载扩展时会删除网关设置和日志。订单和付款数据始终保留。默认值：off。

导入 / 导出

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

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

结账

在 Payment Method 步骤，客户选择付款方式（默认为 Webpay Plus）。在 Confirm Order 步骤，客户会看到您的说明以及提示 You will be redirected to Webpay (Transbank) to complete the payment. OpenCart 在此步骤创建订单，此时仍没有状态。当客户点击 Confirm Order 后，扩展会以整数比索为单位，按订单总额创建一笔 Transbank 交易（带小数的总额会四舍五入到最接近的比索），客户会直接进入 Webpay 表单，在那里使用信用卡、借记卡或预付卡付款。在 OpenCart 4 中，客户通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

客户返回时，扩展会通过服务器对服务器的方式与 Transbank 确认（commit）交易。只有在 Transbank 确认后，订单才会被标记为已付款：响应必须是已批准的，并且金额、buy order 和会话必须与商店为本次尝试发送的信息一致。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规的订单邮件、更新库存；客户会看到 OpenCart 订单成功页面，并显示 Your Webpay payment has been received. 对于待审核的订单，页面会显示 Your Webpay payment was received and is being reviewed by the store.

如果确认请求失败（例如超时），扩展会向 Transbank 查询交易状态。如果仍无法确定状态，订单将保持无状态，客户会带着 We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again. 返回结账页面。如果此时有另一个请求正在确认同一购物车，或者 Transbank 已批准付款但订单状态尚未设置，客户会看到 Payment confirmation 页面，其中显示 Your Webpay payment is being confirmed. Please do not pay again — check again in a moment.，并有 Check again 和 Back to checkout 按钮。之后会根据已保存的响应设置状态，无需再次确认。

如果客户在 Webpay 上取消，或 Webpay 表单过期或报错，则不会扣款。客户会带着提示返回结账页面，例如 You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. 银行卡被拒时会显示 Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. 购物车会被保留，每次新的尝试都会是一笔新的 Webpay 交易。在 OpenCart 4 中，这些提示会显示在结账页面上方。

在 OpenCart 3 中，每次显示 Confirm Order 步骤时，OpenCart 都会创建一个新订单。OpenCart 4 则为结账保留一个订单并对其进行更新，因此在付款被取消或拒绝后，客户会用新的 Webpay 交易为同一个订单付款。如果订单在付款开始后发生了变化（其货币或总额与交易不再匹配），交易将不会被确认，因此 Transbank 不会扣款，客户会看到 Your order changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. 如果订单已有状态，或同一购物车的另一个订单已付款，迟到的返回同样不会被确认：客户会进入已付款订单的成功页面，或看到 This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

在 OpenCart 4 中，如果结账所用的订单在没有 Webpay 付款的情况下已获得状态，或在此期间被商店关闭，那么下一次点击 Confirm Order 时会将客户送回结账页面并显示相同的提示，购物车将以新订单付款。如果结账所用的订单已付款，但此后购物车发生了变化（包括数量变化），客户会被送回结账页面，新的购物车将以新订单付款。

如果 Webpay 无法发起付款，客户将停留在 Confirm Order 步骤，并看到简短提示，例如 Could not connect to Webpay. Please try again in a moment. 或 Webpay could not start the payment. Please try again or choose another payment method. 技术原因会写入日志。

Transbank 没有付款 webhook：结果会在客户从 Webpay 返回时处理。如果客户在 Webpay 页面关闭浏览器且从未返回，交易不会被确认，订单将保持无状态；据 Transbank 称，未确认的交易不会结算。该扩展不支持 Webpay Plus Mall、已保存的 Oneclick 卡、订阅、延迟扣款或货币转换。

订单与退款

订单状态

无状态（缺失订单）: 客户已被转到 Webpay，但尚未付款、已取消、让表单过期、银行卡被拒，或付款尚无法确认。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders，才会显示此类订单。

Order Status After Payment（默认 Processing）: Transbank 已批准付款。备注会显示授权码、银行卡后四位、buy order、金额、付款类型和分期期数。

Transbank Payment On Hold Status（默认 Pending）: Transbank 授权了一笔与订单不匹配的付款（金额、buy order 或会话）。备注会列出差异。请检查 Transbank 门户，然后完成订单或退还付款。

Refunded Status（默认 Refunded）: 付款已通过该扩展全额退款。

如果 Webpay 为已有状态的订单返回付款，或为已被其他订单付款的购物车返回付款，该付款不会被确认，备注会提醒您在客户报告扣款时检查 Transbank 门户。取消、表单过期、表单错误和银行卡被拒的情况也会被记录。备注是订单 History 中的条目，客户看不到。

VibeFox Transbank Gateway 选项卡

在 Sales > Orders 中打开一个通过 Webpay 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox Transbank Gateway 选项卡会显示 Buy order 及其环境（测试付款会显示 Integration 标签）、付款的 Status、Authorization code、Card / payment type（含分期期数）、Charged / refunded、退款表单、退款记录、Webpay attempts of the order 以及 Transbank notes。该选项卡对有权访问扩展的用户可见。

退款

在该选项卡中，以 CLP 输入 Amount（会自动填入尚未退还的金额），可选填写 Reason (optional)，然后点击 Refund via Transbank。确认询问 Refund this amount via Transbank? 全额和部分退款均以整数比索为单位。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。带小数的部分金额会被拒绝，并显示 Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. 带小数的订单总额的最后零头会像扣款一样四舍五入。退款金额不会超过 Transbank 实际扣款的金额。退款会发送到付款时所在的环境，因此对于正式付款，必须已设置正式凭据。

Transbank 会返回冲正（REVERSED）或作废（NULLIFIED）结果。成功的退款会被添加到退款记录和备注中，包括金额、类型、授权码以及 Transbank 上的剩余余额。全额退款会设置 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。如果 Transbank 不接受退款，选项卡会显示错误，且不会记录任何退款。

在 Sales > Returns 中的商品退货不会通过 Transbank 退回款项。在 Transbank 门户中进行的退款不会导入 OpenCart。

许可证密钥

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

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

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

故障排除

结账时不显示 Webpay Plus: 请检查许可证是否有效、Enable / Disable 是否已开启、客户是否以 CLP 付款，并且在集成模式关闭的情况下，是否已保存有效的 Production Commerce Code（12 位数字，以 5970 开头）和 Production API Key Secret。同时检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。如果缺少凭据或商店货币不是 CLP，设置页面会显示警告。

付款已完成，但订单仍无状态: Transbank 没有 webhook，因此订单只有在客户从 Webpay 返回时才会获得状态。如果客户在 Webpay 上关闭了浏览器，则交易未被确认，据 Transbank 称也不会结算。请开启 Debug log，查看 Log 字段，并在 Transbank 门户中检查该交易。

客户看到 We could not confirm your Webpay payment with Transbank: 确认请求失败，且无法检查状态。订单未被更改，原因已记录在日志中。客户可以稍后重试。如果 Transbank 门户显示该交易已授权，请在客户再次付款之前与其联系。

客户看到 Your order changed after the Webpay payment was started: 订单总额或货币与交易不一致。没有扣款；客户需要重新付款。

客户在 Confirm Order 后看到错误: 请开启 Debug log，并查看扩展页面上的 Log 字段。Webpay payments are not available at the moment 通常表示正式凭据错误。Could not connect to Webpay 表示无法连接到 Transbank。Transbank Webpay only supports payments in CLP (Chilean Peso) 表示订单使用的是其他货币。This payment method is not available. Please reload the checkout page. 表示结账会话与订单不再匹配：客户需要重新加载结账页面。

总额和退款相差几个比索: CLP 货币有小数位。Webpay 只收取整数比索，因此总额会被四舍五入。请在 System > Localisation > Currencies 中将 CLP 的小数位设为 0。

付款后订单处于审核状态: 请阅读 VibeFox Transbank Gateway 选项卡中的备注（参见订单状态），然后完成订单或退还付款。

退款失败，提示 The production Commerce Code / API Key are missing: 该付款是在正式环境中完成的，但未保存正式凭据。请输入凭据后重试。

退款失败，提示 Transbank refused the refund 或 Transbank did not approve the refund: Transbank 没有接受该退款；消息会显示其返回的原因或类型及响应代码。没有退款任何金额。请在 Transbank 门户中检查该交易。

退款失败，提示 Another request is processing this order: 该订单正在同时进行退款或确认。请稍后再试。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Transbank Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除其事件和启动动作，该启动动作用于在维护模式下放行来自 Webpay 的返回）。如果开启了 Delete data on uninstall，则其他网关设置（标题、描述、集成模式、凭据、调试日志开关）和日志会被删除；如果关闭，这些内容会保留，以便之后重新安装时使用。订单的 Webpay 交易尝试和退款始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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