VibeFox KOMOJU for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。低于此版本的 PHP 无法安装本模块。

KOMOJU 账户：您需要密钥（sk_live_...，以及测试模式下的 sk_test_...），以及在 KOMOJU 控制面板中创建的 Webhook 的密钥令牌（参见配置）。不需要可公开的密钥（publishable key）。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 购买。一个密钥只能用于一个域名。

安装

1. 在后台进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox KOMOJU Payment，然后点击 Configure。

3. 在配置页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 在 KOMOJU 控制面板中，添加一个 Webhook，填入 Webhook URL 部分所示的 URL 和事件，并复制其密钥令牌（参见配置）。

5. 输入正式环境的密钥和正式环境 Webhook 的密钥令牌，并输入测试模式所用的测试密钥和令牌。开启 Enable/Disable，然后点击 Save。

安装时，模块会创建两种订单状态：Awaiting KOMOJU payment 和 KOMOJU payment on hold。PrestaShop 只会将新的付款模块关联到安装时已启用的国家：之后启用的国家，必须在 Payment > Preferences 中为该模块勾选。您还可以在那里限制币种和客户组。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox KOMOJU Payment > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。在字段上方，当测试模式开启时，页面会显示 KOMOJU Sandbox Mode is enabled.。当当前模式没有密钥（此时结账页面将隐藏该付款方式）或没有 Webhook 密钥令牌（此时 KOMOJU 通知会被拒绝，因此便利店和银行转账付款永远无法确认），以及 KOMOJU 不支持店铺默认币种（此时以该币种计价的购物车将隐藏该付款方式）时，页面会发出警告。

KOMOJU 付款

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

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：KOMOJU Payment。

Description：结账时显示在付款方式下方的文字。默认：Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

正式环境 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)。默认：关闭。开启时，结账页面会在描述上方显示 Test mode。

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

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

已保存的密钥和令牌不会再次显示。字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

清除已保存的密钥：勾选某个密钥或令牌，然后点击 Save 将其删除。字段留空则保留已保存的值。

Webhook 地址

Webhook 会向您的店铺通知付款情况，包括延迟的便利店和银行转账付款。在 KOMOJU 控制面板的 Settings > Webhooks 中，为正式模式和测试模式分别添加本部分显示的 URL。使用友好 URL 时，它的格式类似 https://your-shop/module/wcp_komoju_payment/webhook，可能带有语言代码，例如 /en/。请完全按照设置页面显示的内容复制 URL。然后，将每个 Webhook 的密钥令牌分别复制到 Live Webhook Secret Token 或 Sandbox Webhook Secret Token 中。

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

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

高级

Invoice Prefix：发送给 KOMOJU 的订单号前缀，后面接购物车编号。如果多个店铺使用同一个 KOMOJU 账户，请让每个店铺的前缀各不相同。默认：PS-。

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

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

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

结账

在付款步骤中，顾客选择付款方式（默认为 KOMOJU Payment）并确认。模块会按购物车总额和购物车币种创建 KOMOJU 付款会话，并将顾客带到 KOMOJU 付款页面。电子邮件、姓名、账单和收货地址以及订购的商品会传递给 KOMOJU。付款页面将根据购物车的语言以日语、英语或韩语显示（其他语言则显示英语）。顾客在那里选择付款方式。可用的付款方式取决于您的 KOMOJU 账户和购物车币种。此时尚未创建订单。

付款完成后，顾客返回您的店铺。模块会使用付款所属模式的密钥，从 KOMOJU API 读取付款会话。只有在 KOMOJU 确认付款后，即通过已签名的 Webhook，或顾客返回时读取会话，订单才会被标记为已付款。随后订单被创建，顾客会看到标准的订单确认页面，并显示 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 状态创建，确认页面会告知顾客按照 KOMOJU 的说明完成付款（例如前往便利店或通过银行转账）。顾客付款且 KOMOJU 发送 Webhook 后，订单变为 Payment accepted。如果凭单之后过期或付款失败，确认页面会显示 Your KOMOJU payment was not completed. Please contact us about this order.

如果付款未完成，顾客会返回结账页面，并看到 The payment was not completed. You can try again or choose another payment method. 购物车会被保留。如果总额未变，新的尝试会复用未关闭的 KOMOJU 会话。使用旧总额的会话会在 KOMOJU 中被取消；如果某个会话在此期间已付款，则会创建订单，而不是新建付款。

如果 KOMOJU 无法启动付款，顾客会停留在结账页面，并看到简短提示，例如 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. 技术原因会写入日志。

如果购物车中的优惠券在付款与确认之间失效，PrestaShop 会将其从订单中移除。订单随后会进入 KOMOJU payment on hold 状态并附带备注，因为顾客是按折扣后的价格付款的。

即使店铺处于维护模式，Webhook 仍会工作，并且不受店铺国家限制的阻挡。

模块在您的网站上没有银行卡表单、保存的银行卡或订阅功能。它不限制付款方式：付款方式在 KOMOJU 页面上选择。它没有手动扣款操作：为手动扣款授权的付款必须在 KOMOJU 控制面板中扣款，在此之前，订单会保持 Awaiting KOMOJU payment 状态。

订单和退款

订单状态

No order yet：顾客已被带到 KOMOJU 但尚未付款，或 KOMOJU 尚未确认付款。此时仅存在购物车。

Payment accepted：KOMOJU 已确认付款。付款会以 KOMOJU 付款 ID 作为交易 ID 记录，备注中会显示付款 ID、付款方式以及确认方式（Webhook 或返回）。

Awaiting KOMOJU payment：便利店或银行转账凭单已开具并等待付款，或付款正在等待 KOMOJU 控制面板中的扣款。

KOMOJU payment on hold：KOMOJU 报告的金额或币种与订单总额不符（例如，付款开始后购物车被修改），优惠券已被移除，或订单取消后付款才被扣款。备注会说明原因。请检查订单并处理，或退还付款。

Canceled：付款凭单已过期或付款已取消。

Payment error：现有订单的付款失败。

Refunded：付款已全额退还，可在订单页面或 KOMOJU 控制面板中操作。

如果已付款订单又扣了第二笔款，订单不会改变。备注会提示您，如果这是重复付款，请在 KOMOJU 控制面板中退款。已退款的订单永远不会被重新开启。

KOMOJU 付款区块

订单页面会显示 KOMOJU payment 区块，包括 KOMOJU 付款 ID（链接到 KOMOJU 控制面板中的该付款）以及付款方式、会话、KOMOJU 中的订单号、状态、已付金额和已退金额；测试付款会显示 Test mode 标记；另外还有退款记录和订单的 KOMOJU notes。

退款

在 KOMOJU payment 区块中输入金额（会自动填入尚未退还的金额），可选填写原因，然后点击 Refund via KOMOJU。请确认提示 Refund this amount through KOMOJU? This cannot be undone. 支持全额和部分退款。您需要拥有编辑订单的权限。退款金额以 KOMOJU 实际收取的金额为上限，因此在金额不符之后，您最多只能退还顾客所付的金额，而不是订单总额。退款使用付款所属模式的密钥发送，因此必须已设置该模式的密钥。模块会先在 KOMOJU 中核对付款，并拒绝超过仍可退款金额的退款。如果 KOMOJU 无法自动退款（某些付款方式，例如便利店，需要顾客的银行信息），将显示 KOMOJU 的错误信息，并且不会记录任何内容：此类退款请在 KOMOJU 控制面板中处理。只有 KOMOJU 确认后，退款才算完成。成功的退款会添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会改变状态。只有 KOMOJU 已扣款后，才能退款。

对于 KOMOJU 转换为其他币种的付款（例如，EUR 购物车使用 JPY 的便利店付款），从 PrestaShop 只能进行全额退款。部分退款请在 KOMOJU 控制面板中进行。

模块不会创建信用单。订单页面上标准的 PrestaShop 退款按钮不会通过 KOMOJU 退回款项。

在 KOMOJU 控制面板中进行的退款会通过 Webhook 到达，并附带备注添加到退款记录中。整笔付款退款后，订单会设为 Refunded。对于转换为其他币种的付款，在控制面板中进行的部分退款仅会记录在订单上：请在 PrestaShop 中手动记录相应金额（信用单）。

许可证密钥

本模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox KOMOJU Payment 许可证区块位于 Modules > Module Manager > VibeFox KOMOJU Payment > Configure 页面中，位于设置上方，是第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以隐藏部分字符的方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有一行 Product: presta-payment-komoju，以及链接 Manage licenses and domains in your account，点击后将打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。区块中的文字跟随后台语言（包含英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用上一次已知的状态运行。

一个密钥只能用于一个域名：主店铺的域名，多店铺配置中亦是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 KOMOJU。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前完成模块设置，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也仍可进行。

许可证到期后，模块仍会继续运行，但更新和支持需要续期。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时没有显示 KOMOJU：请检查许可证是否有效，Enable/Disable 是否开启，以及当前模式是否有密钥：测试模式需要 Sandbox Secret Key，正式模式需要 Live Secret Key。购物车币种必须受 KOMOJU 支持。缺少内容时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于该购物车币种、顾客所在国家和顾客组。

付款已完成，但未创建订单：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 is busy, retry later. 或 Temporary error, retry later.:订单正被另一请求更新，或当时无法创建订单（例如模块已禁用），或无法检查付款。KOMOJU 会重试该通知。原因记录在日志中。

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

订单处于 KOMOJU payment on hold 或 Awaiting KOMOJU payment 状态：请阅读订单区块中的 KOMOJU notes。可能是凭单在等待付款，付款在等待 KOMOJU 控制面板中的扣款，金额或币种不一致，优惠券已被移除，或付款发生在订单取消之后。

退款失败：请阅读提示信息。可能是付款所属模式的密钥缺失，付款无法自动退款（请在 KOMOJU 控制面板中退款），KOMOJU 无法用当前配置的密钥识别该付款，或者转换过的付款只能全额退款。

开发人员可以使用 actionKomojuPSupportedCurrencies 钩子修改币种列表，并使用 actionKomojuPSessionParams 钩子修改付款会话（例如付款方式）。

卸载

前往 Modules > Module Manager，打开 VibeFox KOMOJU Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态总会被删除。如果 Delete data on uninstall 已开启，则会删除网关设置和日志。如果已关闭，则会保留所有设置，以便日后重新安装。KOMOJU 交易和退款以及订单状态 Awaiting KOMOJU payment 和 KOMOJU payment on hold 始终会保留，因此重新安装后，旧订单仍可被确认和退款。现有订单会保留其付款备注和交易 ID。

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