VibeFox Xendit for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

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

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

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

安装

1. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Xendit Payment Gateway，然后点击 Configure。

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

4. 粘贴您的 Xendit Secret 密钥，在 Xendit 控制面板中设置 Webhook URL，并粘贴验证令牌（参见配置）。

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

安装时，模块会创建订单状态 Xendit payment on hold。PrestaShop 会为所有币种、国家和客户组提供新的付款模块。您可以在 Payment > Preferences 中对其进行限制。

配置

所有设置都在模块页面上：Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。字段上方的方框会显示当前模式：TEST MODE（发票使用 Test Secret 密钥创建，不会收取真实款项）或 LIVE MODE（发票使用 Live Secret 密钥创建，将向顾客收费）。当当前模式的 Secret 密钥缺失或前缀错误时（此时结账页面会隐藏付款方式），以及当前模式的 Webhook 验证令牌为空时（Xendit 通知会被拒绝，因此只有在顾客返回店铺时才会创建订单），该方框会发出警告。

Xendit

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

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

Description：结账时显示在付款方式下方的文字。默认：Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

API 密钥

在 Xendit Dashboard > Settings > Developers > API keys 中创建一个具有 Money-in（发票）写入权限的 Secret API 密钥，测试模式和正式模式各创建一次。密钥决定发票在哪个模式下创建。保存时，前缀与其字段不符的密钥不会被保存，页面会显示例如 Test secret key was not saved: it must start with xnd_development_。其他设置仍会保存。

Test Mode：使用 Test Secret 密钥创建发票，因此不会收取真实款项。默认：开启。关闭后将使用 Live Secret 密钥接受真实付款。开启期间，顾客会在付款方式下方看到 Test mode: no real money is charged.

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

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

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

Webhook

Webhook 用于告知您的店铺某张发票已付款。在 Xendit Dashboard > Settings > Developers > Webhooks 中，为测试模式和正式模式分别将本部分 Webhook URL 中显示的 URL 设置到 Invoices > Invoice paid。您也可以选择为 Invoice expired 设置该 URL。若启用了友好 URL，其形式为：https://your-shop/module/wcp_xendit_payment_gateway/webhook，可能带有语言代码，例如 /en/。请严格按照设置中显示的内容复制。

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

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

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

Clear saved secrets：勾选某个密钥或令牌，然后点击 Save 将其删除。空字段会保留已保存的值。

付款

Invoice Description：显示在 Xendit 发票上的描述。您可以使用占位符 {order_id}、{order_number} 和 {site_name}。由于订单是在付款后创建的，{order_id} 和 {order_number} 都是购物车编号。HTML 会被移除，文本会被截断为 255 个字符。默认：Order #{order_id}。

Order Status After Payment：Xendit 确认付款后设置的订单状态。

高级

Debug Log：将 API 请求和 Webhook 写入模块文件夹中的 logs/xendit_p_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。API 密钥、令牌和顾客数据不会被记录。默认：关闭。

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

Delete Data on Uninstall：开启时，卸载模块会删除模块设置和日志。订单数据（订单的发票 ID）和 Xendit payment on hold 订单状态始终会保留。默认：关闭。

结账

当购物车币种为 IDR、PHP、VND、THB、MYR、USD 或 SGD 时，会显示该付款方式。顾客在付款步骤中选择它（默认为 Xendit）并确认。模块会以购物车币种为购物车总额创建一张 Xendit 发票，并将顾客转到 Xendit 发票页面。由于 Xendit 不接受这些币种的小数，IDR 和 VND 金额会被四舍五入为整数。顾客的电子邮件地址会传递给 Xendit。在发票页面上，顾客使用您 Xendit 账户中为该币种启用的付款渠道之一付款，例如虚拟账户、电子钱包、二维码、零售网点或银行卡。此时尚未创建订单。

付款后，顾客返回您的店铺。只有在 Xendit 确认之后，订单才会被标记为已付款：通过 Webhook，或者在顾客返回时由服务器向 Xendit API 发出请求。随后订单才会被创建，顾客会看到标准的订单确认页面。如果 Xendit 尚未确认付款，将显示 Payment confirmation 页面，其中包含 Your payment has not been confirmed by Xendit yet. Your order will be created 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. 购物车会被保留。

顾客可以再次支付同一购物车。如果购物车总额、币种和模式均未更改，且未结发票至少还有五分钟有效期，顾客会被引导至同一张发票。否则，旧发票会先被设为过期，并创建新发票，因此同一购物车永远不会同时存在两张未结发票。如果旧发票已付款，则会创建订单而不是再次收款。

如果 Xendit 无法发起付款，顾客会停留在结账页面，并看到简短提示，例如 Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method.，或者提示该币种不被您的账户接受，或者订单总额超出 Xendit 的金额限制。技术原因会写入日志。总额为零的购物车无法使用 Xendit 付款。

即使店铺处于维护模式，Webhook 仍然有效，并且不会受到店铺国家限制的阻挡。

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

订单

订单状态

暂无订单：顾客已被转到 Xendit 但尚未付款，或 Xendit 尚未确认付款。此时只存在购物车。

Payment accepted or Delivered：付款已确认。状态遵循 Order Status After Payment。付款会以 Xendit 发票 ID 作为交易 ID 记录，备注中会显示发票 ID、已付金额、付款渠道和模式。

Xendit payment on hold：已付款的发票与购物车总额或币种不符，或付款金额低于总额（例如，在发票创建后购物车被修改）。备注会说明原因。请在 Xendit 控制面板中核实该付款，然后处理订单或退款。如果同一购物车的另一张发票之后以正确金额付款，则付款会被记录，订单会转为已付款状态。

如果某张发票是为已取消或已退款的订单付款，订单状态不会改变。备注会提示您在 Xendit 控制面板中退款，或手动恢复订单。如果某张发票是为已付款的订单付款，订单不会改变，备注会提示您在 Xendit 控制面板中退还重复付款。

Xendit payment 区块

订单页面会显示 Xendit payment 区块，包括发票 ID、模式（测试付款会带有 Test mode 标记）、付款状态、订单所有发票的列表（日期、发票、外部 ID、金额和已付金额、状态、付款渠道）以及订单的 Payment notes。

退款

退款不会从店铺发送到 Xendit。请在 Xendit 控制面板中为该付款办理退款（搜索 Xendit payment 区块中显示的发票 ID），并在订单中手动记录退款。订单页面上 PrestaShop 的标准退款按钮不会通过 Xendit 退还款项。

许可证密钥

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

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用上一次已知的状态运行。

一个密钥只能用于一个域名：主店铺的域名，多店铺配置下同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

如果没有有效的密钥，结账时不会向顾客显示 Xendit。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认。

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

故障排除

结账时没有显示 Xendit：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否有前缀正确的 Secret 密钥（测试模式为 xnd_development_ 开头的 Test Secret Key，正式模式为 xnd_production_ 开头的 Live Secret Key），以及购物车币种是否为 IDR、PHP、VND、THB、MYR、USD 或 SGD。密钥缺失或错误时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于该购物车币种、顾客所在国家和顾客所属客户组。

付款已完成，但未创建订单：Webhook 没有正常工作。请在您所用模式（测试或正式）的 Xendit 控制面板中，检查 Webhook URL 中显示的 URL 是否已为 Invoice paid 设置，并且该模式的验证令牌是否已保存在对应字段中。Xendit 控制面板会显示您的店铺对每个 Webhook 的响应。顾客付款后返回店铺时，订单也会被创建。

Webhook 响应 Webhook verification token is not configured：未设置任何验证令牌。请将令牌粘贴到设置中。

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

Webhook 响应 Token does not match the mode of this invoice：该发票是在另一模式中创建的。测试通知绝不会确认正式付款，反之亦然。请在购物车付款所用的模式中设置 Webhook 和令牌。

Webhook 响应 Ignored: not an invoice of this store：该发票并非由本店铺创建，例如同一 Xendit 账户上的其他集成所创建。Xendit 控制面板中的 Test 按钮也会收到此响应，这表明 URL 和令牌均正常。Ignored: unknown order 和 Ignored: unknown invoice 表示本店铺无法识别该购物车或发票。

Webhook 响应 Temporary error：无法连接 Xendit API 来核实发票，发票所属模式的 Secret 密钥缺失，购物车在同一时刻正被其他请求更新，或订单无法创建（例如模块已停用）。Xendit 会重试 Webhook。如果在两种模式下都发起过付款，请检查两个 Secret 密钥是否都已设置，并开启 Debug Log 查看原因。

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

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

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

顾客看到 A payment for this order was already received by Xendit and is being reviewed：该购物车之前的某张发票已付款，但订单尚未能确认。请在 Xendit 控制面板和日志中核实该付款。

顾客看到 We could not match this payment to an order：Xendit 的返回链接不属于本店铺的任何购物车，或者无法匹配到购物车的任何发票。请在 Xendit 控制面板和日志中核实该付款。

付款后订单显示 Xendit payment on hold：请阅读 Xendit payment 区块中的备注。已付金额或币种与购物车不一致。请处理订单，或在 Xendit 控制面板中退款。

对于开发人员，模块提供了 actionWcpXenditInvoiceRequest、actionWcpXenditSupportedCurrencies 和 actionWcpXenditCurrencyDecimals 钩子，用于修改发票请求、币种列表以及每种币种的小数位数。

卸载

前往 Modules > Module Manager，打开 VibeFox Xendit Payment Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 Xendit 发票数据和 Xendit payment on hold 订单状态始终会保留。现有订单会保留其付款备注和交易 ID。

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