Skip to main content
This guide walks through a complete integration: authenticate, assess a transaction, enforce the decision, report fraud, and receive a webhook.
All HTTP examples use $CLAUSUM_API_BASE — the API hostname your organization receives from Clausum support. For sandbox trials this is often https://sandbox.clausum.ai. See Access & environments.

​
Prerequisites

1

Create a Clausum account

Sign in to the sandbox application and complete onboarding for your organization.
2

Confirm your API base URL

Store the base URL support assigned to you:
export CLAUSUM_API_BASE="https://sandbox.clausum.ai"  # example — use your assigned host
3

Generate API keys

Go to Integraciones → Claves de integración and create:
  • Checkout (browser) — for the Browser SDK (clm_pub_...).
  • Server (backend) — for your API only (clm_sk_...).
See API keys for the third type, Event ingest (clm_wh_...), used only for webhook ingest.
Store server keys in environment variables or a secrets manager. Treat them like a password.

​
1. Assess a transaction

Send transaction details to the assessment endpoint before you capture the payment. 
curl -X POST "$CLAUSUM_API_BASE/api/v1/assess" \
  -H "Authorization: Bearer $CLAUSUM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "currency": "MXN",
    "email": "customer@example.com",
    "payment_method": { "type": "card", "card_bin": "411111", "card_last4": "4242", "card_country": "MX" },
    "device": { "ip": "201.150.10.22", "fingerprint": "fp_9a8b7c6d" },
    "metadata": { "order_id": "ORD-123" }
  }'
The response contains a decision and a risk_score from 0–100: 
{
  "decision": "approve",
  "risk_score": 8,
  "signals": ["short_session"],
  "session_id": "ps_1716998400000_a1b2c3d4e",
  "blocked_by": null,
  "latency_ms": 42
}

​
2. Enforce the decision

Map the decision to an action in your checkout. See Risk decisions for the full model. 
switch (assessment.decision) {
  case "approve":
    await capturePayment(order)
    break
  case "review":
    await flagForManualReview(order, assessment)
    break
  case "challenge":
    await request3DSorOTP(order) // step-up verification
    break
  case "decline":
    throw new Error("Transaction blocked: " + (assessment.blocked_by ?? "high risk"))
}
Adopt a fail-open strategy for availability: if the assessment call errors or times out, default to your normal flow and log the incident rather than blocking legitimate customers.

​
3. Report fraud when it happens

When a chargeback or confirmed fraud arrives, report it. Clausum opens a case, blocklists the offending email / card BIN / IP, and notifies the chain. 
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"
  }'

​
4. Receive webhooks

Add a webhook endpoint in the dashboard and subscribe to events. Clausum signs every delivery so you can verify authenticity — see Receiving webhooks. 
// POST handler on your server
export async function POST(req: Request) {
  const raw = await req.text()
  const signature = req.headers.get("x-clausum-signature")!
  if (!verifyClausumSignature(raw, signature, process.env.CLAUSUM_WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 })
  }
  const event = JSON.parse(raw)
  if (event.event === "fraud.detected") {
    // freeze the account, notify ops, etc.
  }
  return new Response("ok")
}

​
Next steps

Getting started (dashboard)

Onboarding, simulation, and panel on sandbox.

Real-time assessment

Best practices for the signals you should send.

Browser SDK

Capture device and behavioral signals automatically.

Blocklists

Manage emails, IPs, BINs, devices, and more.

Webhook events

The full catalog of events you can subscribe to.