# 卡交易事件

> 接收授权、撤销、结算、退款和验证等卡交易事件通知。

```yaml
openapi: 3.1.0
info:
  title: 卡交易事件
  version: 1.0.0
  description: 接收授权、撤销、结算、退款和验证等卡交易事件通知。
webhooks:
  card.transaction.event:
    post:
      summary: 卡交易事件
      description: 接收授权、撤销、结算、退款和验证等卡交易事件通知。
      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.cardTransactionEvent`。
                  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 版本时可为空。
                  x-onerway-signature-participation: included
                data:
                  type: object
                  properties:
                    txnType:
                      type: string
                      description: 交易类型。
                      enum:
                        - AUTHORIZATION
                        - REVERSAL
                        - CLEARING
                        - REFUND
                        - VERIFICATION
                      x-enum-descriptions:
                        AUTHORIZATION: 授权交易。
                        REVERSAL: 撤销交易。
                        CLEARING: 清算交易。
                        REFUND: 退款交易。
                        VERIFICATION: 验证交易。
                    txnStatus:
                      type: string
                      description: 交易状态。
                      enum:
                        - S
                        - F
                        - P
                      x-enum-descriptions:
                        S: 成功。
                        F: 失败。
                        P: 处理中。
                    txnOrderNo:
                      type: string
                      description: 交易订单号。
                    originTxnOrderNo:
                      type:
                        - string
                        - "null"
                      description: 原交易订单号。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No original transaction applies.
                          zh: 无原交易时返回 `null`。
                    originTxnOrderNoForRefund:
                      type:
                        - string
                        - "null"
                      description: 退款原支付订单号。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No original payment order applies for refund.
                          zh: 无退款原支付订单时返回 `null`。
                    cardId:
                      type: string
                      description: 交易事件返回的卡片 ID 或脱敏卡标识。
                    authTime:
                      type:
                        - integer
                        - "null"
                      description: 授权时间，UTC 毫秒级时间戳。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No authorization time applies.
                          zh: 无授权时间时返回 `null`。
                    authorizationCode:
                      type:
                        - string
                        - "null"
                      description: 授权码。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No authorization code applies.
                          zh: 无授权码时返回 `null`。
                    authMessageDesc:
                      type:
                        - string
                        - "null"
                      description: 授权说明。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No authorization description applies.
                          zh: 无授权说明时返回 `null`。
                    transactionAmount:
                      type: number
                      description: 交易金额。
                    transactionCurrency:
                      type: string
                      description: 交易币种。
                    transactionTime:
                      type: integer
                      description: 交易时间，UTC 毫秒级时间戳。
                    cardAmount:
                      type: number
                      description: 卡片金额。
                    cardCurrency:
                      type: string
                      description: 卡片币种。
                    settleAmount:
                      type:
                        - number
                        - "null"
                      description: 清算金额。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No settlement amount applies.
                          zh: 无清算金额时返回 `null`。
                    settleCurrency:
                      type:
                        - string
                        - "null"
                      description: 清算币种。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No settlement currency applies.
                          zh: 无清算币种时返回 `null`。
                    settleTime:
                      type:
                        - integer
                        - "null"
                      description: 清算时间，UTC 毫秒级时间戳。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No settlement time applies.
                          zh: 无清算时间时返回 `null`。
                    transactionFee:
                      type:
                        - number
                        - "null"
                      description: 交易手续费。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No transaction fee applies.
                          zh: 无交易手续费时返回 `null`。
                    transactionFeeCurrency:
                      type:
                        - string
                        - "null"
                      description: 交易手续费币种。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No transaction fee applies.
                          zh: 无交易手续费时返回 `null`。
                    crossBorderFee:
                      type:
                        - number
                        - "null"
                      description: 跨境手续费。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No cross-border fee applies.
                          zh: 无跨境手续费时返回 `null`。
                    crossBorderFeeCurrency:
                      type:
                        - string
                        - "null"
                      description: 跨境手续费币种。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No cross-border fee applies.
                          zh: 无跨境手续费时返回 `null`。
                    exchangeFee:
                      type:
                        - number
                        - "null"
                      description: 换汇手续费。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No exchange fee applies.
                          zh: 无换汇手续费时返回 `null`。
                    exchangeFeeCurrency:
                      type:
                        - string
                        - "null"
                      description: 换汇手续费币种。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No exchange fee applies.
                          zh: 无换汇手续费时返回 `null`。
                    merchantId:
                      type:
                        - string
                        - "null"
                      description: 卡交易中的商户 ID。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant descriptor is available.
                          zh: 无商户描述信息时返回 `null`。
                    merchantName:
                      type:
                        - string
                        - "null"
                      description: 商户名称。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant descriptor is available.
                          zh: 无商户描述信息时返回 `null`。
                    merchantCountry:
                      type:
                        - string
                        - "null"
                      description: 商户国家。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant country is available.
                          zh: 无商户国家信息时返回 `null`。
                    merchantCountryCode:
                      type:
                        - string
                        - "null"
                      description: 商户国家代码。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant country code is available.
                          zh: 无商户国家代码时返回 `null`。
                    merchantStateProvince:
                      type:
                        - string
                        - "null"
                      description: 商户州 / 省。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant state or province is available.
                          zh: 无商户州 / 省信息时返回 `null`。
                    merchantCity:
                      type:
                        - string
                        - "null"
                      description: 商户城市。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant city is available.
                          zh: 无商户城市信息时返回 `null`。
                    merchantPostalCode:
                      type:
                        - string
                        - "null"
                      description: 商户邮编。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant postal code is available.
                          zh: 无商户邮编时返回 `null`。
                    merchantMccCode:
                      type:
                        - string
                        - "null"
                      description: 商户 MCC。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant MCC is available.
                          zh: 无商户 MCC 时返回 `null`。
                  description: 卡交易事件业务数据。
                  x-onerway-signature-participation: included
            examples:
              authorization_success:
                summary: 授权成功
                value:
                  request_id: replace_with_event_id
                  event_type: issuing.cardTransactionEvent
                  created_at: 2026-01-01T00:00:00Z
                  version: "1.0"
                  data:
                    txnType: AUTHORIZATION
                    txnStatus: S
                    txnOrderNo: TXN20260101001
                    originTxnOrderNo: null
                    originTxnOrderNoForRefund: null
                    cardId: "100001"
                    authTime: 1735689600000
                    authorizationCode: AUTH001
                    authMessageDesc: Approved
                    transactionAmount: 50
                    transactionCurrency: USD
                    transactionTime: 1735689600000
                    cardAmount: 50
                    cardCurrency: USD
                    settleAmount: 50
                    settleCurrency: USD
                    settleTime: 1735776000000
                    transactionFee: 0.5
                    transactionFeeCurrency: USD
                    crossBorderFee: null
                    crossBorderFeeCurrency: null
                    exchangeFee: null
                    exchangeFeeCurrency: null
                    merchantId: example_merchant_id
                    merchantName: Example Merchant
                    merchantCountry: United States
                    merchantCountryCode: US
                    merchantStateProvince: WA
                    merchantCity: Seattle
                    merchantPostalCode: "98101"
                    merchantMccCode: "5411"
      responses:
        "200":
          description: 成功接收并受理卡交易事件后返回 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
```