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

# Comercios PSP

> Registra comercios hijos bajo una organización PSP y pasa submerchant_id en assess.

Los proveedores de servicios de pago (PSP) procesan en nombre de muchos **comercios**. Clausum los mantiene en un registro bajo tu organización PSP — no como cuentas tenant separadas.

## Requisitos

| Regla | Detalle |
| - | - |
| Tipo de organización | `psp` (establecido durante onboarding) |
| Assess | Si tienes **cualquier** comercio activo, **`submerchant_id` es obligatorio** en cada `POST /api/v1/assess` |
| Claves | `clm_sk_*` a nivel org para middleware; **claves con scope** opcionales por comercio |

Descubre reglas de segmento: `GET /api/v1/assess` → `field_requirements_by_segment.psp`.

## Registrar comercios

### Panel

**Conexiones → Comercios** — registra, emite claves sandbox con scope, abre protección por comercio.

### Partner API (recomendado para automatización)

Requiere org `clm_sk_*` con `submerchants:read` / `submerchants:write`:

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

| Method | Path | Auth | Purpose |
| - | - | - | - |
| `GET` | `/api/v1/partner/submerchants` | Partner `clm_sk_*` | List + active keys |
| `POST` | `/api/v1/partner/submerchants` | Partner | Create (+ optional `issue_keys`) |
| `PATCH` | `/api/v1/partner/submerchants/:id` | Partner | Update, protection overrides |
| `DELETE` | `/api/v1/partner/submerchants/:id` | Partner | Archive + revoke scoped keys |
| `GET/POST/DELETE` | `/api/v1/partner/submerchants/:id/keys` | Partner | Scoped keys per child |

### Dashboard API (session JWT)

Mismo registro desde la UI del panel — requiere admin con sesión iniciada:

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/v1/submerchants` | List (optional `?include_keys=1`) |
| `POST` | `/api/v1/submerchants` | Create |
| `PATCH` | `/api/v1/submerchants/:id` | Update + protection profile |
| `DELETE` | `/api/v1/submerchants/:id` | Deactivate |

## Claves API con scope

Cada comercio puede tener su propia `clm_sk_sbx_*` / `clm_pub_sbx_*`. Assess con clave con scope **fija** `submerchant_id` desde la clave — enviar un id distinto devuelve `403`.

Las claves a nivel org deben pasar `submerchant_id` en cada pago.

## Protección por comercio

Tras el registro, cada hijo **hereda** tu plantilla de protección org por defecto.

| Necesidad | Guía |
| - | - |
| Establecer plantilla + propagar a todos | [Protección por comercio PSP](/es/guides/psp-submerchant-protection) |
| Reglas y blocklists org-wide | [Espacio de protección](/es/guides/protection-workspace) |

Ejemplo rápido de override Partner:

```json theme={null}
{
  "protection": {
    "score_adjustment": 10,
    "min_decision": "review",
    "max_amount_major": 5000
  }
}
```

## Assess con comercio

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

Usa valores `external_id` estables de tu onboarding — se convierten en el `submerchant_id` canónico en assess.

La respuesta puede incluir `submerchant_id` y `submerchant_name` para conciliación y webhooks salientes.

<Tip>
  Configura tu [plantilla de protección](/es/guides/psp-submerchant-protection) una vez, propaga a todos los hijos, luego personaliza solo los comercios que necesiten política más estricta o laxa.
</Tip>


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