VibeFox Omise for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。

HTTPS：银行卡字段位于您的结账页面上，因此结账页面应通过 HTTPS 提供。即便如此，银行卡数据仍绝不会到达您的服务器。Omise 只向 HTTPS 地址发送 Webhook，并且银行的 3-D Secure 页面也必须是 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. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Omise Payment 并点击 Configure。

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

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

5. 开启 Enable/Disable 并点击 Save。在测试模式下使用 Omise 测试卡（例如 4242 4242 4242 4242）测试付款，然后关闭 Test mode。

安装时，模块会创建三个订单状态：Omise payment authorized、Omise payment on hold 和 Awaiting Omise payment。该付款方式会在安装时已启用的国家/地区提供。如果之后启用更多国家/地区，请在 Payment > Preferences 中为其允许该模块，您还可以在那里按货币和客户组进行限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Omise Payment > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，测试模式开启时页面会显示 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 用于开启或关闭该付款方式。默认值：off。

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: 使用测试密钥，不会产生真实扣款。两个密钥会同时切换。订单的捕获、退款和状态检查始终使用订单付款时所处模式的密钥。默认值：on。

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

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

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

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

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

Clear saved secrets: 勾选一个私钥并点击 Save 即可将其删除。空字段会保留已保存的值。

付款与 Webhook

Webhook URL: 您店铺的 Webhook 地址。启用友好 URL 时，地址形如 https://your-shop/module/wcp_omise_payment/webhook。请完全按照设置页面所示复制，并在 Omise 控制面板的 Settings > Webhooks 中添加（仅限 HTTPS）。模块会处理以下事件（本节也列出了它们）：

Omise 不对 Webhook 签名，因此绝不信任 Webhook 的内容：该扣款必须是本店铺为该购物车创建的，并且其状态会使用付款模式的私钥从 Omise API 重新读取。如果没有 Webhook，顾客在 3-D Secure 期间关闭浏览器的订单不会自动创建，而且在 Omise 控制面板中进行的捕获在您点击 Sync payment status 之前不会被识别。

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

Per-charge webhook: 随每笔扣款发送 Webhook URL。当多家店铺共用一个 Omise 账户时很有用。仅当店铺使用 HTTPS 时有效；否则使用控制面板中设置的 Webhook。默认值：off。

高级

Debug log: 将 API 请求和付款事件写入模块文件夹中的 logs/omise_p_debug.log.php。该文件无法通过网页访问。密钥、令牌和银行卡数据绝不会被记录。默认值：off。关闭时不会写入任何内容，包括错误，因此在排查问题时请开启。

Log: 显示日志的大小和最新条目，并提供清除按钮。

Delete data on uninstall: 开启后，卸载模块时会删除设置和调试日志。订单的 Omise 扣款和退款属于付款记录，始终会保留。默认值：off。

结账

在付款步骤中，顾客选择付款方式（默认为 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 会在浏览器中使用购物车的账单地址，将银行卡转换为一次性令牌。银行卡字段绝不会提交到您的店铺。缺失或无效的字段会显示在表单下方，例如 Please enter a valid card number.

随后，您的店铺使用私钥，按购物车货币与购物车总额创建扣款。扣款说明为店铺名称和购物车编号，购物车 ID 保存在扣款的元数据中。此时尚未创建订单。如果银行要求 3-D Secure，顾客会被引导至银行页面，然后返回您的店铺，结果会从 Omise API 重新读取。

只有在 Omise 确认后，订单才会被标记为已付款：扣款必须已捕获，且金额和货币必须与购物车一致。顾客会看到标准的订单确认页面，并显示 Your card payment has been received. 使用 Authorize only 时，页面显示 Your card payment has been authorized. The amount will be charged when your order is processed. 如果 Omise 仍将付款报告为待处理，订单会以 Awaiting Omise payment 状态创建，页面显示 Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. 如果在 3-D Secure 之后无法立即确认付款，将显示 Payment confirmation 页面，内容为 We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.，并附带 Check again 按钮。

如果银行卡被拒，则不会创建订单。顾客将停留在结账页面，并显示 Payment failed: 及原因（例如余额不足、安全码无效或发卡行拒绝），并可使用同一购物车重试。如果 3-D Secure 失败，顾客同样会带着原因返回结账页面；如果扣款期间已过期或被撤销，提示信息为 The payment was not completed. Please try again.

重试绝不会重复扣款：如果该购物车之前的扣款已付款或已授权，则直接创建订单，无需新的扣款。未完成的 3-D Secure 尝试会在新的扣款发生之前过期。如果同一购物车（已有订单）的第二笔扣款仍为已付款状态（例如在另一个浏览器标签页中），订单不会被更改，并会有备注提醒您在 Omise 控制面板中退款或撤销。

即使店铺处于维护模式，Webhook 仍可正常工作，并且不受店铺国家/地区限制的影响。

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

订单与退款

订单状态

No order yet: 顾客正在进行 3-D Secure，或银行卡被拒。此时只存在购物车。

Payment accepted: 付款已确认。付款会以 Omise 扣款 ID（chrg_...）作为交易 ID 进行记录，备注中会显示金额、扣款以及确认方式（结账、3-D Secure 返回、Webhook、付款重试、手动捕获或手动同步）。备注是订单的私人消息，仅在后台可见。

Omise payment authorized: 银行卡已通过 Authorize only 完成授权。请使用 Capture payment 或 Void authorization。

Awaiting Omise payment: Omise 尚未确认付款。Webhook 或 Sync payment status 会更新订单。

Omise payment on hold: 扣款金额或货币与订单不一致，例如购物车在 3-D Secure 期间被修改。备注会显示两个数值。已捕获的付款仍会记录在订单上。请检查订单，然后处理订单或退还款项。

Payment error: 待处理的付款之后失败。已付款的订单绝不会因后续的失败事件而被降级。

Canceled: 扣款已过期，或授权已被撤销。

Refunded: 付款已通过模块全额退款。

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

Omise 付款区块

订单页面会显示一个 Omise payment 区块，其中包含扣款 ID、付款操作、扣款状态、卡品牌及末尾数字、已扣金额、订单金额及已退款金额、测试付款的 Test mode 标记，以及退款记录。区块中的按钮需要具备编辑订单的权限，并需要付款时所处模式的私钥。无需访问模块页面。每项操作的结果都会显示在区块顶部。

Capture payment: 捕获全部已授权金额，并将订单设置为 Payment accepted。仅对已授权的订单显示。

Void authorization: 撤销授权；不捕获任何款项，订单将设置为 Canceled。仅对已授权的订单显示。

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

退款

在 Omise payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Omise。确认提示 Refund this amount through Omise? This cannot be undone.。支持全额和部分退款。退款以 Omise 实际扣款的金额和货币进行，因此在金额或货币不一致后，您最多可以退还顾客实际支付的金额，而不是订单总额。退款会在付款时所处的模式中发送，因此必须已设置该模式的私钥。退款原因会随退款一起保存在 Omise 中。退款成功后，会在退款记录和备注中添加，并附上 Omise 退款 ID。全额退款会将订单设置为 Refunded；部分退款不会更改状态。对于尚未捕获的授权，只能进行全额退款，且会撤销该授权。如果 Omise 拒绝退款，区块会显示 Refund failed. 及 Omise 的消息，并且不会记录任何退款。

本模块不会创建贷项通知单。订单页面上标准的 PrestaShop 退款按钮不会通过 Omise 退还款项。在 Omise 控制面板中进行的退款不会记录在 PrestaShop 中；Sync payment status 会显示已退款的总额。

许可证密钥

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

如果密钥未被接受，区块会说明原因，例如 密钥未找到、该密钥属于其他产品、已达到域名数量上限，或 许可证已于某日期到期。店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。

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

如果没有有效的密钥，结账时不会向顾客显示 Omise 付款方式。如果仍然启动了付款，顾客会看到 此付款方式不可用。请选择其他方式。 PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已启动的付款仍会被确认，退款也仍可正常进行。

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

故障排除

Omise does not appear at checkout: 请检查许可证是否有效，Enable/Disable 是否已开启，当前模式的两个密钥是否都已填写（测试模式使用测试密钥，否则使用正式密钥），以及购物车货币是否为受支持的货币之一。缺少密钥时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车货币、顾客所在国家/地区以及顾客所属客户组。

The payment went through, but no order was created or the order stays Awaiting Omise payment: Webhook 无法正常工作。请在 Omise 控制面板中检查 Webhook URL 是否与 Webhook URL 中显示的完全一致，并且使用 HTTPS。对于已有订单，请点击 Sync payment status。开启 Debug log 以查看 Webhook 的响应。

Webhook answers Charge ID does not match order or Order not found: 事件中的扣款并非由本店铺为该购物车创建。不会更改任何内容。

Webhook answers Order is being processed, retry later or Failed to verify charge: 购物车在同一时刻被另一请求锁定，无法连接 Omise API，或缺少付款模式的私钥。Omise 会重试 Webhook。

Webhook answers The order could not be created, retry later: 无法创建订单，例如模块已被禁用。开启 Debug log 以查看原因。

The webhook URL shows Method not allowed in the browser: 这是正常现象。该 URL 仅接受来自 Omise 的请求。

Warning on save: key must start with ... or must be a live key: 密钥被粘贴到了错误的字段，因此未保存。测试密钥以 pkey_test_ / skey_test_ 开头，正式密钥以 pkey_ / skey_ 开头。

The customer sees Card payments are temporarily unavailable: 密钥有误，或银行卡令牌属于另一模式（正式模式下使用测试令牌，或反之）。请检查密钥和 Test mode。

The customer sees We could not reach the payment provider: 创建扣款时未收到 Omise 的有效响应。扣款可能已创建；请先检查 Omise 控制面板，再让顾客重新付款。

The customer sees This order is already being paid: 结账被同时提交了两次。顾客应稍候并查看邮件，然后再重试。

Order is Omise payment on hold after payment: 请阅读订单中的备注（参见订单状态），然后处理订单或退还款项。

Refund fails with a message about the mode: 付款是在测试或正式模式中完成的，而该模式的私钥尚未设置。请输入私钥后重试。

Partial refund of an authorized order fails: 付款仅为授权状态。请先进行捕获，或全额退款以撤销授权。

卸载

进入 Modules > Module Manager，打开 VibeFox Omise Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置和调试日志将被删除。如果已关闭，所有设置都会保留，以便之后重新安装。Omise 扣款和退款记录，以及订单状态 Omise payment authorized、Omise payment on hold 和 Awaiting Omise payment 始终会保留，因此即使重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。

Omise 是其各自所有者的商标。本模块与 Omise 无关联，亦未获得 Omise 的认可。