> ## 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. # 创建退款 > 创建退款。`charge` 与 `payment_id` 必须二选一且不能同时传：普通支付退款传 `charge`，表示要退款的普通支付 ID；订阅退款传 `payment_id`，表示订阅账单产生的支付 ID。新建退款当前进入 `processing` 状态。 ## OpenAPI ````yaml /zh/api/refund-openapi.json post /api/v1/refunds/create 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/create: post: tags: - 退款 summary: 创建退款 description: >- 创建退款。`charge` 与 `payment_id` 必须二选一且不能同时传：普通支付退款传 `charge`，表示要退款的普通支付 ID；订阅退款传 `payment_id`，表示订阅账单产生的支付 ID。新建退款当前进入 `processing` 状态。 operationId: createRefund parameters: - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRefundRequest' examples: payment_refund: summary: 普通支付退款示例 value: charge: 2026012811010010133371000000xxxx refund_id: refund_20250101001 amount: 5000000 currency: USDT reason: requested_by_customer description: 客户申请退款 metadata: customer_id: customer_123 refund_note: 商品质量问题 subscription_refund: summary: 订阅退款示例 value: payment_id: 2026012811010010133371000000xxxx refund_id: refund_20250101002 amount: 1000000 currency: USDT reason: duplicate description: '`charge` 与 `payment_id` 必须且只能传一个；不要同时传两个字段。' responses: '201': description: 退款创建成功。 content: application/json: schema: $ref: '#/components/schemas/Refund' '400': description: 请求参数错误（如参数缺失、金额超限、订单状态不允许退款） content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 认证失败（API Key 无效或签名错误） 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' '429': description: 请求过多或超过每日退款限额 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务器错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: 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: CreateRefundRequest: type: object required: - refund_id - amount - currency properties: charge: type: string description: 普通支付退款使用。传要退款的普通支付 ID。 payment_id: type: string description: 订阅退款使用。传订阅账单产生的支付 ID。 refund_id: type: string description: 商户自定义唯一退款单号，作为幂等键。 amount: type: integer format: int64 minimum: 1 description: 退款金额，使用币种最小单位，必须大于 0。 currency: type: string enum: - USDT - USDC description: 退款币种，当前请求结构限制为 `USDT` 或 `USDC`。 reason: type: string enum: - requested_by_customer - duplicate - fraudulent - expired_uncaptured description: 退款原因。 description: type: string description: 退款说明。 refund_to_address: type: string description: 可选链上退款目标地址。 refund_to_address_id: type: integer format: int64 description: 可选链上退款目标地址 ID；仅大于 0 时生效。 metadata: type: object additionalProperties: true description: 商户自定义元数据。 description: >- `charge` 与 `payment_id` 必须二选一且不能同时传。普通支付退款使用 `charge`；订阅退款使用 `payment_id`。 oneOf: - title: 普通支付退款 required: - charge - title: 订阅退款 required: - payment_id Refund: 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: 商户自定义元数据。 invoice_id: type: string description: 订阅退款时返回的发票 ID。 subscription_id: type: string description: 订阅退款时返回的订阅 ID。 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` 为空字符串。 ````