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

# Evaluación en tiempo real (pay-in)

> POST /api/v1/assess — evalúa riesgo de checkout antes del capture

Pay-in assess es la integración **principal**: llama a Clausum cuando el cliente envía el pago, luego ramifica según `decision` antes de cobrar la tarjeta o billetera.

## Endpoint

```
POST https://dashboard.clausum.ai/api/v1/assess
Authorization: Bearer clm_sk_...
Content-Type: application/json
Idempotency-Key: <optional header; order_id also dedupes>
```

Permiso partner requerido: **Assess** en la clave API.

## Cuerpo de la solicitud

```json theme={null}
{
  "amount": 125.00,
  "amount_unit": "major",
  "currency": "USD",
  "order_id": "shop_order_8842",
  "submerchant_id": "sm_optional_psp_only",
  "customer": {
    "email": "buyer@example.com",
    "phone": "+15551234567",
    "ip_address": "198.51.100.42",
    "billing_country": "US"
  },
  "device": {
    "fingerprint": "fp_abc123",
    "user_agent": "Mozilla/5.0 ..."
  },
  "payment_method": {
    "type": "card",
    "bin": "424242",
    "last4": "4242"
  },
  "metadata": {
    "cart_id": "cart_99"
  }
}
```

### Montos

La API assess acepta codificación flexible de montos. **Preferido:** unidades mayores decimales.

| Campo | Descripción |
| - | - |
| `amount` | Mayor decimal (p. ej. `125.00` USD) — **recomendado** |
| `amount_unit` | `"major"` o `"minor"` — desambigua enteros |
| `amount_minor` | Centavos explícitos (siempre unidades menores) |
| Legacy | Entero sin `amount_unit` → interpretado como **centavos** (encabezado de deprecación devuelto) |

| Contexto | Unidad |
| - | - |
| UI de simulación del panel | Unidades mayores (125 = \$125.00) |
| `amount_limit` de blocklist / regla en Panel | Unidades mayores |

Llama `GET /api/v1/assess` (sin auth) para el catálogo en vivo de montos y requisitos de campos de tu versión desplegada.

### Idempotencia

* Envía **`order_id`** estable por intento de checkout
* Reintentos con el mismo `order_id` devuelven la decisión **cacheada** (sin doble scoring)
* Encabezado opcional `Idempotency-Key` para partners que prefieren dedup por encabezado

### Subcomercios PSP

Si tu tipo de organización es **psp**, pasa `submerchant_id` (UUID Clausum de [API de Submerchants](/es/guides/psp-submerchants)) para que reglas y blocklists tengan scope en ese comercio.

## Respuesta

```json theme={null}
{
  "decision": "approve",
  "risk_score": 18,
  "signals": ["velocity_email_1h"],
  "session_id": "ps_7f3a...",
  "assess_flow": "payin",
  "protection_scope": {
    "rules_org_id": "uuid",
    "active_rules": 12,
    "active_blocklists": 3
  }
}
```

### Decisiones

| Decision | Acción recomendada |
| - | - |
| `approve` | Proceder con capture |
| `review` | Retener para revisión manual o step-up |
| `challenge` | SCA / OTP / verificación adicional |
| `decline` | No capture; muestra fallo genérico. Dispara webhook `transaction.blocked` |

## Salud y resiliencia

| HTTP | Significado |
| - | - |
| `200` | Decisión devuelta |
| `503` + `ASSESS_MAINTENANCE` | Mantenimiento de plataforma — usa tu política de fallback |
| `504` + `ASSESS_TIMEOUT` | Timeout — reintenta con el mismo `order_id` |

Consulta [Resiliencia de assess](/es/guides/assess-resilience).

## Simulación (panel)

Usuarios autenticados pueden probar vía `POST /api/v1/simulation/assess` (misma forma de payload, etiquetado como simulación). **No** uses `/api/demo/assess` para tu tenant — ese endpoint apunta a la org demo pública.

## Relacionado

* [Assess de payout](/es/guides/payout-assessment) — flujos salientes
* [Eventos webhook](/es/concepts/webhook-events) — `transaction.created` en approve/review/challenge
* [Blocklists](/es/concepts/blocklists) — listas de tenant y plataforma


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