Batch scoring

Request
Response

POST {BASE_URL}/api/v1/score/batch
X-API-Key: <your-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": []
}

Scores multiple transactions in one request (offline path). Maximum 1,000 transactions per request. Authentication: X-API-Key. Requires fraud_detection_consent=true on your client.

Request body

The body is an object with a transactions array. See Transaction fields reference for full details.

Field	Type	Description
`transactions`	array	Transactions to score. Minimum 1, maximum 1,000

Each array item shares the same schema as POST /score. Required fields:

Field	Type	Description
`transaction_id`	UUID	Unique per client (24 h idempotency)
`merchant_reference`	string	Your internal reference (1–128 characters)
`user_token`	string	User SHA-256 (64 hex)
`merchant_id`	string	Merchant ID on your platform
`amount`	decimal	Amount > 0
`currency`	string	ISO 4217 (e.g. `COP`, `USD`)
`transaction_type`	string	See Enums
`payment_method`	string	See Enums
`timestamp`	datetime	ISO 8601 UTC
`ip_hash`	string	IP SHA-256 (64 hex)
`transaction_country`	string	ISO 3166-1 alpha-2
`mcc`	string	Merchant Category Code (4 digits)
`merchant_risk_tier`	string	`LOW`, `MEDIUM`, or `HIGH`

Optional fields

Enrich scoring (device, geo, merchant, balances). Not required, but they improve rules and model features.

Field	Type	When to send
`destination_account_token`	string	PAYOUT, TRANSFER, P2P, CASHOUT — destination account SHA-256
`card_bin`	string	Card payments — first 6 digits (BIN)
`is_tax_applied`	boolean	Whether tax/VAT was applied. Default `false`
`device_fingerprint_hash`	string	Device fingerprint SHA-256
`os_type`	string	`ANDROID`, `IOS`, `WINDOWS`, `MACOS`, …
`client_type`	string	`WEB`, `MOBILE_APP`, `API`, `POS`, …
`is_emulator`	boolean	`true` if the client detected an emulator
`is_vpn_proxy`	boolean	`true` if IP is VPN or proxy
`is_datacenter_ip`	boolean	`true` if IP is datacenter/hosting
`ip_country`	string	Country from IP (ISO alpha-2)
`destination_country`	string	Cross-border transfers
`merchant_age_days`	integer	Days since merchant onboarding
`origin_balance_before`	number	Origin balance before the transaction
`origin_balance_after`	number	Origin balance after (debits: before − amount)
`destination_balance_before`	number	Destination balance before credit
`destination_balance_after`	number	Destination balance after credit

Full reference: Transaction fields.

Do not send plaintext PII. Use SHA-256 hashes for user_token, ip_hash, and account tokens.

See Thresholds and decisions and SHAP features to interpret each item in results[].

Response fields

Field	Description
`job_id`	Batch job identifier
`total`	Submitted transactions
`completed`	Successfully scored
`failed`	Failures (see `errors`)
`results`	Array of scoring responses (same schema as `/score`)
`errors`	`{ "transaction_id": "...", "message": "..." }` per failed item

More request examples

PAYIN — Bre-B
PAYOUT — bank transfer

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

Include destination_account_token for payouts and transfers to a destination account.

Typical errors

403 — Fraud consent not granted
409 — Duplicate transaction_id within 24 h window (on an item)
422 — Empty array, more than 1,000 items, or validation on an element
504 — Scoring timeout on an item

Kairo Connect

Kairo Shield — Introduction

Kairo Shield — Getting started

Kairo Shield — API

Kairo Shield — Reference

Kairo Shield — Webhooks

Kairo Shield — Summary

Request body

Optional fields

Response fields

More request examples

Typical errors

See also

​Request body

​Optional fields

​Response fields

​More request examples

​Typical errors

​See also

Request body

Optional fields

Response fields

More request examples

Typical errors

See also