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

# 列出退款

> 分页列出当前组织的退款，并使用筛选条件进行对账。

请使用属于目标组织的 API 密钥进行认证。

每笔退款的字段与 `refund.succeeded`、`refund.failed` [Webhook](https://docs.anyway.sh/zh/api-reference/endpoint/webhooks.md)
相同，事件和 API 读取可以用同一套代码对账。`status` 为 `succeeded`、`failed` 或
`pending`（仍在审核或处理中）。`pending` 不会发送 Webhook；退款结束时会发送
`refund.succeeded` 或 `refund.failed`。

按时间段对账时，使用 `date_from` 和 `date_to` 筛选并逐页读取。查看某个订单的全部退款时，
使用 `order_id` 筛选。`totalRefundedCents` 和 `fullyRefunded` 反映请求时订单的状态。Webhook 中的这两个字段是事件发生时的值；同一订单之后又有退款成功时，API 返回的合计会高于之前那条 Webhook。


## OpenAPI

````yaml api-reference/openapi.json GET /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:
    get:
      tags:
        - refunds
      summary: List refunds
      description: >-
        Returns the org's refunds, newest first, in the same shape as the
        refund.succeeded / refund.failed webhooks. status is succeeded, failed
        or pending (awaiting review or processing). totalRefundedCents and
        fullyRefunded describe the order as of the request, so they can be
        higher than in an earlier webhook for the same refund if a later refund
        on the order succeeded.
      parameters:
        - description: Page number
          name: page
          in: query
          schema:
            type: integer
            default: 1
        - description: Page size (max 100)
          name: size
          in: query
          schema:
            type: integer
            default: 20
        - description: Filter by order ID (ORD_...)
          name: order_id
          in: query
          schema:
            type: string
        - description: succeeded, failed or pending
          name: status
          in: query
          schema:
            type: string
        - description: Refunds requested at or after this unix timestamp
          name: date_from
          in: query
          schema:
            type: integer
        - description: Refunds requested at or before this unix timestamp
          name: date_to
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_PaginatedResponse-merchantapi_RefundResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    response.ApiResponse-merchantapi_PaginatedResponse-merchantapi_RefundResponse:
      type: object
      properties:
        data:
          $ref: >-
            #/components/schemas/merchantapi.PaginatedResponse-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.PaginatedResponse-merchantapi_RefundResponse:
      type: object
      properties:
        current:
          description: 'Deprecated: use page.'
          type: integer
          deprecated: true
        page:
          type: integer
        pages:
          type: integer
        records:
          type: array
          items:
            $ref: '#/components/schemas/merchantapi.RefundResponse'
        size:
          type: integer
        total:
          type: integer
    response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    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
  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.