Reporting fraud

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

Transaction flagged

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

Case opened

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

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.

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

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

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

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.

{
  "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.

Get started

Integrate by client type

Capabilities — prevention

Capabilities — events & ops

Dashboard

Core concepts

Reference

Reporting fraud

What happens on report

Authentication

Identify the transaction

Examples

Reasons

Controlling notifications

Response

​What happens on report

​Authentication

​Identify the transaction

​Examples

​Reasons

​Controlling notifications

​Response

What happens on report

Authentication

Identify the transaction

Examples

Reasons

Controlling notifications

Response