PayPal 支付状态查询响应字段调整 (2026-06-16)

接口变更

user

POST /api/orders/payment_status
- 功能：根据 paypal_order_id 查询 PayPal 支付结果，供 PayPal 返回页轮询使用。
- 变更：响应新增统一判断字段 payment_result；PayPal 远端状态字段改为 paypal_* 命名；移除容易混淆的旧字段 status、order_status、capture_status、capture_id。

接口示例

user

`POST /api/orders/payment_status`

功能说明：查询 PayPal 支付的当前结果。
变更说明：前端支付结果判断只使用 payment_result。local_order_status 和 local_session_status 只作为辅助展示、排查、兜底；不要用它们作为主要支付结果判断。

请求参数

字段	类型	必填	说明
`paypal_order_id`	`string`	是	PayPal order id，从 PayPal 返回页 URL query 中获取

请求示例

{
  "paypal_order_id": "2L146185MU803905Y"
}

响应字段

字段	类型	说明
`paypal_order_id`	`string`	PayPal order id
`payment_result`	`string`	前端应优先使用的统一支付结果：`success` / `cancelled` / `conflicted` / `failed` / `processing` / `pending`
`paypal_order_status`	`string	null`
`paypal_capture_status`	`string	null`
`paypal_capture_id`	`string	null`
`local_order_status`	`string	null`
`local_session_status`	`string	null`

响应示例：支付成功

{
  "data": {
    "paypal_order_id": "2L146185MU803905Y",
    "paypal_order_status": "completed",
    "paypal_capture_status": "completed",
    "paypal_capture_id": "9TU30802256203744",
    "local_order_status": "paying",
    "local_session_status": "pending",
    "payment_result": "success"
  }
}

响应示例：支付已取消

用户打开 PayPal 支付页后，如果在站内取消了本地支付订单，再回到 PayPal 页面完成授权，后端不会继续 capture。前端轮询本接口时会得到本地取消结果。

{
  "data": {
    "paypal_order_id": "2L146185MU803905Y",
    "paypal_order_status": null,
    "paypal_capture_status": null,
    "paypal_capture_id": null,
    "local_order_status": "cancelled",
    "local_session_status": "cancelled",
    "payment_result": "cancelled"
  }
}

响应示例：PayPal capture 处理中

{
  "data": {
    "paypal_order_id": "2L146185MU803905Y",
    "paypal_order_status": "approved",
    "paypal_capture_status": "pending",
    "paypal_capture_id": "3A384378MG7692232",
    "local_order_status": "paying",
    "local_session_status": "pending",
    "payment_result": "processing"
  }
}

响应示例：查询不到远端状态

{
  "data": {
    "paypal_order_id": "2L146185MU803905Y",
    "paypal_order_status": null,
    "paypal_capture_status": null,
    "paypal_capture_id": null,
    "local_order_status": "paying",
    "local_session_status": "pending",
    "payment_result": "pending"
  }
}

前端判断规则

前端只使用 payment_result 判断页面状态：

`payment_result`	建议展示
`success`	支付成功
`cancelled`	订单已取消，支付不会继续成功
`conflicted`	支付状态冲突，提示联系客服或等待人工处理
`failed`	支付失败，提示用户重新发起支付
`processing`	支付处理中，继续轮询或提示稍后查看
`pending`	暂无明确结果，继续轮询

前端轮询示例

async function pollPaymentStatus(paypalOrderId: string) {
  const { data } = await api.post('/api/orders/payment_status', {
    paypal_order_id: paypalOrderId,
  })

  switch (data.payment_result) {
    case 'success':
      return 'success'
    case 'cancelled':
      return 'cancelled'
    case 'conflicted':
      return 'conflicted'
    case 'failed':
      return 'failed'
    case 'processing':
    case 'pending':
    default:
      return 'retry'
  }
}

移除字段

本次不保留旧字段兼容，前端不要再读取以下字段：

旧字段	替代字段
`status`	`payment_result`
`order_status`	`paypal_order_status`
`capture_status`	`paypal_capture_status`
`capture_id`	`paypal_capture_id`

错误响应

404：找不到 PayPal checkout session，或当前用户无权查询该 session。

{
  "message": "PayPal checkout session not found"
}

422：参数校验失败。

{
  "message": "The paypal order id field is required."
}

ON THIS PAGE

#PayPal 支付状态查询响应字段调整 (2026-06-16)

#接口变更

#user

#接口示例

#user

#POST /api/orders/payment_status

#请求参数

#请求示例

#响应字段

#响应示例：支付成功

#响应示例：支付已取消

#响应示例：PayPal capture 处理中

#响应示例：查询不到远端状态

#前端判断规则

#前端轮询示例

#移除字段

#错误响应

PayPal 支付状态查询响应字段调整 (2026-06-16)

接口变更

user

接口示例

user

`POST /api/orders/payment_status`

请求参数

请求示例

响应字段

响应示例：支付成功

响应示例：支付已取消

响应示例：PayPal capture 处理中

响应示例：查询不到远端状态

前端判断规则

前端轮询示例

移除字段

错误响应