> ## 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.

# 取消退款

> 取消当前仍处于 `processing` 状态的退款。已完成、失败或已取消的退款不能再取消。



## OpenAPI

````yaml /zh/api/refund-openapi.json post /api/v1/refunds/{refund_id}/cancel
openapi: 3.1.0
info:
  title: StablePay 退款 API
  version: '2026-04-14'
  summary: StablePay 退款相关接口：创建退款、查询退款、取消退款。
  description: >-
    StablePay 退款接口的 OpenAPI 规范。


    ## 认证方式


    所有接口均需同时携带 **Bearer API Key** 与 **签名请求头**：


    - `Authorization: Bearer {api_key}`

    - `X-StablePay-Timestamp`: Unix 时间戳（秒）

    - `X-StablePay-Nonce`: 随机字符串，建议使用 UUID，用于防重放

    - `X-StablePay-Signature`: HMAC-SHA256 签名


    ## 签名规则


    签名字符串格式：`{timestamp}.{nonce}.{requestBody}`


    - `POST` 请求：`requestBody` 为原始 JSON 字符串

    - `GET` 请求：`requestBody` 为空字符串


    使用商户 API Secret 对签名字符串进行 HMAC-SHA256 运算，输出 16 进制小写字符串作为
    `X-StablePay-Signature`。


    ## 金额精度


    所有金额字段均使用最小精度单位表示（USDT/USDC 统一为 6 位精度，即 1 USDT = 1000000）。
servers:
  - url: https://api.stablepay.co
    description: 生产环境
security:
  - bearerAuth: []
    stablepayTimestamp: []
    stablepayNonce: []
    stablepaySignature: []
tags:
  - name: 退款
    description: 创建、查询和取消退款。
paths:
  /api/v1/refunds/{refund_id}/cancel:
    post:
      tags:
        - 退款
      summary: 取消退款
      description: 取消当前仍处于 `processing` 状态的退款。已完成、失败或已取消的退款不能再取消。
      operationId: cancelRefund
      parameters:
        - $ref: '#/components/parameters/RefundId'
        - $ref: '#/components/parameters/XStablePayTimestamp'
        - $ref: '#/components/parameters/XStablePayNonce'
        - $ref: '#/components/parameters/XStablePaySignature'
      responses:
        '200':
          description: 退款取消成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundCancellation'
        '400':
          description: 请求错误或当前状态不允许取消
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 认证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          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:
    RefundId:
      name: refund_id
      in: path
      required: true
      description: 商户创建退款时提供的唯一退款 ID。
      schema:
        type: string
      example: refund_20250101001
    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:
    RefundCancellation:
      type: object
      required:
        - refund_id
        - status
        - canceled_at
      properties:
        refund_id:
          type: string
          description: 商户提供的退款单号。
        status:
          type: string
          enum:
            - canceled
        canceled_at:
          type: integer
          format: int64
          description: 取消时间，Unix 秒。
    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 秒。
  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` 为空字符串。

````