{ "openapi": "3.1.0", "info": { "title": "NextAppMarket Payment API", "version": "2.4.5", "description": "Target integration contract based on 2.4.5, updated for production-only payments. Confirm capability activation. Send Payment API requests to https://pay.appconnect.cn/payment/v1. All monetary amounts use integer minor units." }, "servers": [ { "url": "https://pay.appconnect.cn/payment/v1", "description": "CN Payment API — production" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/orders": { "get": { "operationId": "findOrderByExternalOrderId", "summary": "Find an order by your business reference", "tags": [ "orders" ], "x-required-scope": "payments:read", "parameters": [ { "name": "app_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "external_order_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/findOrderByExternalOrderIdResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Exact lookup within authorized app; at most one result. Same reference with different economic input is a conflict." } }, "/orders/{order_id}": { "get": { "operationId": "getOrder", "summary": "Retrieve an order", "tags": [ "orders" ], "x-required-scope": "payments:read", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getOrderResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Authorized resource read." } }, "/refunds/{refund_id}": { "get": { "operationId": "getRefund", "summary": "Retrieve a refund", "tags": [ "refunds" ], "x-required-scope": "refunds:read", "parameters": [ { "name": "refund_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getRefundResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Authorized resource read." } }, "/orders/{order_id}/refunds": { "post": { "operationId": "createRefund", "summary": "Request a refund", "tags": [ "orders" ], "x-required-scope": "refunds:write", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "202": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createRefundResponse" } } }, "headers": { "Location": { "schema": { "type": "string", "pattern": "^/" }, "description": "Authorized resource or operation status path; accepted is not financial success." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Suggested polling delay in seconds." } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Validate actor, resource ownership and the typed command before committing. Idempotency is scoped by customer, environment, actor and domain command.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundInput" } } } } } }, "/operations/{operation_id}": { "get": { "operationId": "getOperation", "summary": "Retrieve an operation", "tags": [ "operations" ], "x-required-scope": "operations:read", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getOperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Authorized resource read." } }, "/payment-sessions": { "post": { "operationId": "createPaymentSession", "summary": "Create a payment session", "tags": [ "payment-sessions" ], "x-required-scope": "payments:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "202": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createPaymentSessionResponse" } } }, "headers": { "Location": { "schema": { "type": "string", "pattern": "^/" }, "description": "Authorized resource or operation status path; accepted is not financial success." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Suggested polling delay in seconds." } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Validate actor, resource ownership and the typed command before committing. Idempotency is scoped by customer, environment, actor and domain command.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" } } } } } }, "/orders/{order_id}/close": { "post": { "operationId": "closeOrder", "summary": "Close an unpaid order", "tags": [ "orders" ], "x-required-scope": "payments:write", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "202": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/closeOrderResponse" } } }, "headers": { "Location": { "schema": { "type": "string", "pattern": "^/" }, "description": "Authorized resource or operation status path; accepted is not financial success." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Suggested polling delay in seconds." } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Validate actor, resource ownership and the typed command before committing. Idempotency is scoped by customer, environment, actor and domain command.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } } } }, "/hms/verifications": { "post": { "operationId": "verifyHmsPurchase", "summary": "Verify an HMS purchase", "tags": [ "hms" ], "x-required-scope": "purchases:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "202": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/verifyHmsPurchaseResponse" } } }, "headers": { "Location": { "schema": { "type": "string", "pattern": "^/" }, "description": "Authorized resource or operation status path; accepted is not financial success." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Suggested polling delay in seconds." } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Validate actor, resource ownership and the typed command before committing. Idempotency is scoped by customer, environment, actor and domain command.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPurchase" } } } } } }, "/hms/verifications/{verification_id}": { "get": { "operationId": "getHmsVerification", "summary": "Retrieve an HMS verification", "tags": [ "hms" ], "x-required-scope": "purchases:read", "parameters": [ { "name": "verification_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getHmsVerificationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Authorized resource read." } }, "/hms/restorations": { "post": { "operationId": "restoreHmsPurchase", "summary": "Restore an HMS purchase", "tags": [ "hms" ], "x-required-scope": "purchases:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "202": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/restoreHmsPurchaseResponse" } } }, "headers": { "Location": { "schema": { "type": "string", "pattern": "^/" }, "description": "Authorized resource or operation status path; accepted is not financial success." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Suggested polling delay in seconds." } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "One supplied purchase evidence per request; client obtains owned purchases via HMS. No customer service state changes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPurchase" } } } } } }, "/orders/{order_id}/channel-confirmation": { "get": { "operationId": "getChannelConfirmation", "summary": "Retrieve channel confirmation", "tags": [ "orders" ], "x-required-scope": "purchases:read", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getChannelConfirmationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Authorized resource read." } }, "/orders/{order_id}/fulfillment-attestations": { "post": { "operationId": "attestHmsFulfillment", "summary": "Attest fulfillment", "tags": [ "orders" ], "x-required-scope": "purchases:write", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 191 } } ], "responses": { "202": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/attestHmsFulfillmentResponse" } } }, "headers": { "Location": { "schema": { "type": "string", "pattern": "^/" }, "description": "Authorized resource or operation status path; accepted is not financial success." }, "Retry-After": { "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "Suggested polling delay in seconds." } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Validate actor, resource ownership and the typed command before committing. Idempotency is scoped by customer, environment, actor and domain command.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentAttestation" } } } } } }, "/orders/{order_id}/payment-session": { "get": { "operationId": "getPaymentSession", "summary": "Retrieve the original payment session", "tags": [ "orders" ], "x-required-scope": "payments:read", "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } } ], "responses": { "200": { "description": "Resource or accepted operation. Accepted is not financial success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getPaymentSessionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found in authorized scope", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "409": { "description": "Version, request or state conflict", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "410": { "description": "Expired cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "422": { "description": "Business rule or capability unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } }, "503": { "description": "Authoritative dependency unavailable", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ] } } } } }, "description": "Retrieve original invocation; never create another order. Expired invocation requires authoritative channel check before any replacement attempt." } } }, "components": { "schemas": { "Meta": { "type": "object", "additionalProperties": true, "properties": { "request_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The API request correlation ID." }, "as_of": { "type": "string", "format": "date-time", "description": "The time represented by the response, in RFC 3339 format." }, "sync_lag_seconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Known reporting synchronization delay in seconds; null when unknown or not applicable." }, "data_source": { "type": "string", "enum": [ "cn", "us" ], "description": "The response source: cn for the China service or us for US reporting." } }, "required": [ "request_id", "data_source", "as_of", "sync_lag_seconds" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "enum": [ "VALIDATION_FAILED", "UNAUTHENTICATED", "SCOPE_DENIED", "RESOURCE_NOT_FOUND", "VERSION_CONFLICT", "IDEMPOTENCY_CONFLICT", "REQUEST_IN_PROGRESS", "REFUND_WINDOW_EXPIRED", "REFUND_CAPACITY_EXCEEDED", "FUNDS_UNAVAILABLE", "APPROVAL_REQUIRED", "SELF_APPROVAL_FORBIDDEN", "APPROVAL_STALE", "ADVANCE_LIMIT_EXCEEDED", "POLICY_NOT_ACCEPTED", "PRODUCTION_NOT_READY", "CAPABILITY_UNAVAILABLE", "SUBJECT_MISMATCH", "EVIDENCE_REUSED", "CURSOR_EXPIRED", "RATE_LIMITED", "AUTHORITATIVE_UNAVAILABLE", "ENDPOINT_NOT_VERIFIED", "CONFIGURATION_INCOMPLETE", "STATE_CONFLICT", "UPLOAD_INCOMPLETE", "EVIDENCE_UNAVAILABLE", "BANK_RESULT_UNVERIFIED", "SECRET_RECOVERY_EXPIRED", "AUTH_STAGE_REQUIRED", "TWO_FACTOR_INVALID", "RECENT_AUTH_REQUIRED", "TEMPORARY_PASSWORD_EXPIRED" ] }, "message": { "type": "string", "maxLength": 1024, "minLength": 1 }, "request_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The API request correlation ID." }, "retryable": { "type": "boolean", "description": "Whether the request may be retried later. Preserve the original command and idempotency key." }, "current_version": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "operation_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ], "description": "The asynchronous operation ID used to retrieve progress." }, "status_path": { "anyOf": [ { "type": "string", "pattern": "^/" }, { "type": "null" } ], "description": "The relative API path used to retrieve the resource or operation. Resolve against the assigned trusted service." }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 1024 }, "code": { "type": "string", "minLength": 1, "maxLength": 1024 }, "message": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "field", "code", "message" ] }, "minItems": 0, "maxItems": 100 } }, "required": [ "code", "message", "request_id", "retryable", "current_version", "operation_id", "status_path", "details" ] }, "Version": { "type": "object", "additionalProperties": false, "properties": { "expected_version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The resource version you most recently read, used to prevent overwriting a concurrent change." } }, "required": [ "expected_version" ] }, "CreatePayment": { "type": "object", "additionalProperties": false, "properties": { "app_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform application ID authorized by the credential." }, "amount_minor": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "currency": { "type": "string", "enum": [ "CNY" ], "description": "The three-letter uppercase currency code." }, "external_order_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your business order ID, unique within the application. Available through the Payment API; omitted from US reporting and customer webhooks." }, "description": { "type": "string", "minLength": 1, "maxLength": 128 }, "scene": { "type": "object", "additionalProperties": false, "properties": { "client_ip": { "anyOf": [ { "type": "string", "format": "ipv4" }, { "type": "string", "format": "ipv6" } ], "description": "The IP address of the customer initiating the payment." }, "return_url_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The ID of an approved return-URL configuration. Do not send an arbitrary URL." } }, "required": [], "description": "Entry-specific payment context. wechat_h5 requires client_ip and return_url_id." }, "payment_entry": { "type": "string", "enum": [ "wechat_app", "wechat_h5", "wechat_native", "alipay_app", "alipay_wap", "alipay_page", "alipay_qr" ], "description": "The payment provider and entry method, such as wechat_h5 or alipay_qr." } }, "required": [ "app_id", "payment_entry", "amount_minor", "currency", "external_order_id", "description" ], "allOf": [ { "if": { "properties": { "payment_entry": { "const": "wechat_h5", "description": "The payment provider and entry method, such as wechat_h5 or alipay_qr." } } }, "then": { "required": [ "scene" ], "properties": { "scene": { "required": [ "client_ip", "return_url_id" ], "description": "Entry-specific payment context. wechat_h5 requires client_ip and return_url_id." } } } } ] }, "Invocation": { "oneOf": [ { "$ref": "#/components/schemas/InvocationSdkString" }, { "$ref": "#/components/schemas/InvocationSdkFields" }, { "$ref": "#/components/schemas/InvocationRedirectUrl" }, { "$ref": "#/components/schemas/InvocationQrUrl" }, { "$ref": "#/components/schemas/InvocationHtmlForm" } ], "discriminator": { "propertyName": "kind" } }, "PaymentSession": { "type": "object", "additionalProperties": false, "properties": { "order": { "$ref": "#/components/schemas/CnOrder" }, "invocation": { "anyOf": [ { "$ref": "#/components/schemas/Invocation" }, { "type": "null" } ] } }, "required": [ "order", "invocation" ] }, "VerifyPurchase": { "type": "object", "additionalProperties": false, "properties": { "app_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform application ID authorized by the credential." }, "product_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform HMS product mapping ID, separate from the provider product ID." }, "client_user_id": { "type": "string", "maxLength": 191, "writeOnly": true, "minLength": 1, "description": "A stable, opaque user identifier from your application for HMS ownership verification. Processed in China; do not send names, email addresses, or phone numbers." }, "external_order_id": { "type": "string", "maxLength": 128, "minLength": 1, "description": "Your business order ID, unique within the application. Available through the Payment API; omitted from US reporting and customer webhooks." }, "purchase_evidence": { "type": "string", "maxLength": 65536, "writeOnly": true, "minLength": 1, "description": "Provider evidence serialized for the activated adapter. The HMS tutorial proposes a huawei-iap-v1 JSON wrapper; this is a target design requiring adapter implementation and a validated fixture before live use. Preserve the original signed SDK strings." } }, "required": [ "app_id", "product_id", "client_user_id", "external_order_id", "purchase_evidence" ] }, "Verification": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." }, "status": { "type": "string", "enum": [ "pending", "verified", "rejected", "unknown" ], "description": "The business state of the resource. HTTP 202 alone does not indicate completion." }, "order_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ], "description": "The platform order ID. Your business order reference is external_order_id." }, "failure_code": { "anyOf": [ { "type": "string", "maxLength": 1024, "minLength": 1 }, { "type": "null" } ], "description": "The failure classification, or null when there is no recorded failure." }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The current resource version used for concurrency control." } }, "required": [ "id", "status", "order_id", "failure_code", "version" ] }, "Refund": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." }, "app_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform application ID authorized by the credential." }, "order_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform order ID. Your business order reference is external_order_id." }, "amount_minor": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "currency": { "type": "string", "enum": [ "CNY" ], "description": "The three-letter uppercase currency code." }, "review_status": { "type": "string", "enum": [ "received", "needs_materials", "under_review", "awaiting_funds", "approved", "rejected", "cancelled" ], "description": "The refund review state, separate from provider execution." }, "execution_status": { "type": "string", "enum": [ "not_submitted", "accepted", "submitting", "processing", "unknown", "succeeded", "failed", "cancelled" ], "description": "The provider execution state. unknown means that the result is unresolved." }, "valid_received_at": { "type": "string", "format": "date-time", "description": "When the valid refund request was received, used to assess the request deadline." }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The public refund version. Advances when the request, execution, or confirmed economics change." }, "execution_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ], "description": "The provider-execution reference, or null before execution is created." }, "economics": { "type": "object", "additionalProperties": false, "properties": { "estimate": { "anyOf": [ { "$ref": "#/components/schemas/RefundEconomics" }, { "type": "null" } ] }, "actual": { "anyOf": [ { "$ref": "#/components/schemas/RefundEconomics" }, { "type": "null" } ] } }, "required": [ "estimate", "actual" ] } }, "required": [ "id", "app_id", "order_id", "amount_minor", "currency", "review_status", "execution_status", "valid_received_at", "version", "execution_id", "economics" ], "description": "The refund ID remains stable throughout review, provider execution, and economics updates. Its public version advances as these change." }, "RefundInput": { "type": "object", "additionalProperties": false, "properties": { "amount_minor": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "reason": { "type": "string", "enum": [ "customer_request", "duplicate", "fraud", "service_issue", "consumer_complaint", "other" ] }, "expected_order_version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "amount_minor", "reason", "expected_order_version" ] }, "Operation": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "manual_review" ], "description": "The business state of the resource. HTTP 202 alone does not indicate completion." }, "resource": { "anyOf": [ { "$ref": "#/components/schemas/ResourceRef" }, { "type": "null" } ] }, "failure_code": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "The failure classification, or null when there is no recorded failure." }, "created_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." }, "status_path": { "type": "string", "pattern": "^/", "description": "The relative API path used to retrieve the resource or operation. Resolve against the assigned trusted service." } }, "required": [ "id", "status", "resource", "failure_code", "created_at", "completed_at", "status_path" ] }, "ChannelConfirmation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." }, "order_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform order ID. Your business order reference is external_order_id." }, "status": { "type": "string", "enum": [ "awaiting_attestation", "pending", "confirmed", "unknown", "manual_review", "not_required" ], "description": "The business state of the resource. HTTP 202 alone does not indicate completion." }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The current resource version used for concurrency control." } }, "required": [ "id", "order_id", "status", "version" ] }, "FulfillmentAttestation": { "type": "object", "additionalProperties": false, "properties": { "expected_version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The resource version you most recently read, used to prevent overwriting a concurrent change." }, "fulfilled_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." }, "fulfillment_reference": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Your durable business fulfillment reference." } }, "required": [ "expected_version", "fulfillment_reference", "fulfilled_at" ] }, "ResourceRef": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "app", "order", "refund", "settlement", "case", "approval_case", "policy", "evidence", "credential", "webhook_endpoint", "payout_attempt", "ledger_entry", "admin_grant" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." } }, "required": [ "type", "id" ] }, "CnOrder": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." }, "app_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The platform application ID authorized by the credential." }, "environment": { "type": "string", "enum": [ "production" ], "description": "The payment environment. This edition supports production." }, "amount_minor": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "currency": { "type": "string", "enum": [ "CNY" ], "description": "The three-letter uppercase currency code." }, "status": { "type": "string", "enum": [ "pending", "processing", "unknown", "paid", "failed", "closed" ], "description": "The business state of the resource. HTTP 202 alone does not indicate completion." }, "paid_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." }, "policy_snapshot_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ], "description": "The public resource identifier." }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The current resource version used for concurrency control." }, "created_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." }, "payment_entry": { "type": "string", "enum": [ "wechat_app", "wechat_h5", "wechat_native", "alipay_app", "alipay_wap", "alipay_page", "alipay_qr", "hms_iap" ], "description": "The payment provider and entry method, such as wechat_h5 or alipay_qr." }, "paid_amount_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "refunded_amount_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "pending_refund_amount_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Refund principal reserved by valid requests and provider executions in progress. A transfer between these stages is counted once." }, "refund_request_deadline_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "A valid refund request must be received before this exclusive deadline. Null before payment." }, "external_order_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your business order ID, unique within the application. Available through the Payment API; omitted from US reporting and customer webhooks." } }, "required": [ "id", "app_id", "environment", "payment_entry", "amount_minor", "paid_amount_minor", "refunded_amount_minor", "pending_refund_amount_minor", "currency", "status", "paid_at", "refund_request_deadline_at", "policy_snapshot_id", "version", "created_at", "external_order_id" ], "description": "CN customer-server view. External reference never enters the US order projection." }, "WechatSdkFields": { "type": "object", "additionalProperties": false, "properties": { "provider": { "const": "wechat" }, "app_id": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The WeChat AppID for the native SDK invocation, separate from the platform application ID." }, "merchant_id": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The payment provider merchant identifier." }, "prepay_id": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The public resource identifier." }, "package": { "type": "string", "minLength": 1, "maxLength": 1024 }, "nonce": { "type": "string", "minLength": 1, "maxLength": 1024 }, "timestamp": { "type": "string", "pattern": "^\\d{1,20}$" }, "signature": { "type": "string", "minLength": 1, "maxLength": 1024 }, "signature_algorithm": { "type": "string", "enum": [ "RSA", "HMAC-SHA256", "MD5" ] } }, "required": [ "provider", "app_id", "merchant_id", "prepay_id", "package", "nonce", "timestamp", "signature", "signature_algorithm" ], "description": "Normalized fields; adapter maps these to selected SDK native names. Algorithm must match verified account capability, never client selection." }, "InvocationSdkString": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "sdk_string" }, "sdk_string": { "type": "string", "minLength": 1, "maxLength": 65536 }, "expires_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." } }, "required": [ "kind", "sdk_string", "expires_at" ] }, "InvocationSdkFields": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "sdk_fields" }, "sdk_fields": { "$ref": "#/components/schemas/WechatSdkFields" }, "expires_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." } }, "required": [ "kind", "sdk_fields", "expires_at" ] }, "InvocationRedirectUrl": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "redirect_url" }, "redirect_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "expires_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." } }, "required": [ "kind", "redirect_url", "expires_at" ] }, "InvocationQrUrl": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "qr_url" }, "qr_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." } }, "required": [ "kind", "qr_url", "expires_at" ] }, "InvocationHtmlForm": { "type": "object", "additionalProperties": false, "properties": { "kind": { "const": "html_form" }, "html_form": { "type": "string", "minLength": 1, "maxLength": 65536 }, "expires_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." } }, "required": [ "kind", "html_form", "expires_at" ] }, "RefundEconomics": { "type": "object", "additionalProperties": false, "properties": { "developer_principal_reversal_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "platform_principal_reversal_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "original_payment_fee_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "developer_fee_already_borne_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "developer_fee_adjustment_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "An integer in the smallest currency unit: fen for CNY or cents for USD." }, "developer_refund_cost_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Principal reversal plus signed incremental original-fee adjustment; consumer refund principal is never reduced." }, "outstanding_debt_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Debt as of calculated_at, not a live debt balance. Current outstanding debt is read from Balance." }, "policy_snapshot_id": { "type": "string", "minLength": 1, "maxLength": 40, "description": "The public resource identifier." }, "calculated_at": { "type": "string", "format": "date-time", "description": "An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai." } }, "required": [ "developer_principal_reversal_minor", "platform_principal_reversal_minor", "original_payment_fee_minor", "developer_fee_already_borne_minor", "developer_fee_adjustment_minor", "developer_refund_cost_minor", "outstanding_debt_minor", "policy_snapshot_id", "calculated_at" ] }, "findOrderByExternalOrderIdResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CnOrder" }, "maxItems": 100 }, "meta": { "$ref": "#/components/schemas/Meta" }, "next_cursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "data", "meta", "next_cursor" ] }, "getOrderResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CnOrder" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "getRefundResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Refund" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "createRefundResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Refund" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "getOperationResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Operation" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "createPaymentSessionResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentSession" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "closeOrderResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Operation" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "verifyHmsPurchaseResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Verification" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "getHmsVerificationResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Verification" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "restoreHmsPurchaseResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Verification" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "getChannelConfirmationResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ChannelConfirmation" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "attestHmsFulfillmentResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ChannelConfirmation" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "getPaymentSessionResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PaymentSession" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Server-side API key bound to the target service, application, production environment, and authorized scopes." } } }, "x-documentation-edition": "2026-10-28", "x-documentation-status": "target-contract" }