> ## 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.

# Reportar fraude

> Reporta fraude confirmado y deja que Clausum bloquee, abra un expediente y notifique la cadena.

<Note>
  Reporta fraude contra tu host API asignado (`$CLAUSUM_API_BASE`). Consulta [Acceso y entornos](/es/concepts/access-and-environments).
</Note>

Cuando el fraude está confirmado — llega un chargeback, se detecta account takeover, o tu equipo confirma un expediente — repórtalo a Clausum con una sola llamada. Clausum hace el trabajo pesado automáticamente.

## Qué ocurre al reportar

<Steps>
  <Step title="Transacción marcada">
    La transacción coincidente se marca `is_fraudulent` con el motivo y marca de tiempo.
  </Step>

  <Step title="Expediente abierto">
    Se crea un expediente con `reference_number` generado, prioridad derivada de monto y motivo, y tipo de incidente mapeado.
  </Step>

  <Step title="Blocklists actualizadas">
    El correo ofensor (`block`), BIN de tarjeta (`flag`, para card testing / friendly fraud) e IP (`block`) se agregan a tus blocklists y se vinculan al expediente.
  </Step>

  <Step title="Cadena notificada">
    Alertas por correo van a los participantes configurados (comercio, adquirente, emisor, compliance) y se dispara el webhook `fraud.detected`.
  </Step>
</Steps>

## Autenticación

Requiere una clave secreta con permiso `fraud:report`.

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

## Identificar la transacción

Proporciona **uno** de estos para referenciar una transacción existente:

* `transaction_id` — UUID interno de transacción Clausum.
* `payment_id` + `provider` — p. ej. `pi_3Nxyz` + `stripe` (mismo id que assess `payment_id`).
* `external_transaction_id` + `provider` — alias deprecado de `payment_id`.

Si aún no existe transacción, proporciona datos inline suficientes (`amount` + `email`) y Clausum crea una.

## Ejemplos

<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>

## Motivos

| `reason` | Usar para |
| - | - |
| `chargeback` | Chargeback / disputa del emisor |
| `friendly_fraud` | Titular legítimo reclamando fraude |
| `card_testing` | Transacciones pequeñas de prueba para validar tarjetas robadas |
| `account_takeover` | Cuenta de cliente comprometida |
| `identity_theft` | Identidad robada usada para transaccionar |
| `other` | Cualquier otro caso |

## Controlar notificaciones

Usa el objeto `notify` para decidir qué partes reciben alerta. Adjunta evidencia con `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 }
}
```

## Respuesta

```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>
  Tras reportar, las nuevas entradas de blocklist entran en vigor de inmediato — el mismo correo, BIN o IP se evaluará contra ellas en la próxima llamada [`/assess`](/es/guides/realtime-assessment).
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.