Clausum intelligence network

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

The network augments assess — it does not replace your local rules, blocklists, or the synchronous assess call. Prevention first.

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 · PSP · Merchant

How it fits your stack

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)

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.

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

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.

3. Publish signals

Send confirmed fraud indicators from your core or fraud platform (up to 500 entries per request):

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

4. Protect pay-in and payout

Every payment or disbursement should call assess before money moves:

Pay-in: Real-time assessment
Payout: Payout assessment

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

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

Quick start — PSP (5 steps)

1. Complete PSP onboarding

Register sub-merchants before live assess — PSP submerchants. Every pay-in assess must include submerchant_id when your registry is non-empty.

2. Create middleware keys

clm_sk_* on your PSP orchestration layer with assess + optional network:contribute. Never embed secret keys in sub-merchant frontends.

3. Assess before settlement

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

4. Optionally contribute aggregated signals

Publish BIN ranges, emails, or IPs observed across your portfolio (with legal approval):

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.

5. Route webhooks per sub-merchant

Outbound events include metadata for routing — Receiving webhooks. Pipe acquirer events via Event ingestion as a complement to assess.

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:

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

Core receives transfer request
Middleware calls POST /api/v1/assess/payout
On decline → hold transfer, open case
On approve / review → follow your policy matrix (Assess resilience)

Pair with payout blocklists (flow_scope: payout) — 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. 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:

Receives payment attempt from sub-merchant checkout
Calls assess with submerchant_id
Branches on decision before capture

See architecture diagram in PSP integration.

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 and 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)
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

Bank integration

Payout-first institutional plan

PSP integration

Sub-merchant routing plan

Real-time assess

Pay-in API

Payout assess

Disbursement API

API keys

Permissions and prefixes

Capabilities

Module catalog by segment

Support: api@clausum.ai

Get started

Integrate by client type

Capabilities — prevention

Capabilities — events & ops

Dashboard

Core concepts

Reference

Clausum intelligence network

Who this guide is for

How it fits your stack

Quick start — bank (5 steps)

Quick start — PSP (5 steps)

API reference

Publish signals

Network stats (partner)

Dashboard membership (session)

Revoke signals (dashboard session)

Supported signal types

Privacy and compliance

Trust and consumption

Bank integration patterns

Core banking / SPEI

Fraud feed batch jobs

Cases and regulatory workflow

PSP integration patterns

Middleware owns orchestration

Multi-tenant signal contribution

Institutional add-ons

Managed feeds (CLM-ADD-INTEL)

Go-live checklists

Bank

PSP

Troubleshooting

Bank integration

PSP integration

Real-time assess

Payout assess

API keys

Capabilities

​Who this guide is for

​How it fits your stack

​Quick start — bank (5 steps)

​Quick start — PSP (5 steps)

​API reference

​Publish signals

​Network stats (partner)

​Dashboard membership (session)

​Revoke signals (dashboard session)

​Supported signal types

​Privacy and compliance

​Trust and consumption

​Bank integration patterns

​Core banking / SPEI

​Fraud feed batch jobs

​Cases and regulatory workflow

​PSP integration patterns

​Middleware owns orchestration

​Multi-tenant signal contribution

​Institutional add-ons

​Managed feeds (CLM-ADD-INTEL)

​Go-live checklists

​Bank

​PSP

​Troubleshooting

​Related guides

Bank integration

PSP integration

Real-time assess

Payout assess

API keys

Capabilities

Who this guide is for

How it fits your stack

Quick start — bank (5 steps)

Quick start — PSP (5 steps)

API reference

Publish signals

Network stats (partner)

Dashboard membership (session)

Revoke signals (dashboard session)

Supported signal types

Privacy and compliance

Trust and consumption

Bank integration patterns

Core banking / SPEI

Fraud feed batch jobs

Cases and regulatory workflow

PSP integration patterns

Middleware owns orchestration

Multi-tenant signal contribution

Institutional add-ons

Managed feeds (CLM-ADD-INTEL)

Go-live checklists

Bank

PSP

Troubleshooting

Related guides