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