状态定义

本文档定义了支付系统中使用的所有状态码,包括交易状态、订单状态等。

交易状态 (trade_state)

交易状态用于表示订单在支付渠道中的实时状态,综合了微信支付、支付宝和云闪付的状态定义。

状态列表

状态码	状态名称	说明	是否终态
SUCCESS	支付成功	用户已完成支付,资金已到账	✅ 是
REFUND	转入退款	订单已发起退款申请	✅ 是
NOTPAY	未支付	订单已创建,等待用户支付	❌ 否
CLOSED	已关闭	订单已关闭,可能原因:超时未支付、商户主动关闭、全额退款	✅ 是
REVOKED	已撤销	仅付款码支付会返回	✅ 是
USERPAYING	用户支付中	仅付款码支付会返回,需轮询查询最终结果	❌ 否
PAYERROR	支付失败	仅付款码支付会返回	✅ 是

状态流转

状态说明

终态状态

终态状态表示订单已到达最终状态,不会再次流转:

• SUCCESS: 支付成功,资金已到账
• CLOSED: 订单已关闭,不会再次开启
• REFUND: 已转入退款流程
• REVOKED: 已撤销,仅付款码支付
• PAYERROR: 支付失败,仅付款码支付

中间态状态

中间态状态表示订单仍在处理中,可能继续流转:

• NOTPAY: 等待用户支付
• USERPAYING: 用户正在支付过程中,仅付款码支付,需轮询查询最终结果

使用建议

1. 判断支付是否成功

// 使用 trade_state 判断
if (result.data.trade_state === 'SUCCESS') {
  // 支付成功
}

2. 判断订单是否可支付

// 订单可支付的条件
const canPay = trade.trade_state === 'NOTPAY';

3. 处理支付结果

switch (trade.trade_state) {
  case 'SUCCESS':
    // 支付成功,更新订单状态
    break;
  case 'REFUND':
    // 已转入退款
    break;
  case 'NOTPAY':
    // 等待用户支付
    break;
  case 'CLOSED':
    // 订单已关闭
    break;
  case 'REVOKED':
    // 已撤销(仅付款码支付)
    break;
  case 'USERPAYING':
    // 用户支付中,需轮询(仅付款码支付)
    break;
  case 'PAYERROR':
    // 支付失败(仅付款码支付)
    break;
}

注意事项

1. 优先使用 trade_state: trade_state 是支付渠道的真实状态,更准确
2. 终态判断: 只有终态状态才表示订单已完成最终处理
3. 付款码支付: USERPAYING、PAYERROR、REVOKED 仅在付款码支付场景下返回
4. 状态同步: 交易状态可能存在短暂延迟,建议轮询确认最终状态
5. 退款状态: REFUND 表示已发起退款,退款是否完成需查询退款接口