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 POST is accepted, with a JSON body; unknown fields are ignored.
  • Success response: 200 {"success": true}; duplicate events return 200 {"success": true, "duplicate": true}. Errors are plain text.
  • Amount fields *_fen are in fen (1/100 CNY).
  • Operator notifications go to the tenant configuration's XAI_MAIL (or the deployment's XAI_MAIL if not set); user notifications go to the user's Email and BillingEmail; invoice notifications are also sent to invoice_info.email in the request.

Endpoints

EndpointRecipientIdempotencyKey required fields
POST /x-notify/group-buy-formedOperatorStandardgroup_id, target_count, paid_count, product_code
POST /x-notify/group-buy-auto-refundOperatorStandardattempted_count, orders[]
POST /x-notify/invoice-completedUser (plus an in-app notification)Standardinvoice_request_id, order_id, user_id, out_trade_no, invoice_url
POST /x-notify/digital-deliveredUser (plus an in-app notification)Standardorder_id, user_id, out_trade_no, delivery_content (≀ 20000 bytes)
POST /x-notify/revenue-daily-reportOperatorStandardreport_date, source
POST /x-notify/fulfillment-deadOperatorStrictsource, 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-staleOperatorStrictsource, 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-Key request header and the idempotency_key body 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 returns 409 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

StatusExample
400Invalid JSON body, product_code is required, No system notification email configured, Idempotency-Key header and idempotency_key payload are required
403Insufficient manager permissions; 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 (strict idempotency endpoints)
500Failed to enqueue notification email