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

> Register child merchants under a PSP organization and pass submerchant_id on assess.

Payment service providers (PSPs) often process on behalf of many **submerchants**. Clausum models them as a logical registry tied to your organization — not separate tenant accounts.

## Requirements

| Rule              | Detail                                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| Organization type | `psp` (set during onboarding)                                                                               |
| When registered   | If your org has **any** active submerchant, **`submerchant_id` is required** on every `POST /api/v1/assess` |
| Keys              | Same Partner keys (`clm_sk_*` / `clm_pub_*`) as the PSP org                                                 |

Discover segment rules: `GET /api/v1/assess` → `field_requirements_by_segment.psp`.

## Register submerchants

**Dashboard:** Conexiones → wizard sandbox/production → **Subcomercios**.

**API:**

```bash theme={null}
curl -X POST "$CLAUSUM_API_BASE/api/v1/submerchants" \
  -H "Authorization: Bearer $CLAUSUM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "sm_acme_mx",
    "name": "Acme MX Store",
    "country": "MX",
    "mcc": "5411"
  }'
```

| Method   | Path                       | Purpose       |
| -------- | -------------------------- | ------------- |
| `GET`    | `/api/v1/submerchants`     | List registry |
| `POST`   | `/api/v1/submerchants`     | Create        |
| `PATCH`  | `/api/v1/submerchants/:id` | Update        |
| `DELETE` | `/api/v1/submerchants/:id` | Deactivate    |

All endpoints require Partner auth (`401` without a valid `clm_sk_*`).

## Assess with submerchant

```json theme={null}
{
  "amount": 4500,
  "currency": "USD",
  "email": "buyer@example.com",
  "submerchant_id": "sm_acme_mx",
  "order_id": "ORD-9912"
}
```

Response may include `submerchant_id` and `submerchant_name` for reconciliation and outbound webhooks.

<Tip>
  Use stable `external_id` values from your onboarding system — they become the canonical `submerchant_id` in assess.
</Tip>