> ## 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. # 查询退款 > 根据商户提供的 `refund_id` 获取退款详情，包含当前状态、链上交易哈希、失败原因等完整信息。 ## OpenAPI ````yaml /zh/api/refund-openapi.json get /api/v1/refunds/{refund_id} 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}: get: tags: - 退款 summary: 查询退款 description: 根据商户提供的 `refund_id` 获取退款详情，包含当前状态、链上交易哈希、失败原因等完整信息。 operationId: getRefund 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/RefundDetail' '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: RefundDetail: type: object description: 退款详情。 properties: refund_id: type: string description: 商户提供的退款单号。 payment_id: type: string description: 订阅退款场景返回的支付标识。 order_id: type: string description: 商户订单 ID，普通支付退款场景返回。 amount: type: integer format: int64 description: 退款金额，使用币种最小单位。 currency: type: string enum: - USDT - USDC description: 退款币种。 status: $ref: '#/components/schemas/RefundStatus' reason: type: string enum: - requested_by_customer - duplicate - fraudulent - expired_uncaptured description: 退款原因。 description: type: string description: 退款说明。 created_at: type: integer format: int64 description: 退款创建时间，Unix 秒。 metadata: type: object additionalProperties: true description: 商户自定义元数据。 failure_reason: type: string enum: - charge_already_refunded - insufficient_funds - expired_or_canceled_card - declined_by_bank - lost_or_stolen_card - unknown description: 失败原因，仅失败时返回。 transaction_hash: type: string description: 链上交易哈希，仅退款成功后返回。 receipt_number: type: string description: 退款凭证号。 processed_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 秒。 RefundStatus: type: string enum: - pending - processing - completed - failed - canceled description: 退款状态。新建退款当前通常返回 `processing`。 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` 为空字符串。 ````