支付通知 API
支付通知 API
XSI 本身不处理支付。接入 XPAY 等支付网关时,网关在订单事件发生后调用以下接口,由 XSI 向租户运营者或终端用户发送邮件与站内通知。这些接口只发送通知,不改变任何余额、订单或退款状态;充值入账通过《账号管理 API》完成。
认证与通用规则
- 使用管理者级 API Key:
Authorization: Bearer <key>。建议为支付网关单独创建一个账号并只在服务端保存其 Key。 - 只接受
POST,请求体为 JSON;未知字段被忽略。 - 成功响应:
200 {"success": true};重复事件返回200 {"success": true, "duplicate": true}。错误为纯文本。 - 金额字段
*_fen以“分”为单位。 - 运营者通知发送到租户配置
XAI_MAIL(未配置时使用部署的XAI_MAIL);用户通知发送到用户的Email、BillingEmail;发票通知还会发送到请求中的invoice_info.email。
端点
| 端点 | 收件人 | 幂等方式 | 关键必填字段 |
|---|---|---|---|
POST /x-notify/group-buy-formed | 运营者 | 普通 | group_id、target_count、paid_count、product_code |
POST /x-notify/group-buy-auto-refund | 运营者 | 普通 | attempted_count、orders[] |
POST /x-notify/invoice-completed | 用户(另写站内通知) | 普通 | invoice_request_id、order_id、user_id、out_trade_no、invoice_url |
POST /x-notify/digital-delivered | 用户(另写站内通知) | 普通 | order_id、user_id、out_trade_no、delivery_content(≤ 20000 字节) |
POST /x-notify/revenue-daily-report | 运营者 | 普通 | report_date、source |
POST /x-notify/fulfillment-dead | 运营者 | 严格 | source、tenant_code、fulfillment_job_id、order_id、user_id、job_type、out_trade_no、max_attempts(> 0)、last_error、dead_at;amount_fen、attempt 须非负 |
POST /x-notify/refund-reconcile-stale | 运营者 | 严格 | source、tenant_code、refund_id、order_id、user_id、out_trade_no、out_refund_no、requested_refund_fen、last_error、requested_at、detected_at |
invoice-completed 与 digital-delivered 要求 user_id 属于调用者的账号树,否则返回 403 cannot notify user outside current account tree。
幂等
普通幂等:以请求体的 idempotency_key 为事件键;省略时使用默认组合键(例如 invoice_completed:<tenant_code>:<invoice_request_id>)。同一端点、同一租户下,同一事件键 30 天内尽力去重;成功响应表示通知已入队。
严格幂等(fulfillment-dead、refund-reconcile-stale):
- 必须同时提供请求头
Idempotency-Key与请求体idempotency_key,两者一致且不超过 255 字节(UTF-8)。 - 请求体不超过 64 KiB,且不能有尾随数据。
- 同一键、相同内容返回
duplicate: true;同一键、不同内容返回409 Idempotency-Key was already used with a different payload。
示例
curl -X POST "$XSI_BASE_URL/x-notify/invoice-completed" \
-H "Authorization: Bearer $XPAY_NOTIFY_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "inv-20261118-0001",
"source": "xpay",
"tenant_code": "my-tenant",
"invoice_request_id": 1001,
"order_id": 52001,
"user_id": 42,
"out_trade_no": "T202611180001",
"amount_fen": 9950,
"invoice_url": "https://pay.example.com/invoices/1001.pdf",
"invoice_info": {"type": "normal", "company_name": "Example Ltd.", "email": "[email protected]"}
}'curl -X POST "$XSI_BASE_URL/x-notify/fulfillment-dead" \
-H "Authorization: Bearer $XPAY_NOTIFY_KEY" \
-H "Idempotency-Key: fj-889-dead" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "fj-889-dead",
"source": "xpay", "tenant_code": "my-tenant",
"fulfillment_job_id": 889, "job_type": "recharge",
"order_id": 52001, "user_id": 42, "out_trade_no": "T202611180001",
"amount_fen": 9950, "attempt": 5, "max_attempts": 5,
"last_error": "upstream timeout", "dead_at": "2026-11-18T10:00:00+08:00"
}'错误
| 状态码 | 示例 |
|---|---|
400 | Invalid JSON body、product_code is required、No system notification email configured、Idempotency-Key header and idempotency_key payload are required |
403 | 管理者权限不足;cannot notify user outside current account tree |
404 | User not found |
405 | Method not allowed |
409 | Idempotency-Key was already used with a different payload |
413 | Request body too large(严格幂等端点) |
500 | Failed to enqueue notification email |