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

# Clausum intelligence network

> Contribute and consume shared fraud signals — integration guide for banks and PSPs

**Clausum intelligence** combines two layers that apply during `POST /api/v1/assess` and `POST /api/v1/assess/payout`:

| Layer                     | Contract                                    | Who operates it                      | What you do                                                                                |
| ------------------------- | ------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Managed feeds**         | CLM-ADD-INTEL                               | Clausum staff                        | Nothing — AbuseIPDB, HIBP, MISP, and platform blocklists apply automatically when entitled |
| **Collaborative network** | CLM-ADD-NET-C (consume) + opt-in contribute | Participating banks, PSPs, merchants | Publish signals via API; receive peer signals in assess when consumption is enabled        |

<Warning>
  The network **augments** assess — it does not replace your local rules, blocklists, or the synchronous assess call. [Prevention first](/concepts/capabilities).
</Warning>

## Who this guide is for

| Segment            | Typical role                                    | Integration profile                                                |
| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------ |
| **Bank** (`banco`) | Core banking, treasury, fraud ops               | `financial_institution` — contribute + consume when contracted     |
| **PSP** (`psp`)    | Acquirer middleware, sub-merchant orchestration | `partner` — contribute aggregated signals; consume when contracted |
| **Merchant**       | Optional peer contributor                       | `merchant` — contribute only unless staff enables consume          |

Segment plans: [Bank](/segments/bank) · [PSP](/segments/psp) · [Merchant](/segments/merchant)

## How it fits your stack

```mermaid theme={null}
sequenceDiagram
  participant Core as Your core / PSP middleware
  participant CL as Clausum assess
  participant Net as Collaborative network
  participant M as Managed feeds (Clausum)

  Core->>CL: POST /assess or /assess/payout
  CL->>M: Match managed intel (if entitled)
  CL->>Net: Match peer signals (if consume enabled)
  CL->>CL: Local rules + blocklists
  CL-->>Core: decision + session_id + signals
```

| Capability            | Endpoint                            | Purpose                                               |
| --------------------- | ----------------------------------- | ----------------------------------------------------- |
| **Real-time gate**    | `POST /api/v1/assess`               | Pay-in decision before capture                        |
| **Payout gate**       | `POST /api/v1/assess/payout`        | Disbursement decision before release                  |
| **Network publish**   | `POST /api/v1/network/intelligence` | Bulk shared signals for other participants            |
| **Webhooks / ingest** | `clm_wh_*`                          | Post-payment events — **not** a substitute for assess |

***

## Quick start — bank (5 steps)

<Steps>
  <Step title="1. Create a server key">
    **Dashboard → Conexiones → Claves API** — create `clm_sk_*` with:

    * `assess` — required to benefit from consumed signals
    * `network:contribute` — publish signals (or `fraud:report` for single reports)

    See [API keys](/guides/api-keys).
  </Step>

  <Step title="2. Enable contribution">
    Banks use profile **`financial_institution`**. Contribution is toggled in the dashboard:

    * **Inteligencia** (`/dashboard/network`) → **Inicio rápido** panel (banks only) or **Configuración** tab → enable **Contribuir a la red**

    <Note>
      **Consuming** peer signals in assess is enabled by Clausum on your contract (**CLM-ADD-NET-C**). Contact your account manager — it is not self-serve via API.
    </Note>
  </Step>

  <Step title="3. Publish signals">
    Send confirmed fraud indicators from your core or fraud platform (up to **500 entries** per request):

    ```bash theme={null}
    curl -s -X POST "${CLAUSUM_API_BASE}/api/v1/network/intelligence" \
      -H "Authorization: Bearer ${CLAUSUM_SECRET_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "entries": [
          {
            "list_type": "email",
            "value": "confirmed-fraud@example.com",
            "severity": "block",
            "reason_code": "confirmed_fraud",
            "reason_detail": "Internal case #12345",
            "confidence": 90,
            "source": "bank_feed"
          },
          {
            "list_type": "card_bin",
            "value": "411111",
            "severity": "flag",
            "reason_code": "card_testing",
            "source": "bank_feed"
          }
        ]
      }'
    ```
  </Step>

  <Step title="4. Protect pay-in and payout">
    Every payment or disbursement should call assess **before** money moves:

    * Pay-in: [Real-time assessment](/guides/realtime-assessment)
    * Payout: [Payout assessment](/guides/payout-assessment)

    When network **consume** is active, assess matches normalized fields against peer signals from contributors whose trust score meets your threshold.
  </Step>

  <Step title="5. Operate and revoke">
    * **Inteligencia → Mis señales** — review and revoke false positives
    * **Inteligencia → Participantes** — see contributing institutions (when consume is on)
    * **Protección** — compact status for managed + network layers
  </Step>
</Steps>

***

## Quick start — PSP (5 steps)

<Steps>
  <Step title="1. Complete PSP onboarding">
    Register sub-merchants before live assess — [PSP submerchants](/guides/psp-submerchants). Every pay-in assess must include `submerchant_id` when your registry is non-empty.
  </Step>

  <Step title="2. Create middleware keys">
    `clm_sk_*` on your PSP orchestration layer with `assess` + optional `network:contribute`. Never embed secret keys in sub-merchant frontends.
  </Step>

  <Step title="3. Assess before settlement">
    ```json theme={null}
    {
      "amount": 150.00,
      "amount_unit": "major",
      "currency": "MXN",
      "submerchant_id": "uuid-from-registry",
      "order_id": "sm-8842-checkout-001",
      "email": "payer@example.com",
      "device": { "ip": "203.0.113.5" }
    }
    ```

    Your middleware enforces `decision` before settling funds to the sub-merchant. See [PSP integration](/segments/psp).
  </Step>

  <Step title="4. Optionally contribute aggregated signals">
    Publish BIN ranges, emails, or IPs observed across your portfolio (with legal approval):

    ```bash theme={null}
    curl -s -X POST "${CLAUSUM_API_BASE}/api/v1/network/intelligence" \
      -H "Authorization: Bearer ${CLAUSUM_SECRET_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "entries": [{
          "list_type": "ip_address",
          "value": "203.0.113.44",
          "severity": "review",
          "reason_code": "velocity_abuse",
          "source": "api"
        }]
      }'
    ```

    Enable **Contribuir** in **Inteligencia → Configuración**.
  </Step>

  <Step title="5. Route webhooks per sub-merchant">
    Outbound events include metadata for routing — [Receiving webhooks](/guides/receiving-webhooks). Pipe acquirer events via [Event ingestion](/guides/event-ingestion) as a complement to assess.
  </Step>
</Steps>

***

## API reference

### Publish signals

```
POST /api/v1/network/intelligence
Authorization: Bearer clm_sk_...
Content-Type: application/json
```

**Permissions:** `network:contribute` or `fraud:report` (secret key only).

**Body:** `entries[]` (max 500) or single `list_type` + `value`.

| Field           | Required    | Description                                        |
| --------------- | ----------- | -------------------------------------------------- |
| `list_type`     | Yes         | Signal type (see table below)                      |
| `value`         | Yes         | Raw value — normalized server-side                 |
| `severity`      | Recommended | `block`, `flag`, or `review`                       |
| `reason_code`   | Recommended | Short machine code                                 |
| `reason_detail` | Optional    | Human note (not shown to other tenants)            |
| `confidence`    | Optional    | 0–100                                              |
| `source`        | Optional    | `api`, `bank_feed`, `fraud_report`, …              |
| `external_ref`  | Optional    | Stable id from your feed for idempotent batch jobs |
| `expires_at`    | Optional    | ISO timestamp                                      |

**Response:**

```json theme={null}
{
  "success": true,
  "accepted": 2,
  "skipped": 0,
  "errors": [],
  "list_types_supported": ["email", "email_domain", "ip_address", "..."]
}
```

**Errors:**

| Code                          | Meaning                                                         |
| ----------------------------- | --------------------------------------------------------------- |
| `NETWORK_CONTRIBUTE_DISABLED` | Enable contribution in Dashboard → Inteligencia → Configuración |
| `VALIDATION_ERROR`            | Invalid `list_type`, empty batch, or >500 entries               |

### Network stats (partner)

```
GET /api/v1/network/intelligence
Authorization: Bearer clm_sk_...
```

**Permissions:** `network:signals:read`, `network:contribute`, `fraud:report`, or `assess`.

Returns your membership snapshot, contributed active count, and network pool size.

### Dashboard membership (session)

```
GET /api/v1/network/membership
PATCH /api/v1/network/membership
```

Authenticated with **dashboard session** (browser cookie after sign-in), not partner keys.

Tenants may PATCH **`contribute_enabled`** only. **`consume_enabled`** and **`integration_profile`** are managed by Clausum based on organization type and contract.

### Revoke signals (dashboard session)

```
GET /api/v1/network/signals?page=1&limit=25
PATCH /api/v1/network/signals
{ "id": "entry-uuid" }
```

Sets `is_active = false` for your organization's entry. Also available in **Inteligencia → Mis señales**.

***

## Supported signal types

| `list_type`          | Matching in assess            | Storage             |
| -------------------- | ----------------------------- | ------------------- |
| `email`              | Payer email                   | Normalized / hashed |
| `email_domain`       | Email domain                  | Plain               |
| `ip_address`         | `device.ip`                   | Plain               |
| `ip_range`           | CIDR                          | Plain               |
| `device_fingerprint` | Device fingerprint            | Hashed              |
| `card_bin`           | Card BIN                      | Plain               |
| `card_hash`          | Tokenized PAN hash            | Hashed              |
| `country`            | Billing / beneficiary country | Plain               |
| `phone`              | Phone number                  | Normalized / hashed |
| `customer_id`        | Core customer reference       | Hashed              |

**Severity behavior:** a peer signal with `block` can force **decline** during assess, similar to a local blocklist hit.

***

## Privacy and compliance

| Data                                                  | Dashboard display       | Cross-tenant matching   |
| ----------------------------------------------------- | ----------------------- | ----------------------- |
| Email, phone, customer\_id, fingerprints, card hashes | Safe masked labels only | Normalized / hashed     |
| BIN, country, IP, email domain                        | Plain labels            | Plain normalized values |

Before contributing:

* Confirm your **legal / compliance** team approves sharing each signal class
* Document internal case IDs in `reason_detail` — not exposed to other tenants
* Maintain a runbook to **revoke** false positives via **Mis señales**

***

## Trust and consumption

Each contributor has a **trust score** (0–100). When **consume** is enabled, assess applies signals only from contributors at or above your organization's minimum trust threshold (configured by Clausum).

Dashboard **Participantes** lists institutions with active contributions and whether they meet your threshold.

***

## Bank integration patterns

### Core banking / SPEI

Call assess **synchronously** in the authorization path before releasing funds:

1. Core receives transfer request
2. Middleware calls `POST /api/v1/assess/payout`
3. On `decline` → hold transfer, open case
4. On `approve` / `review` → follow your policy matrix ([Assess resilience](/guides/assess-resilience))

Pair with payout blocklists (`flow_scope: payout`) — [Blocklists](/concepts/blocklists).

### Fraud feed batch jobs

Schedule nightly or hourly jobs from your fraud warehouse:

* Map internal tables → `entries[]`
* Use stable `external_ref` per row for idempotent updates
* Start with `severity: review` in UAT; promote to `block` after validation

### Cases and regulatory workflow

Link high-severity network hits to [Case management](/guides/case-management). [Report fraud](/guides/report-fraud) can complement bulk API for ad-hoc confirmations.

***

## PSP integration patterns

### Middleware owns orchestration

Clausum does **not** call Stripe, Mercado Pago, or your acquirer. Your PSP layer:

1. Receives payment attempt from sub-merchant checkout
2. Calls assess with `submerchant_id`
3. Branches on `decision` before capture

See architecture diagram in [PSP integration](/segments/psp).

### Multi-tenant signal contribution

When contributing portfolio-level signals:

* Avoid sub-merchant PII in `reason_detail`
* Prefer BIN, IP, and velocity patterns over raw emails when possible
* Separate sandbox and production keys per environment

### Institutional add-ons

PSPs with treasury or disbursement products should also evaluate [Payout assessment](/guides/payout-assessment) and [Regulatory screening](/guides/regulatory-screening) when on **CLM-MOD-INST**.

***

## Managed feeds (CLM-ADD-INTEL)

When entitled, Clausum-operated threat feeds apply automatically during assess — no API setup.

Check status in **Dashboard → Protección** (Inteligencia Clausum strip). Staff syncs feeds on the platform side; tenants see signal counts and last sync time only.

This layer is independent of the collaborative network — you may have one, both, or neither depending on contract.

***

## Go-live checklists

### Bank

* [ ] Server key with `assess` + `network:contribute`
* [ ] Contribution enabled in **Inteligencia → Configuración**
* [ ] **CLM-ADD-NET-C** confirmed with account manager if consuming peer signals
* [ ] Payout assess wired before SPEI/wire release ([Bank integration](/segments/bank))
* [ ] UAT: publish test signal from staging org → verify assess match
* [ ] Runbook for revoking false positives in **Mis señales**
* [ ] Certification sign-off on `cert.clausum.ai` when provided

### PSP

* [ ] All active sub-merchants registered with stable `external_id`
* [ ] Every assess includes `submerchant_id` when registry is non-empty
* [ ] Middleware enforces decision before acquirer capture
* [ ] Optional: contribution enabled + legal sign-off for aggregated signals
* [ ] Webhook routing tested per sub-merchant
* [ ] Sandbox UAT on `sandbox.clausum.ai` before production

***

## Troubleshooting

| Symptom                           | Check                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `403 NETWORK_CONTRIBUTE_DISABLED` | Enable **Contribuir** in Inteligencia settings                               |
| Peer signals never match          | Confirm **CLM-ADD-NET-C** active; check trust threshold with account manager |
| `401` on network API              | Use `clm_sk_*` with `network:contribute`, not `clm_wh_*`                     |
| Assess works but no network layer | Consumption is contract-gated — managed intel and local rules still apply    |
| Duplicate signals                 | Use consistent normalization; revoke old entry in **Mis señales**            |

***

## Related guides

<CardGroup cols={2}>
  <Card title="Bank integration" icon="building-columns" href="/segments/bank">
    Payout-first institutional plan
  </Card>

  <Card title="PSP integration" icon="sitemap" href="/segments/psp">
    Sub-merchant routing plan
  </Card>

  <Card title="Real-time assess" icon="bolt" href="/guides/realtime-assessment">
    Pay-in API
  </Card>

  <Card title="Payout assess" icon="money-bill-transfer" href="/guides/payout-assessment">
    Disbursement API
  </Card>

  <Card title="API keys" icon="key" href="/guides/api-keys">
    Permissions and prefixes
  </Card>

  <Card title="Capabilities" icon="table-list" href="/concepts/capabilities">
    Module catalog by segment
  </Card>
</CardGroup>

Support: **[api@clausum.ai](mailto:api@clausum.ai)**