> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairoconnect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Scoring en tiempo real

> POST /score — evaluar una transacción para fraude en tiempo real

<Tabs>
  <Tab title="Petición">
    ```http theme={null}
    POST {BASE_URL}/api/v1/score
    X-API-Key: <su-api-key>
    Content-Type: application/json

    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "merchant_reference": "MERCH-TX-001",
      "user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
      "merchant_id": "merchant_001",
      "amount": "150000.00",
      "currency": "COP",
      "transaction_type": "PAYIN",
      "payment_method": "CARD",
      "card_bin": "411111",
      "client_type": "MOBILE_APP",
      "is_tax_applied": true,
      "timestamp": "2025-06-15T14:30:00Z",
      "ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
      "transaction_country": "CO",
      "mcc": "5812",
      "merchant_risk_tier": "MEDIUM",
      "merchant_age_days": 365
    }
    ```
  </Tab>

  <Tab title="Respuesta">
    ```http theme={null}
    HTTP/1.1 200 OK
    Content-Type: application/json

    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "fraud_score": 0.15,
      "risk_level": "LOW",
      "decision": "APPROVE",
      "decision_source": "MODEL",
      "top_features": [
        {"feature": "amount_log", "importance": 0.05},
        {"feature": "channel_ord", "importance": -0.03}
      ],
      "model_version": "kairo-shield",
      "threshold_used": {
        "low_max": 0.25,
        "medium_max": 0.55,
        "high_max": 0.80
      },
      "processing_time_ms": 42.5,
      "scoring_timeout_ms": 500,
      "request_id": "req-abc123",
      "uiaf_reportable": false
    }
    ```
  </Tab>
</Tabs>

Evalúa una transacción en tiempo real. Objetivo de latencia: **p99 \< 500 ms** en el camino caliente.

**Autenticación:** `X-API-Key`. Requiere `fraud_detection_consent=true` en su cliente.

## Cuerpo de la petición

Consulte la [referencia de campos de transacción](/docs/shield/reference/transaction-fields) para el detalle completo. Campos obligatorios:

| Campo                 | Tipo     | Descripción                                         |
| --------------------- | -------- | --------------------------------------------------- |
| `transaction_id`      | UUID     | Identificador único por cliente (idempotencia 24 h) |
| `merchant_reference`  | string   | Su referencia interna (1–128 caracteres)            |
| `user_token`          | string   | SHA-256 del usuario (64 hex)                        |
| `merchant_id`         | string   | ID del comercio en su plataforma                    |
| `amount`              | decimal  | Monto > 0                                           |
| `currency`            | string   | ISO 4217 (ej. `COP`, `USD`)                         |
| `transaction_type`    | string   | Ver [Enums](/docs/shield/reference/enums)                |
| `payment_method`      | string   | Ver [Enums](/docs/shield/reference/enums)                |
| `timestamp`           | datetime | ISO 8601 UTC                                        |
| `ip_hash`             | string   | SHA-256 de la IP (64 hex)                           |
| `transaction_country` | string   | ISO 3166-1 alpha-2                                  |
| `mcc`                 | string   | Merchant Category Code (4 dígitos)                  |
| `merchant_risk_tier`  | string   | `LOW`, `MEDIUM` o `HIGH`                            |

### Campos opcionales

Enriquecen el scoring (dispositivo, geo, comercio, balances). No son obligatorios, pero mejoran reglas y features del modelo.

| Campo                        | Tipo    | Cuándo enviarlo                                               |
| ---------------------------- | ------- | ------------------------------------------------------------- |
| `destination_account_token`  | string  | PAYOUT, TRANSFER, P2P, CASHOUT — SHA-256 de la cuenta destino |
| `card_bin`                   | string  | Pagos con tarjeta — primeros 6 dígitos (BIN)                  |
| `is_tax_applied`             | boolean | Si aplicó impuesto/VAT. Default `false`                       |
| `device_fingerprint_hash`    | string  | SHA-256 del fingerprint de dispositivo                        |
| `os_type`                    | string  | `ANDROID`, `IOS`, `WINDOWS`, `MACOS`, …                       |
| `client_type`                | string  | `WEB`, `MOBILE_APP`, `API`, `POS`, …                          |
| `is_emulator`                | boolean | `true` si el cliente detectó emulador                         |
| `is_vpn_proxy`               | boolean | `true` si la IP es VPN o proxy                                |
| `is_datacenter_ip`           | boolean | `true` si la IP es de datacenter/hosting                      |
| `ip_country`                 | string  | País derivado de la IP (ISO alpha-2)                          |
| `destination_country`        | string  | Transferencias cross-border                                   |
| `merchant_age_days`          | integer | Días desde el onboarding del comercio                         |
| `origin_balance_before`      | number  | Saldo origen antes de la transacción                          |
| `origin_balance_after`       | number  | Saldo origen después (débitos: before − amount)               |
| `destination_balance_before` | number  | Saldo destino antes del crédito                               |
| `destination_balance_after`  | number  | Saldo destino después del crédito                             |

Detalle completo en [Campos de transacción](/docs/shield/reference/transaction-fields).

<Warning>
  **No envíe PII en claro.** Use hashes SHA-256 para `user_token`, `ip_hash` y tokens de cuenta.
</Warning>

Consulte [Umbrales y decisiones](/docs/shield/reference/thresholds) y [Features SHAP](/docs/shield/reference/shap-features) para interpretar la respuesta.

## Más ejemplos de petición

<Tabs>
  <Tab title="PAYIN — Bre-B">
    ```json theme={null}
    {
      "transaction_id": "660e8400-e29b-41d4-a716-446655440001",
      "merchant_reference": "MERCH-BREB-001",
      "user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
      "merchant_id": "merchant_001",
      "amount": "250000.00",
      "currency": "COP",
      "transaction_type": "PAYIN",
      "payment_method": "BREB",
      "is_tax_applied": false,
      "timestamp": "2025-06-15T14:30:00Z",
      "device_fingerprint_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "os_type": "ANDROID",
      "client_type": "MOBILE_APP",
      "is_emulator": false,
      "ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
      "transaction_country": "CO",
      "mcc": "6012",
      "merchant_risk_tier": "MEDIUM",
      "merchant_age_days": 120
    }
    ```
  </Tab>

  <Tab title="PAYOUT — transferencia">
    ```json theme={null}
    {
      "transaction_id": "770e8400-e29b-41d4-a716-446655440002",
      "merchant_reference": "MERCH-PAYOUT-001",
      "user_token": "a3f2b8c9d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
      "merchant_id": "merchant_001",
      "destination_account_token": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "amount": "500000.00",
      "currency": "COP",
      "transaction_type": "PAYOUT",
      "payment_method": "BANK_TRANSFER",
      "is_tax_applied": false,
      "timestamp": "2025-06-15T15:00:00Z",
      "client_type": "API",
      "ip_hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b201",
      "transaction_country": "CO",
      "destination_country": "CO",
      "mcc": "6010",
      "merchant_risk_tier": "MEDIUM",
      "merchant_age_days": 365
    }
    ```

    Incluya `destination_account_token` en desembolsos y transferencias hacia cuenta destino.
  </Tab>
</Tabs>

## Errores típicos

* **403** — Consentimiento de fraude no otorgado
* **409** — `transaction_id` duplicado en ventana de 24 h
* **422** — Validación (enum inválido, amount ≤ 0, hash no de 64 caracteres)
* **504** — Timeout de scoring

## Ver también

* [Scoring por lote](/docs/shield/api/score-batch)
* [Campos de transacción](/docs/shield/reference/transaction-fields)
* [Enums permitidos](/docs/shield/reference/enums)