> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建退款

> 对银行卡订单全额或部分退款。

请使用属于目标组织、且为全部权限或勾选了 `sales:refunds:execute` 权限的 API 密钥进行认证。只有 `Owner`、`Admin` 和 `Finance` 角色可以授予该权限。

* 仅在 Anyway 为你的组织开通 API 退款后可用，请[联系 Anyway 支持](mailto:support@anyway.sh)开通。开通前，无论使用哪种密钥，对你的订单发起的退款都返回 `403` `REFUND_API_NOT_ENABLED`。订单本身的错误（如订单不存在时的 `404`）会先返回。
* 输入与控制台订单上的退款按钮相同。省略 `amountCents` 即退还订单剩余可退的全部金额。`reason` 可选：`duplicate`、`fraudulent` 或 `requested_by_customer`。币种始终为订单币种。
* 请发送唯一的 `Idempotency-Key` 请求头（必填；1–200 个 ASCII 字符，范围 `0x21` 到 `0x7E`，不含空格）。相同密钥和相同请求体返回同一笔退款，不会重复退款。相同密钥搭配不同的订单、金额或原因返回 `409`。
* 仅支持 90 天内的银行卡订单。更早的订单请联系 Anyway 支持。
* `200` 且 `status` 为 `succeeded` 表示退款已完成。`202` 且 `status` 为 `pending` 表示退款在等待 Anyway 审核或卡组织处理。当这笔退款使订单累计退款金额达到审核阈值或以上，或使你的组织超出每日退款限额（与控制台退款共用）时，需要审核；同一订单同一时间只能有一笔退款在等待审核。请使用相同的 `Idempotency-Key` 重试以获取最新状态，或等待 `refund.succeeded` 或 `refund.failed` [Webhook](https://docs.anyway.sh/zh/api-reference/endpoint/webhooks.md)。
* 响应与[查看退款](https://docs.anyway.sh/zh/api-reference/endpoint/get-refund.md)返回的退款对象相同。通过 API 发起的退款也会显示在控制台的订单上。

| 状态码 | 错误码 | 含义 |
| - | - | - |
| `400` | `BAD_REQUEST` | 缺少或无效的 `Idempotency-Key`、未知字段、金额小于等于 0，或 `reason` 无效。 |
| `400` | `REFUND_AMOUNT_TOO_LARGE` | `amountCents` 超过订单剩余可退金额。 |
| `400` | `REFUND_NOT_REFUNDABLE` | 省略了 `amountCents`，且订单已没有可退金额。 |
| `400` | `REFUND_UNSUPPORTED_METHOD` | 订单不是银行卡支付。 |
| `400` | `REFUND_WINDOW_EXPIRED` | 订单已超过 90 天。 |
| `400` | `amount_too_large`、`charge_already_refunded` 或 `charge_disputed` | 发卡网络拒绝：金额超过剩余可退金额、已全额退款或存在争议。 |
| `401` | | API 密钥缺失或无效。 |
| `403` | `INSUFFICIENT_SCOPE` | 密钥缺少 `sales:refunds:execute`。 |
| `403` | `REFUND_API_NOT_ENABLED` | 你的组织未开通 API 退款。请联系 Anyway 支持。 |
| `404` | | 订单 ID 不存在，或属于其他组织。 |
| `409` | `REFUND_PENDING_EXISTS` | 该订单上另一笔退款正在等待审核。 |
| `409` | `REFUND_IDEMPOTENCY_MISMATCH` | 该 `Idempotency-Key` 已用于不同的订单、金额或原因。 |
| `409` | `REFUND_FAILED` 或 `REFUND_REJECTED` | 该 `Idempotency-Key` 对应的退款已失败或被拒绝。请使用新的密钥重试。 |
| `503` | `REFUND_UNAVAILABLE` | 支付服务商繁忙或不可用，或这笔退款仍在处理中。请使用相同的 `Idempotency-Key` 重试。 |


## OpenAPI

````yaml api-reference/openapi.json POST /v1/refunds
openapi: 3.0.3
info:
  description: >-
    Organization-scoped commerce API for merchant backends: create and manage
    checkout sessions, and query commerce records.
  title: Anyway Merchant API
  contact: {}
  version: '1.0'
  x-source: anyway-backend-go
servers:
  - url: https://merchant-api-prod.anyway.sh
security: []
paths:
  /v1/refunds:
    post:
      tags:
        - refunds
      summary: Create a refund
      description: >-
        Refunds a card order, in full or in part, the same as the Refund button
        in the dashboard. Requires Full access or the `sales:refunds:execute`
        permission, and refunds through the API must be enabled for the
        organization by Anyway (otherwise 403 REFUND_API_NOT_ENABLED). Send a
        unique `Idempotency-Key` (required): the same key with the same body
        returns the same refund; the same key with a different order, amount or
        reason returns 409 REFUND_IDEMPOTENCY_MISMATCH. Card orders only, and
        orders older than 90 days can't be refunded. A refund that reaches the
        approval threshold, or takes the organization past its daily refund
        limit, returns 202 with status pending and waits for Anyway review. If
        the refund is still processing, retry with the same `Idempotency-Key`.
        Unknown request fields return 400. The result is sent as a
        refund.succeeded or refund.failed webhook.
      parameters:
        - description: >-
            Unique creation request key: 1-200 ASCII characters in the range
            0x21-0x7E (no spaces or control characters)
          name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: true
        description: Order and amount
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchantapi.CreateRefundRequest'
      responses:
        '200':
          description: >-
            OK. The refund succeeded, or an earlier request with this
            Idempotency-Key is returned.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_RefundResponse
        '202':
          description: >-
            Accepted. The refund is pending: waiting for Anyway review, or still
            processing.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_RefundResponse
        '400':
          description: >-
            Bad Request. Missing or invalid Idempotency-Key, an unknown field,
            an amount of 0 or less, an invalid reason, REFUND_UNSUPPORTED_METHOD
            (not a card order), REFUND_WINDOW_EXPIRED (older than 90 days), or
            amount_too_large, charge_already_refunded, charge_disputed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '403':
          description: >-
            Forbidden. The API key lacks the required permission
            (INSUFFICIENT_SCOPE), or refunds through the API are not enabled for
            the organization (REFUND_API_NOT_ENABLED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '404':
          description: Not Found. Unknown order, or it belongs to another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '409':
          description: >-
            Conflict. REFUND_PENDING_EXISTS, REFUND_IDEMPOTENCY_MISMATCH, or
            REFUND_FAILED / REFUND_REJECTED for a retried Idempotency-Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '503':
          description: >-
            Service Unavailable. The payment provider is busy or down; retry
            with the same Idempotency-Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    merchantapi.CreateRefundRequest:
      type: object
      required:
        - orderId
      properties:
        orderId:
          type: string
          description: The order to refund (ORD...). Card orders only.
        amountCents:
          type: integer
          description: >-
            Amount to refund, in the order's currency. Omit to refund everything
            still refundable.
        reason:
          type: string
          enum:
            - duplicate
            - fraudulent
            - requested_by_customer
          description: Optional reason
    response.ApiResponse-merchantapi_RefundResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/merchantapi.RefundResponse'
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    response.ApiResponse-any:
      type: object
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    merchantapi.RefundResponse:
      type: object
      properties:
        amountCents:
          description: this refund, in the order's currency
          type: integer
        createdAt:
          description: when the refund was requested
          type: string
        currency:
          description: lowercase ISO 4217
          type: string
        failedAt:
          description: 'failed: when it was rejected or declined'
          type: string
        failureReason:
          description: >-
            FailureReason (failed only) is "rejected" (declined during Anyway's
            review)

            or "declined" (declined when processed).
          type: string
        fullyRefunded:
          type: boolean
        orderId:
          type: string
        orgId:
          type: string
        reason:
          type: string
          nullable: true
        refundId:
          description: Anyway RFN_ id
          type: string
        refundedAt:
          description: 'succeeded: when the payment partner confirmed it'
          type: string
        status:
          description: '"succeeded" | "failed"; Merchant API reads also "pending"'
          type: string
        totalRefundedCents:
          description: >-
            TotalRefundedCents sums every succeeded refund on the order (this
            one

            included when it succeeded); FullyRefunded is true once it reaches
            the

            order's total paid. A webhook carries both as of its event; a
            Merchant API

            read, as of the request. They differ once a later refund on the
            order succeeds.
          type: integer
    response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    APIKeyAuth:
      description: 'Merchant API key (format: ak_BASE64)'
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.