VibeFox KOMOJU for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

KOMOJU 账户：您需要 KOMOJU 后台中创建的 Webhook 的密钥（正式环境 sk_live_...，测试模式则为 sk_test_...）以及该 Webhook 的密钥令牌（参见配置）。不需要公开密钥。KOMOJU 必须能够访问您商店的 Webhook URL。

订单货币：JPY、USD、EUR、TWD、KRW、PLN、GBP、HKD、SGD、NZD、AUD、IDR、MYR、PHP、THB、CNY、BRL、CHF、CAD 或 VND。对于其他货币的订单，将隐藏该支付方式。

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

安装

下载文件是一个压缩包，包含两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包中有 README.txt、OpenCart 3 安装包 wcp_komoju_payment-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_komoju_payment.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 在 KOMOJU 后台添加一个 Webhook，URL 和事件使用 Webhook URL 部分所示的内容，并复制其密钥令牌（参见配置）。

5. 输入正式环境的密钥和正式 Webhook 密钥令牌，以及沙盒模式使用的测试密钥。打开 Enable/Disable，然后点击 Save。

OpenCart 4

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

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

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

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

新安装时，支付方式默认关闭，沙盒模式也默认关闭。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox KOMOJU Payment > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。当测试模式开启时，设置上方会显示 KOMOJU Sandbox Mode is enabled.。如果当前模式没有密钥（此时结账时会隐藏该支付方式）或没有 Webhook 密钥令牌（此时 KOMOJU 的通知会被拒绝，因此便利店和银行转账付款永远不会被确认），页面会发出警告；如果 KOMOJU 不支持商店的默认货币（此时该货币的订单会隐藏该支付方式），页面也会发出警告。如果没有修改扩展的权限，页面仅显示设置，无法保存。

保存时，Title 最多 128 个字符，Sort Order 必须为整数（允许负数），Total 须为 0 或更大的数字，且地理区域和订单状态必须存在。否则不会保存任何内容，页面会指出出错的字段。缺少密钥不影响保存。

KOMOJU 支付

Enable/Disable：Enable KOMOJU Payment Gateway 开启或关闭该支付方式。默认：关闭。

Title：客户在结账时看到的支付方式名称，也是订单中保存的支付方式名称。默认：KOMOJU Payment。如果留空，则使用默认名称。最多 128 个字符。

Description：在 Confirm Order 步骤中显示给客户、位于确认按钮上方的文字。默认：Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

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

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

Total：订单必须达到的结账总额（以商店默认货币计）才会提供 KOMOJU。留空则对任何金额都提供 KOMOJU。

正式环境 API 密钥

密钥可在 KOMOJU 后台找到（那里有各部分的链接）：密钥在 Settings > API keys 下，Webhook 密钥令牌在 Settings > Webhooks 下（请先在那里添加 Webhook URL 部分所示的 Webhook URL）。

Live Secret Key：您的 KOMOJU 正式环境密钥。以 sk_live_ 开头。

Live Webhook Secret Token：正式环境 Webhook 的密钥令牌。用于验证每条通知的签名。

测试模式

KOMOJU 对测试和正式付款使用相同的 API 地址：由密钥决定模式。付款会保留其付款时所在的模式，因此订单的退款和状态查询始终使用该模式的密钥。

Sandbox Mode：Enable test mode (use the test keys below, no real payments)。默认：关闭。开启时，Confirm Order 步骤会在描述上方显示 Test mode。

Sandbox Secret Key：您的 KOMOJU 测试密钥。以 sk_test_ 开头。

Sandbox Webhook Secret Token：测试模式 Webhook 的密钥令牌。

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

Webhook URL

Webhook 会将付款信息通知您的商店，包括延迟的便利店（konbini）和银行转账付款。在 KOMOJU 后台的 Settings > Webhooks 中，添加本部分显示的 URL，正式模式和测试模式都要添加。在 OpenCart 3 中 URL 形如 https://your-store/index.php?route=extension/payment/wcp_komoju_payment/webhook；在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_komoju_payment/payment/wcp_komoju_payment.webhook，由您 OpenCart 安装的前台地址生成。请完全按照设置中显示的内容复制该 URL。然后将每个 Webhook 的密钥令牌复制到 Live Webhook Secret Token 或 Sandbox Webhook Secret Token 中。

请选择以下事件（本部分也列出了这些事件）：

过期、取消和失败事件只会针对订单的当前付款修改订单，因此较早尝试的付款无法取消以其他方式支付的订单。没有有效签名的 Webhook 会被拒绝。使用两个密钥令牌之一签名的 Webhook 会被接受，但仅限于同一模式的付款。没有 Webhook 时，信用卡付款在客户返回商店时仍会被确认，但便利店和银行转账付款则永远不会被确认。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 KOMOJU 确认付款之后，订单才会获得状态。下方每个字段都列出您的 OpenCart 订单状态。

Order Status After Payment：付款已收款，且金额和货币已核实。默认：Processing。

Awaiting KOMOJU Payment Status：付款已授权：已签发便利店凭证或银行转账凭证，或付款正等待在 KOMOJU 后台收款。默认：Pending。

KOMOJU Payment On Hold Status：实付金额或货币与订单不符，或付款是在订单被取消后到达的。备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。

Cancelled Payment Status：等待中订单的付款已过期或被取消，例如便利店凭证未在规定时间内付款。默认：Canceled。

Failed Payment Status：等待中订单的付款失败。默认：Failed。

Refunded Status：付款全额退款后设置，可以在订单页面或 KOMOJU 后台进行退款。默认：Refunded。

您可以在 System > Localisation > Order Statuses 中创建自己的状态，例如 Awaiting KOMOJU payment 或 On hold，然后在此处选择。

高级

Invoice Prefix：发送给 KOMOJU 的订单号前缀。KOMOJU 中的编号由前缀、OpenCart 订单号和一个简短的随机后缀组成，例如 OC-123-A1B2C3。如果您在多个商店中使用同一个 KOMOJU 账户，请为每个商店设置唯一的前缀。默认：OC-。

Enable Logging：将 KOMOJU 事件和 API 调用写入 OpenCart 日志文件夹（storage/logs）中的 komoju_p_debug.log.php。该文件无法通过网页打开。密钥和客户数据不会被记录。错误和警告始终会被写入。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除网关设置和日志。订单以及 KOMOJU 的交易和退款始终保留，因此旧订单在重新安装后仍可确认和退款。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤，客户选择支付方式（默认为 KOMOJU Payment）。在 Confirm Order 步骤，客户会看到您的描述以及提示 You will be redirected to the KOMOJU payment page to complete the payment.。OpenCart 在此步骤创建订单，此时仍无状态。当客户点击 Confirm Order 时，扩展会以订单货币为订单总额创建 KOMOJU 付款会话，并将客户带到 KOMOJU 付款页面。客户的电子邮件、姓名、付款和配送地址以及订购的商品会传递给 KOMOJU。该页面会根据客户的语言以日语、英语或韩语显示（其他语言则以英语显示）。客户在页面上选择付款方式。可用的付款方式取决于您的 KOMOJU 账户和订单货币。

在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中），然后点击结账页面底部的 Confirm Order。OpenCart 4 默认不要求付款地址；此时扩展会将配送地址作为付款地址。

付款后，客户会返回您的商店。扩展会使用付款所在模式的密钥，通过 KOMOJU API 读取付款会话。只有在 KOMOJU 确认之后，订单才会被标记为已付款：通过签名的 Webhook，或客户返回时读取会话。随后，订单以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，客户会看到 OpenCart 订单成功页面，并显示 Your payment with KOMOJU has been received.。如果此时无法连接 KOMOJU，或付款已确认但尚未应用，则会显示 Payment confirmation 页面，其中包含 We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. 以及 Check again 按钮。

对于便利店和银行转账付款，客户会获得一份付款凭证。订单获得 Awaiting KOMOJU Payment Status，成功页面会告知客户付款已授权，须按照 KOMOJU 的指示完成（例如在便利店或通过银行转账）。客户付款且 KOMOJU 发出 Webhook 后，订单会转为 Order Status After Payment。如果凭证过期，订单会转为 Cancelled Payment Status。

如果付款未完成，客户会返回结账页面，并看到 The payment was not completed. You can try again or choose another payment method.。如果订单已被取消，提示为 The KOMOJU payment was not completed and the order has been cancelled.。购物车会被保留。在 OpenCart 4 中，这些提示显示在结账页面上方。每次新尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单；OpenCart 4 则会更新结账的订单并以新的尝试支付同一订单）都会检查本订单以及同一购物车中其他订单的未结 KOMOJU 会话：本订单中总额未变的未结会话会被复用，其他未结会话会在 KOMOJU 中被取消，而期间已付款的会话则会确认其订单，而不是创建新的付款。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在此期间已被关闭（例如便利店凭证已过期、付款失败或您取消了订单），客户会被带回结账页面，并显示 Your previous order was cancelled or its payment failed. Please confirm the order again. 如果订单已经生成，且购物车中现在是其他商品，提示为 Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. 两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。

如果 KOMOJU 无法发起付款，客户会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 KOMOJU could not accept this payment: 后跟原因，KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us.，或 Payment error: Could not connect to KOMOJU. Please try again in a moment.。技术原因会写入日志。

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

该扩展在您的网站上没有银行卡表单，也不支持已保存的银行卡或订阅。它不限制支付方式：付款方式在 KOMOJU 页面上选择。它没有手动收款操作：为手动收款而授权的付款必须在 KOMOJU 后台收款，在此之前订单会保持在 Awaiting KOMOJU Payment Status。

订单和退款

订单状态

No status (missing order)：客户已被引导至 KOMOJU 但尚未付款，或 KOMOJU 尚未确认付款。在 Sales > Orders 中，此类订单仅在 Order Status 筛选条件设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：KOMOJU 已确认付款。备注会显示 KOMOJU 付款 ID、付款方式以及确认方式（Webhook 或返回）。

Awaiting KOMOJU Payment Status（默认 Pending）：便利店或银行转账凭证已签发并等待付款，或付款正等待在 KOMOJU 后台收款。

KOMOJU Payment On Hold Status（默认 Pending）：KOMOJU 报告的金额或货币与订单总额不同，或付款是在订单被取消后收款的。备注会说明原因。请检查订单，然后完成订单或退还付款。

Cancelled Payment Status（默认 Canceled）：付款凭证已过期或付款已取消。

Failed Payment Status（默认 Failed）：等待中订单的付款失败。

Refunded Status（默认 Refunded）：付款已全额退款，可以在订单页面或 KOMOJU 后台进行。

如果对已付款的订单，或对已付款购物车中的另一订单再次收取付款，订单不会被更改。备注会提示您，如果这是重复付款，请在 KOMOJU 后台退款。已退款的订单永远不会被重新打开。

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

VibeFox KOMOJU Payment 标签

在 Sales > Orders 中打开一笔使用 KOMOJU 付款的订单。在订单页面底部，History 和 Additional 旁边，VibeFox KOMOJU Payment 标签会显示 KOMOJU 付款 ID（链接到 KOMOJU 后台中的该付款）、测试付款的 Test mode 标签、付款方式、会话、KOMOJU 中的订单号、状态、Paid / refunded 金额、退款表单、退款历史（来自 OpenCart 或 KOMOJU 后台）以及订单的 KOMOJU notes。该标签仅对有权访问此扩展的用户显示。

退款

在 VibeFox KOMOJU Payment 标签中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via KOMOJU。确认提示 Refund this amount through KOMOJU? This cannot be undone.。支持全额和部分退款。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。退款金额以 KOMOJU 实际收取的金额为上限，因此在金额出现差异后，您最多只能退还客户实付的金额，而不是订单总额。退款使用付款所在模式的密钥发送，因此必须已设置该模式的密钥。扩展会先在 KOMOJU 中核实付款，并拒绝超过仍可退款金额的退款。如果 KOMOJU 无法自动退款（某些付款方式，例如便利店，需要客户的银行信息），将显示 KOMOJU 的错误信息，且不会记录任何内容：此类退款请在 KOMOJU 后台处理。只有 KOMOJU 确认后，退款才算完成。成功的退款会添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，且不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。只有 KOMOJU 完成付款收款后，才能进行退款。

对于 KOMOJU 转换为其他货币的付款（例如，以 JPY 支付 EUR 订单的便利店付款），从 OpenCart 只能进行全额退款。部分退款请在 KOMOJU 后台进行。

Sales > Returns 中的商品退货不会通过 KOMOJU 退回款项。

在 KOMOJU 后台进行的退款会通过 Webhook 送达，并附带备注添加到退款历史中。当整笔付款被退款时，订单会被设置为 Refunded Status。对于已转换为其他货币的付款，在后台进行的部分退款仅会在订单上做备注：请在 OpenCart 中手动记录相应金额。

许可证密钥

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

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

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

故障排除

KOMOJU 未出现在结账页面：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否已设置密钥：沙盒模式为 Sandbox Secret Key，正式模式为 Live Secret Key。客户必须使用 KOMOJU 支持的货币付款。设置页面会在缺少内容时显示警告。另外请检查支付地址是否在所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍没有状态：Webhook 没有生效。请在 KOMOJU 后台检查所用模式的 Webhook 是否存在，其 URL 是否与 Webhook URL 部分显示的完全一致，以及事件是否已选中。检查其密钥令牌是否填写在对应字段中（Live Webhook Secret Token 或 Sandbox Webhook Secret Token），并查看扩展页面上的 Log 字段。信用卡付款在客户返回您的商店时也会被确认，但便利店和银行转账付款只能通过 Webhook 确认。

Webhook 返回 Failed to verify KOMOJU webhook signature.：密钥令牌缺失，或属于另一个 Webhook。KOMOJU 会重试该通知。

Webhook 返回 Mode mismatch, ignored.：该 Webhook 使用的是与付款模式不同的密钥令牌签名。请为正式模式和测试模式分别使用独立的 Webhook 和令牌，并检查两者是否互换。

Webhook 返回 Order not found.：该付款不属于本商店的订单，例如是使用同一 KOMOJU 账户的其他商店付款的。该事件会被忽略。

Webhook 返回 Order is busy, retry later. 或 Temporary error, retry later.：订单正被另一请求更新，或当时无法处理该付款。KOMOJU 会重试该通知。原因见日志。

Webhook URL 在浏览器中显示错误：这是正常现象。该 URL 只接受来自 KOMOJU 的已签名请求。

订单处于等待或暂挂状态：请阅读订单标签中的 KOMOJU notes。可能是凭证正在等待付款，付款正在等待在 KOMOJU 后台收款，金额或货币不匹配，或付款是在订单取消后到达的。

标签中没有退款表单：标签会说明原因：KOMOJU 尚未收取该付款、付款已全额退款、您的用户组没有修改扩展的权限，或付款模式的密钥未设置。

退款失败：请阅读提示信息。付款所在模式的密钥可能缺失，该付款可能无法自动退款（请在 KOMOJU 后台退款），KOMOJU 可能无法以已配置的密钥识别该付款，或者对于已转换的付款只能进行全额退款。

面向开发者：扩展会触发 OpenCart 事件 komoju_p_supported_currencies（用于更改货币列表）和 komoju_p_session_params（用于更改付款会话，例如付款方式）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox KOMOJU Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其启动动作，该动作在维护模式下允许 Webhook 和客户的返回请求通过）。如果 Delete data on uninstall 已开启，其他网关设置（标题、描述、密钥、Webhook 令牌、沙盒模式、发票前缀、日志记录）和日志都会被删除。如果未开启，这些内容会保留，以便之后重新安装时使用。KOMOJU 的交易和退款始终会保留，因此旧订单在重新安装后仍可确认和退款。现有订单会保留其付款备注。

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

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