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

# Integración PSP

> Integración para proveedores de servicios de pago — subcomercios, Partner API y assess multi-tenant

Para **`organization_type = psp`**: procesas pagos en nombre de muchos comercios. Cada assess pay-in debe identificar **a qué subcomercio** pertenece la transacción.

## Módulos que necesitas

| Módulo | ¿Obligatorio? | Guía |
| - | - | - |
| **Prevención — pay-in assess** | Sí | [Assess en tiempo real](/es/guides/realtime-assessment) |
| **Registro de subcomercios** | Sí (si hay hijos registrados) | [Subcomercios PSP](/es/guides/psp-submerchants) |
| **Claves API** | Sí | [Claves API](/es/guides/api-keys) |
| **Webhooks salientes** | Recomendado | [Recibir webhooks](/es/guides/receiving-webhooks) |
| **Resiliencia de assess** | Sí (prod) | [Resiliencia de assess](/es/guides/assess-resilience) |
| **Ingest de eventos** | Recomendado | [Ingest de eventos](/es/guides/event-ingestion) |
| **SDK para navegador** | Por checkout de subcomercio | [SDK para navegador](/es/guides/browser-sdk) |
| **Payout assess** | Si CLM-MOD-INST / tesorería | [Assess de payout](/es/guides/payout-assessment) |
| **Inteligencia Clausum** | Si está contratado | [Red de inteligencia](/es/guides/clausum-intelligence-network) |

## Fases de integración

<Steps>
  <Step title="Fase 1 — Organización y claves">
    1. Completa el onboarding PSP en el Panel de Control.
    2. **Conexiones → Claves API** — clave **Secret** (`clm_sk_*`) para orquestación en servidor (middleware PSP).
    3. Claves **Publishable** opcionales por checkout de subcomercio si expones embeds del SDK.
  </Step>

  <Step title="Fase 2 — Registro de subcomercios">
    1. Registra cada comercio hijo — [Subcomercios PSP](/es/guides/psp-submerchants):\
       `POST /api/v1/partner/submerchants` (Partner API) o **Conexiones → Comercios**.
    2. Guarda el `external_id` de Clausum mapeado a tu ledger — se convierte en `submerchant_id` en assess.
    3. **Regla:** si tu org tiene subcomercios registrados, assess **debe** incluir un `submerchant_id` válido.
  </Step>

  <Step title="Fase 2b — Plantilla de protección">
    1. Abre **Comercios → Plantilla y propagación** — define umbrales, alertas, ajuste de score.
    2. **Guardar y propagar** para aplicar a todos los hijos no personalizados.
    3. Personaliza comercios individuales solo cuando sea necesario — [Protección de subcomercios PSP](/es/guides/psp-submerchant-protection).
  </Step>

  <Step title="Fase 3 — Orquestación Partner API">
    Tu middleware llama assess por cada intento de pago:

    ```json theme={null}
    {
      "amount": 150.00,
      "amount_unit": "major",
      "currency": "MXN",
      "submerchant_id": "uuid-from-registry",
      "order_id": "sm-8842-checkout-001",
      "payment_id": "your-ledger-charge-id",
      "email": "payer@example.com",
      "device": { "ip": "203.0.113.5" }
    }
    ```

    1. `POST /api/v1/assess` con `clm_sk_*`.
    2. Aplica `decision` antes de liquidar fondos al subcomercio.
    3. La protección por subcomercio hereda tu plantilla de org — personaliza en [Protección de subcomercios](/es/guides/psp-submerchant-protection).
    4. Devuelve `session_id` a tu ledger para auditoría.

    Consulta [Assess en tiempo real](/es/guides/realtime-assessment).
  </Step>

  <Step title="Fase 4 — Webhooks e ingest">
    1. Configura URL saliente por entorno (sandbox vs producción).
    2. Enruta eventos a backends de subcomercios usando `submerchant_id` en metadatos del payload.
    3. Canaliza eventos de adquirente/PSP vía [Ingest de eventos](/es/guides/event-ingestion) (`clm_wh_*` — por defecto; sin catálogo de marcas). Guía opcional [Stripe](/es/guides/stripe-webhooks) solo si necesitas el adaptador nativo.
  </Step>

  <Step title="Fase 5 — Inteligencia y go-live">
    1. Claves API separadas por entorno y cargas de trabajo principales.
    2. [Resiliencia de assess](/es/guides/assess-resilience) — reintentos idempotentes con el mismo `order_id`.
    3. Monitorea actividad de API en **Conexiones → Monitor**.
    4. Opcional: [Red de inteligencia Clausum](/es/guides/clausum-intelligence-network) — contribuye señales de cartera; solicita consumo vía account manager.
    5. Si módulo institucional: evalúa [Assess de payout](/es/guides/payout-assessment) para flujos de tesorería.
  </Step>
</Steps>

## Campos obligatorios de assess (pay-in)

| Campo | Nivel |
| - | - |
| `amount`, `currency` | **Obligatorio** |
| `submerchant_id` | **Obligatorio** cuando hay subcomercios registrados |
| `order_id` | Recomendado |
| `payment_id` | Recomendado — id de cargo en tu ledger |
| `device.ip` | Recomendado en assess de servidor |
| `email` | Recomendado |

Catálogo en vivo: `GET /api/v1/assess` → `field_requirements_by_segment.psp`.

## Nota de arquitectura

```mermaid theme={null}
sequenceDiagram
  participant SM as Checkout subcomercio
  participant PSP as Tu middleware PSP
  participant CL as Clausum assess
  participant ACQ as Adquirente / rail

  SM->>PSP: Intento de pago
  PSP->>CL: POST /assess + submerchant_id
  CL-->>PSP: decision + session_id
  alt decline
    PSP-->>SM: Rechazo
  else approve
    PSP->>ACQ: Captura / liquidación
  end
```

## Checklist de go-live

* [ ] Todos los subcomercios activos registrados con `external_id` estable
* [ ] Cada assess incluye `submerchant_id` cuando el registro no está vacío
* [ ] Idempotencia vía `order_id` por intento de pago
* [ ] Enrutamiento de webhooks probado por subcomercio
* [ ] UAT en sandbox en `sandbox.clausum.ai` antes de promoción a producción

## Enlaces de capacidades

<CardGroup cols={2}>
  <Card title="Protección de subcomercios" icon="shield" href="/es/guides/psp-submerchant-protection">
    Plantilla, propagar, personalizar
  </Card>

  <Card title="Subcomercios" icon="sitemap" href="/es/guides/psp-submerchants">
    API de registro e interfaz
  </Card>

  <Card title="Assess en tiempo real" icon="bolt" href="/es/guides/realtime-assessment">
    Detalles de API pay-in
  </Card>

  <Card title="Webhooks" icon="webhook" href="/es/guides/receiving-webhooks">
    Eventos salientes
  </Card>

  <Card title="Red de inteligencia" icon="network-wired" href="/es/guides/clausum-intelligence-network">
    Contribuir y consumir señales
  </Card>

  <Card title="Catálogo de capacidades" icon="table-list" href="/es/concepts/capabilities">
    Todos los módulos por segmento
  </Card>
</CardGroup>


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