支付通知 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"
  }'

错误

状态码示例
400Invalid 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
404User not found
405Method not allowed
409Idempotency-Key was already used with a different payload
413Request body too large(严格幂等端点)
500Failed to enqueue notification email

相关文档