Skip to main content
Report fraud against your assigned API host ($CLAUSUM_API_BASE). See Access & environments.
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

1

Transaction flagged

The matching transaction is marked is_fraudulent with the reason and timestamp.
2

Case opened

A case (expediente) is created with a generated reference_number, priority derived from amount and reason, and a mapped incident type.
3

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

Chain notified

Email alerts go to the configured participants (merchant, acquirer, issuer, compliance) and the fraud.detected webhook fires.

​
Authentication

Requires a secret key with the fraud:report permission. 
Authorization: Bearer clm_sk_xxx

​
Identify the transaction

Provide one of these to reference an existing transaction:
  • transaction_id — the Clausum transaction id.
  • external_transaction_id + provider — e.g. pi_3Nxyz + stripe.
If no transaction exists yet, provide enough inline data (amount + email) and Clausum creates one.

​
Examples

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"
  }'

​
Reasons

reasonUse for
chargebackIssuer chargeback / dispute
friendly_fraudLegitimate cardholder claiming fraud
card_testingSmall probing transactions to validate stolen cards
account_takeoverCompromised customer account
identity_theftStolen identity used to transact
otherAnything else

​
Controlling notifications

Use the notify object to decide which parties are alerted. Attach evidence with evidence_urls. 
{
  "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

{
  "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"] }
  }
}
After reporting, the new blocklist entries take effect immediately — the same email, BIN, or IP will be scored against them on the next /assess call.