VibeFox Midtrans for WooCommerce — 帮助
系统要求
WordPress：6.0 或更高版本。
WooCommerce：8.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法激活。
PHP：8.0 或更高版本。
店铺币种：印尼盾（IDR）。使用其他币种时，结账页面会隐藏该付款方式。不进行币种转换。
Midtrans 账户：您需要从 Midtrans Dashboard > Settings > Access Keys 获取 Server Key，分别在 Sandbox 后台和正式后台获取。仅使用 Server Key。Snap Redirect 不需要 Client Key。付款方式本身（GoPay、QRIS、虚拟账户等）需在您的 Midtrans 账户中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥仅适用于一个域名。
安装
1. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_midtrans_payment_gateway 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 将店铺币种设置为印尼盾（IDR）。
4. 打开设置：WooCommerce > Settings > Payments > Midtrans > Manage，或在插件列表页点击插件名称下方的 Settings。
5. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
6. 输入 Server Key，并将付款通知 URL 复制到 Midtrans 后台（参见「配置」）。
7. 开启 Enable/Disable。先在 Sandbox 中测试，然后将 Environment 切换为 Production。
配置
所有设置都位于同一页面：WooCommerce > Settings > Payments > Midtrans。页面在字段上方会提示：所选环境缺少 Server Key 时（此时该付款方式在结账时会被隐藏）、店铺币种不是 IDR 时，并且在选择 Sandbox 时显示 Sandbox mode: payments are simulated, no real money is charged.。在付款方式列表中，Midtrans 在输入 Server Key 之前会标记为「需要设置」，并在 Sandbox 中显示 Test mode。
常规
Enable/Disable：Enable Midtrans payments 用于启用或禁用该付款方式。默认：off。
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。该部分提供正式和 Sandbox 后台的链接。
Environment：新付款使用的 Midtrans 环境。切换后会使用所选环境的密钥和 API。订单会保留其付款时所用的环境，用于退款和通知。默认：Sandbox。
Production Server Key：以 Mid-server- 开头。请妥善保密。
Sandbox Server Key：以 SB-Mid-server- 开头。
付款通知 URL
通知会告知您的店铺付款已完成。该部分显示需要使用的 URL，格式类似：https://your-site/wc-api/midtrans_p_callback/。请将其粘贴到您所使用的 Sandbox 和正式后台中的 Midtrans Dashboard > Settings > Payment > Notification URL。如果在浏览器中打开该 URL，会显示一段简短说明，您可借此确认其可以访问。Midtrans 后台中的 Test notification URL 按钮同样会得到响应。
每条通知都必须带有使用您某个 Server Key 生成的有效签名，并且密钥所属环境必须与订单环境一致。签名无效的通知会被拒绝。随后会从 Midtrans 状态 API 重新读取状态。插件会处理以下 Midtrans 交易状态：
若未设置付款通知 URL，只有在顾客付款后返回店铺时，订单才会被确认。
付款设置
Midtrans 仅以 IDR 收款，金额以整数印尼盾发送。若订单明细之和与四舍五入后的总额不符，会向 Midtrans 发送一行 Rounding adjustment。
Status after payment：付款确认后的订单状态。状态一次性设置，不会重复向顾客发送邮件。
Payment page expiry (minutes)：顾客可以付款的时长（Snap 页面、虚拟账户等）。留空或填 0 则使用 Midtrans 默认值。
Order ID prefix：添加到发送给 Midtrans 的订单号前，以便多家店铺共用一个 Midtrans 账户。仅允许字母、数字以及 - _ . ~，最多 20 个字符；保存时会删除其他字符。其他店铺的通知会被忽略。默认：WC-。
高级
Debug log：Log API calls and notifications 会写入 WooCommerce > Status > Logs，来源为 wcp_midtrans_payment_gateway。错误始终会被记录。密钥和顾客数据绝不会被记录。默认：off。
Delete data on uninstall：Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. 默认：off。
结账
顾客选择付款方式（默认为 Midtrans）并提交订单。插件会以整数印尼盾为订单总额创建 Midtrans Snap 交易，并附带订单明细、运费、税费以及顾客的账单和收货信息，然后将顾客引导至 Midtrans 付款页面。在该页面，顾客可选择您 Midtrans 账户中启用的任意付款方式。
付款完成后，顾客会返回您店铺的订单接收页面。返回链接本身绝不会将订单标记为已付款：插件会查询 Midtrans 状态 API，只有在 Midtrans 确认后才会将订单标记为已付款。在付款未确认期间，页面会显示 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.，并同时显示所使用的付款方式。
若付款未完成，顾客会被引导至 Pay for order 页面，并显示 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 已付款，则订单被确认，不会创建新交易。
若 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 返回的原因。技术原因会添加到订单备注中。
该付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。
插件仅使用 Snap Redirect。没有 Snap 弹窗、您网站上的银行卡表单、保存的银行卡或一键付款、分期或促销设置（付款方式请在 Midtrans 后台配置），也不支持 WooCommerce 订阅。银行卡付款会立即扣款，没有单独的授权与扣款。
订单与退款
订单状态
Pending payment：顾客已被引导至 Midtrans，但尚未选择付款方式。
On hold：顾客选择了延迟付款方式且尚未付款，银行卡付款正在欺诈审核（challenge）中，或已付金额或币种与订单不符。若取消订单后又收到付款，也会设为「保留」；订单不会自动重新开启。订单备注会说明原因。
Processing, Completed or On hold after payment：付款已确认。状态依据 Status after payment 设置。订单备注会显示付款方式和 Midtrans ID。交易 ID 即 Midtrans 交易 ID，在订单页面中会链接到该订单所在环境的 Midtrans 后台交易。
Failed：付款失败，或处于 challenge 的银行卡付款被拒绝。
Cancelled：未付款的交易已过期或被取消。库存退还。当您在 WooCommerce 中取消未付款的 Midtrans 订单时（或未付款订单计时器自动取消时），其待处理的 Midtrans 交易（例如已生成的虚拟账户）会被设为过期，从而无法再被支付。
若已付款订单又收到第二笔付款，订单不会再次被更改。备注会提示您在 Midtrans 后台退还第二笔付款。针对已退款订单的付款仅添加备注。
退款
打开订单，点击 Refund，输入金额后点击 Refund via Midtrans（按钮上会显示您的 Title）。支持以整数印尼盾进行全额和部分退款；带小数的金额会被拒绝。退款会在订单付款时所在的环境中发送，因此该环境的 Server Key 必须已设置。Midtrans 仅对部分付款方式和交易状态允许通过 API 退款（例如已结算的银行卡、GoPay、QRIS 或 ShopeePay 付款）。若 Midtrans 不接受退款，WooCommerce 会显示错误且不会记录退款；此时请在 Midtrans 后台退款。成功退款会添加到订单备注中。
在 Midtrans 后台完成的退款会通过通知到达，并自动记录为 WooCommerce 退款，原因为 Refunded in the Midtrans dashboard。
许可证密钥
本插件需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Midtrans 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥并不会释放该域名的名额，请在您的 vibefox.net 账户中释放名额。
若没有有效密钥，Midtrans 不会在结账时向顾客显示。若仍发起了付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍能看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件列表页和 WooCommerce 页面会显示提醒。已有订单不受影响：已发起的付款仍会被确认，退款也照常工作。
许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。
故障排除
结账时不显示 Midtrans：请检查许可证是否有效、Enable/Disable 是否已开启，以及所选 Environment 是否已填写 Server Key。请检查店铺币种（或 Pay for order 页面上的订单币种）是否为 IDR。设置页面会针对上述每个问题显示警告。
付款已成功，但订单仍为 Pending payment：通知未正常工作。请检查所用环境（Sandbox 或正式）的 Midtrans 后台中是否已设置付款通知 URL，并确认其可以访问：在浏览器中打开该 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 会重试该通知。
订单处于 On hold：请阅读订单备注。顾客尚未完成延迟付款，或银行卡付款正在欺诈审核，或已付金额或币种与订单不符。
顾客下单时出现错误：查看订单备注，或开启 Debug log 并在 WooCommerce > Status > Logs 中查看来源 wcp_midtrans_payment_gateway。非 IDR 订单会显示 Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
退款失败：该付款方式或交易状态不允许通过 API 退款；请在 Midtrans 后台退款，退款会自动记录到 WooCommerce 中。若提示未为该订单付款所在的环境配置 Server Key，请填入该密钥后重试。
许可证区块显示错误：请按区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活该密钥。若无法连接许可证服务器，插件会沿用最后一次已知的状态继续运行。
卸载
停用插件会保留所有数据。如需移除，请先停用，再在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置和日志仅在开启 Delete data on uninstall 时才会被删除，否则会保留，以便日后重新安装。已有订单会保留其付款备注和交易 ID。
Midtrans 是其各自所有者的商标。本插件与 Midtrans 无关联，也未获得 Midtrans 的认可。