# 查询 3DS 记录

> 按卡片、交易订单号和时间范围分页查询 3DS 发送记录。

```yaml
openapi: 3.1.0
info:
  title: 查询 3DS 记录
  version: 1.0.0
  description: 按卡片、交易订单号和时间范围分页查询 3DS 发送记录。
paths:
  /api/v1/merchant/card/query3dsNotify:
    post:
      summary: 查询 3DS 记录
      description: 按卡片、交易订单号和时间范围分页查询 3DS 发送记录。
      parameters:
        - name: ApiKey
          in: header
          required: true
          description: Onerway 分配的发卡 API key 请求 Header。
          schema:
            type: string
            description: Onerway 分配的发卡 API key 请求 Header。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                txnOrderNo:
                  type: string
                  description: 交易订单号筛选条件。
                  x-onerway-constraints:
                    - kind: rule
                      text: 长度不能超过 64 个字符。
                cardId:
                  type: string
                  description: 卡片 ID 筛选条件。
                  x-onerway-constraints:
                    - kind: rule
                      text: 长度不能超过 64 个字符。
                startTime:
                  type: integer
                  description: 查询开始时间，Unix 秒级时间戳。
                endTime:
                  type: integer
                  description: 查询结束时间，Unix 秒级时间戳。
                pageNum:
                  type: integer
                  description: 页码。
                  x-onerway-constraints:
                    - kind: range
                      min: 1
                pageSize:
                  type: integer
                  description: 每页条数。
                  x-onerway-constraints:
                    - kind: range
                      min: 1
                      max: 100
              required:
                - cardId
                - pageNum
                - pageSize
            examples:
              query-by-card:
                summary: 按卡片查询 3DS 记录
                value:
                  cardId: example_card_id
                  startTime: 1767225600
                  endTime: 1767312000
                  pageNum: 1
                  pageSize: 10
      responses:
        "200":
          description: 返回 3DS 记录
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 业务响应码；`20000` 表示成功。
                  respMsg:
                    type: string
                    description: 响应信息。
                  data:
                    type:
                      - object
                      - "null"
                    properties:
                      totalRecords:
                        type: integer
                        description: 总记录数。
                      pageSize:
                        type: integer
                        description: 每页条数。
                      current:
                        type: integer
                        description: 当前页码。
                      pageNum:
                        type: integer
                        description: 当前页码。
                      totalPages:
                        type: integer
                        description: 总页数。
                      records:
                        type: array
                        description: 当前页的 3DS 发送记录。
                        items:
                          type: object
                          properties:
                            txnOrderNo:
                              type: string
                              description: 交易订单号。
                            merchantNo:
                              type: string
                              description: 商户号。
                            cardId:
                              type: string
                              description: 卡片 ID。
                            type:
                              type: string
                              description: 3DS 认证类型，当前固定为 `OTP`。
                              enum:
                                - OTP
                              x-enum-descriptions:
                                OTP: 一次性验证码认证。
                            sendMethod:
                              type: string
                              description: 3DS 验证码发送方式。
                              enum:
                                - WEBHOOK
                                - EMAIL
                              x-enum-descriptions:
                                WEBHOOK: 通过 Webhook 发送。
                                EMAIL: 通过邮件发送。
                            sendTarget:
                              type: string
                              description: 用于发送的 Webhook 或邮件目标。
                            sendStatus:
                              type: string
                              description: 发送状态代码。
                              enum:
                                - I
                                - S
                                - F
                              x-enum-descriptions:
                                I: 发送状态代码 `I`。
                                S: 发送状态代码 `S`。
                                F: 发送状态代码 `F`。
                            sendTime:
                              type: integer
                              description: 发送时间，Unix 毫秒级时间戳。
                            card3dsValues:
                              type:
                                - string
                                - "null"
                              description: 3DS 一次性验证码。此值属于敏感认证数据，请勿记录到日志或在使用后长期存储。
                              x-onerway-value:
                                nullable: true
                                empty: true
                                when:
                                  en: Returned as `null` or an empty string when no 3DS value is available.
                                  zh: 无 3DS 验证码时返回 `null` 或空字符串。
                            currency:
                              type:
                                - string
                                - "null"
                              description: 交易币种。
                              x-onerway-value:
                                nullable: true
                                empty: true
                                when:
                                  en: Returned as `null` or an empty string when no transaction currency is
                                    available.
                                  zh: 无交易币种时返回 `null` 或空字符串。
                            amount:
                              type:
                                - number
                                - "null"
                              description: 交易金额。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: Returned as `null` when no transaction amount is available.
                                  zh: 无交易金额时返回 `null`。
                            merchantName:
                              type:
                                - string
                                - "null"
                              description: 商户名称。
                              x-onerway-value:
                                nullable: true
                                empty: true
                                when:
                                  en: Returned as `null` or an empty string when no merchant name is available.
                                  zh: 无商户名称时返回 `null` 或空字符串。
                        x-onerway-value:
                          empty: true
                          when:
                            en: Returned as an empty array when no 3DS record matches.
                            zh: 无匹配 3DS 记录时返回空数组。
                    description: 分页 3DS 发送记录。
                    x-onerway-value:
                      nullable: true
                      when:
                        en: Returned as `null` when the query fails.
                        zh: 查询失败时返回 `null`。
              examples:
                success:
                  summary: 返回 3DS 记录
                  value:
                    respCode: "20000"
                    respMsg: success
                    data:
                      totalRecords: 1
                      pageSize: 10
                      current: 1
                      pageNum: 1
                      totalPages: 1
                      records:
                        - txnOrderNo: example_transaction_order
                          merchantNo: example_merchant_no
                          cardId: example_card_id
                          type: OTP
                          sendMethod: WEBHOOK
                          sendTarget: https://example.com/webhooks/3ds
                          sendStatus: S
                          sendTime: 1767225600000
                          card3dsValues: "123456"
                          currency: USD
                          amount: 125.5
                          merchantName: Example Merchant
```