# Card transaction event

> Receive card transaction event notifications for authorization, reversal, settlement, refund, and verification events.

```yaml
openapi: 3.1.0
info:
  title: Card transaction event
  version: 1.0.0
  description: Receive card transaction event notifications for authorization,
    reversal, settlement, refund, and verification events.
webhooks:
  card.transaction.event:
    post:
      summary: Card transaction event
      description: Receive card transaction event notifications for authorization,
        reversal, settlement, refund, and verification events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_id:
                  type: string
                  description: Unique event identifier for deduplication.
                  x-onerway-signature-participation: included
                event_type:
                  type: string
                  description: Event type identifier.
                  x-onerway-constraints:
                    - kind: values
                      text: Fixed to `issuing.cardTransactionEvent` for this webhook.
                  x-onerway-signature-participation: included
                created_at:
                  type: string
                  description: Event creation time in ISO 8601 format.
                  x-onerway-signature-participation: included
                version:
                  type:
                    - string
                    - "null"
                  description: Webhook API version selected when the subscription is created.
                  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: Transaction type.
                      enum:
                        - AUTHORIZATION
                        - REVERSAL
                        - CLEARING
                        - REFUND
                        - VERIFICATION
                      x-enum-descriptions:
                        AUTHORIZATION: Authorization transaction.
                        REVERSAL: Reversal transaction.
                        CLEARING: Clearing transaction.
                        REFUND: Refund transaction.
                        VERIFICATION: Verification transaction.
                    txnStatus:
                      type: string
                      description: Transaction status.
                      enum:
                        - S
                        - F
                        - P
                      x-enum-descriptions:
                        S: Succeeded.
                        F: Failed.
                        P: Processing.
                    txnOrderNo:
                      type: string
                      description: Transaction order number.
                    originTxnOrderNo:
                      type:
                        - string
                        - "null"
                      description: Original transaction order number.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No original transaction applies.
                          zh: 无原交易时返回 `null`。
                    originTxnOrderNoForRefund:
                      type:
                        - string
                        - "null"
                      description: Original payment order number for refund.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No original payment order applies for refund.
                          zh: 无退款原支付订单时返回 `null`。
                    cardId:
                      type: string
                      description: Card ID or masked card identifier returned by the transaction
                        event.
                    authTime:
                      type:
                        - integer
                        - "null"
                      description: Authorization time, as a UTC timestamp in milliseconds.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No authorization time applies.
                          zh: 无授权时间时返回 `null`。
                    authorizationCode:
                      type:
                        - string
                        - "null"
                      description: Authorization code.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No authorization code applies.
                          zh: 无授权码时返回 `null`。
                    authMessageDesc:
                      type:
                        - string
                        - "null"
                      description: Authorization description.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No authorization description applies.
                          zh: 无授权说明时返回 `null`。
                    transactionAmount:
                      type: number
                      description: Transaction amount.
                    transactionCurrency:
                      type: string
                      description: Transaction currency.
                    transactionTime:
                      type: integer
                      description: Transaction time, as a UTC timestamp in milliseconds.
                    cardAmount:
                      type: number
                      description: Card amount.
                    cardCurrency:
                      type: string
                      description: Card currency.
                    settleAmount:
                      type:
                        - number
                        - "null"
                      description: Settlement amount.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No settlement amount applies.
                          zh: 无清算金额时返回 `null`。
                    settleCurrency:
                      type:
                        - string
                        - "null"
                      description: Settlement currency.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No settlement currency applies.
                          zh: 无清算币种时返回 `null`。
                    settleTime:
                      type:
                        - integer
                        - "null"
                      description: Settlement time, as a UTC timestamp in milliseconds.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No settlement time applies.
                          zh: 无清算时间时返回 `null`。
                    transactionFee:
                      type:
                        - number
                        - "null"
                      description: Transaction fee.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No transaction fee applies.
                          zh: 无交易手续费时返回 `null`。
                    transactionFeeCurrency:
                      type:
                        - string
                        - "null"
                      description: Transaction fee currency.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No transaction fee applies.
                          zh: 无交易手续费时返回 `null`。
                    crossBorderFee:
                      type:
                        - number
                        - "null"
                      description: Cross-border fee.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No cross-border fee applies.
                          zh: 无跨境手续费时返回 `null`。
                    crossBorderFeeCurrency:
                      type:
                        - string
                        - "null"
                      description: Cross-border fee currency.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No cross-border fee applies.
                          zh: 无跨境手续费时返回 `null`。
                    exchangeFee:
                      type:
                        - number
                        - "null"
                      description: Exchange fee.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No exchange fee applies.
                          zh: 无换汇手续费时返回 `null`。
                    exchangeFeeCurrency:
                      type:
                        - string
                        - "null"
                      description: Exchange fee currency.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No exchange fee applies.
                          zh: 无换汇手续费时返回 `null`。
                    merchantId:
                      type:
                        - string
                        - "null"
                      description: Merchant ID from the card transaction.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant descriptor is available.
                          zh: 无商户描述信息时返回 `null`。
                    merchantName:
                      type:
                        - string
                        - "null"
                      description: Merchant name.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant descriptor is available.
                          zh: 无商户描述信息时返回 `null`。
                    merchantCountry:
                      type:
                        - string
                        - "null"
                      description: Merchant country.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant country is available.
                          zh: 无商户国家信息时返回 `null`。
                    merchantCountryCode:
                      type:
                        - string
                        - "null"
                      description: Merchant country code.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant country code is available.
                          zh: 无商户国家代码时返回 `null`。
                    merchantStateProvince:
                      type:
                        - string
                        - "null"
                      description: Merchant state or province.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant state or province is available.
                          zh: 无商户州 / 省信息时返回 `null`。
                    merchantCity:
                      type:
                        - string
                        - "null"
                      description: Merchant city.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant city is available.
                          zh: 无商户城市信息时返回 `null`。
                    merchantPostalCode:
                      type:
                        - string
                        - "null"
                      description: Merchant postal code.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant postal code is available.
                          zh: 无商户邮编时返回 `null`。
                    merchantMccCode:
                      type:
                        - string
                        - "null"
                      description: Merchant MCC code.
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No merchant MCC is available.
                          zh: 无商户 MCC 时返回 `null`。
                  description: Card transaction event business data.
                  x-onerway-signature-participation: included
            examples:
              authorization_success:
                summary: Authorization succeeded
                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: Return HTTP 200 with `respCode=20000` after the card transaction
            event is received and accepted. Onerway retries when the response
            code is not `20000`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                  respMsg:
                    type: string
                required:
                  - respCode
                  - respMsg
              examples:
                return_success:
                  summary: Return success JSON
                  value:
                    respCode: "20000"
                    respMsg: success
```