{ "openapi": "3.1.0", "info": { "title": "u积分 商户 API", "version": "1.3.0", "description": "Merchant Bearer API. 120 requests/minute per merchant. Points use six decimals. Signed order.paid/order.refunded webhooks with retries; query latest order before idempotent fulfilment. Refunds require logged-in merchant web dashboard confirmation. No API refunds or API withdrawals. Refund status fields and order.refunded webhooks remain available." }, "servers": [ { "url": "/api/merchant/v1", "description": "当前平台域名；生产需 HTTPS" } ], "security": [ { "MerchantKey": [] } ], "paths": { "/account": { "get": { "summary": "查询商户和共用积分账户余额", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getAccount" } }, "/orders": { "post": { "summary": "幂等创建积分收款订单", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "createOrder", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "为业务订单持久化的 UUID，同参数重试必须相同" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrder" }, "example": { "outTradeNo": "SHOP-001", "title": "示例商品", "amount": "1.250001", "expiresInSeconds": 1800 } } } } }, "get": { "summary": "倒序分页查询订单", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "listOrders", "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "上一页 nextBefore；每页最多 50 条" }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Trimmed search. Exact platform ID or payment/refund reference; substring external order number/title. Wildcards are literal." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "paid", "refunded", "cancelled", "expired" ] } }, { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "description": "Inclusive createdAt Unix seconds." }, { "name": "to", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "description": "Exclusive createdAt Unix seconds; greater than from when both set." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shop", "api" ] }, "description": "订单来源筛选；不传返回全部来源。" } ] } }, "/orders/{id}": { "get": { "summary": "按平台 UUID 查询自己的订单", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/orders/by-number/{outTradeNo}": { "get": { "summary": "按商户订单号查询", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getOrderByNumber", "parameters": [ { "name": "outTradeNo", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" } } ] } }, "/orders/{id}/cancel": { "post": { "summary": "取消 pending 订单；重复取消幂等", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "cancelOrder", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } } } }, "/webhook": { "get": { "summary": "Read configuration; never returns secret", "operationId": "getWebhook", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Webhook encryption secret not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "CAS configuration; effective changes cancel undelivered events; identical saves keep version and events", "operationId": "saveWebhook", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSaved" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Webhook encryption secret not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } } } }, "/webhook/events": { "get": { "summary": "List own delivery records, newest first, up to 50", "operationId": "listWebhookEvents", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Webhook encryption secret not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } ] } }, "/webhook/events/{eventId}": { "get": { "summary": "Read event snapshot and last 50 delivery attempts", "operationId": "getWebhookEvent", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDetail" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Webhook encryption secret not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$" } } ] } }, "/webhook/events/{eventId}/retry": { "post": { "summary": "Retry failed event on current enabled configuration; pending is idempotent; 10/minute", "operationId": "retryWebhookEvent", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Webhook encryption secret not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$" } } ] } }, "/orders/summary": { "get": { "summary": "Exact receipts, refunds and net totals across all filtered orders", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSummary" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "orderSummary", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Trimmed search. Exact platform ID or payment/refund reference; substring external order number/title. Wildcards are literal." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "paid", "refunded", "cancelled", "expired" ] } }, { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "description": "Inclusive createdAt Unix seconds." }, { "name": "to", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "description": "Exclusive createdAt Unix seconds; greater than from when both set." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shop", "api" ] }, "description": "订单来源筛选；不传返回全部来源。" } ] } }, "/orders/{id}/detail": { "get": { "summary": "Own order with original payer ID and associated webhook delivery summaries", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetail" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getOrderDetail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/orders/export": { "get": { "summary": "Export filtered orders to UTF-8 BOM CSV (up to 5000; 5 per minute)", "responses": { "200": { "description": "成功", "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" }, "description": "本次请求诊断编号" }, "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\"merchant-orders.csv\"" } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "参数不正确、余额不足或容量超限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "密钥无效或撤销", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "商户停用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "订单或接口不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "幂等冲突或状态不允许", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "每商户每分钟 120 次限流", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "内部错误，保留原参数查询后重试", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "exportOrders", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Trimmed search. Exact platform ID or payment/refund reference; substring external order number/title. Wildcards are literal." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "paid", "refunded", "cancelled", "expired" ] } }, { "name": "from", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "description": "Inclusive createdAt Unix seconds." }, { "name": "to", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 253402300799 }, "description": "Exclusive createdAt Unix seconds; greater than from when both set." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "shop", "api" ] }, "description": "订单来源筛选；不传返回全部来源。" } ], "description": "No cursor; all filtered results. Returns 400/export_limit above 5000, never truncates. Quotes and line breaks escaped; formula-like cells prefixed with apostrophe. Import IDs and amounts as text in spreadsheets. Counts against both 5 exports/min and merchant 120 requests/min." } } }, "components": { "securitySchemes": { "MerchantKey": { "type": "http", "scheme": "bearer", "bearerFormat": "um_live_<64 hex characters>", "description": "商户中心创建，服务端保存，支持撤销" } }, "schemas": { "Order": { "type": "object", "required": [ "id", "cursor", "merchantId", "outTradeNo", "title", "amount", "amountMicros", "currency", "status", "checkoutUrl", "paymentReference", "refundReference", "createdAt", "expiresAt", "paidAt", "refundedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "cursor": { "type": "string", "pattern": "^[0-9]+$" }, "merchantId": { "type": "string", "format": "uuid" }, "outTradeNo": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{6}$" }, "amountMicros": { "type": "string", "pattern": "^[0-9]+$" }, "currency": { "const": "POINTS" }, "status": { "type": "string", "enum": [ "pending", "paid", "cancelled", "expired", "refunded" ] }, "checkoutUrl": { "type": "string", "format": "uri" }, "paymentReference": { "type": [ "string", "null" ], "format": "uuid" }, "refundReference": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "paidAt": { "type": [ "integer", "null" ] }, "refundedAt": { "type": [ "integer", "null" ] }, "source": { "type": "string", "enum": [ "shop", "api" ], "description": "订单来源：shop 为商城订单，api 为 API/商户收款订单；按商城购买记录关联判断。" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Only present for shop orders: purchased item count." }, "unitAmountMicros": { "type": "string", "pattern": "^[0-9]+$", "description": "Only present for shop orders: unit price snapshot in integer micro points; amountMicros is the full order total." } } }, "CreateOrder": { "type": "object", "required": [ "outTradeNo", "title", "amount" ], "properties": { "outTradeNo": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "amount": { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,6})?$" }, "expiresInSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 1800 } }, "additionalProperties": false }, "Account": { "type": "object", "required": [ "merchantId", "name", "status", "balanceMicros", "reservedMicros", "currency", "decimals" ], "properties": { "merchantId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "balanceMicros": { "type": "string", "pattern": "^[0-9]+$" }, "reservedMicros": { "type": "string", "pattern": "^[0-9]+$" }, "currency": { "const": "POINTS" }, "decimals": { "const": 6 } } }, "OrderList": { "type": "object", "required": [ "data", "nextBefore" ], "properties": { "data": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Order" } }, "nextBefore": { "type": [ "string", "null" ] } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } } } } }, "Empty": { "type": "object", "additionalProperties": false }, "WebhookConfig": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": [ "string", "null" ], "format": "uuid" }, "updatedAt": { "type": [ "integer", "null" ] } }, "required": [ "url", "enabled", "version", "updatedAt" ] }, "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "enabled": { "type": "boolean" }, "version": { "type": [ "string", "null" ], "format": "uuid" }, "rotateSecret": { "type": "boolean", "default": false } }, "required": [ "url", "enabled", "version" ], "additionalProperties": false }, "WebhookSaved": { "allOf": [ { "$ref": "#/components/schemas/WebhookConfig" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Returned once on first configuration, URL change or rotation. Use entire whsec_ string as HMAC key." } }, "required": [] } ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$" }, "type": { "type": "string", "enum": [ "order.paid", "order.refunded" ] }, "createdAt": { "type": "integer" }, "merchantId": { "type": "string", "format": "uuid" }, "apiVersion": { "type": "string", "const": "2026-11-04" }, "data": { "type": "object", "required": [ "id", "merchantId", "outTradeNo", "title", "amount", "amountMicros", "currency", "status", "paymentReference", "refundReference", "createdAt", "expiresAt", "paidAt", "refundedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "merchantId": { "type": "string", "format": "uuid" }, "outTradeNo": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{6}$" }, "amountMicros": { "type": "string", "pattern": "^[0-9]+$" }, "currency": { "const": "POINTS" }, "status": { "type": "string", "enum": [ "pending", "paid", "cancelled", "expired", "refunded" ] }, "paymentReference": { "type": [ "string", "null" ], "format": "uuid" }, "refundReference": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "paidAt": { "type": [ "integer", "null" ] }, "refundedAt": { "type": [ "integer", "null" ] } } } }, "required": [ "id", "type", "createdAt", "merchantId", "apiVersion", "data" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$" }, "cursor": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "order.paid", "order.refunded" ] }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer" }, "totalAttempts": { "type": "integer" }, "nextAttemptAt": { "type": [ "integer", "null" ] }, "lastHttpStatus": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "deliveredAt": { "type": [ "integer", "null" ] } }, "required": [ "id", "cursor", "orderId", "type", "url", "status", "attempts", "totalAttempts", "nextAttemptAt", "lastHttpStatus", "lastError", "createdAt", "deliveredAt" ] }, "WebhookList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "nextBefore": { "type": [ "string", "null" ] } }, "required": [ "data", "nextBefore" ] }, "WebhookAttempt": { "type": "object", "properties": { "attempt": { "type": "integer" }, "startedAt": { "type": "integer" }, "finishedAt": { "type": [ "integer", "null" ] }, "httpStatus": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "attempt", "startedAt", "finishedAt", "httpStatus", "error" ] }, "WebhookDetail": { "allOf": [ { "$ref": "#/components/schemas/WebhookDelivery" }, { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/WebhookEvent" }, "deliveryAttempts": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/WebhookAttempt" } } }, "required": [ "event", "deliveryAttempts" ] } ] }, "OrderSummary": { "type": "object", "properties": { "totalOrders": { "type": "integer", "minimum": 0 }, "counts": { "type": "object", "properties": { "pending": { "type": "integer", "minimum": 0 }, "paid": { "type": "integer", "minimum": 0 }, "cancelled": { "type": "integer", "minimum": 0 }, "expired": { "type": "integer", "minimum": 0 }, "refunded": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "paid", "cancelled", "expired", "refunded" ] }, "paidAmountMicros": { "type": "string", "pattern": "^[0-9]+$" }, "refundedAmountMicros": { "type": "string", "pattern": "^[0-9]+$" }, "netAmountMicros": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "totalOrders", "counts", "paidAmountMicros", "refundedAmountMicros", "netAmountMicros" ], "description": "All filtered orders, independent of before. paidAmountMicros includes refunded originals; net subtracts refunds, not transfers/withdrawals. Exact integer strings, possibly above safe integer. Filtered by creation time, not payment time. Reads may change during concurrent trading." }, "OrderDetail": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "type": "object", "properties": { "payerAccountId": { "type": [ "string", "null" ], "description": "Original platform payer account ID, not email; null before payment." }, "webhookEvents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$" }, "type": { "type": "string", "enum": [ "order.paid", "order.refunded" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed", "cancelled" ] }, "totalAttempts": { "type": "integer" }, "lastHttpStatus": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "deliveredAt": { "type": [ "integer", "null" ] } }, "required": [ "id", "type", "status", "totalAttempts", "lastHttpStatus", "lastError", "createdAt", "deliveredAt" ] } } }, "required": [ "payerAccountId", "webhookEvents" ] } ] } } }, "webhooks": { "merchantOrderEvent": { "post": { "summary": "Order paid or fully refunded", "description": "HTTPS POST to configured allowlisted host, no redirects. HMAC-SHA256 over UTF-8 timestamp + dot + exact raw body, key is entire whsec_ secret. X-UPoints-Signature=v1=. Verify <=300s clock skew; match header ID to body ID; persist inbox before 2xx, deduplicate event.id, query current order before business action. At-least-once and unordered. First send plus 7 retries after 60/300/900/3600/10800/21600/43200 seconds, subject to minute Cron/backlog. Stable body and ID; fresh timestamp/signature on each send.", "security": [], "parameters": [ { "in": "header", "name": "X-UPoints-Event-ID", "required": true, "schema": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$" } }, { "in": "header", "name": "X-UPoints-Timestamp", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{1,12}$" } }, { "in": "header", "name": "X-UPoints-Signature", "required": true, "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "204": { "description": "Persisted successfully, including duplicates. Any 2xx accepted." }, "default": { "description": "Retry on non-2xx, timeout or network error. Response body ignored." } } } } } }