> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # 取消支付会话 > 取消/过期一个支付会话。当前实现会将会话标记为过期；不存在的会话会按幂等语义返回简化成功响应。 ## OpenAPI ````yaml /zh/api/openapi.json post /api/v1/checkout/sessions/{session_id}/cancel openapi: 3.1.0 info: title: StablePay 支付 API version: '2026-03-31' summary: 支付会话和支付方式查询 API。 description: >- StablePay 支付 API 的 OpenAPI 规范。 说明： - 基础 URL：https://api.stablepay.co - 认证方式：Bearer API Key + `X-StablePay-Timestamp` + `X-StablePay-Nonce` + `X-StablePay-Signature` - 签名字符串：`{timestamp}.{nonce}.{requestBody}` - 签名算法：HMAC-SHA256，小写 hex - GET 请求的 `requestBody` 为空字符串。 servers: - url: https://api.stablepay.co description: 生产环境 security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: 支付会话 description: 创建、查询和取消支付会话。 - name: 支付方式 description: 查询支付方式。 paths: /api/v1/checkout/sessions/{session_id}/cancel: post: tags: - 支付会话 summary: 取消支付会话 description: 取消/过期一个支付会话。当前实现会将会话标记为过期；不存在的会话会按幂等语义返回简化成功响应。 operationId: cancelPaymentSession parameters: - $ref: '#/components/parameters/SessionId' - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' responses: '200': description: 支付会话取消成功。 content: application/json: schema: $ref: '#/components/schemas/CancelPaymentSessionResponse' '400': description: 请求参数错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 认证失败。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 支付会话不存在或无访问权限。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务器错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: SessionId: name: session_id in: path required: true description: 支付会话 ID。 schema: type: string XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 schema: type: string example: '1735689600' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 schema: type: string example: a1b2c3d4e5f6... schemas: CancelPaymentSessionResponse: oneOf: - $ref: '#/components/schemas/PaymentSession' - type: object required: - session_id - status properties: session_id: type: string description: 支付会话 ID。 status: type: string enum: - cancelled - expired description: 幂等取消的简化状态。代码中不存在的会话会返回 `cancelled`。 ErrorResponse: type: object description: 错误响应。 properties: error: type: object properties: type: type: string description: 错误类型。 code: type: string description: 错误代码。 message: type: string description: 错误信息。 param: type: string description: 相关参数。 doc_url: type: string description: 错误文档链接。 decline_code: type: string description: 拒绝代码。 request_log_url: type: string description: 请求日志链接。 charge: type: string description: 相关支付 ID。 request_id: type: string description: 请求 ID。 timestamp: type: integer format: int64 description: 错误发生时间，Unix 秒。 PaymentSession: type: object required: - id - amount_total - currency - payment_status - created - expires_at properties: id: type: string description: 支付会话 ID。 amount_total: type: integer format: int64 description: 订单总金额，使用货币最小单位。 currency: type: string description: 商户账本币种，小写返回。 payment_status: $ref: '#/components/schemas/PaymentStatus' created: type: integer format: int64 description: 创建时间，Unix 秒。 expires_at: type: integer format: int64 description: 过期时间，Unix 秒。 url: type: string format: uri description: 收银台 URL。 line_items: type: array items: $ref: '#/components/schemas/LineItem' description: 商品明细。 tax_amount: type: integer format: int64 description: 税费金额，使用货币最小单位。 shipping_amount: type: integer format: int64 description: 运费金额，使用货币最小单位。 exchange_rate: type: string description: 存在币种转换时返回的汇率值。 target_currency: type: string description: 用户实际链上支付币种，例如 `USDT`。 target_amount_total: type: integer format: int64 description: 目标支付金额，使用目标币种最小单位。 rate_locked_at: type: integer format: int64 description: 汇率锁定时间，Unix 秒。 subscription_id: type: string description: 关联订阅 ID，仅订阅场景返回。 invoice_id: type: string description: 关联发票 ID，仅发票/订阅场景返回。 metadata: type: object additionalProperties: type: string description: 商户自定义元数据。 PaymentStatus: type: string enum: - pending - processing - paid - failed - expired - canceled description: 支付状态。`confirming` 会映射为 `processing`，`completed` 会映射为 `paid`。 LineItem: type: object required: - price_data - quantity additionalProperties: false properties: price_data: $ref: '#/components/schemas/PriceData' quantity: type: integer minimum: 1 description: 商品数量，必须大于 0。 PriceData: type: object required: - currency - unit_amount - product_data additionalProperties: false properties: currency: type: string description: 商品币种，必须与订单 `currency` 一致。 unit_amount: type: integer format: int64 minimum: 1 description: 商品单价，使用货币最小单位。 product_data: $ref: '#/components/schemas/ProductData' ProductData: type: object required: - name additionalProperties: false properties: name: type: string description: 商品名称，不能为空。 description: type: string description: 商品描述。 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key，例如 `Bearer sk_live_xxx`。 stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 ````