VibeFox Midtrans for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

货币：印度尼西亚盾（IDR）。Midtrans 仅以 IDR 收款，因此只有当结账货币为 IDR 时才会提供该支付方式。不进行货币转换。如果您的商店没有 IDR 货币，请在 System > Localisation > Currencies 中添加。

Midtrans 账户：您需要 Midtrans Dashboard > Settings > Access Keys 中的 Server Key，沙盒后台和生产后台的都需要。仅使用 Server Key。Snap Redirect 不需要 Client Key。支付方式本身（GoPay、QRIS、虚拟账户等）需要在您的 Midtrans 账户中启用。

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

安装

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

OpenCart 3

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

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

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

4. 输入 Server Key，并将付款通知 URL 复制到 Midtrans 后台（见配置）。

5. 开启 Enable/Disable 并点击 Save。先在 Sandbox 中测试，然后将 Environment 切换为 Production。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥、Server Key 和通知 URL。两个版本的设置页面及其字段相同。只有通知 URL 不同（见配置）。

新安装默认关闭支付方式，并选择 Sandbox 环境。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Midtrans Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当所选环境缺少 Server Key 时（此时结账时将隐藏该支付方式），以及商店默认货币不是 IDR 时，页面都会发出警告；选择 Sandbox 时，页面会显示 Sandbox mode: payments are simulated, no real money is charged.。若您没有修改扩展的权限，页面只能显示设置，无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，Payment page expiry (minutes) 必须是整数。如果某个值有误，页面会显示错误，且不会保存任何内容。

Midtrans

Enable/Disable：Enable Midtrans payments 用于开启或关闭该支付方式。默认：关闭。

Title：结账时顾客看到的支付方式标题。它也会作为支付方式名称保存在订单中。默认：Midtrans。必填。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more。在 Sandbox 中，其上方会显示一行 SANDBOX MODE: no real money is charged.

Sort Order：Midtrans 在结账时的支付方式排列位置。留空或输入整数。

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

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

API 凭据

从 Midtrans Dashboard > Settings > Access Keys 复制 Server Key。该部分包含指向生产后台和沙盒后台的链接。

Environment：新付款使用的 Midtrans 环境。切换时会使用所选环境的密钥和 API。订单会保留其付款所在的环境，用于退款和通知。默认：Sandbox。

Sandbox：用于测试，不产生真实资金。

Production：真实付款。

Production Server Key：以 Mid-server- 开头。请妥善保密。

Sandbox Server Key：以 SB-Mid-server- 开头。

已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it.。只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。

付款通知 URL

通知用于告知您的商店某笔付款已完成。Notification URL 字段显示需要使用的 URL。在 OpenCart 3 上它形如 https://your-store/index.php?route=extension/payment/wcp_midtrans_payment_gateway/webhook，在 OpenCart 4 上形如 https://your-store/index.php?route=extension/wcp_midtrans_payment_gateway/payment/wcp_midtrans_payment_gateway.webhook，由您 OpenCart 安装的前台地址构成。请完全按照设置中显示的内容复制该 URL，并粘贴到您使用的沙盒后台和生产后台中的 Midtrans Dashboard > Settings > Payment > Notification URL。该 URL 必须能从互联网访问。如果在浏览器中打开它，会显示一段简短说明，您可以借此确认它可以访问。Midtrans 后台中的 Test notification URL 按钮也会得到响应。

每条通知都必须带有使用您某个 Server Key 生成的有效签名，并且密钥的环境必须与付款的环境一致。没有有效签名的通知会被拒绝。随后，订单变更前会通过 Midtrans 状态 API 重新读取交易状态。扩展会处理以下 Midtrans 交易状态：

settlement, capture (accepted)：付款已完成。当金额（以整数印尼盾计）和货币与订单相符时，订单会被标记为已付款。

capture (challenge)：被 Midtrans 欺诈检测标记的银行卡付款。在您于 Midtrans 后台批准或拒绝之前，订单会进入审核状态。

pending：顾客选择了延迟付款方式（虚拟账户、便利店、QRIS），或银行卡的 3-D Secure 验证尚未完成。订单会进入等待状态。

expire, cancel：未付款的交易已过期或被取消。等待中的订单会进入 expired / cancelled 状态，适用于所有支付方式。无状态订单不会获得任何状态：仅关闭该次尝试，顾客可以重新付款。

deny：付款被拒绝。等待中的订单会进入 failed 状态。

failure：付款失败。等待中的订单会进入 failed 状态。

refund, partial_refund：在 Midtrans 后台进行的退款会记录在订单中。

如果没有付款通知 URL，订单只有在顾客付款后返回商店时才会被确认；之后完成的延迟付款，在顾客返回之前不会被察觉。

付款设置

Midtrans 仅以 IDR 收款，金额以整数印尼盾发送。如果订单明细加总后与四舍五入的总额不一致，会向 Midtrans 发送一行 Rounding adjustment。

Payment page expiry (minutes)：顾客可以付款的时间长度（Snap 页面、虚拟账户等）。留空或填 0 则使用 Midtrans 的默认值。

Order ID prefix：添加到发送给 Midtrans 的编号之前，使多个商店可以共用同一个 Midtrans 账户。编号为带时间戳的 OpenCart 订单 ID，例如 OC-123-1700000000。仅允许字母、数字以及 - _ . ~，最多 20 个字符；保存时会删除其他字符。其他商店的通知会被忽略。默认：OC-。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时没有状态（缺失订单）。只有在 Midtrans 确认交易之后，订单才会获得状态。下面的每个字段都会列出您的 OpenCart 订单状态。

Status after payment：付款确认后的状态。默认：处理中。您可以选择一个已完成状态，将已付款订单标记为已完成；或选择您自己的审核状态，以便人工检查每个已付款订单。

Awaiting Midtrans payment status：Midtrans 报告 pending：已生成虚拟账户、便利店或 QRIS 码，或银行卡的 3-D Secure 验证尚未完成。默认：待付款。

Midtrans payment on hold status：付款需要您审核（参见订单状态）。默认：待付款，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。

Payment failed status：Midtrans 对等待中的订单报告 deny 或 failure。默认：失败。

Payment expired / cancelled status：等待中订单的待付 Midtrans 交易已过期或被取消。当您手动将未付款的 Midtrans 订单设为此状态时，其待付的 Midtrans 交易（例如已生成的虚拟账户）会被作废，使其无法再付款。默认：已取消。

Refunded status：付款已通过订单页面或 Midtrans 后台全额退款。默认：已退款。

高级

Debug log：将 API 调用和通知写入 OpenCart 日志文件夹（storage/logs）中的 midtrans_p_debug.log.php。该文件无法通过网页打开。错误始终会被记录。密钥和顾客数据绝不会被记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展会删除网关设置和日志。订单的 Midtrans 付款参考信息和退款始终保留，因此旧订单在重新安装后仍可退款。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。Server Key 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 Server Key 会被保留。

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 Midtrans）。在 Confirm Order 步骤中，顾客会看到您的描述，以及说明 You will be redirected to the Midtrans payment page (GoPay, QRIS, ShopeePay, cards, bank transfer and more). 的提示。OpenCart 在此步骤创建订单，仍没有状态。顾客点击 Confirm Order 后，扩展会以整数印尼盾为单位，按订单总额创建一笔 Midtrans Snap 交易，并附带订单明细、运费、折扣、税费以及顾客的账单和收货信息，然后将顾客引导至 Midtrans 付款页面。在那里，顾客可以选择您 Midtrans 账户中启用的任何方式。在 OpenCart 4 上，顾客通过支付方式区块中的 Choose 按钮、在 Payment method options 窗口中选择支付方式，并点击结账页面底部的 Confirm Order。

付款后，顾客返回您的商店。返回链接本身从不会将订单标记为已付款：只有在 Midtrans 确认之后，订单才会被标记为已付款，确认方式可以是签名通知，也可以是顾客返回时对 Midtrans 状态 API 的查询。随后订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。对于延迟付款，页面还会显示 We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. 如果顾客返回时无法连接 Midtrans，则会显示 Payment confirmation 页面，内容为 We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again.，并带有 Check again 按钮和 Back to checkout 按钮。

如果顾客离开 Snap 页面而未付款，会回到结账页面，并看到 The Midtrans payment was not completed. You can try again below. 如果付款被拒绝或已过期，提示为 Your Midtrans payment was declined or has expired. Please try again or choose another payment method. 在 OpenCart 4 上，这些消息显示在结账页面上方。购物车会保留。OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则为结账保留一笔订单并对其重新付款；无论哪种情况，扩展都会将同一购物车的所有订单视为一笔付款：顾客再次付款时，会复用相同金额的未使用或待付 Snap（已生成的虚拟账户仍然有效）；如果金额有变化，则先在 Midtrans 作废待付交易；如果此期间之前的 Snap 已被付款，则确认该笔付款，顾客直接进入成功页面，不会产生新交易。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单期间已在未付款的情况下被关闭（例如付款被拒绝、已过期，或您取消了订单），顾客会被带回结账页面，并看到 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 将为一笔新订单付款。如果该订单已下达，且之后购物车发生了变化，提示为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. 购物车的任何变化（包括数量变化）都视为需要单独付款的新购物车。如果购物车清空后订单的付款才被拒绝或过期（例如虚拟账户付款之后），顾客会看到 The Midtrans payment of order #(number) was declined or has expired, so the order will not be shipped. To buy these items, please place a new order.

如果 Midtrans 无法启动付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短消息：Could not connect to Midtrans. Please try again in a moment.、Midtrans payments are temporarily unavailable. Please choose another payment method or contact us.（例如 Server Key 错误时），或 Midtrans 提供的原因。技术原因会写入日志。

商店处于维护模式时，通知同样有效，因为 OpenCart 3 允许支付扩展的请求通过；在 OpenCart 4 上，扩展为此添加了一个启动动作，它同样允许顾客从 Midtrans 返回。

该扩展仅使用 Snap Redirect。不提供 Snap 弹窗、您网站上的卡片表单、保存的卡片或一键付款，也不提供分期或促销设置（支付方式需在 Midtrans 后台配置），并且不支持订阅。银行卡付款会立即扣款，没有单独的授权与捕获。

订单与退款

订单状态

No status (missing order)：顾客已被引导至 Midtrans 但尚未付款，或 Midtrans 尚未确认付款。在 Sales > Orders 中，只有将 Order Status 筛选设为 Missing Orders 时才会显示此类订单。

Awaiting Midtrans payment status（默认待付款）：顾客选择了延迟付款方式，或开始了一笔尚未完成的银行卡付款。当 Midtrans 报告付款后，订单会转为 Status after payment。

Status after payment（默认处理中）：付款已确认。备注会显示付款方式、Midtrans 订单 ID 和交易信息。

Midtrans payment on hold status（默认待付款）：银行卡付款处于欺诈审核中（challenge，尚未记录任何资金），付款金额或货币与订单不符（订单不会被标记为已付款），或者有付款到达了已取消的订单（订单不会自动重新打开）。备注会说明原因。请检查订单，然后履行订单或退还付款。

Payment expired / cancelled status（默认已取消）：等待中订单的未付交易已过期或被取消。

Payment failed status（默认失败）：付款失败，或被审核的银行卡付款已被拒绝。

Refunded status（默认已退款）：付款已全额退款。

OpenCart 会以常规方式就这些状态变化通知顾客。如果同一购物车又收到第二笔付款，订单不会改变。已付款订单上的备注会提醒您在 Midtrans 后台退还第二笔付款。对已退款订单的付款只会添加一条备注。

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

VibeFox Midtrans Payment Gateway 选项卡

在 Sales > Orders 中打开一笔通过 Midtrans 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Midtrans Payment Gateway 选项卡会显示 Midtrans order ID、Transaction ID（链接到付款所在环境的 Midtrans 后台中的交易；沙盒付款会带有 Sandbox 标签）、Payment method、Status、Paid / refunded 金额、退款表单、退款记录以及订单的 Midtrans notes。有权访问该扩展的用户会看到此选项卡。

退款

在 VibeFox Midtrans Payment Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via Midtrans。确认提示 Refund this amount through Midtrans? This cannot be undone.。全额和部分退款均以整数印尼盾为单位支持；带小数的金额会被拒绝。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。即使订单之后被编辑过，您最多也可以退还 Midtrans 实际收取的金额。退款会在付款所在的环境中发送，因此该环境的 Server Key 必须已设置。Midtrans 仅对部分付款方式和已结算的交易允许通过 API 退款。如果 Midtrans 不接受退款，选项卡会显示错误，且不会记录任何退款；此时请在 Midtrans 后台进行退款。成功的退款会添加到退款记录和备注中。全额退款会将订单设为 Refunded status，但不会通知顾客，也不会将商品退回库存，与手动修改状态相同。部分退款不会改变状态。只有在 Midtrans 报告付款已结算之后，才能进行退款。

Sales > Returns 中的商品退货不会通过 Midtrans 退还款项。

在 Midtrans 后台进行的退款会通过通知传回，并以 Refunded in the Midtrans dashboard 为原因自动添加到退款记录中。如果整笔付款在后台被退款，订单会变为 Refunded status。

许可证密钥

该扩展需要使用 vibefox.net 提供的 VibeFox 许可证密钥。许可证区块 License — VibeFox Midtrans Payment Gateway 是 Extensions > Extensions > Payments > VibeFox Midtrans Payment Gateway > Edit 页面中设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期的截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。下方是 Product: opencart-payment-midtrans 这一行，以及 Manage licenses and domains in your account 链接，它会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户可以更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

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

一个密钥只适用于一个域名：即 OpenCart 配置中的商店地址。从商店移除密钥并不会释放其域名名额，请在您的 vibefox.net 账户中释放名额。

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

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

故障排除

结账时不显示 Midtrans：请检查许可证是否有效、Enable/Disable 是否开启，以及所选 Environment 是否有 Server Key。请检查结账货币是否为 IDR、付款地址是否在所选的 Geo Zone 内，以及订单是否达到设置中的 Total。如果密钥缺失或商店货币不是 IDR，设置页面会显示警告。

付款已完成，但订单仍没有状态：通知功能未正常工作。请检查您所用环境（沙盒或生产）的 Midtrans 后台是否设置了付款通知 URL，该 URL 是否与 Notification URL 中显示的完全一致，以及它是否可以访问：在浏览器中打开它，会显示一段简短说明。开启 Debug log 可查看通知。顾客付款后返回商店时，订单也会获得状态。

通知返回 Invalid signature：通知并非使用您的 Sandbox 或 Production Server Key 签名。请检查设置中的密钥是否与发送通知的后台属于同一个 Midtrans 账户。

通知返回 Server key not configured：没有设置任何 Server Key。请在设置中输入；Midtrans 会重试通知。

通知返回 Order not found — ignored：该 Midtrans 订单 ID 并非由本商店生成，例如同一 Midtrans 账户上的其他商店生成的。请为每个商店设置不同的 Order ID prefix。

通知返回 Environment mismatch — ignored：通知使用的是与付款环境不同的另一环境的密钥签名。

通知返回 Verification failed, please retry：无法连接 Midtrans 状态 API。Midtrans 会重试通知。

通知返回 Busy, please retry：购物车当时正被另一个请求更新，或无法设置订单状态。Midtrans 会重试通知。请查看日志了解原因。

订单处于审核状态：请阅读选项卡中的 Midtrans notes。银行卡付款正在欺诈审核中，付款金额或货币与订单不符，或者付款是在订单被取消之后到达的。

顾客在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段；错误始终会被记录。Server Key 错误会给出 Midtrans 付款暂时不可用的提示。Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method. 表示订单不是 IDR。This payment method is not available. 表示结账会话已与订单不再匹配，或支付方式在此期间被关闭：顾客需要重新加载结账页面。

顾客返回结账页面并看到 Payment verification failed.：返回链接不完整，或不属于该订单。订单仍会从通知中获得状态。

选项卡中没有退款表单：选项卡会说明原因：付款尚未结算、已全额退款、您的用户组没有修改扩展的权限，或订单付款所在环境未设置 Server Key。

退款失败：付款方式或交易状态不允许通过 API 退款；请在 Midtrans 后台退款，退款会自动记录到订单中。

面向开发者：在创建 Snap 交易之前，扩展会以请求数据和订单触发 OpenCart 事件 midtrans_p_snap_payload；订单 ID 和金额不可更改。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Midtrans Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被移除。OpenCart 总会移除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分的订单状态；重新安装后它们会恢复为默认值。扩展的 OpenCart 事件也会被移除（OpenCart 4 上还会移除其在维护模式下放行通知的启动动作）。如果开启了 Delete data on uninstall，其余网关设置（标题、描述、环境、Server Key、付款设置、日志记录）和日志都会被删除；如果关闭，则会保留，以便之后重新安装时使用。订单的 Midtrans 付款参考信息和退款始终保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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