VibeFox Omise for WooCommerce — 帮助

系统要求

WordPress：6.2 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。没有 WooCommerce 时插件无法激活；如果之后关闭了 WooCommerce，网关将不会加载，并显示管理员通知。

PHP：8.0 或更高版本。

HTTPS：银行卡字段位于您的结账页面上，因此结账页面必须通过 HTTPS 提供，并且不得包含不受信任的脚本。银行卡数据仍然绝不会传到您的服务器。Omise 只会将 Webhook 发送到 HTTPS 地址。

店铺货币：THB、JPY、SGD、MYR、USD、EUR、GBP、AUD、CAD、CHF、CNY、DKK、HKD 之一。对于其他货币，结账时将隐藏该付款方式。

Omise 账户：测试模式和正式模式都需要您 Omise 账户的公钥和私钥，可在 Omise 控制面板的 Settings > Keys 中找到；另外还需要在 Settings > Webhooks 中设置一个 Webhook 端点（参见配置）。

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

安装

1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_omise_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

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

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

5. 输入您的 Omise 测试密钥和正式密钥，并在 Omise 控制面板中添加设置页面显示的 Webhook URL（参见配置）。

6. 启用 Enable/Disable。在测试模式下使用 Omise 测试卡（例如 4242 4242 4242 4242）测试一笔付款，然后取消勾选 Test mode。

配置

所有设置都在同一个页面：WooCommerce > Settings > Payments > Omise。测试模式开启时，页面字段上方会显示 Test mode is on — orders are charged with the test keys, no real money is moved.；如果当前模式的公钥或私钥缺失，或者 Omise 不支持店铺货币，页面也会发出警告。在这两种情况下，结账时都会隐藏该付款方式。在付款方式列表中，只要当前模式的两个密钥尚未全部填写，Omise 就会标记为需要设置。

常规

Enable/Disable: Enable card payments via Omise 用于开启或关闭该付款方式。默认：关闭。

Title: 顾客在结账时看到的付款方式名称。默认：Credit / Debit Card。

Description: 结账时银行卡表单上方显示的文字。默认：Pay securely with your credit or debit card via Omise。

API 密钥

您可以在 Omise 控制面板的 Settings > Keys 中找到密钥。测试密钥以 pkey_test_ 和 skey_test_ 开头，正式密钥以 pkey_ 和 skey_ 开头。保存时，如果密钥前缀错误（例如在正式密钥字段中填入了测试密钥），系统会报错拒绝保存，并保留原来的值。

Test mode: Use the test keys (no real charges)。同时切换两组密钥。订单的退款、捕获和状态检查始终使用订单付款时所处模式的密钥。默认：开启。

Test public key: 测试模式的公钥，pkey_test_...

Test secret key: 测试模式的私钥，skey_test_...

Live public key: 正式模式的公钥，pkey_...

Live secret key: 正式模式的私钥，skey_...

付款与 Webhook

此部分显示您店铺的 Webhook URL，格式类似：https://your-site/wp-json/omise-payment/v1/webhook。请完全按照设置中显示的内容复制，并在 Omise 控制面板的 Settings > Webhooks 中添加（仅限 HTTPS）。插件会处理以下事件：

Webhook 的内容绝不会被直接信任：扣款必须是订单中保存的那笔，并且其状态会使用订单所属模式的密钥从 Omise API 重新读取。如果没有 Webhook，那么在 3-D Secure 过程中顾客关闭浏览器的订单会一直保持保留状态，直到您运行 Omise: Sync payment status；而在 Omise 控制面板中进行的捕获也不会被自动获取。

Payment action：银行卡金额的处理方式。

Per-charge webhook：Send the webhook URL with every charge。当多个店铺共用同一个 Omise 账户时很有用。仅当站点使用 HTTPS 时有效；否则使用控制面板中设置的 Webhook。默认：关闭。

高级

Debug log：Log API requests and payment events 会将付款步骤记录到 WooCommerce > Status > Logs，来源为 wcp_omise_payment。密钥、令牌和银行卡数据绝不会被记录。默认：关闭。

Delete data on uninstall：Remove the settings and debug logs when the plugin is deleted。默认：关闭。

结账

顾客选择付款方式（默认为 Credit / Debit Card），并填写银行卡表单：Name on card、Card number、Expiry month (MM)、Expiry year (YYYY) 和 Security code (CVV)。在测试模式下，表单会显示 TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made.。下单时，Omise.js 会在浏览器中将银行卡转换为一次性令牌。银行卡字段绝不会提交到您的服务器。

您的店铺会使用私钥，按订单总额和订单货币创建扣款。扣款描述为店铺名称和订单号，订单 ID 会保存在扣款的元数据中。如果银行要求 3-D Secure，顾客将被跳转至银行页面，完成后再返回您的店铺。结果始终从 Omise API 重新读取。

只有在 Omise 确认后，订单才会被标记为已付款：扣款必须已被捕获，且金额和货币必须与订单完全一致。使用 Authorize only 时，授权成功后订单将进入保留状态。顾客会看到订单已接收页面。

如果银行卡被拒绝，顾客会留在结账页面，并看到 Payment failed: 以及原因，例如余额不足、安全码无效或发卡行拒绝，之后可以重试。3-D Secure 失败后，顾客会被带到 Pay for order 页面。如果在 3-D Secure 之后无法立即确认付款，顾客会看到 We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

重试绝不会重复扣款：如果订单之前的扣款已付款或已授权，则直接完成订单，不会再次扣款。未完成的 3-D Secure 尝试会在创建新扣款之前过期。

该付款方式适用于经典结账、结账区块和 Pay for order 页面，并兼容 WooCommerce 高性能订单存储（HPOS）。

插件仅接受银行卡付款。它不支持其他 Omise 付款方式（PromptPay、TrueMoney、手机银行、分期付款、Konbini、PayNow）、保存的银行卡或 Omise 客户、订阅以及部分捕获。

订单与退款

订单状态

待付款：顾客正在进行 3-D Secure 验证，或尚未完成付款。

处理中：付款已确认。仅包含虚拟可下载商品的订单会像 WooCommerce 通常那样变为已完成。订单备注会显示金额、扣款 ID，以及确认方式（结账、3-D Secure 返回、Webhook、手动捕获或手动同步）。交易 ID 为 Omise 扣款 ID（chrg_...）。

保留，等待捕获：银行卡已通过 Authorize only 授权。请使用 Omise: Capture payment 或 Omise: Void authorization。

保留，待确认：Omise 尚未确认付款，例如顾客在 3-D Secure 过程中关闭了浏览器。Webhook 或 Omise: Sync payment status 会更新订单。

保留，金额不符：扣款的金额或货币与订单不一致。备注会显示两个数值。请检查订单，然后完成订单或退款。

失败：付款被拒绝。已付款的订单绝不会因之后的失败事件而降级。

已取消：扣款已过期或授权已被撤销。

如果针对已取消或已退款的订单收到了已付款或已授权的扣款，订单不会被重新打开。备注会提醒您检查 Omise 控制面板，并手动退款或重新打开订单。

订单操作

Omise: Capture payment：捕获全部已授权金额。仅对已授权订单显示。

Omise: Void authorization：撤销授权；不会捕获任何款项，订单将被取消。仅对已授权订单显示。

Omise: Sync payment status：从 Omise 读取扣款并更新订单。备注还会显示在 Omise 中已退款的总额。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Omise。支持全额退款和部分退款。退款会以付款时所处的模式发送，因此必须已填写该模式的私钥。成功的退款会连同 Omise 退款 ID 一起添加到订单备注中。对于尚未捕获的授权，只能进行全额退款，并且会撤销该授权。如果 Omise 拒绝退款，WooCommerce 会显示 Refund failed. 以及 Omise 的消息，且不会记录任何退款。

在 Omise 控制面板中进行的退款不会作为 WooCommerce 退款导入。Omise: Sync payment status 会显示已退款总额；如有需要，请在 WooCommerce 中手动创建对应的退款。

许可证密钥

本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Omise 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期的截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

如果没有有效的密钥，结账时顾客将看不到 Omise。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标记为 (unlicensed — visible to admins only)，以便您在购买密钥前完成设置和测试。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已开始的付款仍会被确认，捕获和退款也照常工作。

许可证到期后，插件仍可继续工作，但更新和支持需要续费。系统会在后台自动重新检查状态。

故障排除

结账时不显示 Omise：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式的两个密钥是否都已填写（测试模式使用测试密钥，否则使用正式密钥），以及货币是否受支持。在 Pay for order 页面，以订单货币为准。如果密钥或货币有误，设置页面会显示警告。

付款已完成，但订单仍为待付款或保留状态：Webhook 未正常工作。请在 Omise 控制面板中检查 Webhook URL 是否与设置中显示的完全一致且使用 HTTPS。然后在该订单上运行 Omise: Sync payment status。开启 Debug log 可查看 Webhook 的响应。

Webhook 返回 Earlier charge of the order, order not changed：该事件对应订单的一次早期尝试，该尝试已被重试所取代。订单不会有任何变化。如果该早期扣款在 Omise 中仍处于已付款或已授权状态，订单备注会提示一次：请检查 Omise 控制面板是否存在重复付款，并在那里退款或撤销。

Webhook 返回 Charge ID does not match order：事件中的扣款属于另一笔订单。不会有任何变化。

Webhook 返回 Order is being processed, retry later 或 Failed to verify charge：订单被另一个请求锁定，或无法访问 Omise API。Omise 会重试 Webhook。

保存时出错：key must start with ... 或 must be a live key：密钥被粘贴到了错误的字段。测试密钥以 pkey_test_ / skey_test_ 开头，正式密钥以 pkey_ / skey_ 开头。

顾客看到 Card payments are temporarily unavailable：密钥有误，或银行卡令牌属于另一种模式（正式模式中使用了测试令牌，或反之）。请检查密钥和 Test mode。

顾客看到 We could not reach the payment provider：创建扣款时，Omise 没有返回有效的响应。扣款可能已经创建；订单备注会提醒您在再次为订单收费前先检查 Omise 控制面板。

顾客看到 This order is already being paid：结账提交了两次，且几乎同时发生。顾客应等待并查看邮箱后再重试。

付款后订单处于保留状态：请阅读订单备注。订单正在等待捕获，Omise 尚未确认付款，或金额或货币与订单不一致。

退款因模式相关的消息失败：付款是在测试或正式模式下完成的，而该模式的私钥未设置。请填写后重试。

已授权订单的部分退款失败：付款仅处于授权状态。请先捕获，或退还全额以撤销授权。

许可证区块显示错误：请按照区块中的提示操作。例如，如果密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额并点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用上次已知的状态。

卸载

停用插件会保留所有数据。要删除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被删除。只有在开启了 Delete data on uninstall 时，网关设置和日志才会被删除；否则会保留，以便日后重新安装。保存在订单中的 Omise 数据属于付款历史，始终会保留。现有订单会保留其付款备注和交易 ID。

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