VibeFox Midtrans for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。

币种：印尼盾（IDR）。Midtrans 仅以 IDR 收款，因此只有购物车币种为 IDR 时才会提供该付款方式。不进行币种转换。如果您的店铺没有 IDR 币种，请在 International > Localization 中添加。

Midtrans 账户：您需要 Midtrans Dashboard > Settings > Access Keys 中的 Server Key，沙盒后台和正式后台各一个。模块只使用 Server Key。Snap Redirect 不需要 Client Key。付款方式本身（GoPay、QRIS、虚拟账户等）需在您的 Midtrans 账户中启用。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥对应一个域名。

安装

1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Midtrans Payment Gateway，再点击 Configure。

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

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

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

安装时，模块会创建两个订单状态：Awaiting Midtrans payment 和 Midtrans payment on hold。PrestaShop 会为所有币种、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中加以限制。该模块必须保持对 IDR 币种的允许状态。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，如果所选环境缺少 Server Key（此时付款方式会在结账时隐藏）或商店默认币种不是 IDR，页面会发出提醒；选择 Sandbox 时，页面会显示 Sandbox mode: payments are simulated, no real money is charged.

Midtrans

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

Title：结账时向顾客显示的付款方式标题。它也是订单中保存的付款方式名称。默认：Midtrans。必填。

Description：结账时显示在付款方式下方的文字。默认：Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more。在 Sandbox 中会加入一行 SANDBOX MODE: no real money is charged.

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 saved keys：勾选某个密钥并点击 Save 即可删除。空字段会保留已保存的值。

付款通知 URL

通知会告知您的店铺某笔付款已完成。Notification URL 字段显示需要使用的 URL。启用友好 URL 时，它的形式类似 https://your-shop/module/wcp_midtrans_payment_gateway/webhook，可能带有语言代码，例如 /en/。请按设置中显示的内容完整复制该 URL，并粘贴到您所用的沙盒后台和正式后台中的 Midtrans Dashboard > Settings > Payment > Notification URL。在浏览器中打开该 URL 会显示简短说明，因此您可以确认其可以访问。Midtrans 后台中的 Test notification URL 按钮也会获得响应。

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

settlement, capture (accepted)：付款已完成。当金额（整数印尼盾）和币种与购物车一致时，订单以已付款状态创建。

capture (challenge)：被 Midtrans 欺诈检测标记的银行卡付款。在您于 Midtrans 后台批准或拒绝之前，订单保持 Midtrans payment on hold 状态。

pending：顾客选择了延迟付款方式（虚拟账户、便利店）且尚未付款。订单以 Awaiting Midtrans payment 状态创建。

expire, cancel：未付款的交易已过期或被取消。等待中的订单会变为 Canceled，适用于所有付款方式。若没有订单，仅关闭此次尝试，顾客可以重新支付购物车。

deny：付款被拒绝。等待中的订单会变为 Payment error。

failure：付款失败。等待中的订单会变为 Payment error。

refund, partial_refund：在 Midtrans 后台完成的退款会记录到订单中。

如果没有付款通知 URL，只有顾客付款后返回店铺时才会创建订单；之后完成的延迟付款，要等顾客返回后才能被识别。

付款设置

Midtrans 仅以 IDR 收款，金额以整数印尼盾发送。如果订单明细之和与取整后的总额不符，则会向 Midtrans 发送一行 Rounding adjustment。

Status after payment：付款确认后的订单状态。

Processing (default)：Payment accepted，即 PrestaShop 对已付款订单的标准状态。

Completed：每个已付款订单都会变为 Delivered。

On hold：每个已付款订单都会进入 Midtrans payment on hold，以供您人工审核。付款仍会记录在订单中。

Payment page expiry (minutes)：顾客可以付款的时间长度（Snap 页面、虚拟账户等）。留空或填 0 即使用 Midtrans 的默认值。不是整数分钟的值在保存时会被拒绝并报错。

Order ID prefix：添加到发送给 Midtrans 的编号前面，使多家店铺可以共用同一个 Midtrans 账户。编号由购物车 ID 加时间戳组成，例如 WC-123-1700000000。仅允许字母、数字以及 - _ . ~，最多 20 个字符；保存时会删除其他字符。其他店铺的通知会被忽略。默认：WC-。

高级

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

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

Delete data on uninstall：开启后，卸载模块时会删除模块设置和日志。订单、其 Midtrans 付款参考和退款，以及模块的订单状态始终保留，因此旧订单在重新安装后仍可退款。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Midtrans）并确认。模块会以整数印尼盾为购物车总额创建一笔 Midtrans Snap 交易，包含商品明细、运费、折扣、礼品包装、税费以及顾客的账单和收货信息，并将顾客引导至 Midtrans 付款页面。在那里，顾客可以选择您 Midtrans 账户中启用的任意付款方式。此时尚未创建订单。

付款后，顾客返回您的店铺。返回链接本身从不会将订单标记为已付款：只有 Midtrans 确认后（通过已签名的通知，或顾客返回时对 Midtrans 状态 API 的查询），订单才会被标记为已付款。随后订单被创建，顾客看到标准的订单确认页面，并显示所用的付款方式。对于延迟付款，页面显示 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. 对于未付款即已关闭的订单，显示 Your Midtrans payment was not completed. Please contact us about this order. 如果顾客返回时无法连接 Midtrans，Payment confirmation 页面会显示 We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again.，并带有 Check again 按钮。

如果顾客离开 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. 购物车会被保留。顾客再次付款时，相同金额的未使用或待处理 Snap 会被重复使用。如果金额已变化，则会先在 Midtrans 将待处理交易设为过期。如果之前的 Snap 此时已付款，则会创建订单，而不再创建新交易。如果订单已存在且未付款即已关闭，提示为 Your Midtrans payment was declined or has expired. Please place a new order or contact us.

如果 Midtrans 无法发起付款，顾客会停留在结账页面，并显示简短提示：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 给出的原因。技术原因会写入日志。非 IDR 购物车会显示 Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

即使店铺处于维护模式，通知仍然有效，并且不受店铺国家限制的影响。

本模块仅使用 Snap Redirect。没有 Snap 弹窗、您网站上的银行卡表单、保存的银行卡或一键付款、分期或促销设置（请在 Midtrans 后台配置付款方式）以及订阅。银行卡付款会立即扣款，没有单独的授权与扣款。

订单与退款

订单状态

No order yet：顾客已被引导至 Midtrans 但尚未付款，或 Midtrans 尚未确认付款。此时只存在购物车。

Awaiting Midtrans payment：顾客选择了延迟付款方式（虚拟账户、便利店），或开始了一笔尚未完成的银行卡付款。Midtrans 报告付款后，订单变为已付款。

Payment accepted、Delivered 或 Midtrans payment on hold：付款已确认。状态遵循 Status after payment 的设置。付款会以 Midtrans 交易 ID 记录，备注中会显示付款方式和 Midtrans 订单 ID。

Midtrans payment on hold：在以下情况下也会设置此状态：银行卡付款正在欺诈审核中（challenge，尚未记录付款）；已付金额或币种与订单不符（订单不会被标记为已付款）；或订单已取消后又收到付款（订单不会自动重新打开）。备注会说明原因。请检查订单，然后处理订单或退还付款。

Canceled：未付款的交易已过期或被取消。当您自行取消一个未付款的 Midtrans 订单时，其待处理的 Midtrans 交易（例如已发出的虚拟账户）会被设为过期，之后无法再付款。

Payment error：付款失败，或处于审核中的银行卡付款被拒绝。

Refunded：付款已全额退款。

如果已付款的订单又收到第二笔付款，订单不会改变。备注会提醒您在 Midtrans 后台退还第二笔付款。对已退款订单的付款只会添加一条备注。

Midtrans 付款区块

订单页面会显示 Midtrans payment 区块，包括 Midtrans 订单 ID、交易 ID（链接到该付款所在环境的 Midtrans 后台中的交易）、付款方式、状态、已付金额和已退金额、沙盒付款的 Sandbox 标记、退款记录，以及该订单的 Midtrans notes。

退款

在 Midtrans payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Midtrans。确认提示 Refund this amount through Midtrans? This cannot be undone. 支持整数印尼盾的全额和部分退款；带小数的金额会被拒绝。您需要具有编辑订单的权限。即使订单之后被修改，您最多也只能退还 Midtrans 实际收取的金额。退款会在付款发生的环境中发送，因此该环境的 Server Key 必须已设置。Midtrans 仅允许部分付款方式和交易状态通过 API 退款（例如已结算的银行卡付款、GoPay、QRIS 或 ShopeePay 付款）。如果 Midtrans 不接受退款，区块会显示错误，且不会记录任何退款；此时请在 Midtrans 后台退款。退款成功后，会添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不改变状态。Midtrans 报告付款已结算后，退款功能才可用。

本模块不会创建退款凭证。PrestaShop 订单页面的标准退款按钮不会通过 Midtrans 退款。

在 Midtrans 后台完成的退款会通过通知到达，并自动添加到退款记录中，原因为 Refunded in the Midtrans dashboard。如果整笔付款在后台被退还，订单将变为 Refunded。

许可证密钥

本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Midtrans Payment Gateway 许可证区块是 Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure 页面的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以遮蔽形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: presta-payment-midtrans 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。

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

一个密钥只能用于一个域名：主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

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

故障排除

Midtrans does not appear at checkout：检查许可证是否有效、Enable/Disable 是否已开启，以及所选 Environment 是否已设置 Server Key。检查购物车币种是否为 IDR。在 Payment > Preferences 中，检查模块是否允许 IDR、顾客所在国家和顾客所属群组。如果缺少密钥或商店币种不是 IDR，设置页面会显示警告。

The payment went through, but no order was created：通知未正常工作。请检查您所用环境（沙盒或正式）的 Midtrans 后台是否已设置付款通知 URL，该 URL 是否与 Notification URL 中显示的完全一致，以及是否可以访问：在浏览器中打开它，应显示简短说明。开启 Debug log 以查看通知。顾客付款后返回店铺时，订单也会被创建。

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

Notification answers Server key not configured：未设置任何 Server Key。请在设置中输入；Midtrans 会重试该通知。

Notification answers Order not found — ignored：该 Midtrans 订单 ID 并非由本店铺发出，例如同一 Midtrans 账户下的其他店铺发出的。请为每家店铺设置不同的 Order ID prefix。

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

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

Notification answers Busy, please retry：购物车在同一时刻正被另一请求更新，或订单无法创建（例如模块已停用）。Midtrans 会重试该通知。请查看日志以了解原因。

The order is Midtrans payment on hold：请阅读区块中的 Midtrans notes。银行卡付款正在欺诈审核中，已付金额或币种与订单不符，或付款在订单取消后到达。

The customer sees an error when choosing Midtrans：请查看模块页面上的 Log 字段；错误始终会被记录。Server Key 有误时，会显示 Midtrans 付款暂时不可用的提示。

Refund fails：该付款方式或交易状态不允许通过 API 退款；请在 Midtrans 后台退款，退款会自动记录到订单中。如果提示说明未为订单付款所在的环境设置 Server Key，请输入该密钥后重试。

开发者可以通过 actionWcpMidtransSnapPayload 钩子修改发送给 Midtrans 的数据；订单 ID 和金额无法修改。

卸载

进入 Modules > Module Manager，打开 VibeFox Midtrans Payment Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 Midtrans 付款参考和退款，以及 Awaiting Midtrans payment 和 Midtrans payment on hold 订单状态始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。

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