Scoring en tiempo real

Petición
Respuesta

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
}

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
}

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 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
`payment_method`	string	Ver 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.

No envíe PII en claro. Use hashes SHA-256 para user_token, ip_hash y tokens de cuenta.

Consulte Umbrales y decisiones y Features SHAP para interpretar la respuesta.

Más ejemplos de petición

PAYIN — Bre-B
PAYOUT — transferencia

{
  "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
}

{
  "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.

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

Kairo Connect

Kairo Shield — Introducción

Kairo Shield — Comenzando

Kairo Shield — API

Kairo Shield — Referencia

Kairo Shield — Webhooks

Kairo Shield — Resumen

Cuerpo de la petición

Campos opcionales

Más ejemplos de petición

Errores típicos

Ver también

​Cuerpo de la petición

​Campos opcionales

​Más ejemplos de petición

​Errores típicos

​Ver también

Cuerpo de la petición

Campos opcionales

Más ejemplos de petición

Errores típicos

Ver también