VibeFox Xendit for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。未安装时插件无法激活。

PHP：8.0 或更高版本。

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

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

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

安装

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

2. 点击 Activate。

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

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

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

6. 开启 Enable/Disable。在测试模式下下一笔测试订单，然后取消勾选 Test Mode 以接受真实付款。

配置

所有设置都在一个页面中：WooCommerce > Settings > Payments > Xendit。字段上方的横幅会显示当前模式：TEST MODE（使用测试 Secret 密钥创建发票，不会收取真实款项）或 LIVE MODE（使用正式 Secret 密钥创建发票，并向顾客收费）。当当前模式的 Secret 密钥缺失或前缀错误时（此时结账页面会隐藏付款方式），以及当当前模式的 Webhook 验证令牌为空时（Xendit 通知会被拒绝，因此订单只有在顾客返回店铺后才会更新），横幅会发出警告。在付款方式列表中，Xendit 会显示为需要设置，直到当前模式具有有效的 Secret 密钥。

常规

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：Enable test mode 使用测试 Secret 密钥创建发票，因此不会收取真实款项。默认：开启。取消勾选即可使用正式 Secret 密钥接受真实付款。

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

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

Webhook

Webhook 用于通知您的店铺某张发票已付款。请在 Xendit Dashboard > Settings > Developers > Webhooks 中，为测试模式和正式模式分别将本设置区域显示的 URL 设置到 Invoices > Invoice paid。可选地，也可以为 Invoice expired 设置该 URL。URL 格式如下：https://your-site/wc-api/xendit_p_callback/。请完全按照设置页面显示的内容复制。

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

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

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

付款

Invoice Description：显示在 Xendit 发票上的说明。可以使用占位符 {order_id}、{order_number} 和 {site_name}。HTML 会被移除，文本会截断为 255 个字符。默认：Order #{order_id}。

Order Status After Payment：Xendit 确认付款后设置的订单状态。状态会立即设置，且只做一次状态变更。

高级

Debug Log：Log API requests and webhooks 会将请求、Webhook 和状态变更写入 WooCommerce > Status > Logs，来源为 wcp_xendit_payment_gateway。即使此项关闭，错误和警告仍会始终记录。API 密钥、令牌和顾客数据不会被记录。默认：关闭。

Delete Data on Uninstall：Delete the plugin settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单数据（订单中的发票 ID）始终保留。默认：关闭。

结账

当商店币种为 IDR、PHP、VND、THB、MYR、USD 或 SGD 时，会显示付款方式。在 Pay for order 页面，以订单币种为准。顾客选择付款方式（默认为 Xendit）并下单。插件会以订单币种为订单总额创建一张 Xendit 发票，并将顾客引导至 Xendit 发票页面。IDR 和 VND 金额会四舍五入为整数，因为 Xendit 不接受这些币种的小数。顾客的账单电子邮件会传递给 Xendit。在发票页面上，顾客可使用您 Xendit 账户中为该币种启用的任一付款渠道付款，例如虚拟账户、电子钱包、二维码、零售网点或银行卡。

付款后，顾客会返回您店铺的订单已接收页面。只有在 Xendit 确认后，订单才会被标记为已付款：通过 Webhook，或在顾客到达该页面时由服务器向 Xendit API 发起请求确认。在此之前，订单保持为待付款状态。

如果发票失败或过期，Xendit 会将顾客送回。在结账时下的订单会以 WooCommerce 的标准方式取消，其发票会被设为过期。通过 Pay for order 页面付款的订单（例如您为顾客创建的订单）会返回其付款页面，并显示消息 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 付款。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。在测试模式下，结账区块会在付款方式下方显示 Test mode: no real money is charged.。它兼容 WooCommerce 高性能订单存储（HPOS）。

付款始终在 Xendit 页面上完成。插件不支持通过 WooCommerce 退款、保存银行卡、订阅或定期付款，不支持结账页面上的银行卡或电子钱包字段、单独的授权与扣款、xenPlatform 子账户、自定义发票过期时间或付款手续费。

订单

订单状态

Pending payment：发票已创建，但顾客尚未付款，或 Xendit 尚未确认付款。订单备注会显示发票 ID、金额、币种和模式。

Processing or Completed：付款已确认。状态遵循 Order Status After Payment 的设置。订单备注会显示发票 ID、已付金额、付款渠道和模式。交易 ID 即 Xendit 发票 ID。

On hold：已付款的发票与订单总额或币种不符，或实付金额低于总额（例如，发票创建后订单被修改）。订单备注会对此进行说明，即使订单已处于保留状态也会说明。请在 Xendit 控制面板中核对该笔付款，然后处理订单或退款。

Failed：当前发票在未付款的情况下已过期。顾客可以重新支付该订单。

Cancelled：顾客从失败或已过期的发票返回，或订单被您取消，或因 WooCommerce 对未付款订单的超时而取消。未结发票将被设为过期，因此无法再付款。若 Xendit 不接受此操作，备注会提醒您在 Xendit 控制面板中手动使发票过期。

如果为已付款、已取消或已退款的订单支付了发票，订单将保持不变。备注会提醒您在 Xendit 控制面板中退款，或手动恢复订单。

退款

退款不会通过 WooCommerce 发送到 Xendit。请在 Xendit 控制面板中为付款办理退款（订单备注和交易 ID 中包含发票 ID），然后在 WooCommerce 中手动记录退款。

许可证密钥

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

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

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

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

故障排除

Xendit 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否具有前缀正确的 Secret 密钥（测试模式为 xnd_development_ 开头的 Test Secret Key，正式模式为 xnd_production_ 开头的 Live Secret Key），以及商店币种是否为 IDR、PHP、VND、THB、MYR、USD 或 SGD。当密钥缺失或错误时，设置横幅会显示警告。

付款已完成，但订单仍为待付款：Webhook 无法正常工作。请在您所用模式（测试或正式）的 Xendit 控制面板中，检查设置中显示的 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 和令牌均可正常工作。

Webhook 响应「Temporary error」：无法连接 Xendit API 以核对发票，发票所属模式的 Secret 密钥缺失，或订单在同一时刻正被另一请求更新。Xendit 会重试 Webhook。如果您同时有两种模式的订单，请检查两个 Secret 密钥是否均已设置。

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

顾客看到「This payment method is temporarily unavailable」：Xendit 拒绝了请求，例如 Secret 密钥错误，或缺少 Money-in（发票）的写入权限。如有需要，请开启 Debug Log，并查看 WooCommerce > Status > Logs，来源为 wcp_xendit_payment_gateway。如果提示与账单信息有关，则表示 Xendit 未接受请求数据，例如电子邮件地址。

顾客看到「A payment for this order was already received by Xendit and is being reviewed」：该订单之前的某张发票已付款，但与订单不符，因此订单被保留。请在 Xendit 控制面板中核对该笔付款。

付款后订单变为 On hold：请阅读订单备注。已付金额或币种与订单不同。请处理订单，或在 Xendit 控制面板中退款。

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

卸载

停用插件会保留所有数据。如需删除，请在 Plugins 页面停用并删除插件。本插件的许可证密钥和许可证状态始终会被删除。网关设置、插件的其他选项、临时数据及其日志（包括轮换后的日志文件、数据库日志记录，以及 1.0 版的日志文件夹）只有在 Delete Data on Uninstall 开启时才会删除，否则会保留，以便日后重新安装。现有订单会保留其付款备注、发票 ID 和交易 ID。

Xendit 是其各自所有者的商标。本插件与 Xendit 无隶属关系，也不由 Xendit 认可或背书。