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

# Transaction fields

> Complete reference for POST /score and POST /score/batch request bodies

All scoring body fields. Fields marked **Required** are mandatory on `POST /score`.

## Identification and reference

| Field | Req. | Description |
| - | - | - |
| `transaction_id` | Yes | UUID v4. Unique per client within 24 h. Reuse → **409** |
| `merchant_reference` | Yes | Your internal reference. 1–128 characters |
| `user_token` | Yes | User identifier SHA-256 (64 hex). Never send raw IDs |
| `merchant_id` | Yes | Merchant ID on your platform (1–64 characters) |
| `destination_account_token` | No | Destination account SHA-256. Recommended for PAYOUT, TRANSFER, P2P, CASHOUT |

## Amount and type

| Field | Req. | Description |
| - | - | - |
| `amount` | Yes | Decimal > 0. Same precision as your ledger |
| `currency` | Yes | ISO 4217 (`COP`, `USD`, `MXN`, …) |
| `transaction_type` | Yes | See [Enums](/docs/shield/reference/enums) |
| `payment_method` | Yes | See [Enums](/docs/shield/reference/enums) |
| `card_bin` | No | First 6 card digits when applicable |
| `is_tax_applied` | No | Default `false` |

## Time and device

| Field | Req. | Description |
| - | - | - |
| `timestamp` | Yes | Event time in UTC (ISO 8601) |
| `device_fingerprint_hash` | No | Device fingerprint SHA-256 |
| `os_type` | No | `ANDROID`, `IOS`, `WINDOWS`, `MACOS`, … |
| `client_type` | No | `WEB`, `MOBILE_APP`, `API`, `POS`, … |
| `is_emulator` | No | `true` if emulator detected |

## Geo and network

| Field | Req. | Description |
| - | - | - |
| `ip_hash` | Yes | IP SHA-256 (64 hex). Never plaintext IP |
| `is_vpn_proxy` | No | VPN or proxy detected |
| `is_datacenter_ip` | No | Datacenter/hosting IP |
| `ip_country` | No | Country from IP (ISO alpha-2) |
| `transaction_country` | Yes | Country where transaction starts |
| `destination_country` | No | Destination country for cross-border transfers |

## Merchant

| Field | Req. | Description |
| - | - | - |
| `mcc` | Yes | Merchant Category Code (4 digits) |
| `merchant_risk_tier` | Yes | Your risk band: `LOW`, `MEDIUM`, `HIGH` |
| `merchant_age_days` | No | Days since merchant onboarding |

## Balances (optional)

| Field | Description |
| - | - |
| `origin_balance_before` | Origin balance before transaction |
| `origin_balance_after` | Origin balance after (debits: before − amount) |
| `destination_balance_before` | Destination balance before credit |
| `destination_balance_after` | Destination balance after credit |


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