VibeFox IntaSend for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本，并安装 cURL 扩展。

HTTPS：IntaSend 的正式付款和 Webhook 需要 HTTPS。当正式模式开启而店铺地址不是 HTTPS 时，设置页面会提醒您。

IntaSend 账户：您需要 IntaSend 账户的可发布密钥（ISPubKey_...）和密钥（ISSecretKey_...），用于沙盒、正式环境或两者，并且需要在 IntaSend 控制台中添加一个带验证短语（challenge）的 Webhook（参见配置）。可发布密钥用于在结账时创建付款。密钥只在您的服务器上使用，用于向 IntaSend 查询付款状态。

货币：KES、USD、EUR、GBP、UGX、TZS、NGN、GHS、XAF 或 XOF。当顾客的结账货币不是其中之一时，付款方式将被隐藏。

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

安装

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

新安装的扩展默认关闭付款方式并开启测试模式。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox IntaSend Pay Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮保存整个页面。在设置上方，状态框会显示 Test mode: IntaSend sandbox, no real money is charged. 或 Live mode: real payments are accepted. 当前模式的密钥缺失或错误（此时付款方式会在结账时隐藏）、店铺默认货币不受支持、未设置 Webhook 验证短语以及在没有 HTTPS 的情况下使用正式模式时，它也会提醒您。如果您没有修改该扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空或超过 128 个字符，Sort Order 必须是整数，Total 必须是 0 或更大的数字，并且所选的地理区域和订单状态必须存在。否则不会保存任何内容，错误信息会指出对应字段。密钥问题不会阻止保存：状态框会指出这些问题。粘贴的密钥会自动去除首尾空格。

IntaSend

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：IntaSend (M-Pesa, card)。必填，1 到 128 个字符。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

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

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

Total：订单必须达到的结账总额（以店铺默认货币计算），达到后才会提供 IntaSend。留空则对任何金额都提供 IntaSend。

API 密钥

在 IntaSend 控制台的 Settings > API Keys 中获取密钥，沙盒控制台和正式控制台分别获取（该部分提供两者的链接）。测试模式使用沙盒密钥和沙盒 API，正式模式使用正式密钥和正式 API。扩展会检查可发布密钥是否以 ISPubKey_ 开头、密钥是否以 ISSecretKey_ 开头，以及密钥是否属于当前模式：沙盒密钥包含 _test，正式密钥包含 _live。如果不符合，付款方式将被隐藏，状态框会说明原因。

Test mode：使用 IntaSend 沙盒，不会扣除真实款项。默认：开启。关闭后将使用正式密钥接收真实付款。测试模式开启时，顾客在 Confirm Order 步骤会看到 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. 只有在需要更改时才输入新值。要删除已保存的值，请勾选该字段下方的 Clear the saved value，然后点击 Save。

Webhook

即使顾客没有返回店铺（例如关闭了浏览器，或 M-Pesa 稍后才确认），Webhook 也会告知您的店铺付款已完成。在 IntaSend 控制台中（沙盒和正式环境均需设置），打开 Webhooks，并添加本部分 Webhook URL 中显示的网址。在 OpenCart 3 中，它的格式类似 https://your-store/index.php?route=extension/payment/wcp_intasend_pay/webhook；在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_intasend_pay/payment/wcp_intasend_pay.webhook。它由您的 OpenCart 安装的店铺前台地址生成。请完全按照设置中显示的内容复制该网址。在那里输入一个验证短语，并在扩展中输入相同的短语。沙盒和正式环境应使用同一个验证短语。

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

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

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

订单

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

Paid Order Status：IntaSend 确认付款后设置的状态。默认：Processing。

On Hold Status：IntaSend 报告了不同的金额或币种、部分付款，或者订单取消后才到账的付款。订单将获得此状态，并附上说明原因的备注。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Refunded Status：对处于此状态的订单收到的付款只会添加备注，订单不会重新打开。默认：Refunded。扩展本身不执行退款。

高级

Debug log：将结账、返回和 Webhook 事件记录到 OpenCart 日志文件夹（storage/logs）中的 intasend_p_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会移动到 intasend_p_debug.old.log.php。错误和警告始终会被记录。API 密钥、验证短语和顾客数据绝不会被记录。默认：关闭。

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

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

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。密钥和 Webhook 验证短语不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥和 Webhook 验证短语会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 IntaSend (M-Pesa, card)）。在 Confirm Order 步骤中，顾客看到您的说明。OpenCart 在此步骤创建订单，此时仍无状态。当顾客点击 Confirm Order 时，扩展会以订单货币为订单总额创建一个 IntaSend 结账，并将顾客转到 IntaSend 托管的结账页面。顾客在那里使用 M-Pesa、银行卡或您 IntaSend 账户中启用的其他方式付款。顾客的电子邮件、电话以及付款地址的姓名、地址和国家，在符合 IntaSend 字段规则时会传递给 IntaSend。空白或不合规的字段会被省略。每次尝试都会获得自己的 IntaSend 参考编号。

在 OpenCart 4 中，顾客在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中），然后点击结账页面底部的 Confirm Order。OpenCart 4 默认不要求付款地址；此时扩展会将配送地址的地址、城市、邮政编码和国家传给 IntaSend。

付款后，由于 IntaSend 不接受返回地址中的某些字符，顾客会通过店铺的首页地址返回；扩展随后将顾客转到其返回页面。只有在 IntaSend 确认后，订单才会被标记为已付款：扩展会在顾客返回时以及 Webhook 到达时查询 Payment Status API。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。如果订单被置于保留状态，页面还会显示 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. 购物车会保留，顾客可以再次付款。在 OpenCart 4 中，这些提示会显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账的订单，因此付款失败后，顾客会以新的尝试支付同一个订单。但同一购物车只能付款一次：如果同一购物车的另一个订单已经付款，顾客会被带到成功页面，而不是进行新的付款。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单期间已被关闭（例如您取消或退款），顾客会被带回结账页面，并显示 Your previous order was cancelled or refunded. Please confirm the order again. 如果订单已经生成，而购物车中现在有其他商品，提示为 Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. 两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。

如果 IntaSend 无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方显示提示：IntaSend could not start the payment: 以及 IntaSend 给出的原因，或者 IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. 详细信息会写入日志。订单总额为零时无法使用 IntaSend 付款。

即使店铺处于维护模式，Webhook 也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作，放行 Webhook 和顾客的返回请求。

该扩展仅支持一次性付款。店铺不会将退款发送给 IntaSend，并且它不支持保存银行卡、订阅或内嵌（弹窗）付款表单。同一订单较早的结账链接无法在 IntaSend 中取消。

订单

订单状态

No status (missing order)：顾客已被转到 IntaSend 但尚未付款，付款失败，或 IntaSend 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选器设为 Missing Orders 时才会显示这类订单。

Paid Order Status（默认 Processing）：付款已确认。备注会显示 IntaSend 发票、IntaSend 中的付款方式、金额、模式（沙盒或正式）以及确认方式（Webhook 或顾客返回）。

On Hold Status（默认 Pending）：IntaSend 报告的金额或币种与订单总额不同、为部分付款，或是在订单取消后到账的付款。备注会说明情况。请在 IntaSend 控制台中核实付款，然后完成订单或退款。如果之后收到正确的付款，订单会转为 Paid Order Status，并通过电子邮件通知顾客。

如果已付款的订单又收到第二笔付款，订单不会发生变化。备注会提示您，如果这是重复付款，请在 IntaSend 控制台中退款。处于 Refunded Status 的订单收到付款时，只会添加备注，订单不会重新打开。

备注是订单 History 中的条目，顾客看不到。

VibeFox IntaSend Pay Gateway 选项卡

在 Sales > Orders 中打开一个通过 IntaSend 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox IntaSend Pay Gateway 选项卡会显示该订单的 IntaSend checkout attempts（日期、参考编号、IntaSend 结账、环境、金额、发票和付款方式，以及附带失败原因的结果）、Invoices processed（发票、IntaSend 状态、金额和结果）以及该订单的 IntaSend notes。该选项卡为只读，仅对有权访问该扩展的用户显示。

退款

店铺不会将退款发送给 IntaSend。请在 IntaSend 控制台中退还付款，然后在 OpenCart 中手动记录退款，例如将订单设为 Refunded Status。

许可证密钥

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

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

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

故障排除

结账时没有显示 IntaSend：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的密钥是否已填写并属于该模式：测试模式使用沙盒密钥（包含 _test），正式模式使用正式密钥（包含 _live）。设置页面顶部的状态框会显示问题所在。顾客的结账货币必须受支持。还需检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：M-Pesa 的确认可能需要一点时间。IntaSend 报告最终状态时，Webhook 会设置订单状态。请检查 IntaSend 控制台中的 Webhook 网址（沙盒或正式，取决于您使用的模式）是否与 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 网址在浏览器中显示 Method not allowed：这是正常现象。该网址只接受来自 IntaSend 的请求。

订单处于 On Hold Status：请阅读 VibeFox IntaSend Pay Gateway 选项卡中的备注。已付金额或币种与订单不符，付款为部分付款，或付款是在订单取消后到达的。请在 IntaSend 控制台中核实该付款。

顾客在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段（开启 Debug log 可获得更多详细信息）。如果当前模式的密钥有误，顾客会看到 IntaSend is not available at the moment. Please choose another payment method or contact the store. This payment method is not available. 表示结账会话已与订单不再匹配，或付款方式在此期间被关闭：顾客需要重新加载结账页面。如果日志显示返回网址包含 IntaSend 不接受的字符，则原因在于店铺地址。

顾客看到 We could not match this payment to an order：返回链接已被修改或属于其他订单。如果顾客已付款，Webhook 仍会设置订单状态。

对开发者：在创建结账之前，扩展会触发 OpenCart 事件 intasend_p_checkout_payload，并附带请求数据、订单和模式；事件 intasend_p_supported_currencies 可以修改货币列表。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox IntaSend Pay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装后会恢复默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其启动动作，该动作在维护模式下放行 Webhook 和顾客返回请求）。如果 Delete data on uninstall 已开启，其余网关设置（标题、说明、测试模式、密钥、Webhook 验证短语、调试日志开关）和日志都会被删除。如果未开启，这些设置会保留，供以后重新安装时使用。订单的 IntaSend 结账尝试记录和发票总会被保留。现有订单会保留其付款备注。

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

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