Payment Notification API
Payment Notification API
XSI does not process payments itself. When integrated with a payment gateway such as XPAY, the gateway calls the endpoints below after order events occur, and XSI sends emails and in-app notifications to the tenant operator or the end user. These endpoints only send notifications; they never change any balance, order or refund state. Top-ups are credited through the Account Management API.
Authentication and common rules
- Use a manager-level API key:
Authorization: Bearer <key>. We recommend creating a dedicated account for the payment gateway and keeping its key on the server only. - Only
POSTis accepted, with a JSON body; unknown fields are ignored. - Success response:
200 {"success": true}; duplicate events return200 {"success": true, "duplicate": true}. Errors are plain text. - Amount fields
*_fenare in fen (1/100 CNY). - Operator notifications go to the tenant configuration's
XAI_MAIL(or the deployment'sXAI_MAILif not set); user notifications go to the user'sEmailandBillingEmail; invoice notifications are also sent toinvoice_info.emailin the request.
Endpoints
| Endpoint | Recipient | Idempotency | Key required fields |
|---|---|---|---|
POST /x-notify/group-buy-formed | Operator | Standard | group_id, target_count, paid_count, product_code |
POST /x-notify/group-buy-auto-refund | Operator | Standard | attempted_count, orders[] |
POST /x-notify/invoice-completed | User (plus an in-app notification) | Standard | invoice_request_id, order_id, user_id, out_trade_no, invoice_url |
POST /x-notify/digital-delivered | User (plus an in-app notification) | Standard | order_id, user_id, out_trade_no, delivery_content (β€ 20000 bytes) |
POST /x-notify/revenue-daily-report | Operator | Standard | report_date, source |
POST /x-notify/fulfillment-dead | Operator | Strict | source, tenant_code, fulfillment_job_id, order_id, user_id, job_type, out_trade_no, max_attempts (> 0), last_error, dead_at; amount_fen and attempt must be non-negative |
POST /x-notify/refund-reconcile-stale | Operator | Strict | 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 and digital-delivered require user_id to belong to the caller's account tree; otherwise they return 403 cannot notify user outside current account tree.
Idempotency
Standard idempotency: the idempotency_key in the request body is the event key; if omitted, a default composite key is used (e.g. invoice_completed:<tenant_code>:<invoice_request_id>). For the same endpoint and tenant, each event key is deduplicated on a best-effort basis within 30 days; a success response means the notification has been queued.
Strict idempotency (fulfillment-dead, refund-reconcile-stale):
- Both the
Idempotency-Keyrequest header and theidempotency_keybody field are required; they must match and be at most 255 bytes (UTF-8). - The request body must not exceed 64 KiB and must not contain trailing data.
- The same key with the same payload returns
duplicate: true; the same key with a different payload returns409 Idempotency-Key was already used with a different payload.
Examples
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"
}'Errors
| Status | Example |
|---|---|
400 | Invalid JSON body, product_code is required, No system notification email configured, Idempotency-Key header and idempotency_key payload are required |
403 | Insufficient manager permissions; 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 (strict idempotency endpoints) |
500 | Failed to enqueue notification email |