VibeFox IntaSend for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本，并启用 cURL 扩展。在较旧的 PHP 版本上或未启用 cURL 时，模块拒绝安装。

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. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

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

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

4. 粘贴您的 IntaSend 沙盒和/或正式密钥，在 IntaSend 后台添加 Webhook，并在模块中输入相同的验证短语（参见配置）。

5. 开启 Enable/Disable 并点击 Save。开启 Test mode 测试一笔付款，然后关闭 Test mode 以接受真实付款。

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

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox IntaSend Pay Gateway > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。字段上方的状态框会显示 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：使用 IntaSend 沙盒，不会收取真实费用。默认：开启。关闭它即可使用正式密钥接受真实付款。在测试模式开启期间，结账时付款方式下方会显示 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 验证短语不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Webhook

即使顾客没有返回店铺（例如关闭了浏览器，或 M-Pesa 稍后才确认），Webhook 也会通知您的店铺已完成付款。在 IntaSend 后台（沙盒和正式环境都需要），打开 Webhooks，并添加本部分 Webhook URL 中显示的 URL。启用友好 URL 时，它类似于 https://your-shop/module/wcp_intasend_pay/webhook，可能带有语言代码，例如 /en/。请完全按照设置中显示的内容复制 URL。在那里输入一个验证短语，并在模块中输入相同的短语。沙盒和正式环境请使用同一个验证短语。

Webhook challenge：与 IntaSend 后台中相同的验证短语。使用其他短语的 Webhook 会被拒绝。在此字段为空时，Webhook 不会被处理，付款只会在顾客返回店铺时才被确认。这类 Webhook 会收到 Ignored 响应而非错误，这样在您输入验证短语之前，IntaSend 就不会停用该 Webhook。

清除已保存的密钥：勾选 Sandbox secret key、Live secret key 或 Webhook challenge，然后点击 Save 即可删除。字段为空则保留已保存的值。

模块会对 IntaSend 报告的以下付款状态作出反应。每次在更改任何内容之前，它都会向 Payment Status API 查询真实状态：

并非本店铺结账付款的通知，例如同一 IntaSend 账户的付款链接或转账事件，会收到 Ignored 响应，这样 IntaSend 就不会停用 Webhook。

高级

Debug log：将结账、返回和 Webhook 事件记录到模块文件夹中的 logs/intasend_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。API 密钥和顾客数据从不记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载模块时会删除网关设置和日志。订单保存的 IntaSend 引用属于付款记录，始终保留。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 IntaSend (M-Pesa, card)）并确认。模块会按购物车金额和购物车币种创建 IntaSend 结账，并将顾客转到 IntaSend 托管的结账页面。顾客在那里使用 M-Pesa、银行卡或您 IntaSend 账户中启用的其他付款方式付款。当顾客的电子邮件以及账单地址的姓名、地址、电话和国家符合 IntaSend 的字段规则时，这些信息会传给 IntaSend。空白或不合规的字段会被省略。此时尚未创建订单。

付款后，顾客会返回您的店铺。只有在 IntaSend 确认后，订单才会标记为已付款：模块会在顾客返回时以及 Webhook 到达时向 Payment Status API 查询。之后订单会被创建，顾客会看到标准的订单确认页面。如果订单被置为保留状态，页面会显示 Your payment was received and your order is being reviewed. We will contact you if anything is needed. 如果付款尚未确认，或者此时无法连接 IntaSend，则会显示 Payment confirmation 页面，内容为 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.，并带有 Check again 和 Back to checkout 按钮。IntaSend 一确认付款，Webhook 就会创建订单。

如果付款失败，顾客会返回结账页面，并显示 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. 详细信息会写入日志。总额为零的购物车无法通过 IntaSend 付款。

即使店铺处于维护模式，Webhook 仍然有效，并且不受店铺国家限制的影响。当友好 URL 关闭时，顾客会通过店铺首页返回，因为 IntaSend 不接受返回地址中的某些字符。

本模块仅支持一次性付款。退款不会从店铺发送至 IntaSend，并且不支持保存银行卡、订阅或嵌入式（弹窗式）付款表单。同一购物车的旧结账链接无法在 IntaSend 取消。

订单

订单状态

No order yet：顾客已被转到 IntaSend 但尚未付款，或者 IntaSend 尚未确认付款。此时只存在购物车。

Payment accepted：付款已确认。付款会以 IntaSend 发票 ID 作为交易 ID 记录，备注中会显示发票、IntaSend 中的付款方式、金额、模式（沙盒或正式）以及确认方式（Webhook 或顾客返回）。

IntaSend payment on hold：IntaSend 报告的金额或币种与购物车总额不符、为部分付款，或者付款是在订单被取消之后到达的。备注会对此进行说明；当 IntaSend 收取的金额为订单币种时，该金额会被记录为一笔付款。请在 IntaSend 后台核对付款，然后处理订单或退款。如果之后到达了正确的付款，订单会转为 Payment accepted。

如果已付款的订单又收到第二笔付款，订单不会被更改。备注会提醒您，如果这是重复付款，请在 IntaSend 后台退款。对已退款订单的付款会添加备注，但不会重新打开订单。

IntaSend 付款区块

订单页面会显示 IntaSend payment 区块，其中列出订单购物车的每一次结账尝试（日期、参考号、IntaSend 结账、环境、金额、发票和结果，失败时附上原因），以及 Invoices processed（发票、IntaSend 状态、金额和结果）。该区块为只读。

退款

退款不会从店铺发送至 IntaSend。请在 IntaSend 后台退还付款，并在 PrestaShop 中手动记录退款。

许可证密钥

本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。模块 Configure 页面顶部的许可证区块 License — VibeFox IntaSend Pay Gateway 位于 Modules > Module Manager > VibeFox IntaSend Pay Gateway > Configure 中、设置上方，是第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会显示被遮挡的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺中移除密钥）。下方显示 Product: presta-payment-intasend 一行，以及 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 账户中释放该名额。

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

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

故障排除

结账时没有显示 IntaSend：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的密钥是否已填写且属于该模式：测试模式使用沙盒密钥（含 _test），正式模式使用正式密钥（含 _live）。购物车币种必须受支持。设置页面顶部的状态框会显示问题所在。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客群组。

付款已完成，但没有创建订单：M-Pesa 确认可能需要一点时间。当 IntaSend 报告最终状态时，Webhook 会创建订单。请检查 IntaSend 后台（沙盒或正式，取决于您使用的模式）中的 Webhook URL 是否与 Webhook URL 中显示的完全一致，以及其中的验证短语是否与 Webhook challenge 相同。顾客返回店铺或点击 Check again 时也会创建订单。

Webhook 返回 Ignored: webhook challenge not configured：Webhook challenge 为空。请输入 IntaSend 后台中的验证短语。

Webhook 返回 Invalid challenge：IntaSend 和模块中的验证短语不一致，或者 Webhook 没有验证短语。

Webhook 返回 Verification unavailable, retry later 或 Busy, retry later：当时无法连接 IntaSend，购物车正在被另一个请求确认，或者无法创建订单（例如模块已被禁用）。IntaSend 会重试 Webhook。原因记录在日志中。

Webhook 返回 Invoice not verified 或 Invoice does not match the reference：IntaSend 未确认此发票属于该购物车。不做任何更改。

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

订单处于 IntaSend payment on hold：请阅读订单备注。已付金额或币种与购物车不符，付款为部分付款，或者付款是在订单取消之后到达的。请在 IntaSend 后台核对付款。

顾客选择 IntaSend 时看到错误：请查看模块页面上的 Log 字段（开启 Debug log 可获得更多细节）。如果当前模式的密钥有误，顾客会看到 IntaSend is not available at the moment. Please choose another payment method or contact the store. 如果日志显示返回 URL 包含 IntaSend 不接受的字符，原因在于店铺地址。

顾客看到 We could not match this payment to an order：返回链接已被修改，或属于另一个购物车。如果顾客已付款，Webhook 仍会创建订单。

卸载

进入 Modules > Module Manager，打开 VibeFox IntaSend Pay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志会被删除。如果已关闭，所有设置都会保留，以便之后重新安装。订单的 IntaSend 结账尝试和发票，以及订单状态 IntaSend payment on hold，始终会保留。现有订单会保留其付款备注和交易 ID。

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