VibeFox KOMOJU for WooCommerce — 帮助

系统要求

WordPress: 6.0 或更高版本。

WooCommerce: 7.0 或更高版本，已安装并启用。否则插件拒绝启用。

PHP: 8.0 或更高版本。

HTTPS: 网站须使用 HTTPS，且 KOMOJU 必须能够访问 Webhook URL。

KOMOJU account: 需要密钥（sk_live_...；测试模式使用 sk_test_...）及在 KOMOJU 控制面板创建的 Webhook 密钥令牌（参见“配置”）。不需要可发布密钥。

Store currency: JPY、USD、EUR、TWD、KRW、PLN、GBP、HKD、SGD、NZD、AUD、IDR、MYR、PHP、THB、CNY、BRL、CHF、CAD 或 VND。其他币种会隐藏此付款方式。

VibeFox license key: 从 vibefox.net 购买。每个密钥用于一个域名。

安装

1. 在 WordPress 打开 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，点击 Install Now。也可通过 FTP 将 wcp_komoju_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

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

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

5. 在 KOMOJU 控制面板添加 Webhook，使用设置页面显示的 URL 和列出的事件，然后复制其密钥令牌（参见“配置”）。

6. 输入正式密钥和正式 Webhook 密钥令牌，以及沙盒模式的测试凭据。开启 Enable/Disable 并保存。

配置

所有设置都在同一页面：WooCommerce > Settings > Payments > KOMOJU Payment。测试模式开启时，字段上方显示 KOMOJU Sandbox Mode is enabled.。当前模式缺少密钥时会警告（结账时隐藏付款方式），缺少 Webhook 密钥令牌时也会警告（拒绝 KOMOJU 通知，因此便利店和银行转账付款永远不会确认），店铺币种不受支持时同样警告。在付款方式列表中，当前模式配置密钥前，KOMOJU 标记为需要设置；沙盒模式开启时显示测试标记。

常规

Enable/Disable: Enable KOMOJU Payment Gateway 开启或关闭付款方式。默认：off。

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）。

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)。默认：off。开启时，结账页面在说明上方显示 Test mode。

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

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

Webhook URL

Webhook 向店铺通知付款情况，包括延迟到账的便利店和银行转账付款。在 KOMOJU 控制面板的 Settings > Webhooks 中，分别为正式和测试模式添加此设置区块显示的 URL，例如 https://your-site/wc-api/komoju_p_webhook/。如果网站 URL 使用语言前缀，请完整照抄设置中显示的 URL。然后将每个 Webhook 的密钥令牌复制到 Live Webhook Secret Token 或 Sandbox Webhook Secret Token。

选择以下事件：

到期、取消和失败事件仅针对订单当前付款修改订单，因此先前尝试的付款不能取消正在通过其他方式付款的订单。没有有效签名的 Webhook 会被拒绝。使用任一密钥令牌签名的 Webhook 都可接受，但仅限相同模式的订单。没有 Webhook 时，银行卡付款仍可在顾客返回店铺时确认，但便利店和银行转账付款永远不会确认。

高级

Invoice Prefix: 发送给 KOMOJU 的订单号前缀。如果多个店铺共用 KOMOJU 账户，请为各店铺设置唯一前缀。默认：WC-。

Enable Logging: Log KOMOJU events and API calls，位于 WooCommerce > Status > Logs，来源为 wcp_komoju_payment，不含密钥或顾客数据。错误始终记录。默认：off。

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单数据（订单内的 KOMOJU 付款 ID）始终保留。默认：off。

结账

顾客选择付款方式（默认 KOMOJU Payment）并下单。插件按订单总额及币种创建 KOMOJU 付款会话，将顾客跳转到 KOMOJU 付款页面。账单电子邮箱、姓名、账单和配送地址以及所订商品会传给 KOMOJU。页面根据网站语言以日语、英语或韩语显示（其他语言使用英语）。顾客在那里选择付款方式。可用方式取决于您的 KOMOJU 账户和订单币种。

付款后顾客返回店铺。插件使用订单模式的密钥从 KOMOJU API 读取付款会话。仅在 KOMOJU 通过签名 Webhook 或顾客返回时的会话读取确认后，订单才标记为已付款。如果当时无法连接 KOMOJU，顾客会进入订单已收到页面，并看到 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.

便利店和银行转账付款会向顾客发放付款凭单。订单设为保留，顾客付款且 KOMOJU 发送 Webhook 后完成。凭单到期则取消订单。

付款未完成时，顾客返回 Pay for order 页面并看到 The payment was not completed. You can try again or choose another payment method. 若总额未变，新尝试会复用未关闭的 KOMOJU 会话。旧总额的会话会在 KOMOJU 取消，期间已付款的会话则会确认订单。当未付款订单被取消时（由您、顾客或 WooCommerce 库存保留计时器取消），其未关闭的 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. 详情添加到订单备注和日志。

此付款方式支持经典结账、结账区块及 Pay for order 页面，兼容 WooCommerce High-Performance Order Storage（HPOS）。

插件不提供站内银行卡表单、保存银行卡或订阅。不限制付款方式，由顾客在 KOMOJU 页面选择。不提供手动扣款操作：获授权进行手动扣款的付款须在 KOMOJU 控制面板扣款，订单此前保持保留状态。

订单和退款

订单状态

Pending payment: 顾客已跳转至 KOMOJU，尚未付款，或 KOMOJU 尚未确认付款。

Processing or Completed: KOMOJU 已确认付款。WooCommerce 设置已付款订单的常规状态。订单备注显示 KOMOJU 付款 ID、付款方式及确认途径（Webhook 或返回）。交易 ID 即 KOMOJU 付款 ID，在订单页面可链接到 KOMOJU 控制面板中的付款。

On hold: 已签发便利店或银行转账凭单等待付款，或付款等待在 KOMOJU 控制面板扣款。金额或币种与订单不符，或订单取消后才扣款时，也会将订单设为保留。订单备注会说明原因。请履行订单或退款。

Failed: 付款失败，顾客可重试。

Cancelled: 付款凭单到期或付款已取消。

Refunded: 已通过 WooCommerce 或 KOMOJU 控制面板全额退款。

已付款订单若发生第二笔扣款，不会再次修改订单。备注会要求您在重复付款时到 KOMOJU 控制面板退款。已退款订单绝不会重新开启。

退款

打开订单，点击 Refund，输入金额并点击 Refund via KOMOJU Payment。支持全额和部分退款。退款使用订单付款时模式的密钥，因此必须配置该模式的密钥。插件先检查 KOMOJU 中的付款，拒绝超过剩余可退金额的退款。如果 KOMOJU 无法自动退款（某些方式如便利店付款需要顾客银行信息），会显示 KOMOJU 错误且不记录任何退款：请到 KOMOJU 控制面板处理。只有 KOMOJU 确认后退款才算完成。成功退款会添加到订单备注。

对于 KOMOJU 转换为其他币种的付款（例如 EUR 订单的 JPY 便利店付款），WooCommerce 仅支持全额退款。部分退款请在 KOMOJU 控制面板操作。

在 KOMOJU 控制面板进行的退款通过 Webhook 传入，并自动记录为 WooCommerce 退款。全额退款将订单设为已退款。对于转换币种的付款，控制面板中的部分退款只会添加订单备注：请在 WooCommerce 使用 "Refund manually" 记录对应金额。

许可证密钥

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

每个密钥用于一个域名。从网站移除密钥不会释放域名名额。请在 vibefox.net 账户中释放。

没有有效密钥时，结账顾客看不到 KOMOJU。如果仍启动付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到带有 (unlicensed — visible to admins only) 标记的付款方式，以便您购买密钥前配置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已启动的付款仍会确认，退款仍可使用。

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

故障排除

结账时不显示 KOMOJU：检查许可证有效、Enable/Disable 已开启，且当前模式配置了密钥：沙盒模式为 Sandbox Secret Key，正式模式为 Live Secret Key。店铺币种须受 KOMOJU 支持。设置页面会提示缺失项。

付款成功但订单仍为Pending payment：Webhook 未正常工作。在 KOMOJU 控制面板检查当前模式的 Webhook 是否存在、URL 是否与设置完全相同、事件是否已选中。检查密钥令牌是否填入对应字段（Live Webhook Secret Token 或 Sandbox Webhook Secret Token），并查看 WooCommerce > Status > Logs，来源 wcp_komoju_payment。银行卡付款也会在顾客返回时确认，便利店和转账则只能通过 Webhook 确认。

Webhook 返回 Failed to verify KOMOJU webhook signature：密钥令牌缺失或属于其他 Webhook。KOMOJU 会重试通知。

Webhook 返回 Mode mismatch, ignored：签名使用的密钥令牌属于另一模式，与订单付款模式不同。正式与测试模式请使用独立 Webhook 和令牌。

Webhook 返回 Order is busy, retry later 或 Temporary error, retry later：其他请求正在更新订单，或当时无法检查付款。KOMOJU 会重试通知。

订单为 On hold：阅读订单备注。可能是凭单等待付款、付款等待在 KOMOJU 控制面板扣款、金额或币种不符，或订单取消后才收到付款。

退款失败：阅读提示。可能缺少付款模式的密钥，付款不能自动退款（请到 KOMOJU 控制面板退款），或转换币种的付款只能全额退款。

许可证区块显示错误：按提示处理。例如密钥已用于其他域名，请在 vibefox.net 账户释放名额并点击 Check now。网站地址更改后，点击 Check now 为新域名激活密钥。许可证服务器无法连接时，插件按最后已知状态继续运行。

开发者可通过 komoju_p_supported_currencies 筛选器修改币种列表，通过 komoju_p_session_params 筛选器修改付款会话，例如付款方式。

卸载

停用插件保留所有数据。要移除，请在 Plugins 页面停用并删除。此插件的许可证密钥和状态始终删除。仅在 Delete data on uninstall 开启时删除网关设置及日志，否则保留以供日后重装。现有订单保留付款备注及交易 ID。

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