Scoring por lote

Petición
Respuesta

POST {BASE_URL}/api/v1/score/batch
X-API-Key: <su-api-key>
Content-Type: application/json

{
  "transactions": [
    {
      "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

{
  "job_id": "batch-20250615-001",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "results": [
    {
      "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": 38.2,
      "scoring_timeout_ms": 500,
      "request_id": "req-batch-001",
      "uiaf_reportable": false
    }
  ],
  "errors": []
}

Evalúa múltiples transacciones en una sola petición (camino offline). Máximo 1.000 transacciones por request. Autenticación: X-API-Key. Requiere fraud_detection_consent=true en su cliente.

Cuerpo de la petición

El body es un objeto con el array transactions. Consulte la referencia de campos de transacción para el detalle completo.

Campo	Tipo	Descripción
`transactions`	array	Transacciones a evaluar. Mínimo 1, máximo 1.000

Cada elemento del array comparte el mismo esquema que POST /score. 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 cada ítem en results[].

Campos de respuesta

Campo	Descripción
`job_id`	Identificador del job de lote
`total`	Transacciones enviadas
`completed`	Scoring exitoso
`failed`	Fallos (ver `errors`)
`results`	Array de respuestas de scoring (mismo esquema que `/score`)
`errors`	`{ "transaction_id": "...", "message": "..." }` por ítem fallido

Más ejemplos de petición

PAYIN — Bre-B
PAYOUT — transferencia

{
  "transactions": [
    {
      "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
    }
  ]
}

{
  "transactions": [
    {
      "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 (en algún ítem)
422 — Array vacío, más de 1.000 ítems, o validación en algún elemento
504 — Timeout de scoring en algún ítem

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

Campos de respuesta

Más ejemplos de petición

Errores típicos

Ver también

​Cuerpo de la petición

​Campos opcionales

​Campos de respuesta

​Más ejemplos de petición

​Errores típicos

​Ver también

Cuerpo de la petición

Campos opcionales

Campos de respuesta

Más ejemplos de petición

Errores típicos

Ver también