VibeFox Xendit for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

店铺币种：IDR、PHP、VND、THB、MYR、USD 或 SGD。对于其他结账币种，不会显示付款方式。实际可用的付款渠道和币种取决于您的 Xendit 账户。

Xendit 账户：您需要一个测试模式的密钥 API，并具有 Money-in（账单）写入权限，另需一个正式模式的密钥 API，以及每个模式的 webhook 验证令牌（参见配置）。仅使用密钥和验证令牌。无需公钥，因为顾客在 Xendit 托管的账单页面付款。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_xendit_payment_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_xendit_payment_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 粘贴您的 Xendit 密钥，在 Xendit Dashboard 中设置 webhook URL，并粘贴验证令牌（参见配置）。

5. 打开 Enable/Disable，点击 Save。在测试模式下下一笔测试订单，然后关闭 Test Mode 以接收真实付款。

OpenCart 4

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

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

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

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

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

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Xendit Payment Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。如果没有修改扩展的权限，页面会显示设置但无法保存。

设置上方的方框会显示当前模式：TEST MODE（账单使用测试密钥创建，不会收取真实费用）或 LIVE MODE（账单使用正式密钥创建，顾客将被扣款）。如果当前模式的密钥缺失或前缀错误，页面会发出警告（此时结账页面会隐藏付款方式）；如果当前模式的 webhook 验证令牌为空，页面也会警告（Xendit 通知会被拒绝，因此订单只会在顾客返回店铺时更新）。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须是整数（允许负数），Total 必须是大于或等于 0 的数字，并且地理区域和订单状态必须存在。否则不会保存任何内容，页面会指出相应字段。

Xendit

Enable/Disable：Enable Xendit 用于开启或关闭付款方式。默认：off。

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

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

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

Geo Zone：仅为所选地理区域内的付款地址提供 Xendit。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：在提供 Xendit 之前，订单需要达到的结账总额（按店铺默认币种计算）。留空则对任何金额都提供 Xendit。

API 密钥

在 Xendit Dashboard > Settings > Developers > API keys（该部分有链接）中创建一个具有 Money-in（账单）写入权限的密钥 API，测试模式一个，正式模式一个。密钥决定账单在哪里创建。保存时，如果密钥不以其字段的前缀开头，则不会保存，页面会显示例如 Test secret key was not saved: it must start with xnd_development_。其他设置仍会保存。

Test Mode：使用测试密钥创建账单，因此不会收取真实费用。默认：on。关闭后将使用正式密钥接收真实付款。开启期间，顾客在 Confirm Order 步骤会看到 Test mode: no real money is charged.

Test Secret Key：Xendit 测试模式的密钥。以 xnd_development_ 开头。

Live Secret Key：Xendit 正式模式的密钥。以 xnd_production_ 开头。

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

Webhook

Webhook 用于告知您的店铺某张账单已付款。在 Xendit Dashboard > Settings > Developers > Webhooks（该部分有链接）中，为测试模式和正式模式的 Invoices > Invoice paid 设置 Webhook URL 中显示的 URL。也可以选择为 Invoice expired 设置。该 URL 在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_xendit_payment_gateway/webhook，在 OpenCart 4 中则形如 https://your-store/index.php?route=extension/wcp_xendit_payment_gateway/payment/wcp_xendit_payment_gateway.webhook，由您 OpenCart 安装的店铺前台地址构成。请完全按照设置中显示的内容复制。该 URL 必须可以从互联网访问。

然后将每个模式的 Webhook verification token从 Xendit Dashboard 复制到对应的字段中。Xendit 会在 x-callback-token 请求头中发送该令牌。没有账单所在模式令牌的通知会被拒绝。该令牌只能证明通知来自 Xendit：账单的状态、金额和币种始终会使用该模式的密钥从 Xendit API 重新读取。没有 webhook 时，只有顾客付款后返回店铺，订单才会被确认。

Test Webhook Verification Token：Xendit 测试模式的 webhook 验证令牌。

Live Webhook Verification Token：Xendit 正式模式的 webhook 验证令牌。

付款

Invoice Description：显示在 Xendit 账单上的描述。您可以使用占位符 {order_id} 和 {order_number}（两者都是 OpenCart 订单号）以及 {site_name}（店铺名称）。HTML 会被移除，文本会被截断为 255 个字符。默认：Order #{order_id}。

Order Status After Payment：已确认付款一次性设置的订单状态。

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Xendit 通过 API 确认付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Paid Order Status：使用 Processing 确认付款后的状态。默认：Processing。

Complete Order Status：使用 Completed 确认付款后的状态。默认：Complete。

On Hold (Review) Status：账单支付的金额或币种与订单不同（创建账单后购物车被修改，或为部分付款）。备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态并在此处选择。

高级

Debug Log：将 API 请求和 webhook 写入 OpenCart 日志文件夹（storage/logs）中的 xendit_p_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移动到 xendit_p_debug.old.log.php。即使此项关闭，错误和警告仍会始终被记录。密钥、令牌和顾客数据不会被记录。默认：off。

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

Delete Data on Uninstall：开启后，卸载扩展会删除网关设置和日志。订单数据（订单的 Xendit 账单 ID）始终保留。默认：off。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。密钥和令牌不会被导出。

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

结账

当结账币种为 IDR、PHP、VND、THB、MYR、USD 或 SGD 时，会显示付款方式。顾客在 Payment Method 步骤中选择它（默认为 Xendit）。在 Confirm Order 步骤，顾客会看到您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。当顾客点击 Confirm Order 时，扩展会以订单币种为订单总额创建一张 Xendit 账单，并将顾客转到 Xendit 账单页面。IDR 和 VND 的金额会四舍五入为整数，因为 Xendit 不接受这些币种的小数。顾客的电子邮件地址会传递给 Xendit。在账单页面，顾客使用您 Xendit 账户中为该币种启用的付款渠道之一付款，例如虚拟账户、电子钱包、二维码、零售网点或银行卡。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并在结账页面底部点击 Confirm Order。

付款后，顾客返回您的店铺。只有在 Xendit 确认后，订单才会被标记为已付款：通过 webhook，或在顾客返回时由服务器向 Xendit API 发起请求。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。如果 Xendit 尚未确认付款，Payment confirmation 页面会显示 Your payment has not been confirmed by Xendit yet. Your order will be confirmed as soon as Xendit confirms it — please do not pay again.，并带有 Check again 和 Back to checkout 按钮。webhook 一到达就会设置订单状态。

如果账单失败或过期，Xendit 会将顾客送回。扩展会先检查账单（它可能已在另一个标签页中支付），然后将其过期，使其无法再被支付。顾客会回到结账页面，并看到 The Xendit payment was not completed. You can try again or choose another payment method. 购物车会被保留。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账中的唯一订单，因此付款失败或过期后，下一次 Confirm Order 会为同一订单创建新的账单。如果同一购物车的另一个订单已付款，顾客会直接进入成功页面，不会被重复收费。如果订单总额、币种和模式未改变，并且该订单的未结账单在至少再五分钟内仍然有效，顾客会被发送到同一张账单。否则会先使旧账单过期，再创建一张新账单，因此同一购物车永远不会有两张未结账单。如果旧账单已经付款，则确认那笔付款，而不是创建新的付款。

在 OpenCart 4 中，如果结账中的订单期间已被店铺关闭（例如取消或退款），或者已付款但购物车此后有变化（包括新数量），顾客会被送回结账页面，并看到 Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order.，下一次 Confirm Order 会支付新订单。在 OpenCart 4 中，此消息、未完成付款的消息以及 We could not match this payment to an order. If you were charged, please contact us. 会显示在结账页面上方。

如果 Xendit 无法启动付款，顾客会停留在 Confirm Order 步骤，按钮上方会显示简短消息，例如 Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method.，或者提示该币种不被您的账户接受，或订单总额超出 Xendit 的金额限制。技术原因会写入日志。金额为零的订单无法使用 Xendit 付款。

即使店铺处于维护模式，webhook 和顾客的返回也仍然有效：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展为其添加了启动动作。

付款始终在 Xendit 页面上完成。扩展不支持从后台退款、保存银行卡、订阅或定期付款，结账页面上也没有银行卡或电子钱包字段，不支持分别授权和扣款，也不支持 xenPlatform 子账户。

订单

订单状态

无状态（缺失订单）：顾客已被转到 Xendit 但尚未付款，或者 Xendit 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Paid Order Status 或 Complete Order Status（默认 Processing 或 Complete）：付款已确认。状态遵循 Order Status After Payment。备注会显示账单 ID、付款金额、付款渠道和模式。

On Hold (Review) Status（默认 Pending）：已付款的账单与订单总额或币种不符，或付款金额少于总额（例如，创建账单后购物车被修改）。备注会说明原因。请在 Xendit Dashboard 中核实付款，然后发货或退款。如果同一订单之后另一张账单以正确金额付款，订单会转为已付款状态。

如果为一个状态不同的订单（例如已取消或已退款）付款了一张账单，订单状态不会改变。备注会提示您在 Xendit Dashboard 中退款，或手动恢复订单。如果为已付款的订单，或为已付款购物车中的另一个订单付了第二张账单，订单不会改变，且已付款订单上的备注会提示您在 Xendit Dashboard 中退还重复付款。

备注是订单 History 中的条目，顾客看不到。它们以 Xendit 一词开头。

VibeFox Xendit Payment Gateway 选项卡

在 Sales > Orders 中打开一个通过 Xendit 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Xendit Payment Gateway 选项卡会显示 Xendit invoice、Mode（测试付款会带有 Test 标签）、付款 Status、Invoices of this order and its cart 表格（日期、订单、账单 ID、外部 ID、模式、金额、已付金额、状态、付款渠道）以及订单的 Payment notes。该选项卡仅对有权访问该扩展的用户显示。

退款

退款不会从店铺发送到 Xendit。请在 Xendit Dashboard 中退还付款（搜索选项卡中显示的账单 ID），之后再在 OpenCart 中更改订单状态。在 Sales > Returns 中的商品退货不会通过 Xendit 退还款项。

许可证密钥

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

没有有效密钥时，结账时不会向顾客显示 Xendit。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 以同一浏览器登录后台的管理员用户，仍会在店铺中看到该付款方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试扩展。在 OpenCart 4 中此预览不可用：店铺看不到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可关闭，并在 7 天内隐藏。现有订单不受影响：已经开始的付款仍会被确认。

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。每次打开管理后台的 Dashboard 或 Edit 页面时都会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。

故障排除

结账时没有显示 Xendit：请检查许可证是否有效，Enable/Disable 是否开启，当前模式是否有正确前缀的密钥（测试模式下的 Test Secret Key 以 xnd_development_ 开头，正式模式下的 Live Secret Key 以 xnd_production_ 开头），以及结账币种是否为 IDR、PHP、VND、THB、MYR、USD 或 SGD。缺少密钥或密钥错误时，设置页面会显示警告。另外请检查付款地址是否在所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：webhook 没有正常工作。在您所用模式（测试或正式）的 Xendit Dashboard 中，检查 Webhook URL 中显示的 URL 是否已设置为 Invoice paid，以及该模式的验证令牌是否已保存在对应字段中。Xendit Dashboard 会显示每个 webhook 的店铺响应。顾客付款后返回店铺时，订单也会获得状态。

Webhook answers Webhook verification token is not configured：两个验证令牌都未设置。请将令牌粘贴到设置中。

Webhook answers Unauthorized：Xendit 发送的令牌与设置中的任何令牌都不匹配。请重新复制正确模式的令牌。

Webhook answers Token does not match the mode of this invoice：账单是在另一种模式下创建的。测试通知绝不会确认正式付款，反之亦然。请在订单付款所用的模式中设置 webhook 和令牌。

Webhook answers Ignored: not an invoice of this store：账单不是由本店铺创建的，例如同一 Xendit 账户上的其他集成创建的。Xendit Dashboard 中的 Test 按钮也会得到此响应，这说明 URL 和令牌是有效的。Ignored: unknown order 和 Ignored: unknown invoice 表示本店铺不认识该订单或账单。

Webhook answers Temporary error：无法连接 Xendit API 以检查账单，账单模式的密钥缺失，或购物车在同一时刻正被另一个请求更新。Xendit 会重试 webhook。如果在两种模式下都开始了付款，请检查两个密钥是否都已设置，并开启 Debug Log 查看原因。

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

密钥未保存：该值与其字段的前缀不符。测试密钥以 xnd_development_ 开头，正式密钥以 xnd_production_ 开头。

顾客看到 This payment method is temporarily unavailable：Xendit 拒绝了请求，例如密钥错误，或密钥缺少 Money-in（账单）的写入权限。请查看扩展页面上的 Log 字段。如果提示与账单信息有关，说明 Xendit 未接受请求数据，例如电子邮件地址。

顾客看到 A payment for this order was already received by Xendit and is being reviewed：该购物车之前的一张账单已付款，但订单尚无法确认。请在 Xendit Dashboard 和日志中检查该笔付款。

顾客看到 We could not match this payment to an order：Xendit 的返回链接不属于本店铺的订单，或无法将账单与订单匹配。请在 Xendit Dashboard 和日志中检查该笔付款。

订单在付款后处于审核状态：请阅读 VibeFox Xendit Payment Gateway 选项卡中的备注。付款金额或币种与订单不符。请处理订单，或在 Xendit Dashboard 中退款。

对于开发者：扩展会触发 OpenCart 事件 xendit_p_invoice_request、xendit_p_supported_currencies 和 xendit_p_currency_decimals，用于修改账单请求、币种列表以及每种币种的小数位数。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Xendit Payment Gateway 旁边的 Uninstall（红色 − 按钮）。扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Payment 部分中的订单状态；重新安装后这些设置会恢复为默认值。在 OpenCart 4 中，扩展的事件以及在维护模式下放行 webhook 和顾客返回的启动动作也会被删除。如果 Delete Data on Uninstall 已开启，则其他网关设置（标题、描述、测试模式、密钥、令牌、账单描述、付款后的订单状态、日志记录）和日志都会被删除。如果未开启，这些设置会被保留，以便之后重新安装时使用。订单的 Xendit 账单数据始终保留。现有订单会保留其付款备注。

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

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