状态定义

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

交易状态 (trade_state)

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

状态列表

状态码	状态名称	说明	适用渠道	是否终态
SUCCESS	支付成功	用户已完成支付,资金已到账	微信、支付宝	✅ 是
NOTPAY	未支付	订单已创建,等待用户支付	微信	❌ 否
WAIT_BUYER_PAY	等待买家付款	交易创建,等待买家付款	支付宝	❌ 否
USERPAYING	用户支付中	用户正在支付,尚未完成(如输入密码中)	微信	❌ 否
PAYERROR	支付失败	支付失败(如银行返回失败等)	微信	✅ 是
CLOSED	已关闭	订单已关闭,可能原因:超时未支付、商户主动关闭、全额退款	微信、支付宝	✅ 是
REFUND	转入退款	订单已发起退款申请	微信、支付宝	✅ 是
TRADE_FINISHED	交易结束	交易已完成,不可退款(支付宝特定状态)	支付宝	✅ 是

状态流转

stateDiagram-v2
    [*] --> NOTPAY: 创建订单(微信)
    [*] --> WAIT_BUYER_PAY: 创建订单(支付宝)
    
    NOTPAY --> USERPAYING: 用户发起支付
    WAIT_BUYER_PAY --> USERPAYING: 用户发起支付
    
    USERPAYING --> SUCCESS: 支付成功
    USERPAYING --> PAYERROR: 支付失败
    USERPAYING --> NOTPAY: 支付中断
    USERPAYING --> WAIT_BUYER_PAY: 支付中断
    
    NOTPAY --> CLOSED: 超时未支付
    WAIT_BUYER_PAY --> CLOSED: 超时未支付
    
    SUCCESS --> REFUND: 发起退款
    REFUND --> CLOSED: 全额退款完成
    
    SUCCESS --> TRADE_FINISHED: 超过退款期限(支付宝)
    
    CLOSED --> [*]
    PAYERROR --> [*]
    TRADE_FINISHED --> [*]

状态说明

终态状态

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

• SUCCESS: 支付成功,资金已到账
• CLOSED: 订单已关闭,不会再次开启
• REFUND: 已转入退款流程
• PAYERROR: 支付失败,需要重新发起支付
• TRADE_FINISHED: 交易结束,不可退款(支付宝特有)

中间态状态

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

• NOTPAY: 等待用户支付
• WAIT_BUYER_PAY: 等待买家付款(支付宝)
• USERPAYING: 用户正在支付过程中

渠道差异

微信支付

• 使用 NOTPAY 表示未支付状态
• PAYERROR 仅在付款码支付等特定场景下返回
• 不存在 TRADE_FINISHED 状态

支付宝

• 使用 WAIT_BUYER_PAY 表示未支付状态
• 存在 TRADE_FINISHED 状态,表示交易结束且不可退款
• 不存在 PAYERROR 状态

订单状态 (status)

订单状态是商户系统内部的订单状态,用于商户业务逻辑处理。

状态码	状态名称	说明
SUCCESS	支付成功	用户已完成支付,资金已到账
CLOSED	已关闭	订单已关闭,可能原因:超时未支付、商户主动关闭
REFUND	已退款	订单已全额或部分退款
PAYING	支付中	用户正在支付,尚未完成

交易状态与订单状态的映射

交易状态 (trade_state)	订单状态 (status)	说明
SUCCESS	SUCCESS	支付成功
TRADE_FINISHED	SUCCESS	交易结束(等同于支付成功)
NOTPAY	PAYING	等待支付
WAIT_BUYER_PAY	PAYING	等待付款
USERPAYING	PAYING	用户支付中
PAYERROR	CLOSED	支付失败
CLOSED	CLOSED	订单已关闭
REFUND	REFUND	已转入退款

使用建议

1. 判断支付是否成功

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

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

2. 判断订单是否可支付

// 订单可支付的条件
const canPay = ['NOTPAY', 'WAIT_BUYER_PAY'].includes(order.trade_state);

3. 处理支付结果

switch (order.trade_state) {
  case 'SUCCESS':
  case 'TRADE_FINISHED':
    // 支付成功,更新订单状态
    break;
  case 'CLOSED':
    // 订单已关闭
    break;
  case 'PAYERROR':
    // 支付失败,提示用户重新支付
    break;
  case 'REFUND':
    // 已退款
    break;
  default:
    // 其他状态,继续等待
    break;
}

注意事项

1. 优先使用 trade_state: trade_state 是支付渠道的真实状态,更准确
2. 终态判断: 只有终态状态才表示订单已完成最终处理
3. 渠道差异: 注意微信和支付宝的状态差异,做好兼容处理
4. 状态同步: 订单状态可能与交易状态存在短暂延迟,建议以 trade_state 为准
5. 退款状态: REFUND 表示已发起退款,退款是否完成需查询退款接口