> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting fraud

> Report confirmed fraud and let Clausum block, open a case, and notify the chain.

<Note>
  Report fraud against your assigned API host (`$CLAUSUM_API_BASE`). See [Access & environments](/concepts/access-and-environments).
</Note>

When fraud is confirmed — a chargeback arrives, an account takeover is detected, or your team confirms a case — report it to Clausum with a single call. Clausum then does the heavy lifting automatically.

## What happens on report

<Steps>
  <Step title="Transaction flagged">
    The matching transaction is marked `is_fraudulent` with the reason and timestamp.
  </Step>

  <Step title="Case opened">
    A case (expediente) is created with a generated `reference_number`, priority derived from amount and reason, and a mapped incident type.
  </Step>

  <Step title="Blocklists updated">
    The offending email (`block`), card BIN (`flag`, for card testing / friendly fraud), and IP (`block`) are added to your blocklists and linked to the case.
  </Step>

  <Step title="Chain notified">
    Email alerts go to the configured participants (merchant, acquirer, issuer, compliance) and the `fraud.detected` webhook fires.
  </Step>
</Steps>

## Authentication

Requires a secret key with the `fraud:report` permission.

```bash theme={null}
Authorization: Bearer clm_sk_xxx
```

## Identify the transaction

Provide **one** of these to reference an existing transaction:

* `transaction_id` — Clausum internal transaction UUID.
* `payment_id` + `provider` — e.g. `pi_3Nxyz` + `stripe` (same id as assess `payment_id`).
* `external_transaction_id` + `provider` — deprecated alias of `payment_id`.

If no transaction exists yet, provide enough inline data (`amount` + `email`) and Clausum creates one.

## Examples

<CodeGroup>
  ```bash By external id theme={null}
  curl -X POST "$CLAUSUM_API_BASE/api/v1/report-fraud" \
    -H "Authorization: Bearer $CLAUSUM_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "external_transaction_id": "pi_3Nxyz",
      "provider": "stripe",
      "reason": "chargeback",
      "description": "Issuer chargeback, reason code 10.4",
      "ip_address": "201.150.10.22"
    }'
  ```

  ```bash Inline data theme={null}
  curl -X POST "$CLAUSUM_API_BASE/api/v1/report-fraud" \
    -H "Authorization: Bearer $CLAUSUM_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 89900,
      "currency": "USD",
      "email": "fraudster@example.com",
      "card_bin": "411111",
      "card_last4": "4242",
      "reason": "card_testing"
    }'
  ```
</CodeGroup>

## Reasons

| `reason`           | Use for                                             |
| ------------------ | --------------------------------------------------- |
| `chargeback`       | Issuer chargeback / dispute                         |
| `friendly_fraud`   | Legitimate cardholder claiming fraud                |
| `card_testing`     | Small probing transactions to validate stolen cards |
| `account_takeover` | Compromised customer account                        |
| `identity_theft`   | Stolen identity used to transact                    |
| `other`            | Anything else                                       |

## Controlling notifications

Use the `notify` object to decide which parties are alerted. Attach evidence with `evidence_urls`.

```json theme={null}
{
  "external_transaction_id": "pi_3Nxyz",
  "provider": "stripe",
  "reason": "chargeback",
  "evidence_urls": ["https://files.example.com/chargeback.pdf"],
  "notify": { "merchant": true, "acquirer": true, "issuer": true, "compliance": true }
}
```

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "case": { "id": "b1f2...", "reference_number": "CLM-LX9A2B", "status": "received", "priority": "high" },
    "transaction": { "id": "txn_123", "external_id": "pi_3Nxyz", "is_fraudulent": true },
    "blocklist": { "entries_added": 2, "types": ["email", "ip"] }
  }
}
```

<Tip>
  After reporting, the new blocklist entries take effect immediately — the same email, BIN, or IP will be scored against them on the next [`/assess`](/guides/realtime-assessment) call.
</Tip>