# 欺诈预警

> 接收包含欺诈类型、源交易、拒付标志和退款状态的欺诈预警回调报文。

```yaml
openapi: 3.1.0
info:
  title: 欺诈预警
  version: 1.0.0
  description: 接收包含欺诈类型、源交易、拒付标志和退款状态的欺诈预警回调报文。
webhooks:
  fraud.alert:
    post:
      summary: 欺诈预警
      description: 接收包含欺诈类型、源交易、拒付标志和退款状态的欺诈预警回调报文。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notificationId:
                  type: string
                  description: 欺诈预警通知的唯一标识，用于商户去重、幂等处理和后续排查。
                  x-onerway-constraints:
                    - kind: rule
                      text: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。
                  x-onerway-signature-participation: included
                fraudType:
                  type: string
                  description: 欺诈类型，表示本次通知识别到的欺诈风险类型。
                  enum:
                    - Lost
                    - Lost Fraud
                    - Stolen
                    - Stolen Fraud
                    - NRI
                    - Never Received Issue
                    - Fraud Application
                    - Fraudulent Application
                    - Counterfeit
                    - Counterfeit Card Fraud
                    - Miscellaneous
                    - Fraudulent Use of Account Number
                    - Card Not Present Fraud
                    - Account Takeover Fraud
                    - First-Party Fraud
                    - Bust-out Collusive Merchant
                    - Incorrect Processing
                    - Merchant Misrepresentation
                    - Manipulation of Account Holder
                    - Manipulation of Cardholder
                    - Modification of Payment Order
                  x-enum-descriptions:
                    Lost: 卡片丢失。
                    Lost Fraud: 涉及遗失卡片的欺诈。
                    Stolen: 卡片被盗。
                    Stolen Fraud: 涉及被盗卡片的欺诈。
                    NRI: 未收到卡片（Never Received Issue）。
                    Never Received Issue: 涉及持卡人未收到的卡片的欺诈。
                    Fraud Application: 欺诈申请。
                    Fraudulent Application: 以欺诈方式申请卡片。
                    Counterfeit: 伪卡。
                    Counterfeit Card Fraud: 伪卡欺诈。
                    Miscellaneous: 其他类型。
                    Fraudulent Use of Account Number: 账号欺诈使用。
                    Card Not Present Fraud: 无卡欺诈。
                    Account Takeover Fraud: 账户盗用欺诈。
                    First-Party Fraud: 第一方欺诈。
                    Bust-out Collusive Merchant: 商户合谋欺诈。
                    Incorrect Processing: 错误处理。
                    Merchant Misrepresentation: 商户虚假陈述。
                    Manipulation of Account Holder: 账户持有人操纵。
                    Manipulation of Cardholder: 持卡人操纵。
                    Modification of Payment Order: 支付指令篡改。
                  x-onerway-signature-participation: included
                createTime:
                  type: string
                  description: 欺诈预警通知生成时间，格式 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-signature-participation: included
                originTransactionId:
                  type: string
                  description: 欺诈预警通知关联的源交易 ID，可用于回到交易查询、拒付查询或退款查询核对原交易状态。
                  x-onerway-constraints:
                    - kind: rule
                      text: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。
                  x-onerway-signature-participation: included
                txnAmount:
                  type: string
                  description: 旧版结算金额字段，表示换算到结算币种后的金额。
                  deprecated: true
                  x-onerway-deprecated:
                    description:
                      en: Do not rely on this field for the settled amount. The actual settlement
                        amount follows the corresponding settlement batch,
                        detail, or report.
                      zh: 请勿依赖本字段判断到账金额。实际结算金额按结算批次结算，以对应批次的结算明细 / 结算报表为准。
                  x-onerway-signature-participation: included
                txnCurrency:
                  type: string
                  description: 旧版结算币种字段。
                  deprecated: true
                  x-onerway-deprecated:
                    description:
                      en: Do not rely on this field for the settlement currency. The settlement
                        currency follows the settlement configuration pre-agreed
                        between the merchant and Onerway.
                      zh: 请勿依赖本字段判断结算币种。结算币种以商户与 Onerway 预先约定的结算配置为准。
                  x-onerway-signature-participation: included
                cardBrand:
                  type: string
                  description: 源交易使用的支付方式或卡品牌。
                  x-onerway-signature-participation: included
                chargebackStatus:
                  type: string
                  description: 源交易的拒付标志。
                  enum:
                    - "0"
                    - "1"
                  x-enum-descriptions:
                    "0": 源交易无拒付。
                    "1": 源交易有拒付。
                  x-onerway-constraints:
                    - kind: consistency
                      text: 此处为 `0` / `1`
                        标志，与[查询拒付记录接口](/zh/payments/api-reference/endpoints/query-chargebacks)中表示拒付生命周期阶段的
                        `chargebackStatus` 语义不同。
                  x-onerway-signature-participation: included
                refundStatus:
                  type: string
                  description: 源交易退款状态。
                  enum:
                    - "0"
                    - "1"
                    - "2"
                  x-enum-descriptions:
                    "0": 未退款。
                    "1": 全部退款。
                    "2": 部分退款。
                  x-onerway-signature-participation: included
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号，标识接收该欺诈预警通知的商户账户。
                  x-onerway-signature-participation: included
                merchantTxnId:
                  type: string
                  description: 商户为源交易生成的商户交易号，稳定返回，可用于商户侧对账、去重和关联原始订单。
                  x-onerway-signature-participation: included
                sign:
                  type: string
                  description: 兼容保留的签名字符串：仅使用第一个启用的密钥计算，密钥轮换期间可能与商户配置的密钥不一致；请改用 `X-Rh-Signature`
                    header 验签。
                  x-onerway-constraints:
                    - kind: rule
                      text: 验签时不要把 `sign` 自身作为待签名字段。
                  x-onerway-signature-participation: signature-field
            examples:
              fraud_notification_default:
                summary: 欺诈预警
                value:
                  notificationId: replace_with_fraud_notification_id
                  fraudType: Fraudulent Use of Account Number
                  createTime: 2025-08-04 10:54:04
                  originTransactionId: replace_with_origin_transaction_id
                  txnAmount: "16.41"
                  txnCurrency: USD
                  cardBrand: VISA
                  chargebackStatus: "0"
                  refundStatus: "0"
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  sign: replace_with_sha256_signature
      responses:
        "200":
          description: 成功接收并受理欺诈预警通知后，返回 HTTP 200，并在响应 body 中返回 `20000`。
          content:
            text/plain:
              schema:
                type: string
              examples:
                return_20000:
                  summary: 返回 20000
                  description: 返回此 webhook 期望的指定成功内容。
                  value: "20000"
```