# Fraud alert webhook

> Receive fraud alert payloads with the fraud type, original transaction, chargeback flag, and refund status.

```yaml
openapi: 3.1.0
info:
  title: Fraud alert webhook
  version: 1.0.0
  description: Receive fraud alert payloads with the fraud type, original
    transaction, chargeback flag, and refund status.
webhooks:
  fraud.alert:
    post:
      summary: Fraud alert webhook
      description: Receive fraud alert payloads with the fraud type, original
        transaction, chargeback flag, and refund status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notificationId:
                  type: string
                  description: Unique identifier of the fraud alert, used for deduplication,
                    idempotent processing, and later investigation.
                  x-onerway-constraints:
                    - kind: rule
                      text: This value is a large-ID-style string. Preserve it as a string in
                        JavaScript systems to avoid precision loss.
                  x-onerway-signature-participation: included
                fraudType:
                  type: string
                  description: Fraud type identified by this notification.
                  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 card.
                    Lost Fraud: Fraud involving a lost card.
                    Stolen: Stolen card.
                    Stolen Fraud: Fraud involving a stolen card.
                    NRI: Never Received Issue.
                    Never Received Issue: Fraud involving a card that was never received.
                    Fraud Application: Fraud application.
                    Fraudulent Application: Fraudulent card application.
                    Counterfeit: Counterfeit card.
                    Counterfeit Card Fraud: Counterfeit card fraud.
                    Miscellaneous: Miscellaneous fraud type.
                    Fraudulent Use of Account Number: Fraudulent use of account number.
                    Card Not Present Fraud: Card-not-present fraud.
                    Account Takeover Fraud: Account takeover fraud.
                    First-Party Fraud: First-party fraud.
                    Bust-out Collusive Merchant: Bust-out collusive merchant.
                    Incorrect Processing: Incorrect processing.
                    Merchant Misrepresentation: Merchant misrepresentation.
                    Manipulation of Account Holder: Manipulation of account holder.
                    Manipulation of Cardholder: Manipulation of cardholder.
                    Modification of Payment Order: Modification of payment order.
                  x-onerway-signature-participation: included
                createTime:
                  type: string
                  description: Fraud alert creation time in `yyyy-MM-dd HH:mm:ss` format.
                  x-onerway-signature-participation: included
                originTransactionId:
                  type: string
                  description: Original Onerway transaction ID associated with this fraud alert.
                    Use it to reconcile the source transaction through payment,
                    chargeback, or refund queries.
                  x-onerway-constraints:
                    - kind: rule
                      text: This value is a large-ID-style string. Preserve it as a string in
                        JavaScript systems to avoid precision loss.
                  x-onerway-signature-participation: included
                txnAmount:
                  type: string
                  description: Legacy amount converted to the settlement currency.
                  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: Legacy settlement currency field.
                  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: Payment method or card brand used by the original transaction.
                  x-onerway-signature-participation: included
                chargebackStatus:
                  type: string
                  description: Chargeback flag of the original transaction.
                  enum:
                    - "0"
                    - "1"
                  x-enum-descriptions:
                    "0": The original transaction has no chargeback.
                    "1": The original transaction has a chargeback.
                  x-onerway-constraints:
                    - kind: consistency
                      text: This field is a `0` / `1` flag and is different from the chargeback
                        lifecycle status returned by [Query
                        chargebacks](/payments/api-reference/endpoints/query-chargebacks).
                  x-onerway-signature-participation: included
                refundStatus:
                  type: string
                  description: Refund status of the original transaction.
                  enum:
                    - "0"
                    - "1"
                    - "2"
                  x-enum-descriptions:
                    "0": Not refunded.
                    "1": Fully refunded.
                    "2": Partially refunded.
                  x-onerway-signature-participation: included
                merchantNo:
                  type: string
                  description: Merchant number assigned by Onerway, identifying the merchant
                    account receiving this fraud alert.
                  x-onerway-signature-participation: included
                merchantTxnId:
                  type: string
                  description: Merchant-side transaction reference for the original transaction,
                    returned consistently for reconciliation, deduplication, and
                    order association.
                  x-onerway-signature-participation: included
                sign:
                  type: string
                  description: Legacy signature string kept for compatibility. It is computed with
                    only the first enabled key and can mismatch your configured
                    key during key rotation; verify notifications with the
                    `X-Rh-Signature` header instead.
                  x-onerway-constraints:
                    - kind: rule
                      text: Exclude `sign` itself from the canonical string when verifying this
                        webhook.
                  x-onerway-signature-participation: signature-field
            examples:
              fraud_notification_default:
                summary: Fraud alert
                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: Return HTTP 200 with `20000` in the response body after the fraud
            alert is received and accepted.
          content:
            text/plain:
              schema:
                type: string
              examples:
                return_20000:
                  summary: Return 20000
                  description: Return the specific success content expected by this webhook.
                  value: "20000"
```
