f

app/main/api/desc/front/pay.api

@@ -45,6 +45,10 @@ service main {
 
 	@handler PaymentCheck
 	post /pay/check (PaymentCheckReq) returns (PaymentCheckResp)
+
+	// 小程序虚拟支付：上报微信/Apple 客户端提示与步骤（写入服务端日志并可选查微信单）
+	@handler XpayClientEvent
+	post /pay/xpay/client-event (XpayClientEventReq) returns (XpayClientEventResp)
 }
 
 type (
@@ -69,6 +73,23 @@ type (
 		WxOrderStatus  int    `json:"wx_order_status,optional"`  // 微信侧订单 status
 		WxOrderDetail  string `json:"wx_order_detail,optional"`  // query_order 原始 order 摘要（排查用）
 	}
+	XpayClientEventReq {
+		OrderNo   string `json:"order_no,optional"`
+		Stage     string `json:"stage" validate:"required"` // prepay_ok, invoke, success, fail, check
+		EventType string `json:"event_type" validate:"required,oneof=info tip fail success"`
+		Message   string `json:"message,optional"` // 微信/Apple 展示给用户的话术（非 HTTP 报错）
+		ErrMsg    string `json:"err_msg,optional"`
+		ErrCode   int    `json:"err_code,optional"`
+		Errno     int    `json:"errno,optional"`
+		SignData  string `json:"sign_data,optional"`
+		Device    string `json:"device,optional"`
+		Extra     string `json:"extra,optional"`
+	}
+	XpayClientEventResp {
+		WxOrderStatus int    `json:"wx_order_status,optional"`
+		WxOrderDetail string `json:"wx_order_detail,optional"`
+		WxSyncError   string `json:"wx_sync_error,optional"`
+	}
 )
 
 type (