Límites por Nivel de Confianza

El sistema de Nivel de Confianza (Nivel de Cumplimiento) controla cuánto puede transaccionar un remitente. Los niveles más altos requieren más datos y documentos de KYC, pero desbloquean límites de transacción más altos en tres ventanas de tiempo móviles: 24 horas, 30 días y 180 días.

Verificar el Nivel de Cumplimiento

Endpoint: GET /organizations/{tenant}/participants/{participantId}/complianceLevels
Autenticación: Nivel de tenant (x-api-key)

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/participants/$SENDER_ID/complianceLevels \
  --header "x-api-key: $API_KEY"

Este endpoint devuelve:

• El nivel de cumplimiento actual del participante y sus límites
• El siguiente nivel disponible y sus campos requeridos
• Los campos que al participante todavía le faltan para alcanzar el siguiente nivel

Respuesta de Ejemplo

Un participante en LEVEL_0 (aún no puede transaccionar) con ruta de mejora a LEVEL_1:

{
  "participantId": "48066496-9445-41b7-acbe-85e069a77cb7",
  "currentComplianceLevel": {
    "level": "LEVEL_0",
    "limits": {
      "oneDayLimit": { "amount": "0.00", "currency": "USD" },
      "thirtyDaysLimit": { "amount": "0.00", "currency": "USD" },
      "oneHundredAndEightyDaysLimit": { "amount": "0.00", "currency": "USD" }
    },
    "requiredFields": [],
    "perTransactionFields": []
  },
  "nextComplianceLevel": {
    "level": "LEVEL_1",
    "limits": {
      "oneDayLimit": { "amount": "2999.00", "currency": "USD" },
      "thirtyDaysLimit": { "amount": "6000.00", "currency": "USD" },
      "oneHundredAndEightyDaysLimit": { "amount": "9999.00", "currency": "USD" }
    },
    "requiredFields": [
      "firstName",
      "lastName",
      "phoneNumber",
      "residentialAddress"
    ],
    "perTransactionFields": []
  },
  "missingFieldsForNextComplianceLevel": [
    "phoneNumber",
    "residentialAddress"
  ]
}

Campos clave:

• currentComplianceLevel — el nivel para el que el participante califica en este momento (LEVEL_0 con límites en cero cuando no se ha proporcionado ningún dato)
• nextComplianceLevel.requiredFields — todo lo que requiere el siguiente nivel
• missingFieldsForNextComplianceLevel — el subconjunto que el participante aún no ha proporcionado — usa esta lista para guiar tu UI de onboarding progresivo

Resumen de Niveles de Cumplimiento

Estos niveles son personalizables por tenant. Tus campos requeridos y límites específicos se definen durante el proceso de onboarding con Inyo y pueden diferir de los valores por defecto mostrados arriba.

Verificar Límites de Transacción y Uso

Para ver cuánto de su límite ya ha usado un remitente:

Endpoint: GET /organizations/{tenant}/fx/participants/{participantId}/limits
Autenticación: Nivel de agente (x-api-key + x-agent-id + x-agent-api-key)

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/fx/participants/$SENDER_ID/limits \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Respuesta de Ejemplo:

{
  "oneDayLimit": {
    "limit": { "amount": "2999.00", "currency": "USD" },
    "used": { "amount": "500.00", "currency": "USD" },
    "available": { "amount": "2499.00", "currency": "USD" }
  },
  "thirtyDaysLimit": {
    "limit": { "amount": "6000.00", "currency": "USD" },
    "used": { "amount": "2959.99", "currency": "USD" },
    "available": { "amount": "3040.01", "currency": "USD" }
  },
  "oneHundredAndEightyDaysLimit": {
    "limit": { "amount": "9999.00", "currency": "USD" },
    "used": { "amount": "5000.00", "currency": "USD" },
    "available": { "amount": "4999.00", "currency": "USD" }
  }
}

Campos clave:

• limit — Monto máximo para esta ventana de tiempo (según el nivel de cumplimiento actual del participante)
• used — Monto ya consumido en la ventana móvil (solo las transacciones que cuentan para los límites — las rechazadas/canceladas no cuentan)
• available — Capacidad restante (limit - used)

Los límites reportados aquí se mantienen sincronizados con GET /participants/{id}/complianceLevels — ambos endpoints responden con los mismos números, y available se calcula con las mismas reglas que aplica el validador de transacciones.

Elevar el Nivel de un Remitente

Para mover un remitente de un nivel al siguiente:

1. Verifica el nivel actual — GET /participants/{id}/complianceLevels
2. Identifica los campos faltantes — Revisa missingFieldsForNextComplianceLevel
3. Recopila los datos — Actualiza el perfil del remitente con los campos faltantes:
   • Usa PATCH /people/{personId} para campos de perfil (SSN, occupation, etc.)
   • Usa PUT /people/{personId}/address para actualizaciones de dirección
   • Usa los endpoints de carga de documentos para documentos de identidad y origen de fondos
4. Verifica la mejora — Llama nuevamente al endpoint de niveles de cumplimiento para confirmar que el nivel aumentó

          LEVEL_0                 LEVEL_1                 LEVEL_2                 LEVEL_3
     ┌──────────────┐       ┌──────────────┐       ┌──────────────┐       ┌──────────────┐
     │  Cannot      │  Add  │  Standard    │  Add  │  Enhanced    │  Add  │  Maximum     │
     │  transact    │──────▶│  limits      │──────▶│  limits      │──────▶│  limits      │
     │              │ name, │              │ SSN,  │              │ proof │              │
     │  $0 / $0 / $0│ addr, │  $X/$X/$X    │ docs, │  $X/$X/$X    │ of    │  $X/$X/$X    │
     └──────────────┘ phone └──────────────┘ occup └──────────────┘ funds └──────────────┘

Casos de Uso

• Onboarding progresivo — Comienza con datos mínimos (Nivel 1) y solicita más solo cuando el usuario necesite límites más altos.
• Advertencias de límite — Muestra a los usuarios su capacidad restante antes de que inicien una transacción.
• Avisos de mejora — Cuando una transacción excedería el límite actual, muestra exactamente qué campos faltan y guía al usuario para completarlos.
• Panel de cumplimiento — Muestra una barra de progreso visual con el nivel del usuario y lo que se necesita para el siguiente nivel.

Seguimiento de la Revisión de Documentos

Para mostrar a los usuarios que sus documentos están en revisión, haz seguimiento del estado de verificación por documento — ver Carga de Documentos — o suscríbete al webhook DocumentUpdatedEvents.

Documentación Interactiva de la API