支付回调（Webhook）API

支付渠道回调接口，用于接收支付结果通知。

路由前缀：/webhook

源码：apps/backend/src/routes/payment.ts

---

认证

Webhook 接口无需用户认证，但通过签名机制验证请求来源合法性。

---

端点

1. 支付回调

POST /webhook/:provider

接收支付渠道的回调通知，验证签名后处理支付结果（更新订单状态、触发履约等）。

路径参数：

参数	类型	说明
provider	ProviderCode	支付渠道代码：paddle、yungouos、stripe、manual、mock

请求头（签名验证）：

不同渠道使用不同的签名 Header：

渠道	签名 Header
Paddle	Paddle-Signature
微信支付	X-Wechatpay-Signature
通用	X-Signature

请求体：

支持 JSON 和 application/x-www-form-urlencoded 两种格式，具体格式由支付渠道决定。原始请求体会被保留用于签名验证。

响应 200 OK：

SUCCESS

返回纯文本 SUCCESS，部分渠道要求此固定响应。

响应 500 Internal Server Error：

FAIL

回调处理失败时返回纯文本 FAIL，不暴露详细错误信息。

---

Mock 支付（开发环境）

以下接口仅在非生产环境可用，用于模拟支付流程。

路由前缀：/mock-payment

2. Mock 支付页面

GET /mock-payment/pay

返回一个模拟支付 HTML 页面，包含"支付成功"和"支付失败"按钮。

查询参数：

参数	类型	必填	说明
provider_order_id	string	是	渠道订单 ID
amount	number	否	金额（分）
currency	string	否	货币（默认 CNY）
method	string	否	支付方式
return_url	string	否	支付完成后跳转 URL（默认 /）

响应 200 OK：

返回 HTML 页面（Content-Type: text/html），用户可点击按钮模拟支付结果。

错误码：

HTTP	说明
400	Missing provider_order_id

---

3. Mock 回调触发

POST /mock-payment/callback

手动触发模拟支付回调，用于开发和测试。

请求体：

字段	类型	必填	说明
provider_order_id	string	是	渠道订单 ID
status	string	是	支付结果：success 或 failed
amount	number	否	支付金额（分）

响应 200 OK：

{
  "success": true,
  "data": {
    "success": true,
    "message": "回调处理完成",
    "orderId": "uuid"
  }
}

错误码：

HTTP	code	说明
500	INTERNAL_ERROR	处理失败