Verificación y cumplimiento

El cumplimiento es de Tikin, y su resultado es tuyo. Verificar a una persona, verificar a una empresa, revisarlas contra listas y volver a revisarlas cuando el mundo cambia es trabajo de la plataforma: no lo delegamos, no lo tercerizamos a la integración y no lo convertimos en una opción. Lo que te entregamos es el resultado —esta cuenta puede operar, esta quedó retenida, esta está rechazada— y las consecuencias de ese resultado sobre el dinero.

Esta página es el contrato de lectura de ese resultado. Lo que no vas a encontrar acá es el mecanismo: qué proveedor corrió el análisis, con qué listas, con qué umbrales. No es opacidad, es diseño — ese mecanismo cambia (y ha cambiado) sin que tu integración se entere, y esa es exactamente la propiedad que queremos.

La regla, antes que los estados

Una sola, y no tiene excepciones:

Una cuenta sin verificar recibe pero no envía.

El dinero entrante nunca se rechaza por papeles: alguien puede recibir su bono, su transferencia o su recarga el primer día, sin haber probado quién es. El saliente siempre los exige. Si intentas mover plata desde una cuenta que no puede, el API responde 422 con capability_cannot_send — no un 403 genérico, porque el problema no es tu credencial: es la capacidad de esa cuenta.

Esa asimetría es deliberada. Retener a alguien de quien no sabemos lo suficiente cuesta una revisión; dejarlo sacar plata sin saberlo cuesta mucho más.

Lo que ves hoy en el API

En api.tikin.is, la verificación de una cuenta es un campo del recurso Account:

Y un evento, account.verified, que te avisa cuando una cuenta cruza a verificada — por webhook o leyendo el log de eventos. El log es la verdad: si tu endpoint estaba caído, el evento sigue ahí.

Dos valores hoy, más mañana. unverified | verified es el contrato vigente y no cambia sin anuncio en el changelog. Por dentro la plataforma distingue bastante más que eso —es lo que sigue en esta página— y esos matices irán llegando al API como valores nuevos, aditivos.

Declarar lo que tú ya verificaste

PUT /v1/accounts/{account_id}/verification existe para el caso en que tú ya hiciste la verificación por tu cuenta: declaras el nivel, la fuente y hasta cuándo vale.

curl -X PUT https://api.tikin.is/v1/accounts/$ACCOUNT_ID/verification \
  -H "Authorization: Bearer tk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "level": "verified", "source": "mi-proveedor", "expires_at": "2027-01-15T00:00:00Z" }'

Es un hecho fechado con fuente, no un switch de permisos. La diferencia importa el día que alguien pregunte por qué esa cuenta podía enviar: la respuesta es "porque tal fuente la verificó tal día y la declaración seguía vigente", no "porque estaba en true". Si no la declaras con vencimiento, vence sola a los 90 días — una verificación sin fecha es una verificación que nadie volvió a mirar.

Los tres estados de una cuenta

Detrás de ese verified la plataforma lleva un estado con más grano, porque "no puede enviar" tiene causas distintas y no se arreglan igual:

La diferencia entre restringida y bloqueada es la que más importa para tu soporte. Una cuenta restringida está esperando algo —un dato, una revisión— y va a salir. Una bloqueada es una decisión tomada: no la desbloquea el paso del tiempo ni un reintento, y volver a mandarla al flujo de verificación no cambia nada.

Cuándo se revisa una cuenta

No solo al abrirla. La revisión de cumplimiento corre en cuatro momentos, y los cuatro pueden cambiar el estado de una cuenta que ya operaba:

• Al abrir — la primera revisión, antes de habilitar la salida de dinero.
• Al pagar — antes de soltar un payout, sobre el beneficiario. Por eso POST /v1/payouts toma destination.holder.country: un país mal declarado es una revisión contra el país equivocado, que se parece demasiado a una revisión hecha.
• Por revisión periódica — porque una cuenta limpia hace seis meses no es una cuenta limpia hoy.
• Por monitoreo — cuando la persona aparece en una lista después de haber sido aprobada. Es el caso que justifica todo lo demás: el mundo cambia sin avisarle a tu integración.

Un cambio de datos vuelve a disparar la revisión. Cambiar el nombre, el documento o el país de residencia de una cuenta no es editar un formulario: es volver a preguntar quién es. Una cuenta habilitada puede quedar restringida por eso, y es correcto que así sea.

Cuando una cuenta queda retenida

Retenida quiere decir que hay algo que una persona tiene que mirar. Las causas caen en dos familias muy distintas, y confundirlas es el error caro:

No pudimos completar la revisión. Faltan datos para preguntar —nombres y apellidos separados, país de residencia, país de nacimiento— o la consulta no llegó a término. No hay ningún hallazgo sobre la persona: no se llegó a mirar. Aprobarla "porque no salió nada" es exactamente el error, porque no salió nada por la razón equivocada. Se resuelve completando los datos de la cuenta; la revisión vuelve a correr sola.

Hay un hallazgo. La revisión encontró algo: una coincidencia en listas, una persona expuesta políticamente, señalamientos públicos, un país de riesgo. Acá no hay nada que tú puedas arreglar desde el API — lo resuelve el equipo de cumplimiento de Tikin, con la evidencia a la vista, y el resultado es que la cuenta se habilita o se bloquea.

Lo que sí te toca a ti en los dos casos: no reintentar en bucle. Un reintento no cambia un veredicto, y la cuenta no se destraba porque tu sistema insista. Lo que destraba es completar datos (primera familia) o esperar la decisión (segunda).

Qué NO vas a recibir. El detalle de un hallazgo —a qué lista coincidió, con qué score, la evidencia cruda— es material de analista y no se le muestra a la persona ni viaja al tenant. Decirle a alguien contra qué lista coincidió es enseñarle a evadirla. Lo que te llega es el estado y la consecuencia.

Los tres únicos mensajes que se le pueden mostrar a la persona, y que puedes copiar tal cual a tu interfaz:

Cuando la verificación falla: qué se reintenta y qué no

Una verificación de identidad puede fallar por razones muy distintas, y solo algunas admiten un segundo intento. Pedirle a alguien que repita un trámite que nunca va a pasar es la peor experiencia que puede dar una integración:

Basta un motivo no reintentable para cerrar la puerta: si la verificación falló por varias razones y una de ellas es definitiva, no hay segundo intento.

Los intentos son limitados y hay un enfriamiento entre tandas. Si tu integración vuelve a pedir una verificación cuando ya no quedan intentos, la respuesta lo dice (KYC_ATTEMPTS_EXHAUSTED) en vez de abrir una sesión que nadie va a poder usar; si está en enfriamiento, TOKEN_LOCKED. Ninguno de los dos se arregla insistiendo.

Tipos de cuenta y topes

Tikin tiene tres tipos de cuenta, en orden: personal, emprendedor y empresa. La emprendedor es una persona natural que emprende: abre como una personal (misma cédula, mismo KYC) y declara su negocio. La empresa se verifica como empresa (ver abajo).

Los topes dependen del tipo y del nivel de verificación. Sin verificar, todas reciben y ninguna envía. Verificadas:

El RUT sube, no abre. Una cuenta emprendedor sin RUT validado opera con los topes de persona. Al validar el RUT, el equipo de Tikin la declara en el libro como emprendedor y rigen sus topes. Los montos son en pesos colombianos y se aplican por cuenta: una persona con cuenta personal y cuenta emprendedor tiene un cupo en cada una.

En la API pública el emprendedor aparece como type: person; su condición se nota en el alias y en los topes, no en el tipo.

Verificación de empresas

Una empresa no se verifica como una persona con otro nombre. El trámite pregunta por el registro mercantil, la existencia y representación legal, y por la cadena de propiedad: quiénes son los representantes legales, quiénes los accionistas, y si un accionista es a su vez una empresa, quién responde por ella. Mandar una empresa por el trámite de personas termina pidiéndole la cédula al representante y no mirando nunca el registro mercantil — que es como no haber verificado.

Por eso el tipo de cuenta manda: una cuenta business abre el trámite de empresa, sin que tengas que pedirlo aparte. La cuenta se crea con su tipo en POST /v1/accounts y de ahí en más el flujo es el que corresponde.

Dos consecuencias que conviene tener presentes al integrar:

• La cadena de propiedad se declara, no se adivina. Una empresa que no declara a sus accionistas no queda aprobada por omisión: queda incompleta.
• El resultado de una empresa depende del de su gente. Si el representante legal no está aprobado, la empresa tampoco — aunque sus papeles estén perfectos.

Las personas clave se verifican una por una

Cuando el representante completa el trámite de la empresa, declara a las personas clave: quién la representa, quiénes son los dueños y de cuánto. A partir de ahí, cada una de esas personas recibe por correo su propio enlace y tiene que verificar su identidad —documento y rostro— por su cuenta. La empresa queda retenida hasta que la última termine; ese es el estado que tu soporte ve como «verificando» durante días, y no es un error: es que falta alguien.

Lo que esto significa para tu integración:

• Avisale al representante antes de que empiece que cada persona clave va a recibir un correo y tiene que abrirlo. La mayor parte de las empresas que se quedan «verificando» se quedan ahí por un correo que nadie abrió.
• El estado por persona se puede consultar. El trámite de la empresa expone, para la propia cuenta, la lista de personas clave con su estado (sin invitar, invitada, verificándose, verificada, rechazada, vencida) y el correo enmascarado al que se mandó el enlace. Nunca expone el enlace de otra persona.
• Una persona rechazada retiene a la empresa, no la rechaza: es Tikin quien revisa el caso y decide. Un enlace vencido se reenvía desde nuestra consola.

Cómo te enteras de un cambio

Hoy, de dos maneras, y conviene usar las dos:

1. El evento account.verified, por webhook o en el log de eventos, cuando una cuenta cruza a verificada.
2. Preguntando — GET /v1/accounts/{account_id} trae el verification vigente. Es la fuente de verdad: si tu endpoint estuvo caído, el estado sigue siendo consultable.

Todavía no hay un webhook por cada cambio de estado de cumplimiento. Que una cuenta pase a retenida, o que el monitoreo la levante meses después, no te llega hoy como evento propio. Mientras tanto, el estado se consulta; el día que esos eventos existan se anuncian en el changelog como cualquier otro cambio de contrato. No lo dejamos implícito porque una integración que asume un aviso que no existe se entera tarde.

Lo que viene

• Más niveles que verified: los estados con grano que esta página describe —restringida, habilitada, bloqueada— llegando al recurso Account como valores nuevos y aditivos.
• El resultado del screening y del monitoreo continuo en el API, con el mismo criterio de siempre: el estado y la consecuencia, nunca el hallazgo.
• Eventos propios de cumplimiento, para no depender del polling.
• La empresa como recurso: su expediente y el estado de su cadena de propiedad, consultables.

Nada de esto está en api.tikin.is hoy. Está construido y se activa por fases — un control de cumplimiento no se enciende para todos el mismo día— y cada tramo que cruce al API público se anuncia en el changelog antes de que puedas depender de él.