# 3DS 事件

> 接收发卡交易的 3DS 一次性验证码事件通知。

```yaml
openapi: 3.1.0
info:
  title: 3DS 事件
  version: 1.0.0
  description: 接收发卡交易的 3DS 一次性验证码事件通知。
webhooks:
  card.threeds.event:
    post:
      summary: 3DS 事件
      description: 接收发卡交易的 3DS 一次性验证码事件通知。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_id:
                  type: string
                  description: 用于去重的唯一事件标识。
                  x-onerway-signature-participation: included
                event_type:
                  type: string
                  description: 事件类型标识。
                  x-onerway-constraints:
                    - kind: values
                      text: 此 webhook 固定为 `issuing.card3dsEvent`。
                  x-onerway-signature-participation: included
                created_at:
                  type: string
                  description: 事件创建时间，ISO 8601 格式。
                  x-onerway-signature-participation: included
                version:
                  type:
                    - string
                    - "null"
                  description: 创建 webhook 订阅时选择的 API 版本。
                  x-onerway-value:
                    nullable: true
                    when:
                      en: No explicit webhook version is configured.
                      zh: 未配置明确 webhook 版本时可为 `null`。
                  x-onerway-signature-participation: included
                data:
                  type: object
                  properties:
                    cardId:
                      type: string
                      description: 卡片 ID。
                    txnOrderNo:
                      type: string
                      description: 交易订单号。
                    type:
                      type: string
                      description: 3DS 认证类型，当前固定为 `OTP`。
                      enum:
                        - OTP
                      x-enum-descriptions:
                        OTP: 一次性验证码认证。
                    card3dsValues:
                      type: string
                      description: 3DS 一次性验证码。此值属于敏感认证数据，请勿记录到日志或在使用后长期存储。
                    description:
                      type:
                        - string
                        - "null"
                      description: 3DS 事件描述。
                      x-onerway-value:
                        nullable: true
                        empty: true
                        when:
                          en: Returned as `null` or an empty string when no description is available.
                          zh: 无事件描述时返回 `null` 或空字符串。
                    transactionTime:
                      type: integer
                      description: 交易时间，Unix 毫秒级时间戳。
                    expireTime:
                      type: integer
                      description: 一次性验证码过期时间，Unix 毫秒级时间戳。
                    currency:
                      type: string
                      description: 交易币种。
                    amount:
                      type: number
                      description: 交易金额。
                    merchantName:
                      type: string
                      description: 商户名称。
                  description: 卡片 3DS 事件业务数据。
                  x-onerway-signature-participation: included
            examples:
              otp_created:
                summary: 3DS 一次性验证码已生成
                value:
                  request_id: replace_with_event_id
                  event_type: issuing.card3dsEvent
                  created_at: 2026-01-01T00:00:00Z
                  version: "1.0"
                  data:
                    cardId: example_card_id
                    txnOrderNo: example_transaction_order
                    type: OTP
                    card3dsValues: "123456"
                    description: ""
                    transactionTime: 1767225600000
                    expireTime: 1767225900000
                    currency: USD
                    amount: 125.5
                    merchantName: Example Merchant
      responses:
        "200":
          description: 成功接收并受理 3DS 事件后返回 HTTP 200 和 `respCode=20000`；响应码不是 `20000` 时
            Onerway 会重试。
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                  respMsg:
                    type: string
                required:
                  - respCode
                  - respMsg
              examples:
                return_success:
                  summary: 返回成功 JSON
                  value:
                    respCode: "20000"
                    respMsg: success
```