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

# Campos de transacción

> Referencia completa del body de POST /score y POST /score/batch

Todos los campos del body de scoring. Los marcados como **Requerido** son obligatorios en `POST /score`.

## Identificación y referencia

| Campo                       | Req. | Descripción                                                              |
| --------------------------- | ---- | ------------------------------------------------------------------------ |
| `transaction_id`            | Sí   | UUID v4. Único por cliente en ventana de 24 h. Reuso → **409**           |
| `merchant_reference`        | Sí   | Su referencia interna (orden, factura). 1–128 caracteres                 |
| `user_token`                | Sí   | SHA-256 del identificador de usuario (64 hex). Nunca envíe IDs en claro  |
| `merchant_id`               | Sí   | ID del comercio en su plataforma (1–64 caracteres)                       |
| `destination_account_token` | No   | SHA-256 de cuenta destino. Recomendado en PAYOUT, TRANSFER, P2P, CASHOUT |

## Monto y tipo

| Campo              | Req. | Descripción                                   |
| ------------------ | ---- | --------------------------------------------- |
| `amount`           | Sí   | Decimal > 0. Misma precisión que su ledger    |
| `currency`         | Sí   | ISO 4217 (`COP`, `USD`, `MXN`, …)             |
| `transaction_type` | Sí   | Ver [Enums](/docs/shield/reference/enums)          |
| `payment_method`   | Sí   | Ver [Enums](/docs/shield/reference/enums)          |
| `card_bin`         | No   | Primeros 6 dígitos de tarjeta (cuando aplica) |
| `is_tax_applied`   | No   | Default `false`                               |

## Tiempo y dispositivo

| Campo                     | Req. | Descripción                             |
| ------------------------- | ---- | --------------------------------------- |
| `timestamp`               | Sí   | Hora del evento en UTC (ISO 8601)       |
| `device_fingerprint_hash` | No   | SHA-256 del fingerprint de dispositivo  |
| `os_type`                 | No   | `ANDROID`, `IOS`, `WINDOWS`, `MACOS`, … |
| `client_type`             | No   | `WEB`, `MOBILE_APP`, `API`, `POS`, …    |
| `is_emulator`             | No   | `true` si detectó emulador              |

## Geolocalización y red

| Campo                 | Req. | Descripción                                  |
| --------------------- | ---- | -------------------------------------------- |
| `ip_hash`             | Sí   | SHA-256 de la IP (64 hex). Nunca IP en claro |
| `is_vpn_proxy`        | No   | VPN o proxy detectado                        |
| `is_datacenter_ip`    | No   | IP de datacenter/hosting                     |
| `ip_country`          | No   | País derivado de IP (ISO alpha-2)            |
| `transaction_country` | Sí   | País donde se inicia la transacción          |
| `destination_country` | No   | País destino en transferencias cross-border  |

## Comercio

| Campo                | Req. | Descripción                                 |
| -------------------- | ---- | ------------------------------------------- |
| `mcc`                | Sí   | Merchant Category Code (4 dígitos)          |
| `merchant_risk_tier` | Sí   | Su banda de riesgo: `LOW`, `MEDIUM`, `HIGH` |
| `merchant_age_days`  | No   | Días desde onboarding del comercio          |

## Balances (opcional)

| Campo                        | Descripción                                     |
| ---------------------------- | ----------------------------------------------- |
| `origin_balance_before`      | Saldo origen antes de la transacción            |
| `origin_balance_after`       | Saldo origen después (debitos: before − amount) |
| `destination_balance_before` | Saldo destino antes del crédito                 |
| `destination_balance_after`  | Saldo destino después del crédito               |