# 卡操作事件

> 接收开卡、冻结、解冻、充值、注销和余额退回等卡操作状态变化通知。

```yaml
openapi: 3.1.0
info:
  title: 卡操作事件
  version: 1.0.0
  description: 接收开卡、冻结、解冻、充值、注销和余额退回等卡操作状态变化通知。
webhooks:
  card.operation.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.cardOperateEvent`。
                  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:
                    operateRecordId:
                      type: integer
                      description: 操作记录 ID。
                    cardId:
                      type: integer
                      description: 卡片 ID。
                    clientRequestId:
                      type: string
                      description: 幂等请求 ID。
                    type:
                      type: string
                      description: 操作类型。
                      enum:
                        - CREATE
                        - FREEZE
                        - UNFREEZE
                        - DEPOSIT
                        - TERMINATE
                        - RETURN
                      x-enum-descriptions:
                        CREATE: 开卡操作。
                        FREEZE: 冻结操作。
                        UNFREEZE: 解冻操作。
                        DEPOSIT: 充值操作。
                        TERMINATE: 注销操作。
                        RETURN: 余额退回操作。
                    status:
                      type: string
                      description: 操作状态。
                      enum:
                        - P
                        - S
                        - F
                      x-enum-descriptions:
                        P: 处理中。
                        S: 成功。
                        F: 失败。
                    remark:
                      type:
                        - string
                        - "null"
                      description: 操作备注。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: No remark is available.
                          zh: 无备注时返回 `null`。
                    amount:
                      type:
                        - number
                        - "null"
                      description: 操作金额。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: The operation has no amount.
                          zh: 该操作无金额时返回 `null`。
                    currency:
                      type:
                        - string
                        - "null"
                      description: 操作币种。
                      x-onerway-value:
                        nullable: true
                        when:
                          en: The operation has no amount currency.
                          zh: 该操作无金额币种时返回 `null`。
                    feeList:
                      type: array
                      description: 费用明细列表。
                      items:
                        type: object
                        properties:
                          feeType:
                            type: string
                            description: 费用类型。
                          feeAmount:
                            type: number
                            description: 费用金额。
                          feeCurrency:
                            type: string
                            description: 费用币种。
                      x-onerway-value:
                        empty: true
                        when:
                          en: Returned as an empty array when no fee applies.
                          zh: 无费用时返回空数组。
                  description: 卡操作事件业务数据。
                  x-onerway-signature-participation: included
            examples:
              deposit_success:
                summary: 充值成功
                value:
                  request_id: replace_with_event_id
                  event_type: issuing.cardOperateEvent
                  created_at: 2026-01-01T00:00:00Z
                  version: "1.0"
                  data:
                    operateRecordId: 200001
                    cardId: 100001
                    clientRequestId: REQ_20260101_001
                    type: DEPOSIT
                    status: S
                    remark: null
                    amount: 100
                    currency: USD
                    feeList:
                      - feeType: DEPOSIT
                        feeAmount: 1
                        feeCurrency: USD
      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
```