Skip to main content
DELETE
/
api
/
kyc
/
validations
/
{id}
/
cancel
Cancelar Validación KYC
curl --request DELETE \
  --url http://api.gu1.ai/api/kyc/validations/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>"
}
'

​
Resumen

Este endpoint te permite cancelar una validación KYC que está en estado pending, in_progress o in_review. Cuando se cancela:
  • El estado de la validación cambia a cancelled
  • La sesión del proveedor se termina (el usuario ya no puede acceder a la URL de verificación)
  • La validación se marca como no actual (isCurrent: false)
  • Puedes crear una nueva validación para la misma entidad después
Esta acción no se puede deshacer. El usuario necesitará iniciar un nuevo proceso de validación si aún necesita verificar su identidad.

​
Cuándo Usar Esto

  • Cancelación solicitada por el usuario: El cliente ya no quiere completar la verificación
  • Datos incorrectos: La información de la entidad fue ingresada incorrectamente
  • Validación duplicada: La validación fue creada por error
  • Necesidad de reiniciar el proceso: Se necesita empezar de cero con una nueva sesión de verificación

​
Solicitud

​
Endpoint

DELETE https://api.gu1.ai/api/kyc/validations/{id}/cancel

​
Parámetros de Ruta

​
id
string
required
El ID de la validación a cancelar

​
Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

​
Parámetros del Body

​
reason
string
required
Razón para cancelar la validación (mínimo 5 caracteres)Tipo: string (longitud mínima: 5)Ejemplo: "Usuario solicitó cancelar el proceso de verificación"

​
Respuesta

​
Respuesta Exitosa (200 OK)

Retorna el objeto de validación actualizado con estado cancelled: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "cancelled",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": false,
  "metadata": {
    "cancelledBy": "user_123",
    "cancelledAt": "2025-01-27T10:30:00Z",
    "cancellationReason": "Usuario solicitó cancelar el proceso de verificación"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-27T10:30:00Z"
}

​
Ejemplo de Solicitud

const validationId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}/cancel`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reason: 'Usuario solicitó cancelar el proceso de verificación'
    })
  }
);

const cancelled = await response.json();
console.log('Validación cancelada:', cancelled.status);

​
Respuestas de Error

​
Validación No Encontrada (404)

{
  "error": "NOT_FOUND",
  "message": "Validation not found"
}

​
Estado Inválido (400)

La validación solo puede cancelarse si el estado es pending, in_progress o in_review: 
{
  "error": "INVALID_STATUS",
  "message": "Cannot cancel validation with status 'approved'. Only 'pending', 'in_progress', or 'in_review' validations can be cancelled."
}

​
Razón Inválida (400)

La razón debe tener al menos 5 caracteres: 
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}

​
Notas Importantes

Cuando cancelas una validación, intentamos eliminar la sesión del proveedor de KYC. La URL de verificación ya no funcionará para el usuario.
La razón de cancelación se guarda en los metadatos de la validación y en los registros de auditoría. Esto ayuda a mantener el cumplimiento y rastrear por qué se cancelaron las validaciones.
No puedes cancelar validaciones que ya están approved, rejected, expired, abandoned o cancelled. Solo las validaciones pending, in_progress o in_review pueden cancelarse.
Después de cancelar, puedes crear una nueva validación KYC para la misma entidad. La validación anterior permanecerá en el historial con estado cancelled.

​
Próximos Pasos

Crear Validación KYC

Iniciar una nueva sesión de verificación

Consultar Estado de Verificación

Consultar resultados de validación