VibeFox IntaSend for WooCommerce — 帮助
系统要求
WordPress：6.2 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时插件无法启用。
PHP：8.0 或更高版本。
HTTPS：IntaSend 要求正式付款和 Webhook 使用 HTTPS。当正式模式已开启而店铺地址不是 HTTPS 时，设置页面会提示您。
IntaSend 账户：您需要 IntaSend 账户的公开密钥（ISPubKey_...）和私密密钥（ISSecretKey_...），可用于沙盒、正式环境或两者，还需要在 IntaSend 控制台中添加一个带验证短语的 Webhook（参见「配置」）。公开密钥用于创建结账。私密密钥仅在您的服务器上使用，用于向 IntaSend 查询付款状态。
店铺币种：KES、USD、EUR、GBP、UGX、TZS、NGN、GHS、XAF 或 XOF。对于其他币种，付款方式将被隐藏。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_intasend_pay 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置页面：WooCommerce > Settings > Payments > IntaSend > Manage，或在插件列表页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 粘贴您的 IntaSend 沙盒和/或正式密钥，在 IntaSend 控制台中添加 Webhook，并在插件中输入相同的验证短语（参见「配置」）。
6. 开启 Enable/Disable。在 Test mode 开启的情况下测试付款，然后取消勾选 Test mode 以接受真实付款。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > IntaSend。字段上方的状态框会显示 Test mode: IntaSend sandbox, no real money is charged. 或 Live mode: real payments are accepted. 如果当前模式的密钥缺失或错误（此时结账页面会隐藏付款方式）、店铺币种不受支持、未设置 Webhook 验证短语，或在未使用 HTTPS 的情况下使用正式模式，状态框还会发出警告。在付款方式列表中，IntaSend 会被标记为「需要设置」，直到当前模式的密钥正确为止。保存时会自动去除粘贴密钥中的空格。
常规
Enable/Disable：Enable IntaSend 用于启用或禁用该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。默认：IntaSend (M-Pesa, card)。
Description：结账时付款方式下方显示的文字。默认：You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.
API 密钥
请在 IntaSend 控制台的 Settings > API Keys 中获取密钥，沙盒控制台和正式控制台分别获取。测试模式使用沙盒密钥和沙盒 API，正式模式使用正式密钥和正式 API。插件会检查公开密钥是否以 ISPubKey_ 开头、私密密钥是否以 ISSecretKey_ 开头，以及密钥是否属于当前模式：沙盒密钥包含 _test，正式密钥包含 _live。如果不符合，付款方式将被隐藏，状态框会说明原因。
Test mode：Use the IntaSend sandbox (no real money is charged)。默认：开启。取消勾选即可使用正式密钥接受真实付款。测试模式开启时，结账页面会在付款方式下方显示 TEST MODE - IntaSend sandbox, no real money is charged.
Sandbox publishable key：以 ISPubKey_test 开头。在创建结账时用于标识您的商户。
Sandbox secret key：以 ISSecretKey_test 开头。仅在您的服务器上用于通过 Payment Status API 确认付款。
Live publishable key：以 ISPubKey_live 开头。
Live secret key：以 ISSecretKey_live 开头。仅在您的服务器上用于确认付款。
Webhook
即使顾客没有返回店铺（例如关闭了浏览器，或 M-Pesa 稍后才确认），Webhook 也会告知您的店铺付款已完成。在 IntaSend 控制台中，分别在沙盒和正式环境中打开 Webhooks，并添加本设置页面此部分显示的 URL。其格式类似 https://your-site/wc-api/intasend_pay/。在那里输入一个验证短语，并在插件中输入相同的短语。沙盒和正式环境使用同一个验证短语。
Webhook challenge：与 IntaSend 控制台中相同的验证短语。使用其他验证短语的 Webhook 会被拒绝。该字段为空时，Webhook 不会被处理，付款只会在顾客返回店铺后才被确认。这类 Webhook 会收到 Ignored 响应而非错误，因此在您输入验证短语之前，IntaSend 不会禁用该 Webhook。
插件会根据 IntaSend 报告的以下付款状态作出反应。每次修改订单前，它都会通过 Payment Status API 查询真实状态：
并非本店铺结账付款的通知（例如付款链接，或同一 IntaSend 账户中的汇款事件）会收到 OK 响应并被忽略，以免 IntaSend 禁用该 Webhook。
高级
Debug log：Log checkout, return and webhook events，位于 WooCommerce > Status > Logs，来源为 wcp_intasend_pay。错误始终会被记录。API 密钥和顾客数据从不会被记录。默认：关闭。
Delete data on uninstall：Delete the gateway settings and logs when the plugin is deleted。订单中保存的 IntaSend 引用属于付款记录，始终会被保留。停用插件不会删除任何内容。默认：关闭。
结账
顾客选择付款方式（默认为 IntaSend (M-Pesa, card)）并下单。插件会按订单金额和订单币种创建 IntaSend 结账，并将顾客转到 IntaSend 托管的结账页面。顾客在该页面使用 M-Pesa、银行卡或您 IntaSend 账户中启用的其他付款方式完成付款。账单邮箱、姓名、地址、电话和国家在符合 IntaSend 字段规则时会传递给 IntaSend。空白或不符合规则的字段将被忽略。
付款后，顾客返回您的店铺。只有在 IntaSend 确认后，订单才会标记为已付款：插件会在顾客返回时以及 Webhook 到达时查询 Payment Status API。如果付款尚未确认，订单接收页面会显示 Your payment is being confirmed by IntaSend (M-Pesa confirmations can take a minute). You will receive an e-mail as soon as it is confirmed. 如果订单已被置为「保留」，页面会显示 Your payment was received and your order is being reviewed. We will contact you if anything is needed.
如果付款失败，或顾客未付款即返回，顾客会回到结账页面（或 Pay for order 页面），并看到 The payment was not successful. Please try again or choose another payment method.（如 IntaSend 提供了原因，则附带原因）或 The payment was not completed. Please try again or choose another payment method. 顾客可以重新为该订单付款。每次尝试都会获得各自的 IntaSend 引用。
如果 IntaSend 无法发起付款，顾客会看到 IntaSend could not start the payment: 及 IntaSend 提供的原因，或 IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. 详细信息会写入日志。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。
本插件仅支持一次性付款。退款不会通过 WooCommerce 发送至 IntaSend，并且不支持保存银行卡、订阅或嵌入式（弹窗式）付款表单。同一订单的旧结账链接无法在 IntaSend 中取消。
订单
订单状态
Pending payment：顾客已被转到 IntaSend 但尚未付款，或 IntaSend 尚未确认付款。
Processing or Completed：付款已确认。WooCommerce 会设置已付款订单的常规状态。订单备注会显示 IntaSend 发票、IntaSend 中的付款方式、金额、模式（沙盒或正式）以及确认方式（Webhook 或顾客返回）。交易 ID 即 IntaSend 发票 ID。
On hold：IntaSend 报告的金额或币种与订单总额不符、付款为部分付款，或付款在订单被取消后才到达。订单备注会说明原因。请在 IntaSend 控制台中核实该笔付款，然后完成订单或退款。
Failed：最近一次付款尝试失败。备注会显示 IntaSend 的原因。顾客可以重试。
如果已付款订单又收到第二笔付款，订单不会再次变更。若属于重复付款，备注会提醒您在 IntaSend 控制台中退款。已退款订单收到的付款会添加备注，但不会重新打开该订单。
退款
退款不会通过 WooCommerce 发送至 IntaSend。请在 IntaSend 控制台中退还付款，然后在 WooCommerce 中手动记录退款。
许可证密钥
本插件需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > IntaSend 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期至何时以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放域名名额，请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，IntaSend 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥之前进行设置和测试。插件页面和 WooCommerce 页面上会出现提醒。现有订单不受影响：已发起的付款仍会被确认。
许可证到期后，插件仍可继续工作，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 IntaSend：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式的密钥是否已填写且属于该模式：测试模式使用沙盒密钥（包含 _test），正式模式使用正式密钥（包含 _live）。店铺币种必须受支持。设置页面顶部的状态框会显示问题所在。
付款已完成，但订单仍为 Pending payment：M-Pesa 的确认可能需要一点时间。IntaSend 报告最终状态后，Webhook 会确认订单。请检查 IntaSend 控制台中的 Webhook URL（沙盒或正式环境，取决于您使用的模式）是否与设置中显示的完全一致，并且那里的验证短语与 Webhook challenge 相同。
Webhook 返回 Ignored: webhook challenge not configured：Webhook challenge 为空。请输入 IntaSend 控制台中的验证短语。
Webhook 返回 Invalid challenge：IntaSend 与插件中的验证短语不一致。
Webhook 返回 Verification unavailable, retry later 或 Busy, retry later：当时无法连接 IntaSend，或该订单正被另一个请求确认。IntaSend 会重试 Webhook。
Webhook 返回 Invoice not verified 或 Invoice does not match the reference：IntaSend 未能确认该发票属于此订单。订单不会被修改。
订单为 On hold：请阅读订单备注。已付金额或币种与订单不符、付款为部分付款，或付款在订单取消后才到达。请在 IntaSend 控制台中核实该笔付款。
顾客下单时看到错误：请开启 Debug log，然后查看 WooCommerce > Status > Logs，来源 wcp_intasend_pay。订单总额必须大于零。如果日志显示返回 URL 包含 IntaSend 不接受的字符，原因在于店铺地址或其中的语言参数。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最近一次已知的状态运行。
卸载
停用插件会保留所有数据。如需删除，请在 Plugins 页面先停用再删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置和日志仅在 Delete data on uninstall 已开启时才会被删除，否则会保留，以便以后重新安装。现有订单会保留其付款备注和交易 ID。
IntaSend 是其各自所有者的商标。本插件与 IntaSend 无关联，也未获得 IntaSend 的认可。