# 查询交易记录

> 按商户交易号、Onerway 交易号或创建时间范围查询交易记录。

```yaml
openapi: 3.1.0
info:
  title: 查询交易记录
  version: 1.0.0
  description: 按商户交易号、Onerway 交易号或创建时间范围查询交易记录。
paths:
  /v1/txn/list:
    post:
      summary: 查询交易记录
      description: 按商户交易号、Onerway 交易号或创建时间范围查询交易记录。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号；获取方式参见[接入准备](/zh/payments/get-started/setup#获取凭证)。
                merchantTxnIds:
                  type: string
                  description: 按商户交易号批量查询，多个值以逗号分隔。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 作为查询条件之一提供；`merchantTxnIds` / `transactionIds` /
                      `startTime` + `endTime` 至少提供一类。
                  x-onerway-constraints:
                    - kind: range
                      max: 10
                      unit: 个 ID
                      text: 单次请求最多传入 10 个以逗号分隔的 ID。
                transactionIds:
                  type: string
                  description: 按 Onerway 交易号批量查询，多个值以逗号分隔。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 作为查询条件之一提供；`merchantTxnIds` / `transactionIds` /
                      `startTime` + `endTime` 至少提供一类。
                  x-onerway-constraints:
                    - kind: range
                      max: 10
                      unit: 个 ID
                      text: 单次请求最多传入 10 个以逗号分隔的 ID。
                startTime:
                  type: string
                  description: 查询时间范围的起点，按交易创建时间过滤，格式 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-required: conditional
                  x-onerway-condition:
                    - 按时间范围查询时需与 `endTime` 成对使用；`merchantTxnIds` /
                      `transactionIds` / `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 天。"
                txnTypes:
                  type: string
                  description: 按交易类型过滤查询结果，多个值以逗号分隔；省略时返回所有交易类型。
                  enum:
                    - SALE
                    - AUTH
                    - REFUND
                  x-enum-descriptions:
                    SALE: 支付。
                    AUTH: 预授权。
                    REFUND: 退款。
                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
                - current
                - sign
            examples:
              american-express-cardholder-name-check-failed:
                summary: American Express 持卡人姓名不匹配
                value:
                  merchantNo: replace_with_merchant_no
                  transactionIds: replace_with_transaction_id
                  current: "0"
                  sign: "{{SIGN}}"
              query-transactions-by-merchant-transaction-id:
                summary: 按商户交易号查询交易记录
                value:
                  current: "1"
                  merchantNo: replace_with_merchant_no
                  merchantTxnIds: txn_demo_202606210001,txn_demo_202606210002
                  sign: "{{SIGN}}"
                  size: "10"
      responses:
        "200":
          description: American Express 持卡人姓名不匹配
          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:
                            transactionId:
                              type: string
                              description: Onerway 为本次交易生成的交易号，JSON 中以 `String` 传输。
                            paymentId:
                              type: string
                              description: 支付意图 ID，JSON 中以 `String` 传输。一个 `paymentId` 可关联多笔 `transactionId`。
                            merchantTxnId:
                              type: string
                              description: 商户为本次交易生成的商户交易号。
                            merchantTxnOriginalId:
                              type:
                                - string
                                - "null"
                              description: 商户侧原始订单或被引用原始交易的商户交易号。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the transaction references a merchant-side original order
                                    or a secondary transaction references an
                                    original transaction.
                                  zh: 交易关联商户侧原始订单或二级交易引用原始交易时有值。
                            originTransactionId:
                              type:
                                - string
                                - "null"
                              description: 被引用的原始交易的 Onerway 交易号，JSON 中以 `String` 传输。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when a secondary transaction references an original transaction.
                                  zh: 二级交易引用原始交易时有值。
                            txnTime:
                              type:
                                - string
                                - "null"
                              description: 交易时间，格式 `yyyy-MM-dd HH:mm:ss`，不直接等同于完成时间。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when transaction time is returned.
                                  zh: 交易记录返回交易时间时有值。
                            txnTimeZone:
                              type:
                                - string
                                - "null"
                              description: 交易时区偏移量，格式 `±HH:mm`。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Returned together with `txnTime` when transaction time is returned.
                                  zh: 随 `txnTime` 返回。
                            txnCompletionTime:
                              type:
                                - string
                                - "null"
                              description: 交易完成时间，格式 `yyyy-MM-dd HH:mm:ss`。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value after the transaction completes.
                                  zh: 交易完成后才有值。
                            productType:
                              type: string
                              description: 本次交易使用的支付产品范围。
                              enum:
                                - ALL
                                - CARD
                                - LPMS
                                - PAYMENT_CODE
                                - ORDER_CODE
                              x-enum-descriptions:
                                ALL: 聚合收银台。
                                CARD: 信用卡。
                                LPMS: 本地支付方式。
                                PAYMENT_CODE: 支付码。
                                ORDER_CODE: 订单码。
                            subProductType:
                              type: string
                              description: 支付产品范围下的交易处理模式。
                              enum:
                                - DIRECT
                                - SUBSCRIBE
                                - INSTALLMENT
                                - TOKEN
                                - AUTO_DEBIT
                              x-enum-descriptions:
                                DIRECT: 直接支付。
                                SUBSCRIBE: 订阅支付。
                                INSTALLMENT: 分期支付。
                                TOKEN: token 支付。
                                AUTO_DEBIT: 代扣。
                            txnType:
                              type: string
                              description: 本笔交易的操作类型；该字段与 `productType`、`subProductType` 共同定义交易模型。
                              enum:
                                - SALE
                                - AUTH
                                - REFUND
                              x-enum-descriptions:
                                SALE: 支付。
                                AUTH: 预授权。
                                REFUND: 退款。
                            status:
                              type: string
                              description: 本笔交易的当前处理状态。
                              enum:
                                - S
                                - F
                                - P
                                - R
                                - N
                                - I
                                - U
                              x-enum-descriptions:
                                S: 成功；交易已成功完成，为终态。
                                F: 失败；交易被拒绝或处理失败，为终态。
                                P: 处理中；交易正在处理，收到终态前不应视为最终结果。
                                R: 需跳转；客户需被跳转以完成支付。
                                N: 已取消；交易未在有效期内完成支付（如收银台超时未付）而关闭，为终态，无资金划转。
                                I: 审核中；交易待审批或人工复核。
                                U: 未支付；等待支付。
                              x-onerway-constraints:
                                - kind: rule
                                  text: "`respCode=20000` 只表示查询请求处理成功，仍应读取本字段判断单笔交易结果。"
                            contractId:
                              type:
                                - string
                                - "null"
                              description: 订阅合约号，标识订阅，是完成后续扣款的关键参数。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the transaction is associated with a subscription contract.
                                  zh: 交易记录关联订阅合约时才有值。
                            tokenId:
                              type:
                                - string
                                - "null"
                              description: 订阅 token 或绑卡 token；两者属不同体系、不可混用。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the transaction is associated with a subscription token or
                                    saved payment method token.
                                  zh: 交易记录关联订阅 token 或绑卡 token 时才有值。
                            userPaymentStatus:
                              type:
                                - string
                                - "null"
                              description: 用户支付状态。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Relevant only for Sofort transactions. Ignore an empty value.
                                  zh: 仅 Sofort 交易关注此字段，空值时忽略。
                            cardType:
                              type:
                                - string
                                - "null"
                              description: 支付方式类型。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when a specific payment method type is returned.
                                  zh: 交易返回具体支付方式类型时有值。
                            paymentMethod:
                              type:
                                - string
                                - "null"
                              description: 客户使用的具体支付方式，涵盖卡与本地支付方式。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value after the customer selects a payment method.
                                  zh: 客户已选定支付方式后才有值。
                            orderAmount:
                              type: string
                              description: 下单金额（原始交易金额）。
                            orderCurrency:
                              type: string
                              description: 下单币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码。
                            settleRate:
                              type: string
                              description: 订单币种与结算币种之间的换算汇率；用于按 `txnAmount = orderAmount * settleRate` 从
                                `orderAmount` 计算 `txnAmount`。
                            txnAmount:
                              type: string
                              description: 订单金额按 `settleRate` 换算后的结算币种金额。
                            txnCurrency:
                              type: string
                              description: 结算币种，[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 三位字母货币代码。
                            customsDeclarationAmount:
                              type:
                                - string
                                - "null"
                              description: 可用于报关的金额。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value only for cross-border transactions that involve customs
                                    declaration.
                                  zh: 涉及海关申报的跨境交易才有值。
                            customsDeclarationCurrency:
                              type:
                                - string
                                - "null"
                              description: 报关金额对应的币种。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value only for cross-border transactions that involve customs
                                    declaration.
                                  zh: 涉及海关申报的跨境交易才有值。
                            arn:
                              type:
                                - string
                                - "null"
                              description: 收单行参考号（ARN），可用于对账与争议处理。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value after an Acquirer Reference Number is generated for the
                                    transaction.
                                  zh: 交易生成 ARN 后才有值。
                            appId:
                              type:
                                - string
                                - "null"
                              description: 处理本次交易的商户应用 ID。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the transaction is associated with a merchant application.
                                  zh: 交易关联到商户应用时有值。
                            website:
                              type:
                                - string
                                - "null"
                              description: 发起交易的网站域名。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the transaction records the initiating website.
                                  zh: 交易记录了发起域名时有值。
                            cardBinCountry:
                              type:
                                - string
                                - "null"
                              description: 卡 BIN（银行识别号）所属国家 / 地区。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value for card transactions when the card BIN country or region can be
                                    identified.
                                  zh: 卡交易且可识别卡 BIN 所属国家 / 地区时有值。
                            cardNumber:
                              type:
                                - string
                                - "null"
                              description: 脱敏卡号，仅保留前 6 位和后 4 位，中间位掩码。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value for card transactions.
                                  zh: 卡交易才有值。
                            walletTypeName:
                              type:
                                - string
                                - "null"
                              description: 钱包类型名称。
                              enum:
                                - GooglePay
                                - ApplePay
                                - EXPR
                                - JIOU
                                - XJK
                                - null
                              x-enum-descriptions:
                                GooglePay: Google Pay 钱包。
                                ApplePay: Apple Pay 钱包。
                                EXPR: 钱包内资金来源：银行卡。
                                JIOU: 钱包内资金来源：白条。
                                XJK: 钱包内资金来源：小金库。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when a digital wallet is used.
                                  zh: 使用数字钱包支付时才有值。
                            reason:
                              type:
                                - string
                                - "null"
                              description: 交易失败原因的详细说明。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the transaction did not succeed.
                                  zh: 交易未成功时才有值。
                            holderName:
                              type:
                                - string
                                - "null"
                              description: 持卡人姓名。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value for card transactions.
                                  zh: 卡交易才有值。
                            eci:
                              type:
                                - string
                                - "null"
                              description: 电子商务指示符（ECI）。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when a card transaction or 3DS result returns an ECI.
                                  zh: 卡交易或 3DS 结果返回 ECI 时有值。
                            email:
                              type:
                                - string
                                - "null"
                              description: 客户电子邮件地址。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when the customer provided an email address.
                                  zh: 客户提供邮箱时有值。
                            creditCard:
                              type: object
                              properties:
                                holderName:
                                  type:
                                    - string
                                    - "null"
                                  description: 持卡人姓名。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a10
                                      en: Has a value when cardholder name is returned.
                                      zh: 返回持卡人姓名时有值。
                                year:
                                  type:
                                    - string
                                    - "null"
                                  description: 卡有效期年份。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a11
                                      en: Has a value when card expiration is returned.
                                      zh: 返回卡有效期时有值。
                                month:
                                  type:
                                    - string
                                    - "null"
                                  description: 卡有效期月份。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a12
                                      en: Has a value when card expiration is returned.
                                      zh: 返回卡有效期时有值。
                                verificationResult:
                                  type:
                                    - object
                                    - "null"
                                  properties:
                                    version:
                                      type: string
                                      description: 3D Secure 协议版本或 `UNKNOWN`。
                                    authenticationFlow:
                                      type:
                                        - string
                                        - "null"
                                      description: 3DS 认证流程类型。
                                      enum:
                                        - FRICTIONLESS
                                        - CHALLENGE
                                        - null
                                      x-enum-descriptions:
                                        FRICTIONLESS: 无摩擦认证，无需客户额外交互。
                                        CHALLENGE: 挑战认证，需要客户完成额外验证。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a1
                                          en: Has a value when the 3DS authentication flow can be identified.
                                          zh: 可识别 3DS 认证流程时有值。
                                    authenticationCode:
                                      type:
                                        - string
                                        - "null"
                                      description: 3DS 或支付渠道返回的认证 / 授权码。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a2
                                          en: Has a value when the payment channel returns an authentication or
                                            authorization code.
                                          zh: 支付渠道返回认证 / 授权码时有值。
                                    chargebackLiability:
                                      type: string
                                      description: 3DS 拒付责任承担方。
                                      enum:
                                        - ISSUER
                                        - MERCHANT
                                        - UNKNOWN
                                      x-enum-descriptions:
                                        ISSUER: 责任转移至发卡行。
                                        MERCHANT: 责任由商户承担。
                                        UNKNOWN: 暂无法判断责任方。
                                    transStatus:
                                      type:
                                        - string
                                        - "null"
                                      description: 3DS（ACS）认证结果。
                                      enum:
                                        - Y
                                        - N
                                        - A
                                        - U
                                        - R
                                        - null
                                      x-enum-descriptions:
                                        Y: 认证成功。
                                        N: 认证失败。
                                        A: 已尝试认证。
                                        U: 无法完成认证。
                                        R: 认证被拒绝。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a3
                                          en: Has a value when the ACS returns an authentication status.
                                          zh: ACS 返回认证状态时有值。
                                    transStatusReason:
                                      type:
                                        - string
                                        - "null"
                                      description: 3DS 认证状态的详细原因说明。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a4
                                          en: Has a value when the 3DS authentication status needs an additional reason.
                                          zh: 需要补充说明 3DS 认证状态时有值。
                                    veresEnrolled:
                                      type:
                                        - string
                                        - "null"
                                      description: 3DS enrollment 结果。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a5
                                          en: Has a value when the 3DS enrollment result is returned.
                                          zh: 3DS enrollment 结果返回时有值。
                                    eci:
                                      type:
                                        - string
                                        - "null"
                                      description: 电子商务指示符（ECI）。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a6
                                          en: Has a value when 3DS or the card transaction returns an ECI.
                                          zh: 3DS 或卡交易返回 ECI 时有值。
                                    cvvResult:
                                      type:
                                        - string
                                        - "null"
                                      description: CVV 安全码校验结果。
                                      enum:
                                        - M
                                        - N
                                        - P
                                        - S
                                        - U
                                        - I
                                        - null
                                      x-enum-descriptions:
                                        M: CVV 匹配成功。
                                        N: CVV 不匹配。
                                        P: CVV 处理错误。
                                        S: CVV 缺失。
                                        U: 系统不可用。
                                        I: CVV 无效。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a7
                                          en: Has a value when the CVV check result is returned.
                                          zh: CVV 校验结果返回时有值。
                                    avsFullResult:
                                      type:
                                        - string
                                        - "null"
                                      description: AVS 地址验证综合结果。
                                      enum:
                                        - Y
                                        - N
                                        - A
                                        - Z
                                        - U
                                        - null
                                      x-enum-descriptions:
                                        Y: 邮政编码与街道地址都匹配。
                                        N: 邮政编码与街道地址都不匹配。
                                        A: 街道地址匹配，邮政编码不匹配。
                                        Z: 邮政编码匹配，街道地址不匹配。
                                        U: 地址验证系统离线。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a8
                                          en: Has a value when the aggregated AVS result is returned.
                                          zh: AVS 综合校验结果返回时有值。
                                    cavvResult:
                                      type:
                                        - string
                                        - "null"
                                      description: 3DS 认证返回的 CAVV 加密值。
                                      x-onerway-value:
                                        nullable: true
                                        when: &a9
                                          en: Has a value when 3DS authentication returns a CAVV.
                                          zh: 3DS 认证返回 CAVV 时有值。
                                  description: 卡验证结果对象。
                                  x-onerway-value:
                                    nullable: true
                                    when:
                                      en: Has a value when card verification results are returned.
                                      zh: 返回卡验证结果时有值。
                                cardType:
                                  type: string
                                  description: 支付方式类型。
                                productCategory:
                                  type:
                                    - string
                                    - "null"
                                  description: 卡产品类别。
                                  enum:
                                    - D
                                    - P
                                    - C
                                    - H
                                    - R
                                    - N
                                    - null
                                  x-enum-descriptions:
                                    D: 借记卡
                                    P: 预付卡
                                    C: 信用卡
                                    H: 签账卡
                                    R: 延迟借记卡
                                    N: 未知
                                  x-onerway-value:
                                    nullable: true
                                    when: &a13
                                      en: Has a value when the card network returns card product category.
                                      zh: 卡组织返回卡产品类别时有值。
                                issuer:
                                  type:
                                    - string
                                    - "null"
                                  description: 发卡行名称。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a14
                                      en: Has a value when the issuer can be identified.
                                      zh: 可识别发卡行时有值。
                                cardBinCountry:
                                  type:
                                    - string
                                    - "null"
                                  description: 卡 BIN（银行识别号）所属国家 / 地区。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a15
                                      en: Has a value when the card BIN country or region can be identified.
                                      zh: 可识别卡 BIN 所属国家 / 地区时有值。
                                authorizationCode:
                                  type:
                                    - string
                                    - "null"
                                  description: 收单行 / 发卡行返回的授权码。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a16
                                      en: Has a value when the payment channel returns an authorization code.
                                      zh: 支付渠道返回授权码时有值。
                                cardNumber:
                                  type:
                                    - string
                                    - "null"
                                  description: 脱敏卡号，仅保留前 6 位和后 4 位，中间位掩码。
                                  x-onerway-value:
                                    nullable: true
                                    when: &a17
                                      en: Has a value when masked card number is returned.
                                      zh: 返回卡号信息时有值。
                              description: 兼容卡信息对象，字段与顶层扁平卡字段及 `paymentMethodDetails.card` 部分重叠。
                            channelRequestId:
                              type:
                                - string
                                - "null"
                              description: 支付渠道侧的请求标识。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value after the transaction enters payment channel processing.
                                  zh: 交易进入支付渠道处理后才有值。
                            lpmsUserId:
                              type:
                                - string
                                - "null"
                              description: 本地支付方式用户标识。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Has a value when a local payment method transaction is associated with a
                                    channel user identifier.
                                  zh: 本地支付方式交易关联到渠道用户标识时有值。
                            paymentMethodDetails:
                              type: object
                              properties:
                                card:
                                  type: object
                                  properties:
                                    checks:
                                      type:
                                        - object
                                        - "null"
                                      properties:
                                        addressCheck:
                                          type:
                                            - string
                                            - "null"
                                          description: AVS 街道地址校验结果。
                                          enum:
                                            - pass
                                            - fail
                                            - unavailable
                                            - unchecked
                                            - notProvided
                                            - unsupported
                                            - null
                                          x-enum-descriptions:
                                            pass: 提交验证的信息与发卡行记录一致。
                                            fail: 提交验证的信息与发卡行记录不一致。
                                            unavailable: 发卡行不支持此类验证。
                                            unchecked: 未执行验证。
                                            notProvided: 未提供本次验证所需的信息。
                                            unsupported: 此交易不支持 AVS。
                                          x-onerway-value:
                                            nullable: true
                                            when:
                                              en: Has a value when AVS street-address verification is performed.
                                              zh: 执行 AVS 街道地址校验时有值。
                                        postalCodeCheck:
                                          type:
                                            - string
                                            - "null"
                                          description: AVS 邮政编码校验结果。
                                          enum:
                                            - pass
                                            - fail
                                            - unavailable
                                            - unchecked
                                            - notProvided
                                            - unsupported
                                            - null
                                          x-enum-descriptions:
                                            pass: 提交验证的信息与发卡行记录一致。
                                            fail: 提交验证的信息与发卡行记录不一致。
                                            unavailable: 发卡行不支持此类验证。
                                            unchecked: 未执行验证。
                                            notProvided: 未提供本次验证所需的信息。
                                            unsupported: 此交易不支持 AVS。
                                          x-onerway-value:
                                            nullable: true
                                            when:
                                              en: Has a value when AVS postal-code verification is performed.
                                              zh: 执行 AVS 邮编校验时有值。
                                        cardholderNameCheck:
                                          type:
                                            - string
                                            - "null"
                                          description: American Express AVS 持卡人姓名验证结果，表示姓名是否与发卡行记录一致。
                                          enum:
                                            - pass
                                            - fail
                                            - unavailable
                                            - unchecked
                                            - notProvided
                                            - unsupported
                                            - null
                                          x-enum-descriptions:
                                            pass: 提交验证的信息与发卡行记录一致。
                                            fail: 提交验证的信息与发卡行记录不一致。
                                            unavailable: 发卡行不支持此类验证。
                                            unchecked: 未执行验证。
                                            notProvided: 未提供本次验证所需的信息。
                                            unsupported: 此交易不支持 AVS。
                                          x-onerway-value:
                                            nullable: true
                                            when:
                                              en: Returns the result when American Express cardholder name verification is
                                                performed, or `null` if it is
                                                not performed.
                                              zh: 执行 American Express 持卡人姓名验证时返回验证结果；未执行时返回 `null`。
                                        avsResultRawCode:
                                          type:
                                            - string
                                            - "null"
                                          description: 卡组织或 Onerway 返回的原始 AVS 结果码。
                                          enum:
                                            - Y
                                            - N
                                            - A
                                            - Z
                                            - U
                                            - null
                                          x-enum-descriptions:
                                            Y: 邮政编码与街道地址都匹配。
                                            N: 邮政编码与街道地址都不匹配。
                                            A: 街道地址匹配，邮政编码不匹配。
                                            Z: 邮政编码匹配，街道地址不匹配。
                                            U: 地址验证不可用。
                                          x-onerway-value:
                                            nullable: true
                                            when:
                                              en: Has a value when a card network or Onerway returns a raw AVS result code.
                                              zh: 卡组织或 Onerway 返回原始 AVS 结果码时有值。
                                        threeDSecureResult:
                                          type:
                                            - object
                                            - "null"
                                          properties:
                                            version:
                                              type: string
                                              description: 3D Secure 协议版本或 `UNKNOWN`。
                                            authenticationFlow:
                                              type:
                                                - string
                                                - "null"
                                              description: 3DS 认证流程类型。
                                              enum:
                                                - FRICTIONLESS
                                                - CHALLENGE
                                                - null
                                              x-enum-descriptions:
                                                FRICTIONLESS: 无摩擦认证，无需客户额外交互。
                                                CHALLENGE: 挑战认证，需要客户完成额外验证。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a1
                                            authenticationCode:
                                              type:
                                                - string
                                                - "null"
                                              description: 3DS 或支付渠道返回的认证 / 授权码。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a2
                                            chargebackLiability:
                                              type: string
                                              description: 3DS 拒付责任承担方。
                                              enum:
                                                - ISSUER
                                                - MERCHANT
                                                - UNKNOWN
                                              x-enum-descriptions:
                                                ISSUER: 责任转移至发卡行。
                                                MERCHANT: 责任由商户承担。
                                                UNKNOWN: 暂无法判断责任方。
                                            transStatus:
                                              type:
                                                - string
                                                - "null"
                                              description: 3DS（ACS）认证结果。
                                              enum:
                                                - Y
                                                - N
                                                - A
                                                - U
                                                - R
                                                - null
                                              x-enum-descriptions:
                                                Y: 认证成功。
                                                N: 认证失败。
                                                A: 已尝试认证。
                                                U: 无法完成认证。
                                                R: 认证被拒绝。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a3
                                            transStatusReason:
                                              type:
                                                - string
                                                - "null"
                                              description: 3DS 认证状态的详细原因说明。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a4
                                            veresEnrolled:
                                              type:
                                                - string
                                                - "null"
                                              description: 3DS enrollment 结果。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a5
                                            eci:
                                              type:
                                                - string
                                                - "null"
                                              description: 电子商务指示符（ECI）。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a6
                                            cvvResult:
                                              type:
                                                - string
                                                - "null"
                                              description: CVV 安全码校验结果。
                                              enum:
                                                - M
                                                - N
                                                - P
                                                - S
                                                - U
                                                - I
                                                - null
                                              x-enum-descriptions:
                                                M: CVV 匹配成功。
                                                N: CVV 不匹配。
                                                P: CVV 处理错误。
                                                S: CVV 缺失。
                                                U: 系统不可用。
                                                I: CVV 无效。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a7
                                            avsFullResult:
                                              type:
                                                - string
                                                - "null"
                                              description: AVS 地址验证综合结果。
                                              enum:
                                                - Y
                                                - N
                                                - A
                                                - Z
                                                - U
                                                - null
                                              x-enum-descriptions:
                                                Y: 邮政编码与街道地址都匹配。
                                                N: 邮政编码与街道地址都不匹配。
                                                A: 街道地址匹配，邮政编码不匹配。
                                                Z: 邮政编码匹配，街道地址不匹配。
                                                U: 地址验证系统离线。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a8
                                            cavvResult:
                                              type:
                                                - string
                                                - "null"
                                              description: 3DS 认证返回的 CAVV 加密值。
                                              x-onerway-value:
                                                nullable: true
                                                when: *a9
                                          description: 3D Secure 验证结果。
                                          x-onerway-value:
                                            nullable: true
                                            when:
                                              en: Has a value when 3DS verification results are returned.
                                              zh: 返回 3DS 验证结果时有值。
                                      description: 验证检查结果，含 AVS 与 3DS 结果。
                                      x-onerway-value:
                                        nullable: true
                                        when:
                                          en: Has a value when AVS, 3DS, or CVV verification results are returned.
                                          zh: 支付渠道返回 AVS / 3DS / CVV 验证结果时有值。
                                    holderName:
                                      type:
                                        - string
                                        - "null"
                                      description: 持卡人姓名。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a10
                                    year:
                                      type:
                                        - string
                                        - "null"
                                      description: 卡有效期年份。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a11
                                    month:
                                      type:
                                        - string
                                        - "null"
                                      description: 卡有效期月份。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a12
                                    cardType:
                                      type: string
                                      description: 支付方式类型。
                                    productCategory:
                                      type:
                                        - string
                                        - "null"
                                      description: 卡产品类别。
                                      enum:
                                        - D
                                        - P
                                        - C
                                        - H
                                        - R
                                        - N
                                        - null
                                      x-enum-descriptions:
                                        D: 借记卡
                                        P: 预付卡
                                        C: 信用卡
                                        H: 签账卡
                                        R: 延迟借记卡
                                        N: 未知
                                      x-onerway-value:
                                        nullable: true
                                        when: *a13
                                    issuer:
                                      type:
                                        - string
                                        - "null"
                                      description: 发卡行名称。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a14
                                    cardBinCountry:
                                      type:
                                        - string
                                        - "null"
                                      description: 卡 BIN（银行识别号）所属国家 / 地区。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a15
                                    authorizationCode:
                                      type:
                                        - string
                                        - "null"
                                      description: 收单行 / 发卡行返回的授权码。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a16
                                    cardNumber:
                                      type:
                                        - string
                                        - "null"
                                      description: 脱敏卡号，仅保留前 6 位和后 4 位，中间位掩码。
                                      x-onerway-value:
                                        nullable: true
                                        when: *a17
                                  description: 卡 / 支付方式兼容详情。
                              description: 支付方式详情对象，`card` 子对象包含卡明细或兼容支付方式明细与验证检查结果。
                            metaData:
                              type:
                                - string
                                - "null"
                              description: 商户自定义数据，可用于对账与业务上下文识别。
                              x-onerway-value:
                                nullable: true
                                empty: true
                                when:
                                  en: Has a value only when custom metadata was submitted in the payment request
                                    or subscription configuration.
                                  zh: 商户在支付请求或订阅配置中传入了自定义数据才有值，未传入时为空。
                      current:
                        type: string
                        description: 响应中的当前页码，统一返回 1-based 页码。
                      size:
                        type: number
                        description: 当前页的记录数（当前固定每页 10 条）。
                      totalPages:
                        type: number
                        description: 按当前页大小计算的总页数。
                      totalElements:
                        type: number
                        description: 符合查询条件的交易总条数。
                    description: 业务数据对象，包含分页交易记录列表与分页信息。
              examples:
                american-express-cardholder-name-check-failed:
                  summary: American Express 持卡人姓名不匹配
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      content:
                        - transactionId: replace_with_transaction_id
                          paymentId: replace_with_payment_id
                          merchantTxnId: example_merchant_transaction_id
                          merchantTxnOriginalId: null
                          txnTime: 2026-01-15 10:30:00
                          txnTimeZone: +08:00
                          txnCompletionTime: 2026-01-15 10:30:30
                          originTransactionId: null
                          productType: CARD
                          subProductType: DIRECT
                          txnType: SALE
                          status: S
                          contractId: null
                          tokenId: null
                          userPaymentStatus: null
                          cardType: AE
                          paymentMethod: AE
                          orderAmount: "100.00"
                          settleRate: "1"
                          orderCurrency: USD
                          txnAmount: "100.00"
                          txnCurrency: USD
                          customsDeclarationAmount: null
                          customsDeclarationCurrency: null
                          arn: null
                          appId: replace_with_app_id
                          website: https://merchant.example.com
                          cardBinCountry: US
                          cardNumber: 370000******0002
                          walletTypeName: null
                          reason: null
                          holderName: Example Cardholder
                          eci: null
                          email: customer@example.com
                          creditCard:
                            holderName: Example Cardholder
                            year: "2029"
                            month: "11"
                            verificationResult: null
                            cardType: AE
                            productCategory: null
                            issuer: Example American Express Issuer
                            cardNumber: 370000******0002
                          channelRequestId: replace_with_channel_request_id
                          lpmsUserId: null
                          paymentMethodDetails:
                            card:
                              checks:
                                addressCheck: fail
                                postalCodeCheck: fail
                                cardholderNameCheck: fail
                                avsResultRawCode: W
                                threeDSecureResult: null
                              holderName: Example Cardholder
                              year: "2029"
                              month: "11"
                              cardType: AE
                              productCategory: null
                              issuer: Example American Express Issuer
                              cardBinCountry: US
                              authorizationCode: replace_with_authorization_code
                              cardNumber: 370000******0002
                          metaData: null
                      current: "1"
                      size: 10
                      totalPages: 1
                      totalElements: 1
```