支付平台显示交易成功，Magento 2 订单却一直停在 Pending，客服不敢发货，客户还可能重复支付。处理这类问题的第一原则是先核对真实资金状态，再决定订单如何恢复，不能直接把数据库 status 改成 processing。

先区分授权成功还是捕获成功

Authorize Only 只冻结或授权金额，Magento 订单可能仍等待后续 Capture；Authorize and Capture 通常在付款成功后生成发票并进入 Processing。支付平台界面中的“成功”可能代表 authorization、capture 或已结算，必须查看具体 transaction type。

后台订单 Payment Information 与 sales_payment_transaction 中的交易记录可以帮助判断：

SELECT transaction_id, parent_txn_id, txn_id, txn_type,
       is_closed, created_at
FROM sales_payment_transaction
WHERE order_id=100001
ORDER BY transaction_id;

不要把真实卡号、签名密钥或完整网关响应输出到日志。

异步支付依赖 Webhook 或 Return URL

客户浏览器跳回成功页不等于服务器已经确认付款。可靠集成通常由支付平台向 Magento Webhook 发送服务器回调。检查回调 URL 的状态码、签名校验、事件 ID 和重试记录。WAF、Basic Auth、维护模式或错误 Base URL 都可能让支付平台无法访问。

如果支付平台多次重试同一事件，Magento handler 必须幂等。同一个 capture 事件不能重复开票；已处理事件应安全返回成功，而不是再次改变订单。

交易匹配失败时回调找不到订单

支付请求中的 merchant reference、increment_id、quote_id 或自定义 metadata 必须能唯一找到订单。多 Store 使用相同显示订单号、自定义编号被修改，或回调只传了旧 quote 引用，都可能导致“支付成功但无订单可更新”。

关联时优先使用网关 transaction ID 与内部保存的引用，不要只按客户邮箱和金额猜测。人工恢复前确认这笔支付没有已经关联到另一订单。

状态标签和内部 state 必须正确映射

支付模块可能把成功事件设置为自定义 status，但该 status 错误绑定在 new state，后台仍表现为 Pending。Magento 的 state 控制可开票、发货、取消等能力，status 主要用于业务展示。修正配置和代码后让服务层执行状态转换，不要只改标签。

故障恢复要防止二次扣款和重复发票

如果资金已捕获，先阻止客户再次支付，核对金额、币种、订单和网关交易；然后通过支付模块提供的同步或 webhook replay 功能恢复。没有安全工具时，应在测试环境验证恢复流程并保留审计记录。

最终测试至少覆盖授权、捕获、支付拒绝、Webhook 延迟、重复 Webhook 和客户未返回网站。每种情况都应得到唯一订单、唯一交易和可解释的 state/status，邮件与库存也要随正确事件发生。