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

# Bank integration (Banco)

> Integration for financial institutions — pay-in rails, payout assess, cases, and fraud network

For **`organization_type = banco`**: you operate core banking, switches, or treasury platforms. You typically integrate **pay-in assess** (when applicable) and **payout assess** before disbursements, plus institutional modules (cases, fraud network).

## Modules you need

| Module                         | Required?         | Guide                                               |
| ------------------------------ | ----------------- | --------------------------------------------------- |
| **Payout assess**              | Yes (dispersions) | [Payout assessment](/guides/payout-assessment)      |
| **Prevention — pay-in assess** | If card/rails API | [Real-time assessment](/guides/realtime-assessment) |
| **API keys**                   | Yes               | [API keys](/guides/api-keys)                        |
| **Blocklists (flow\_scope)**   | Yes for payout    | [Blocklists](/concepts/blocklists)                  |
| **Outbound webhooks**          | Recommended       | [Receiving webhooks](/guides/receiving-webhooks)    |
| **Assess resilience**          | Yes (prod)        | [Assess resilience](/guides/assess-resilience)      |
| **Cases & regulatory**         | Yes (CLM-MOD-OPS) | [Case management](/guides/case-management)          |
| **Report fraud**               | Yes               | [Report fraud](/guides/report-fraud)                |
| **Fraud intelligence network** | If contracted     | Dashboard → Inteligencia                            |
| **Event ingestion**            | Optional          | [Event ingestion](/guides/event-ingestion)          |
| **Browser SDK**                | Rare              | Usually N/A for core banking                        |

## Integration phases

<Steps>
  <Step title="Phase 1 — Core & keys">
    1. Confirm SQL migrations for payout (`079` blocklists `flow_scope`, `080` assess\_flow) with your Clausum team.
    2. **Conexiones → Claves API** — **Secret** keys (`clm_sk_*`) from core middleware only — never in channels.
    3. Document fail-open policy — [Assess resilience](/guides/assess-resilience).
  </Step>

  <Step title="Phase 2 — Payout prevention (primary)">
    Call assess **before** SPEI, wire, or internal transfer authorization:

    ```json theme={null}
    {
      "amount": 25000.00,
      "amount_unit": "major",
      "currency": "MXN",
      "beneficiary": {
        "id": "ben_core_001",
        "name": "Beneficiary SA",
        "country": "MX",
        "clabe": "012180001234567890"
      },
      "origin": { "account_id": "acct_orig_01", "country": "MX" },
      "payout": {
        "channel": "spei",
        "initiated_by": "ops@bank.com",
        "first_to_beneficiary": false
      }
    }
    ```

    1. `POST /api/v1/assess/payout` with `clm_sk_*`.
    2. On `decline` → **do not** release funds; log `session_id` on the transfer record.
    3. Load CLABE/IBAN blocklists with `flow_scope: payout` — [Blocklists](/concepts/blocklists).
    4. Test via `POST /api/v1/simulation/payout` in Dashboard.

    Full playbook: [Payout assessment](/guides/payout-assessment).
  </Step>

  <Step title="Phase 3 — Pay-in (if applicable)">
    When your API exposes card or instant-payment acceptance:

    * `POST /api/v1/assess` with `payment_id`, `customer_id` as core references
    * `order_id` usually N/A outside e-commerce
    * Live fields: `GET /api/v1/assess` → `field_requirements_by_segment.bank`
  </Step>

  <Step title="Phase 4 — Webhooks & core reconciliation">
    1. Outbound URL for `transaction.created`, `transaction.blocked`, `case.created`.
    2. Map `session_id` to core transaction ids.
    3. Optional ingest for switch events — [Event ingestion](/guides/event-ingestion).
  </Step>

  <Step title="Phase 5 — Operations & network">
    1. [Case management](/guides/case-management) for expedientes and regulatory submission.
    2. [Report fraud](/guides/report-fraud) feeds blocklists automatically.
    3. If **CLM-MOD-INST** / network add-on: configure contribute/consume in **Configuración → Empresa → Red de inteligencia**.
    4. UAT on `cert.clausum.ai` when provided for sign-off.
  </Step>
</Steps>

## Required assess fields

### Pay-in (`POST /api/v1/assess`)

| Field                | Level                                 |
| -------------------- | ------------------------------------- |
| `amount`, `currency` | **Required**                          |
| `payment_id`         | Recommended — core / switch reference |
| `customer_id`        | Recommended — account or party id     |
| `order_id`           | Optional                              |

### Payout (`POST /api/v1/assess/payout`)

| Field                                 | Level                                                       |
| ------------------------------------- | ----------------------------------------------------------- |
| `amount`, `currency`                  | **Required**                                                |
| `beneficiary`                         | **Required** — country, name, clabe, iban, or account\_hash |
| `origin.account_id`, `origin.country` | Recommended                                                 |
| `payout.channel`                      | Recommended — `spei`, `wire`, `api`                         |

Live catalog: `GET /api/v1/assess/payout`.

## Payout signals to expect

| Signal                            | Typical trigger                |
| --------------------------------- | ------------------------------ |
| `payout_first_beneficiary`        | First transfer to beneficiary  |
| `payout_high_risk_country`        | Beneficiary jurisdiction       |
| `payout_cross_border_high_amount` | Cross-border above threshold   |
| Blocklist hit                     | CLABE / IBAN / beneficiary\_id |

## Go-live checklist

* [ ] Migrations `079` + `080` applied in production Supabase
* [ ] Payout blocklists loaded with correct `flow_scope`
* [ ] Core calls assess synchronously before transfer release
* [ ] `503` / `504` fallback approved by risk committee
* [ ] Cases workflow and roles configured
* [ ] Certification UAT completed on assigned stage host

## Capability links

<CardGroup cols={2}>
  <Card title="Payout assess" icon="money-bill-transfer" href="/guides/payout-assessment">
    Disbursement API
  </Card>

  <Card title="Blocklists" icon="ban" href="/concepts/blocklists">
    flow\_scope and payout types
  </Card>

  <Card title="Cases" icon="folder-open" href="/guides/case-management">
    Expedientes
  </Card>

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