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

# Merchant integration (Comercio)

> Step-by-step integration for direct merchants — checkout assess, SDK, and webhooks

For **`organization_type = comercio`**: you accept payments on your own behalf (e-commerce, app checkout, subscription billing). Your integration centers on **pay-in assess before capture**.

## Modules you need

| Module                             | Required?            | Guide                                                                                   |
| ---------------------------------- | -------------------- | --------------------------------------------------------------------------------------- |
| **Prevention — pay-in assess**     | Yes                  | [Real-time assessment](/guides/realtime-assessment)                                     |
| **API keys**                       | Yes                  | [API keys](/guides/api-keys)                                                            |
| **Browser SDK**                    | Recommended          | [Browser SDK](/guides/browser-sdk)                                                      |
| **Outbound webhooks**              | Recommended          | [Receiving webhooks](/guides/receiving-webhooks)                                        |
| **Assess resilience**              | Yes (prod)           | [Assess resilience](/guides/assess-resilience)                                          |
| **Stripe / ingest (post-payment)** | Optional             | [Stripe webhooks](/guides/stripe-webhooks) · [Event ingestion](/guides/event-ingestion) |
| **Report fraud**                   | When fraud confirmed | [Report fraud](/guides/report-fraud)                                                    |
| **Cases & operations**             | If CLM-MOD-OPS       | [Case management](/guides/case-management)                                              |
| **Payout assess**                  | No                   | —                                                                                       |
| **Submerchants**                   | No                   | —                                                                                       |

## Integration phases

<Steps>
  <Step title="Phase 1 — Keys & sandbox">
    1. **Conexiones → Claves API** — create **Publishable** (`clm_pub_*`) and **Secret** (`clm_sk_*`) with **Assess** permission.
    2. Run [Quickstart](/quickstart) against sandbox.
    3. Exercise scenarios in **Simulación** — [Simulation guide](/guides/simulation).
  </Step>

  <Step title="Phase 2 — Checkout prevention">
    **Recommended pattern:** browser SDK for device signals → **server assess** with `clm_sk_*` before PSP capture.

    1. Embed [Browser SDK](/guides/browser-sdk) on checkout.
    2. On payment submit, your backend calls `POST /api/v1/assess` with:
       * `amount`, `currency` (decimal major preferred — see assess guide)
       * `order_id` (stable idempotency key)
       * `device.ip` from the HTTP request
       * `email` or `customer_id`
       * `payment_method` (BIN/last4 for card rules)
       * `session_id` from SDK when available
    3. Branch on `decision`: proceed only on `approve` (or your policy for `review` / `challenge`).
    4. **Your server** calls Stripe / Mercado Pago / your PSP — Clausum does not capture for you.

    See [Architecture — protection loop](/concepts/architecture).
  </Step>

  <Step title="Phase 3 — Async notifications">
    1. **Conexiones → Entrada (webhooks)** — set outbound URL.
    2. Subscribe to `transaction.created` and `transaction.blocked`.
    3. Verify `X-Clausum-Signature` — [Receiving webhooks](/guides/receiving-webhooks).
    4. Put `clausum_session_id` in PSP metadata when capturing.
  </Step>

  <Step title="Phase 4 — Post-payment (optional)">
    Connect provider events for disputes and reconciliation:

    * **Stripe:** [Stripe webhooks](/guides/stripe-webhooks)
    * **Other PSPs:** [Event ingestion](/guides/event-ingestion) with `clm_wh_*`

    Post-payment ingest **does not replace** checkout assess.
  </Step>

  <Step title="Phase 5 — Operations & go-live">
    1. Configure [Protection](/guides/protection-workspace) — rules, blocklists, thresholds.
    2. Implement [Assess resilience](/guides/assess-resilience) fail-open policy for `503` / `504`.
    3. Train team on [Transaction monitor](/guides/transaction-monitor).
    4. On confirmed fraud → [Report fraud](/guides/report-fraud).
    5. Production keys on `https://dashboard.clausum.ai` (or your assigned host).
  </Step>
</Steps>

## Required assess fields (pay-in)

| Field                    | Level                                  |
| ------------------------ | -------------------------------------- |
| `amount`, `currency`     | **Required**                           |
| `order_id`               | Recommended — idempotency and webhooks |
| `device.ip`              | Recommended on **server** assess       |
| `email` or `customer_id` | Recommended                            |
| `payment_method`         | Recommended (card BIN rules)           |
| `submerchant_id`         | Not used                               |

Discover live requirements: `GET /api/v1/assess` → `field_requirements_by_segment.merchant`.

## Go-live checklist

* [ ] Server-side assess with `clm_sk_*` before every capture
* [ ] Stable `order_id` per checkout attempt
* [ ] Outbound webhook URL tested in sandbox
* [ ] Resilience policy documented for maintenance / timeout
* [ ] Team roles assigned — [Team & access](/guides/team-and-access)
* [ ] Rate limits understood — [Rate limits](/reference/rate-limits)

## Next capability deep-dives

<CardGroup cols={2}>
  <Card title="Real-time assess" icon="bolt" href="/guides/realtime-assessment">
    Payload, decisions, amounts
  </Card>

  <Card title="Browser SDK" icon="code" href="/guides/browser-sdk">
    Device fingerprinting
  </Card>

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

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