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

> Integration for payment service providers — submerchants, partner API, and multi-tenant assess

For **`organization_type = psp`**: you process payments on behalf of many merchants. Every pay-in assess must identify **which sub-merchant** the transaction belongs to.

## Modules you need

| Module                         | Required?                    | Guide                                               |
| ------------------------------ | ---------------------------- | --------------------------------------------------- |
| **Prevention — pay-in assess** | Yes                          | [Real-time assessment](/guides/realtime-assessment) |
| **Submerchant registry**       | Yes (if children registered) | [PSP submerchants](/guides/psp-submerchants)        |
| **API keys**                   | Yes                          | [API keys](/guides/api-keys)                        |
| **Outbound webhooks**          | Recommended                  | [Receiving webhooks](/guides/receiving-webhooks)    |
| **Assess resilience**          | Yes (prod)                   | [Assess resilience](/guides/assess-resilience)      |
| **Event ingestion**            | Recommended                  | [Event ingestion](/guides/event-ingestion)          |
| **Browser SDK**                | Per sub-merchant checkout    | [Browser SDK](/guides/browser-sdk)                  |
| **Payout assess**              | If CLM-MOD-INST / treasury   | [Payout assessment](/guides/payout-assessment)      |
| **Fraud network**              | If contracted                | Dashboard → Inteligencia                            |

## Integration phases

<Steps>
  <Step title="Phase 1 — Organization & keys">
    1. Complete PSP onboarding in Dashboard.
    2. **Conexiones → Claves API** — **Secret** key (`clm_sk_*`) for server orchestration (PSP middleware).
    3. Optional **Publishable** keys per sub-merchant checkout if you expose SDK embeds.
  </Step>

  <Step title="Phase 2 — Submerchant registry">
    1. Register each child merchant — [PSP submerchants](/guides/psp-submerchants):\
       `POST /api/v1/submerchants` (dashboard JWT) or UI in Conexiones.
    2. Store Clausum `submerchant_id` (UUID) mapped to your `external_id`.
    3. **Rule:** if your org has registered submerchants, assess **must** include valid `submerchant_id` — org-level fallback is rejected.
  </Step>

  <Step title="Phase 3 — Partner API orchestration">
    Your middleware calls assess for each payment attempt:

    ```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` with `clm_sk_*`.
    2. Enforce `decision` before settling funds to the sub-merchant.
    3. Scope rules/blocklists per sub-merchant org in Clausum.
    4. Return `session_id` to your ledger for audit.

    See [Real-time assessment](/guides/realtime-assessment).
  </Step>

  <Step title="Phase 4 — Webhooks & ingest">
    1. Configure outbound URL per environment (sandbox vs production).
    2. Route events to sub-merchant backends using `submerchant_id` in payload metadata.
    3. Pipe acquirer/PSP events via [Event ingestion](/guides/event-ingestion) or [Stripe webhooks](/guides/stripe-webhooks).
  </Step>

  <Step title="Phase 5 — Scale & go-live">
    1. Separate API keys per environment and major workloads.
    2. [Assess resilience](/guides/assess-resilience) — idempotent retries with same `order_id`.
    3. Monitor API activity in **Conexiones → Monitor**.
    4. If institutional module: evaluate [Payout assessment](/guides/payout-assessment) for treasury flows.
  </Step>
</Steps>

## Required assess fields (pay-in)

| Field                | Level                                         |
| -------------------- | --------------------------------------------- |
| `amount`, `currency` | **Required**                                  |
| `submerchant_id`     | **Required** when submerchants are registered |
| `order_id`           | Recommended                                   |
| `payment_id`         | Recommended — your ledger charge id           |
| `device.ip`          | Recommended on server assess                  |
| `email`              | Recommended                                   |

Live catalog: `GET /api/v1/assess` → `field_requirements_by_segment.psp`.

## Architecture note

```mermaid theme={null}
sequenceDiagram
  participant SM as Sub-merchant checkout
  participant PSP as Your PSP middleware
  participant CL as Clausum assess
  participant ACQ as Acquirer / rail

  SM->>PSP: Payment attempt
  PSP->>CL: POST /assess + submerchant_id
  CL-->>PSP: decision + session_id
  alt decline
    PSP-->>SM: Reject
  else approve
    PSP->>ACQ: Capture / settle
  end
```

## Go-live checklist

* [ ] All active submerchants registered with stable `external_id`
* [ ] Every assess includes `submerchant_id` when registry is non-empty
* [ ] Idempotency via `order_id` per payment attempt
* [ ] Webhook routing tested per sub-merchant
* [ ] Sandbox UAT on `sandbox.clausum.ai` before production promotion

## Capability links

<CardGroup cols={2}>
  <Card title="Submerchants" icon="sitemap" href="/guides/psp-submerchants">
    Registry API and UI
  </Card>

  <Card title="Real-time assess" icon="bolt" href="/guides/realtime-assessment">
    Pay-in API details
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/receiving-webhooks">
    Outbound events
  </Card>

  <Card title="Capability catalog" icon="table-list" href="/concepts/capabilities">
    All modules by segment
  </Card>
</CardGroup>