# 查询退款记录

> 按支付意图、退款交易、原交易或时间范围查询退款记录。

```yaml
openapi: 3.1.0
info:
  title: 查询退款记录
  version: 1.0.0
  description: 按支付意图、退款交易、原交易或时间范围查询退款记录。
paths:
  /v1/txn/queryRefunds:
    post:
      summary: 查询退款记录
      description: 按支付意图、退款交易、原交易或时间范围查询退款记录。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
                paymentId:
                  type: string
                  description: 支付意图 ID，JSON 以 `String` 传输，可按 Payment 维度检索关联交易与退款记录。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 作为查询条件之一提供；`paymentId` / `transactionId` /
                      `originTransactionId` / `startTime` + `endTime` 至少提供一类。
                transactionId:
                  type: string
                  description: 退款交易流水号，JSON 以 `String` 传输，可按单次退款交易精确查询退款记录。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 作为查询条件之一提供；`paymentId` / `transactionId` /
                      `originTransactionId` / `startTime` + `endTime` 至少提供一类。
                originTransactionId:
                  type: string
                  description: 退款关联的原始 Onerway 交易 ID，JSON 以 `String` 传输，用于按原交易维度关联退款记录。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 作为查询条件之一提供；`paymentId` / `transactionId` /
                      `originTransactionId` / `startTime` + `endTime` 至少提供一类。
                startTime:
                  type: string
                  description: 查询时间范围的起点，按交易创建时间过滤，格式 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 按时间范围查询时需与 `endTime` 成对提供；`paymentId` / `transactionId` /
                      `originTransactionId` / `startTime` + `endTime` 至少提供一类。
                  x-onerway-constraints:
                    - kind: rule
                      text: "`startTime` 与 `endTime` 的区间最大 90 天。"
                endTime:
                  type: string
                  description: 查询时间范围的终点，格式 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 按时间范围查询时需与 `startTime` 成对提供。
                  x-onerway-constraints:
                    - kind: consistency
                      text: "`endTime` 必须晚于 `startTime`。"
                    - kind: rule
                      text: "`startTime` 与 `endTime` 的区间最大 90 天。"
                current:
                  type: string
                  description: 退款记录查询页码。`0` 和 `1` 都表示第一页；不传默认第一页；响应中的 `current` 统一返回 1-based 页码。
                size:
                  type: string
                  description: 分页大小；本接口每页最多返回 `10` 条，暂不支持自定义分页大小。
                sign:
                  type: string
                  description: 请求签名字符串；生成方式详见[请求签名](/zh/payments/get-started/request-signing)。
              required:
                - merchantNo
                - sign
            examples:
              query-refunds-by-payment-id:
                summary: 按 paymentId 查询退款记录
                value:
                  current: "1"
                  merchantNo: replace_with_merchant_no
                  paymentId: "2031908578000000000"
                  sign: "{{SIGN}}"
                  size: "10"
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 响应码；`20000`
                      表示查询请求处理成功，不代表单条退款最终成功；其余为错误码。完整码表见[响应码](/zh/payments/api-reference/response-codes)。
                  respMsg:
                    type: string
                    description: 响应码对应的可读消息。
                  data:
                    type: object
                    properties:
                      content:
                        type: array
                        description: 符合查询条件的退款记录列表，每条为一笔退款交易。
                        items:
                          type: object
                          properties:
                            paymentId:
                              type: string
                              description: 支付意图 ID，JSON 以 `String` 传输。一个 `paymentId` 可关联多笔交易或退款记录。
                            originTransactionId:
                              type: string
                              description: 退款对应的原 Onerway 交易 ID，JSON 以 `String` 传输。用于把退款记录关联回原交易。
                            transactionId:
                              type: string
                              description: 退款交易 ID，JSON 以 `String` 传输，用于标识单次退款交易。
                            status:
                              type: string
                              description: 当前退款交易状态；取值沿用 `TxnStatusEnum`；`N` 表示已取消退款。
                              enum:
                                - S
                                - F
                                - P
                                - R
                                - N
                                - I
                                - U
                              x-enum-descriptions:
                                S: 成功；交易已成功完成，为终态。
                                F: 失败；交易被拒绝或处理失败，为终态。
                                P: 处理中；交易正在处理，收到终态前不应视为最终结果。
                                R: 需跳转；客户需被跳转以完成支付。
                                N: 已取消；交易未在有效期内完成支付（如收银台超时未付）而关闭，为终态，无资金划转。
                                I: 审核中；交易待审批或人工复核。
                                U: 未支付；等待支付。
                            reason:
                              type:
                                - string
                                - "null"
                              description: 退款失败原因说明。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the refund failed or a failure reason needs to be returned.
                                    Successful refund records can return `null`.
                                  zh: 退款失败或需要返回失败原因时才有值；成功退款记录可能为 `null`。
                            amount:
                              type: string
                              description: 退款金额。
                            currency:
                              type: string
                              description: 退款币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码。
                            arn:
                              type:
                                - string
                                - "null"
                              description: 收单参考号（ARN），可用于对账与争议处理。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value after the acquiring network or channel returns an ARN; returns
                                    `null` when ARN is not available.
                                  zh: 收单网络或渠道返回 ARN 后才有值；ARN 不可用时返回 `null`。
                            createTime:
                              type: string
                              description: 退款创建时间，格式 `yyyy-MM-dd HH:mm:ss`。
                      current:
                        type: string
                        description: 响应中的当前页码，统一返回 1-based 页码。
                      size:
                        type: number
                        description: 当前页分页大小（page size）；实际总记录数见 `totalElements`。
                      totalPages:
                        type: number
                        description: 总页数。
                      totalElements:
                        type: number
                        description: 符合查询条件的退款记录总条数。
                    description: 业务数据对象，包含退款记录列表与分页信息。
```