API Reference - /transaction/analyze

Endpoint

POST https://api.gu1.ai/transaction/analyze

Autenticación

Requiere una clave de API válida en el encabezado de autorización:

Authorization: Bearer YOUR_API_KEY

Headers Requeridos

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Idempotency-Key: unique_request_id  # Opcional pero recomendado

Request Body

transaction

object

required

Objeto de transacción con todos los detalles del pago

Campos Core de Transaction

transaction.externalId

string

required

Tu identificador único para esta transacción (máx. 255 caracteres)

transaction.type

enum

required

Tipo de transacción. Valores posibles:

Tipo	Descripción
`PAYMENT`	Compra o pago a comerciante
`TRANSFER`	Transferencia entre cuentas/usuarios
`WITHDRAWAL`	Retiro de efectivo o débito de cuenta
`DEPOSIT`	Depósito o crédito de cuenta
`REFUND`	Reembolso de una transacción anterior
`CHARGEBACK`	Disputa de contracargo
`REVERSAL`	Reversión de transacción
`FEE`	Cargo de comisión o tarifa
`ADJUSTMENT`	Ajuste de saldo
`OTHER`	Otro tipo de transacción

transaction.amount

number

required

Monto de la transacción (debe ser positivo, máx. 999,999,999.99)

transaction.currency

string

required

Código ISO 4217 de 3 letras (ej: USD, BRL, ARS, EUR)

transaction.timestamp

string

required

Fecha y hora de la transacción en formato ISO 8601 (ej: 2024-10-28T14:30:00Z)

Entidades Involucradas

transaction.originEntityId

string

required

Identificador de la entidad que origina la transacción (tu ID externo)

transaction.destinationEntityId

string

required

Identificador de la entidad receptora (tu ID externo)

Detalles de Pago

transaction.origin

object

required

Detalles del método de pago origen

Show Campos de origin

paymentMethod

enum

required

Método de pago. Valores posibles:Tarjetas:

CARD - Tarjeta de crédito/débito (genérica)
CREDIT_CARD - Tarjeta de crédito
DEBIT_CARD - Tarjeta de débito
PREPAID_CARD - Tarjeta prepagada

Transferencias Bancarias:

BANK_TRANSFER - Transferencia bancaria genérica
WIRE - Transferencia wire
ACH - Transferencia ACH (US)
SEPA - Transferencia SEPA (EU)

Billeteras Digitales:

WALLET - Billetera digital genérica
PAYPAL - PayPal
APPLE_PAY - Apple Pay
GOOGLE_PAY - Google Pay
SAMSUNG_PAY - Samsung Pay
VENMO - Venmo
ZELLE - Zelle

América Latina:

PIX - Pago instantáneo brasileño
CBU - Cuenta bancaria argentina
CVU - Billetera virtual argentina
DEBIN - Débito directo argentino
SPEI - Pago instantáneo mexicano
PSE - Pago online colombiano

Criptomonedas:

CRYPTO - Criptomoneda (genérica)
BITCOIN - Bitcoin
ETHEREUM - Ethereum
STABLECOIN - Stablecoins (USDT, USDC, etc.)

Efectivo y Otros:

CASH - Pago en efectivo
CHECK - Cheque
MONEY_ORDER - Giro postal
MOBILE_MONEY - Dinero móvil (M-Pesa, etc.)
OTHER - Otro método de pago

accountId

string

ID de la cuenta de pago

accountType

enum

Tipo de cuenta:

PERSONAL - Cuenta personal
BUSINESS - Cuenta empresarial
MERCHANT - Cuenta de comerciante
SAVINGS - Cuenta de ahorros
CHECKING - Cuenta corriente
INVESTMENT - Cuenta de inversión
ESCROW - Cuenta de depósito en garantía
PREPAID - Cuenta prepagada
OTHER - Otro tipo de cuenta

Para tarjetas:

cardLast4

string

Últimos 4 dígitos (exactamente 4 dígitos numéricos)

cardBrand

string

Marca de tarjeta (ej: Visa, Mastercard, Amex)

Para transferencias bancarias:

bankName

string

Nombre del banco

accountNumber

string

Número de cuenta

routingNumber

string

Número de routing/CBU/CVU

Para wallets digitales:

walletId

string

ID de la wallet

walletProvider

string

Proveedor de la wallet

transaction.destination

object

required

Detalles del método de pago destino (misma estructura que origin)

Datos de Dispositivo (Opcional)

transaction.originDeviceData

object

Datos del dispositivo que origina la transacción

Show Campos de dispositivo

deviceId

string

ID único del dispositivo

deviceFingerprint

string

Huella digital del dispositivo

ipAddress

string

Dirección IP (formato IPv4 o IPv6 válido)

userAgent

string

User agent del navegador/app

platform

enum

Plataforma: web, ios, android, other

appVersion

string

Versión de la app (formato X.Y.Z)

location

object

Ubicación geográfica

latitude

number

Latitud (-90 a 90)

longitude

number

Longitud (-180 a 180)

country

string

Código ISO 3166-1 alpha-2 (ej: AR, BR, US)

city

string

Nombre de la ciudad

transaction.destinationDeviceData

object

Datos del dispositivo destino (misma estructura que originDeviceData)

Campos Adicionales (Opcional)

transaction.mccCode

string

Merchant Category Code - exactamente 4 dígitos numéricos (ej: 5411 para supermercados)

transaction.customTags

object

Tags personalizados como pares clave-valor para clasificación y filtrado

transaction.metadata

object

Metadata adicional como pares clave-valor

Soporte Multi-Moneda

gu1 proporciona conversión automática de moneda para todas las transacciones. Cada organización tiene una moneda base configurada (por defecto: USD), y todas las transacciones se convierten automáticamente a esta moneda base para una evaluación de reglas y reportes consistentes.

Cómo Funciona

Detección Automática: Cuando la currency de una transacción difiere de la moneda base de tu organización, se activa la conversión automática
Tasas en Tiempo Real: Las tasas de cambio se obtienen de nuestro servicio de monedas en tiempo real
Almacenamiento de Montos Duales: Se almacenan tanto los montos originales como los convertidos
Evaluación de Reglas: Las reglas pueden usar amount (original) o amountBaseCurrency (convertido)

Monedas Soportadas

Más de 150 monedas soportadas incluyendo:

Principales: USD, EUR, GBP, JPY, CHF, CAD, AUD
América Latina: BRL, ARS, MXN, COP, CLP, PEN, UYU
Asia: CNY, INR, KRW, SGD, HKD, THB, MYR
Cripto: BTC, ETH, USDT, USDC
Y muchas más (estándar ISO 4217)

Fuentes de Tasas de Cambio

Fuente	Descripción	Cuándo se Usa
`ms-provider`	Tasas en tiempo real del microservicio de monedas	Fuente primaria
`cache-fallback`	Tasas en caché cuando el servicio no está disponible	Respaldo (< 1h de antigüedad)
`no-conversion`	No se necesita conversión (misma moneda)	Igual a la base
`client-provided`	Tasa personalizada proporcionada por el cliente	Anulación opcional

Campos de Respuesta

Cuando ocurre una conversión de moneda, la respuesta incluye:

{
  "currencyConversion": {
    "originalAmount": 500.00,
    "originalCurrency": "BRL",
    "convertedAmount": 100.00,
    "baseCurrency": "USD",
    "exchangeRate": 0.20,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T14:30:00Z"
  }
}

Uso de Montos Convertidos en Reglas

Las reglas pueden referenciar ambos montos:

{
  "conditions": [
    {
      "field": "amount",
      "operator": "GREATER_THAN",
      "value": 1000
    }
  ]
}

O usar el monto convertido para umbrales consistentes:

{
  "conditions": [
    {
      "field": "amountBaseCurrency",
      "operator": "GREATER_THAN",
      "value": 10000
    }
  ]
}

Mejor Práctica: Usa amountBaseCurrency en las reglas para asegurar umbrales consistentes sin importar la moneda de la transacción.

Manejo de Errores

Si la conversión de moneda falla:

El procesamiento de la transacción continúa con el monto original
El campo currencyConversion se omitirá de la respuesta
Las reglas que usen amountBaseCurrency usarán el amount original como respaldo
El error se registra pero no bloquea la transacción

Ejemplo: Transacción Multi-Moneda

{
  "transaction": {
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": 850.00,
    "currency": "EUR",
    "timestamp": "2024-10-28T15:00:00Z",
    "originEntityId": "customer_france_001",
    "destinationEntityId": "merchant_usa_001"
  }
}

La respuesta incluye conversión:

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "APPROVE"
  },
  "currencyConversion": {
    "originalAmount": 850.00,
    "originalCurrency": "EUR",
    "convertedAmount": 935.00,
    "baseCurrency": "USD",
    "exchangeRate": 1.10,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T15:00:01Z"
  }
}

Response

Success Response (200 OK)

success

boolean

Siempre true en caso de éxito

transaction

object

Información de la transacción analizada

Show Campos

string

ID interno de gu1 para esta transacción

state

enum

Decisión de la transacción:

APPROVE - Aprobada, puede procesarse
REJECT - Rechazada, no debe procesarse
HOLD - En espera, requiere revisión manual
REVIEW_REQUIRED - Requiere revisión adicional
ADDITIONAL_AUTH_REQUIRED - Requiere autenticación adicional
NO_ACTION - Sin acción específica

riskScore

number

Puntuación de riesgo de 0-100 (0 = sin riesgo, 100 = riesgo máximo)

riskLevel

enum

Nivel de riesgo: LOW, MEDIUM, HIGH, CRITICAL

alerts

array

Lista de alertas generadas por reglas

Show Estructura de alerta

string

ID de la alerta

severity

enum

Severidad: info, low, medium, high, critical

Ejemplos

Ejemplo 1: Transferencia PIX (Brasil)

curl -X POST https://api.gu1.ai/transaction/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: txn_pix_001" \
  -d '{
    "transaction": {
      "externalId": "txn_pix_12345",
      "type": "TRANSFER",
      "amount": 500.00,
      "currency": "BRL",
      "timestamp": "2024-10-28T14:30:00Z",
      "originEntityId": "customer_maria_001",
      "destinationEntityId": "merchant_loja_002",
      "origin": {
        "paymentMethod": "PIX",
        "accountType": "PERSONAL",
        "accountId": "[email protected]"
      },
      "destination": {
        "paymentMethod": "PIX",
        "accountType": "BUSINESS",
        "accountId": "11222333000144"
      },
      "originDeviceData": {
        "deviceId": "device_android_001",
        "ipAddress": "177.20.145.30",
        "userAgent": "Mozilla/5.0 (Linux; Android 12) Mobile",
        "platform": "android",
        "appVersion": "2.5.1",
        "location": {
          "latitude": -23.550520,
          "longitude": -46.633308,
          "country": "BR",
          "city": "São Paulo"
        }
      },
      "mccCode": "5411",
      "customTags": {
        "campaign": "black_friday",
        "channel": "mobile_app"
      }
    }
  }'

Ejemplo de Respuesta - Transacción Aprobada

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "APPROVE"
  },
  "riskScore": 15,
  "riskLevel": "LOW",
  "alerts": [],
  "actions": [],
  "currencyConversion": {
    "originalAmount": 500.00,
    "originalCurrency": "BRL",
    "convertedAmount": 100.00,
    "baseCurrency": "USD",
    "exchangeRate": 0.20,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T14:30:01Z"
  },
  "entitiesResolved": {
    "origin": {
      "entityId": "ent_maria_001",
      "wasCreated": false
    },
    "destination": {
      "entityId": "ent_loja_002",
      "wasCreated": false
    }
  },
  "processingTime": 245
}

Ejemplo 2: Pago con Tarjeta (Alto Riesgo)

curl -X POST https://api.gu1.ai/transaction/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "externalId": "txn_card_99999",
      "type": "PAYMENT",
      "amount": 15000.00,
      "currency": "USD",
      "timestamp": "2024-10-28T23:45:00Z",
      "originEntityId": "customer_suspicious_001",
      "destinationEntityId": "merchant_electronics_001",
      "origin": {
        "paymentMethod": "CREDIT_CARD",
        "cardLast4": "4532",
        "cardBrand": "Visa",
        "accountType": "PERSONAL"
      },
      "destination": {
        "paymentMethod": "BANK_TRANSFER",
        "bankName": "First National Bank",
        "accountNumber": "****1234",
        "accountType": "BUSINESS"
      },
      "originDeviceData": {
        "ipAddress": "45.123.222.111",
        "platform": "web",
        "location": {
          "country": "RU"
        }
      },
      "mccCode": "5732"
    }
  }'

Ejemplo de Respuesta - Transacción Rechazada

{
  "success": true,
  "transaction": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "state": "REJECT"
  },
  "riskScore": 85,
  "riskLevel": "CRITICAL",
  "alerts": [
    {
      "id": "alert_001",
      "severity": "critical",
      "category": "high_amount",
      "message": "Transaction amount exceeds daily limit",
      "ruleId": "rule_daily_limit",
      "ruleName": "Daily Transaction Limit"
    },
    {
      "id": "alert_002",
      "severity": "high",
      "category": "location_mismatch",
      "message": "Transaction from high-risk country",
      "ruleId": "rule_geo_check",
      "ruleName": "Geographic Risk Check"
    }
  ],
  "actions": [
    {
      "type": "block_transaction",
      "reason": "Multiple high-risk indicators detected",
      "parameters": {
        "indicators": ["high_amount", "suspicious_location", "new_card"]
      }
    }
  ],
  "processingTime": 312
}

Manejo de Errores

400 Bad Request - Validación Fallida

{
  "success": false,
  "error": {
    "message": "Transaction validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
      "transaction.amount: Amount must be positive",
      "transaction.currency: Currency must be ISO 4217 code (3 letters)",
      "transaction.origin.paymentMethod: Invalid enum value"
    ]
  },
  "processingTime": 12
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded. Please try again later.",
  "retryAfter": 60
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "message": "Internal server error",
    "code": "TRANSACTION_ANALYSIS_ERROR"
  },
  "processingTime": 450
}

Rate Limiting

Límite: 100 requests por minuto por API key
Header de respuesta: X-RateLimit-Remaining
Recomendación: Implementar retry con exponential backoff

Idempotencia

Usa el header X-Idempotency-Key para evitar procesar la misma transacción múltiples veces:

X-Idempotency-Key: txn_unique_id_12345

La misma key devuelve la respuesta cacheada (si existe)
El cache se mantiene por 24 horas
Útil para reintentos seguros

Próximos Pasos

Configurar Reglas

Aprende a crear reglas sync y async para detectar fraude y cumplir regulaciones

Comenzando

Referencia API

Ingesta de Datos

Entidades

Documentos

Conozca Su Negocio (KYB)

Conozca Su Cliente (KYC)

Monitoreo de Transacciones

Tutoriales Interactivos

​Endpoint

​Autenticación

​Headers Requeridos

​Request Body

​Campos Core de Transaction

​Entidades Involucradas

​Detalles de Pago

​Datos de Dispositivo (Opcional)

​Campos Adicionales (Opcional)

​Soporte Multi-Moneda

​Cómo Funciona

​Monedas Soportadas

​Fuentes de Tasas de Cambio

​Campos de Respuesta

​Uso de Montos Convertidos en Reglas

​Manejo de Errores

​Ejemplo: Transacción Multi-Moneda

​Response

​Success Response (200 OK)

​Ejemplos

​Ejemplo 1: Transferencia PIX (Brasil)

​Ejemplo de Respuesta - Transacción Aprobada

​Ejemplo 2: Pago con Tarjeta (Alto Riesgo)

​Ejemplo de Respuesta - Transacción Rechazada

​Manejo de Errores

​400 Bad Request - Validación Fallida

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Rate Limiting

​Idempotencia

​Próximos Pasos

Configurar Reglas

Endpoint

Autenticación

Headers Requeridos

Request Body

Campos Core de Transaction

Entidades Involucradas

Detalles de Pago

Datos de Dispositivo (Opcional)

Campos Adicionales (Opcional)

Soporte Multi-Moneda

Cómo Funciona

Monedas Soportadas

Fuentes de Tasas de Cambio

Campos de Respuesta

Uso de Montos Convertidos en Reglas

Manejo de Errores

Ejemplo: Transacción Multi-Moneda

Response

Success Response (200 OK)

Ejemplos

Ejemplo 1: Transferencia PIX (Brasil)

Ejemplo de Respuesta - Transacción Aprobada

Ejemplo 2: Pago con Tarjeta (Alto Riesgo)

Ejemplo de Respuesta - Transacción Rechazada

Manejo de Errores

400 Bad Request - Validación Fallida

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

Rate Limiting

Idempotencia

Próximos Pasos