VibeFox Omise for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

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 端点（参见 Configuration）。

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

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_omise_payment-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_omise_payment.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本使用同一个许可证密钥。

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Omise Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当测试模式开启时，页面会显示 Test mode is on — orders are charged with the test keys, no real money is moved.；如果当前模式的公钥或私钥缺失（此时结账时会隐藏付款方式），页面会发出警告；如果 Omise 不接受商店的默认货币，页面也会向您发出警告。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，以下情况会阻止保存：Title 为空或超过 128 个字符、Sort Order 不是整数、Total 不是 0 或更大的数字，或订单状态未知。此时不会保存任何内容，并会显示错误。前缀错误的密钥（例如在正式模式字段中填写了测试密钥）不会被保存：保留之前的值，警告中会指明该字段，其他字段则正常保存。

Omise

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

Title：顾客在结账时看到的付款方式名称。订单中保存的付款方式名称也是它。默认：Credit / Debit Card。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中，显示在银行卡表单上方的文字。默认：Pay securely with your credit or debit card via Omise.

Sort Order：结账时 Omise 在付款方式中的位置。可留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址显示银行卡表单。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。在 OpenCart 4 中，如果商店不要求付款地址，则使用送货地址。

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

API 密钥

您可以在 Omise 控制面板的 Settings > Keys 中找到密钥（页面中有相应链接）。测试密钥以 pkey_test_ 和 skey_test_ 开头，正式密钥以 pkey_ 和 skey_ 开头。

Test mode：使用测试密钥，不产生真实扣款。它会同时切换两个密钥。订单的捕获、退款和状态检查始终使用订单付款时所在模式的密钥。默认：on。

Test public key：测试模式的公钥，pkey_test_...，由浏览器中的 Omise.js 使用。

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

Live public key：正式模式的公钥，pkey_...，由浏览器中的 Omise.js 使用。

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

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

付款与 Webhook

Webhook URL：您商店的 Webhook 地址。在 OpenCart 3 中，它的格式类似 https://your-store/index.php?route=extension/payment/wcp_omise_payment/webhook；在 OpenCart 4 中则类似 https://your-store/index.php?route=extension/wcp_omise_payment/payment/wcp_omise_payment.webhook。它由您 OpenCart 安装的前台地址生成。请完全按照设置中显示的内容复制，并在 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。

订单

订单在 Confirm Order 步骤中创建，最初没有状态（即缺失订单），只有在 Omise 对银行卡作出响应之后才会获得状态。OpenCart 没有 On hold 状态：默认情况下，已授权、待审核和等待中的状态均为 Pending，订单选项卡和备注会对它们加以区分。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Order Status After Payment：银行卡已扣款（Capture immediately，或之后的捕获）。默认：Processing。

Authorized Status：Authorize only：金额已预留，但尚未捕获。默认：Pending。

On Hold (Review) Status：扣款金额或货币与订单不一致。默认：Pending。

Awaiting Payment Status：顾客已完成操作，但 Omise 尚未确认扣款。默认：Pending。

Failed Status：带有某种状态的订单的待处理扣款随后失败。默认：Failed。

Canceled Status：扣款已过期或授权已被撤销，没有收取任何款项。默认：Canceled。

Refunded Status：在订单选项卡中全额退款后设置。默认：Refunded。

高级

Debug log：将 API 请求和付款事件写入 OpenCart 日志文件夹（storage/logs）中的 omise_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会移动到 omise_p_debug.old.log.php。密钥、令牌和银行卡数据从不记录。默认：off。此开关关闭时不会写入任何内容，包括错误，因此在排查问题时请将其开启。

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

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

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。私钥不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit / Debit Card）。在 Confirm Order 步骤中，顾客会看到您的说明以及银行卡表单：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. OpenCart 在此步骤创建订单，仍然没有状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式；银行卡表单位于结账页面底部的确认区域，Confirm Order 上方。顾客点击 Confirm Order 后，Omise.js 会在浏览器中，使用订单的付款地址（在 OpenCart 4 中，如果商店不要求付款地址，则使用送货地址），将银行卡转换为一次性令牌。银行卡字段绝不会提交到您的商店。缺失或无效的字段会显示在表单上方，例如 Please enter a valid card number.

随后，您的商店会使用私钥，以订单货币和订单总额创建扣款。扣款说明为商店名称和订单号，订单 ID 会保存在扣款的元数据中。如果银行要求 3-D Secure 验证，顾客会被带到银行页面，然后返回您的商店，结果会通过 Omise API 重新读取。

只有在 Omise 确认之后，订单才会被标记为已付款：扣款必须已被捕获，且其金额和货币必须与订单一致。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规的订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，并显示 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 Payment Status，页面会显示 Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. 之后，当 Omise 确认或拒绝付款时（通过 Webhook 或顾客返回），新的订单状态会附带通知发送给顾客，因此 OpenCart 会向顾客发送邮件。如果在 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 按钮。

如果银行卡被拒绝，订单保持无状态。顾客停留在 Confirm Order 步骤，并显示 Payment failed: 以及原因，例如余额不足、安全码无效或发卡行拒绝，顾客可以使用同一购物车重试。如果 3-D Secure 验证失败，顾客同样会带着原因返回结账页面；如果扣款期间已过期或被撤销，提示信息为 The payment was not completed. Please try again. 在 OpenCart 4 中，3-D Secure 之后的这些提示会显示在结账页面上方。

重试绝不会重复扣款。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则为结账保留一个订单并更新它，因此在银行卡被拒或 3-D Secure 失败后，顾客会用新的扣款支付同一个订单。如果该购物车之前的扣款已付款或已授权，该订单会获得相应状态，并且不会进行新的扣款。未完成的 3-D Secure 尝试会在新扣款之前过期。如果对于已付款的购物车，第二笔扣款仍处于已付款状态（例如在另一个浏览器标签页中），则不会更改任何订单，已付款订单上的备注会提示您在 Omise 控制面板中退款或撤销。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面。如果该订单在此期间已被关闭（例如其扣款失败或已过期，或者您取消或退款了该订单），顾客会被带回结账页面，并显示 Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order.，下一次 Confirm Order 将为新订单付款。如果该订单已付款，而购物车中现在有其他商品或数量不同，顾客同样会被带回结账页面，新的购物车会获得一个新订单。

即使商店处于维护模式，Webhook 也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，该扩展会添加一个启动操作，允许 Webhook 和顾客从 3-D Secure 返回的请求通过。

该扩展仅支持银行卡。它不支持其他 Omise 付款方式（PromptPay、TrueMoney、移动银行、分期付款），不支持保存的银行卡或 Omise 客户，不支持订阅，也不支持部分捕获。

订单与退款

订单状态

无状态（缺失订单）：顾客正在进行 3-D Secure 验证，或银行卡被拒绝。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

在 OpenCart 4 中，结账中未付款的订单可能会获得 Voided 状态，该状态是在顾客返回 Confirm Order 步骤时由 OpenCart 4 设置的。扩展会将此类订单视为无状态订单，之后的付款仍会确认它。

Order Status After Payment（默认 Processing）：付款已确认。备注中会显示金额、Omise 扣款（chrg_...），以及确认方式（结账、3-D Secure 返回、Webhook、付款重试、手动捕获或手动同步）。

Authorized Status（默认 Pending）：银行卡已通过 Authorize only 授权。请使用 Capture payment 或 Void authorization。

Awaiting Payment Status（默认 Pending）：Omise 尚未确认付款。Webhook 或 Sync payment status 会更新订单。

On Hold (Review) Status（默认 Pending）：扣款金额或货币与订单不一致，例如订单在 3-D Secure 过程中被修改。备注会显示两个值。请检查订单并履行，或退还款项。

Failed Status（默认 Failed）：待处理的付款随后失败。已付款订单绝不会因后续的失败事件而被降级。

Canceled Status（默认 Canceled）：扣款已过期，或授权已被撤销。

Refunded Status（默认 Refunded）：付款已通过该扩展全额退款。

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

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

VibeFox Omise Payment 选项卡

在 Sales > Orders 中打开一个通过 Omise 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox Omise Payment 选项卡会显示扣款 ID（测试付款会带有 Test 标签）、付款操作、扣款状态、银行卡品牌和末四位数字、Charged / order / refunded 金额、按钮、退款表单、退款历史，以及该订单的 Omise notes。该选项卡向有权访问此扩展的用户显示。按钮需要修改扩展的权限（在 System > Users > User Groups 中设置），以及付款时所用模式的私钥。每项操作的结果都会显示在选项卡中。

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

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

Sync payment status：例如在 Omise 控制面板中完成捕获或退款之后，从 Omise 重新读取扣款，更新订单，并添加一条备注，其中包含扣款状态以及 Omise 上的累计退款金额。

从选项卡进行的状态更改不会通知顾客，也不会变动库存，与手动更改状态一样。

退款

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

Sales > Returns 中的商品退货不会通过 Omise 退还款项。在 Omise 控制面板中进行的退款不会记录在 OpenCart 中；Sync payment status 会显示累计退款金额。

许可证密钥

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

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

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

故障排除

结账时没有出现 Omise：请检查许可证是否有效，Enable/Disable 是否开启，当前模式的两个密钥是否已输入（测试模式输入测试密钥，否则输入正式密钥），以及顾客是否使用支持的货币之一付款。当密钥缺失时，设置页面会显示警告。另外，请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态或处于 Awaiting Payment Status：Webhook 没有正常工作。请在 Omise 控制面板中检查 Webhook URL 是否与 Webhook URL 中显示的完全一致，并且使用 HTTPS。对于已有的订单，请点击 Sync payment status。开启 Debug log 可查看 Webhook 的响应。

Webhook 响应 Charge ID does not match order 或 Order not found：事件中的扣款并非由本商店为该订单创建。不会对任何内容进行更改。

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

Webhook 响应 The order status could not be set, retry later：当时无法设置订单状态。Omise 会重试该 Webhook。请开启 Debug log 查看原因。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Omise 的请求。

保存时的警告：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：结账被同时提交了两次。顾客应稍等片刻并查看邮件，然后再重试。

订单在付款后处于审核状态：请阅读 VibeFox Omise Payment 选项卡中的备注（参见 Order statuses），然后履行订单或退还款项。

退款失败，并提示与模式相关的信息：付款是在测试模式或正式模式下完成的，而该模式的私钥未设置。请输入私钥后重试。

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

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Omise Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件和启动操作，即在维护模式下允许 Webhook 和 3-D Secure 返回通过的操作）。如果开启了 Delete data on uninstall，其余设置（标题、说明、测试模式、密钥、付款操作、Webhook 和日志选项）以及调试日志都会被删除。如果关闭，则会保留，以便日后重新安装时使用。Omise 的扣款和退款记录始终会保留，因此重新安装后，之前已付款的订单仍然可以退款。现有订单会保留其付款备注。

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

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