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

# Architecture

> How pay-in, payout, blocklists, cases, and webhooks fit together

Clausum sits between your application and money movement. You enrich each transaction with context, Clausum returns a decision, and confirmed outcomes feed back into blocklists and cases.

## The protection loop

<Steps>
  <Step title="Assess">
    Your backend calls `POST /api/v1/assess` (pay-in) or `POST /api/v1/assess/payout` (disbursements) **before** capture or transfer. Clausum evaluates blocklists (with `flow_scope`), rules, velocity, payer history, optional managed threat intel, and returns `decision` + `risk_score`.
  </Step>

  <Step title="Enforce">
    Honor the decision: approve, manual review, step-up challenge, or decline. Do not capture or disburse on `decline`.
  </Step>

  <Step title="Report">
    On confirmed fraud, call `POST /api/v1/report-fraud`. Clausum opens a case and auto-populates blocklists.
  </Step>

  <Step title="Learn">
    New blocklist entries and payer history immediately affect the next assess.
  </Step>

  <Step title="Notify">
    Clausum sends signed outbound webhooks (`transaction.created`, `transaction.blocked`, `case.created`, …) to your configured URL in **Conexiones → Entrada (webhooks)**.
  </Step>
</Steps>

## Surfaces

| Surface                  | URL                                                  | Purpose                                   |
| ------------------------ | ---------------------------------------------------- | ----------------------------------------- |
| **Web app (sandbox)**    | [sandbox.clausum.ai](https://sandbox.clausum.ai)     | Panel, simulation, protection, Conexiones |
| **Production dashboard** | [dashboard.clausum.ai](https://dashboard.clausum.ai) | Live tenant operations                    |
| **Partner API**          | Same host as dashboard for your stage                | Assess, report fraud, ingest              |
| **Management API**       | Same host + dashboard JWT                            | Blocklists, cases, submerchants (PSP)     |

See [Access & environments](/concepts/access-and-environments) for hostname policy.

## Components

| Component         | Endpoint(s)                  | Auth                        | Purpose                    |
| ----------------- | ---------------------------- | --------------------------- | -------------------------- |
| Pay-in assess     | `POST /api/v1/assess`        | `clm_sk_*` / `clm_pub_*`    | Real-time checkout scoring |
| Payout assess     | `POST /api/v1/assess/payout` | `clm_sk_*`                  | Outbound transfer scoring  |
| Fraud reporting   | `POST /api/v1/report-fraud`  | `clm_sk_*` (`fraud:report`) | Confirm fraud, auto-block  |
| Event ingestion   | `POST /api/webhooks/ingest`  | `clm_wh_*`                  | Stream provider events     |
| Stripe inbound    | `POST /api/webhooks/stripe`  | Stripe signature            | Native Stripe adapter      |
| Blocklists        | `/api/v1/blocklists`         | Dashboard JWT               | Manage deny lists          |
| Cases             | `/api/v1/cases*`             | Dashboard JWT               | Regulatory expedientes     |
| PSP submerchants  | `/api/v1/submerchants`       | Dashboard JWT               | Child merchant registry    |
| Outbound webhooks | Your HTTPS URL               | HMAC `X-Clausum-Signature`  | Async notifications        |

## Two authentication surfaces

<CardGroup cols={2}>
  <Card title="Programmatic (API keys)" icon="key">
    Server and browser integration — assess, report fraud, ingest. Keys: `clm_pub_*`, `clm_sk_*`, `clm_wh_*`. Create under **Conexiones → Claves API**.
  </Card>

  <Card title="Management (dashboard JWT)" icon="user-shield">
    Dashboard-backed routes — blocklists, cases, submerchants, team. Supabase session after sign-in.
  </Card>
</CardGroup>

See [Authentication](/concepts/authentication).

## Segment-specific behavior

| Organization type | Typical use                                                 |
| ----------------- | ----------------------------------------------------------- |
| **Comercio**      | E-commerce pay-in assess                                    |
| **PSP**           | Pay-in with `submerchant_id`; optional submerchant registry |
| **Banco**         | Pay-in + payout assess, fraud network                       |

Field requirements vary by segment — call `GET /api/v1/assess` for the catalog, or follow your segment guide:

<CardGroup cols={3}>
  <Card title="Merchant" icon="store" href="/segments/merchant">
    Comercio integration plan
  </Card>

  <Card title="PSP" icon="sitemap" href="/segments/psp">
    Aggregator integration plan
  </Card>

  <Card title="Bank" icon="building-columns" href="/segments/bank">
    Institutional integration plan
  </Card>
</CardGroup>

## Data you provide

Clausum is **payment-platform agnostic** (Stripe, Mercado Pago, SPEI, wires, custom rails).

* **Transaction**: amount, currency, order id
* **Identity**: email, phone, customer id
* **Payment method**: card BIN/last4, country, wallet
* **Device**: IP, fingerprint, user agent
* **Payout**: beneficiary CLABE/IBAN, origin account, initiator
* **Behavior**: SDK session signals (optional)

<Note>
  Only `amount` and `currency` are strictly required; each additional field unlocks more signals.
</Note>