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

# PSP submerchant protection

> Set a protection template for all submerchants, propagate defaults, then customize individual merchants when needed.

PSPs manage many child merchants under **one organization**. Clausum uses a simple model:

1. **Template** — defaults for every submerchant (thresholds, alerts, score adjustment).
2. **Propagate** — push the template to all non-customized children in one click.
3. **Customize** — override rules and alerts for a specific submerchant when needed.

Org-level rules in **Protection** still apply to everyone. Submerchant settings **add** on top — they do not replace your base policy.

## Where to configure

| Task | Dashboard path |
| - | - |
| Template + propagate | **Merchants → Template & propagation** (`/dashboard/submerchants/protection`) |
| Portfolio | **Merchants** (`/dashboard/submerchants`) |
| Per-merchant detail | **Merchants → \[merchant] → Protection** |
| Org-wide rules & blocklists | **Protection** (`/dashboard/protection`) |

<Note>
  Protection template APIs require a **dashboard session** (admin/owner). Partner API keys can set **per-submerchant overrides** via `PATCH /api/v1/partner/submerchants/{id}` — see [PSP submerchants](/guides/psp-submerchants).
</Note>

### Dashboard

| Surface | Path | What you get |
| - | - | - |
| Home (PSP) | `/dashboard` | Compact portfolio summary card |
| Portfolio | `/dashboard/submerchants` | Stats table, risk tiers, drill-down |
| Template | `/dashboard/submerchants/protection` | Defaults + propagate |
| Child detail | `/dashboard/submerchants/[id]` | Enterprise protection + alerts |

APIs (dashboard session): `GET /api/v1/submerchants/portfolio`, `GET /api/v1/submerchants/[id]/stats`, protection defaults routes.

## Step 1 — Set the template

Open **Merchants → Template & propagation** and configure:

| Field | What it does |
| - | - |
| Score adjustment | Adds to risk score for every inherited submerchant |
| Max amount | Cap per payment (major currency units) |
| Approve / decline thresholds | Score bands for approve vs decline |
| Alerts enabled | Creates default alert rules per submerchant (volume spike, high score) |

Click **Save template** to store without touching existing children.

## Step 2 — Propagate

Click **Save and propagate to non-customized** to:

* Update every submerchant with `customized = false`
* Sync alert rules from the template
* **Skip** merchants you already marked as customized

You will see a summary: how many were updated vs skipped.

<Tip>
  Register submerchants first ([PSP submerchants](/guides/psp-submerchants)). Each new child automatically gets a profile that inherits the template.
</Tip>

## Step 3 — Customize one merchant

Open a submerchant → **Protection**:

| Switch | Effect |
| - | - |
| **Inherit org template** (on) | Uses template + org rules in **Protection** |
| **Mark as customized** (on) | Stops propagation; enables scoped rules and alert overrides for this child only |

When customized, assess merges:

* Org rules (`psp_submerchant_id` null)
* Submerchant-scoped rules and blocklists
* Template/profile overrides (thresholds, score adjustment, max amount)

Submerchant-scoped entries **win** over org defaults when both match the same signal.

## How assess uses it

Every `POST /api/v1/assess` with `submerchant_id` resolves the effective profile before scoring:

```mermaid theme={null}
flowchart TD
  A[Assess request + submerchant_id] --> B{Registered submerchant?}
  B -->|No| C[Org rules only]
  B -->|Yes| D[Load protection profile]
  D --> E{Inherits template?}
  E -->|Yes| F[Merge org template + org rules]
  E -->|No / customized| G[Merge profile overrides + scoped rules]
  F --> H[Decision + alerts]
  G --> H
```

## Alerts

Default template alerts (when enabled):

| Alert | Trigger |
| - | - |
| Volume spike | Transaction volume vs baseline (ratio ≥ 2.5) |
| High risk score | Score ≥ 0.75 |

Alerts are stored per submerchant in `behavior_alert_rules`. Customize notification roles in the template or per merchant.

## Partner API (overrides only)

Programmatic per-submerchant adjustments (org-level `clm_sk_*` with `submerchants:write`):

```bash theme={null}
curl -X PATCH "$CLAUSUM_API_BASE/api/v1/partner/submerchants/{id}" \
  -H "Authorization: Bearer $CLAUSUM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inherits_defaults": false,
    "customized": true,
    "protection": { "score_adjustment": 10, "max_amount_major": 5000 },
    "thresholds": { "decline": 70 }
  }'
```

Template save and propagate remain **dashboard-only** today.

## Related guides

<CardGroup cols={2}>
  <Card title="PSP submerchants" icon="sitemap" href="/guides/psp-submerchants">
    Registry, keys, and assess
  </Card>

  <Card title="Protection workspace" icon="shield" href="/guides/protection-workspace">
    Org-wide rules and blocklists
  </Card>

  <Card title="PSP integration" icon="building-columns" href="/segments/psp">
    Full PSP onboarding path
  </Card>

  <Card title="Transaction monitor" icon="chart-line" href="/guides/transaction-monitor">
    Alerts and behavior rules
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.