# Ethoca 预警通知 > 接收包含预警标识、原交易、争议信息和处理状态的 Ethoca 预警回调报文。 ```yaml openapi: 3.1.0 info: title: Ethoca 预警通知 version: 1.0.0 description: 接收包含预警标识、原交易、争议信息和处理状态的 Ethoca 预警回调报文。 webhooks: ethoca.alert.created: post: summary: Ethoca 预警通知 description: 接收包含预警标识、原交易、争议信息和处理状态的 Ethoca 预警回调报文。 requestBody: required: true content: application/json: schema: type: object properties: id: type: number description: Onerway 预警通知记录 ID，用于定位这条预警通知记录。 x-onerway-constraints: - kind: rule text: 该值为大整数；JavaScript 系统中建议按字符串或 64-bit integer 保存，避免精度丢失。 merchantNo: type: string description: Onerway 分配的商户号，标识接收该预警的商户账户。 x-onerway-constraints: - kind: rule text: 通知中可能以 JSON number 形式返回该值；建议按字符串归一化存储和比对，以便与其他 Onerway API 口径一致。 ethocaId: type: string description: Ethoca 预警唯一标识；后续调用 Ethoca 预警处理接口提交处理结果时使用该值。 alertType: type: string description: 预警类型，表示本次通知属于客户争议、欺诈预警还是拒付预警。 enum: - CustomerDispute - FraudAlert - ChargebackAlert x-enum-descriptions: CustomerDispute: 客户争议预警。 FraudAlert: 欺诈预警。 ChargebackAlert: 拒付预警。 alertTime: type: string description: 预警生成时间，格式为 `yyyy-MM-dd HH:mm:ss`。 alertAge: type: - number - "null" description: 预警从生成到当前通知产生时已经过的时间；商户可据此判断预警已发生多久和处置优先级。 x-onerway-constraints: - kind: rule text: 单位为小时。 x-onerway-value: nullable: true when: en: Can return `0` or `null`. zh: 可能返回 `0`，也可能为 `null`，商户应兼容空值。 txnTime: type: string description: 原交易时间，格式为 `yyyy-MM-dd HH:mm:ss`。 txnAmount: type: number description: 原交易金额。 txnCurrency: type: string description: 原交易币种，符合 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) 标准。 resellerSubMerchantId: type: - string - "null" description: 代理运营商的子商户标识。 x-onerway-value: nullable: true empty: true when: en: Has a value for agency sub-merchant alerts. Regular merchant alerts can be empty. zh: 代理运营商子商户预警通知中有值；普通商户预警通知可能为空。 billDesc: type: string description: 商户账单描述，用于将预警匹配到持卡人账单上展示的商户信息。 arn: type: string description: 收单行参考号（ARN），可用于对账、预警核对与争议处理。 submitOutcomeStatus: type: string description: 预警处理结果提交状态，表示该预警是否仍等待处理，或处理结果是否已被接收；不要把本字段等同于最终 `outcome`。 enum: - PENDING_OUTCOME - OUTCOME_RECEIVED x-enum-descriptions: PENDING_OUTCOME: 待处理；该预警仍等待处理结果提交。 OUTCOME_RECEIVED: 已处理；该预警的处理结果已被接收。 outcome: type: - string - "null" description: 商户对该预警的处理结果。 enum: - stopped - partially_stopped - previously_cancelled - missed - notfound - account_suspended - in_progress - shipper_contacted - other - resolved - previously_refunded - unresolved_dispute - null x-enum-descriptions: stopped: 订单已停止。 partially_stopped: 订单部分停止。 previously_cancelled: 交易已被取消。 missed: 已过期，订单已发货或服务已消费。 notfound: 未找到相关订单。 account_suspended: 账户已被暂停。 in_progress: 正在处理该请求。 shipper_contacted: 已联系发货方并尝试拦截货物。 other: 其他未列出的情况。 resolved: 已解决。 previously_refunded: 已退款。 unresolved_dispute: 未解决的争议。 x-onerway-value: nullable: true empty: true when: en: Returns `null` before the alert is handled or before the outcome is synchronized back. zh: 预警尚未处理或处理结果尚未回填时为 `null`。 outcomeUpdatedTime: type: - string - "null" description: 预警处理状态更新时间，格式为 `yyyy-MM-dd HH:mm:ss`。 x-onerway-value: nullable: true empty: true when: en: Returns `null` before the alert outcome status is updated. zh: 预警处理状态尚未更新时为 `null`。 refundStatus: type: - string - "null" description: 与该预警处理结果对应的退款状态。 enum: - refunded - not refunded - not settled - null x-enum-descriptions: refunded: 已完成退款。 not refunded: 未进行退款。 not settled: 退款处理中。 x-onerway-value: nullable: true empty: true when: en: Returns `null` before the alert is handled or before refund status is synchronized back. zh: 预警尚未处理或退款状态尚未回填时为 `null`。 createOpr: type: string description: 记录元数据：创建该预警记录的账号或系统标识。不要使用该字段判断预警状态或需要执行的业务动作。 createTime: type: string description: 该预警记录在 Onerway 创建的时间，格式为 `yyyy-MM-dd HH:mm:ss`。 updateOpr: type: string description: 记录元数据：最近一次更新该预警记录的账号或系统标识。不要使用该字段判断预警状态或需要执行的业务动作。 updateTime: type: string description: 该预警记录在 Onerway 最近一次更新的时间，格式为 `yyyy-MM-dd HH:mm:ss`。 issuer: type: string description: 发卡机构标识；具体取值格式由预警网络返回。 cardNumber: type: string description: 预警关联的交易卡号信息。 x-onerway-constraints: - kind: rule text: 若实际返回完整 PAN，商户应按 PCI DSS 要求处理，不应在日志、工单或普通数据库中明文保存。 ethocaMerchantId: type: string description: Ethoca 商户标识，用于在 Ethoca 预警网络中匹配商户与账单描述。 mcc: type: string description: 商户类别代码 MCC，通常为四位数字，用于表示商户经营类别。 transactionType: type: string description: 原交易类型或交易场景。 initiatedBy: type: string description: 预警发起方，通常为卡组织、发卡机构或相关预警网络标识。 liability: type: string description: 预警或争议相关责任标识。该字段用于辅助理解预警责任信息，不应替代商户对 `alertType`、`outcome` 与退款状态的处理判断。 authCode: type: string description: 原交易授权码，通常由发卡行或收单网络在授权成功后返回。 integratorMemberId: type: string description: 集成商会员编号，用于标识预警网络侧的集成成员关系。 transactionId: type: string description: 原交易在 Onerway 侧的交易号，用于关联交易查询、退款、拒付和预警处理记录。 chargebackReasonCode: type: - string - "null" description: 拒付或争议原因代码，由卡组织或预警网络提供。 x-onerway-value: nullable: true empty: true when: en: Usually has a value for chargeback-related alerts. It can be empty outside a chargeback context or when the alert network does not provide it. zh: 拒付相关预警中通常有值；非拒付语境或预警网络未提供时可能为空。 chargebackAmount: type: - number - "null" description: 预警关联的拒付或争议金额，可能小于或等于原交易金额。 x-onerway-value: nullable: true when: en: Usually has a value for chargeback-related alerts. It can be `null` outside a chargeback context or when the alert network does not provide the amount. zh: 拒付相关预警中通常有值；非拒付语境或预警网络未提供金额时可能为空。 chargebackCurrency: type: - string - "null" description: 拒付或争议金额币种，符合 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) 标准。 x-onerway-value: nullable: true empty: true when: en: Usually has a value for chargeback-related alerts. It can be empty outside a chargeback context or when the alert network does not provide the currency. zh: 拒付相关预警中通常有值；非拒付语境或预警网络未提供币种时可能为空。 examples: ethoca_alert_created: summary: Ethoca 预警通知 value: id: 1234567890 merchantNo: replace_with_merchant_no ethocaId: replace_with_ethoca_id alertType: ChargebackAlert alertTime: 2025-04-14 14:26:21 alertAge: 12 txnTime: 2025-04-13 09:15:00 txnAmount: 100 txnCurrency: USD resellerSubMerchantId: null billDesc: DEMO STORE arn: replace_with_acquirer_reference_number submitOutcomeStatus: PENDING_OUTCOME outcome: null outcomeUpdatedTime: null refundStatus: null createOpr: SYSTEM createTime: 2025-04-14 14:26:21 updateOpr: SYSTEM updateTime: 2025-04-14 14:26:21 issuer: replace_with_issuer_identifier cardNumber: replace_with_card_number ethocaMerchantId: replace_with_ethoca_merchant_id mcc: "5812" transactionType: eCommerce initiatedBy: replace_with_alert_initiator liability: no authCode: replace_with_authorization_code integratorMemberId: replace_with_integrator_member_id transactionId: replace_with_transaction_id chargebackReasonCode: "4837" chargebackAmount: 100 chargebackCurrency: USD responses: "200": description: 成功接收并受理 webhook 后返回 HTTP 200。 ```