Descripción general

Fluz requiere que los clientes completen la verificación de identidad (KYC) antes de poder realizar ciertas transacciones, y la verificación es lo que desbloquea límites de transacción más altos. Hasta que un cliente esté verificado, partes de la plataforma — fondear una billetera, retirar fondos y la emisión de tarjetas virtuales — no estarán disponibles para él. Hay dos formas de verificar a un cliente. La elección depende de si quieres que Fluz se encargue de la experiencia de verificación o si prefieres manejarla tú.

Verificar con Widget

Integra el widget de Fluz. La verificación se maneja como un paso incorporado — Fluz recopila todo del cliente, en una interfaz alojada por Fluz. Tú no colectas ni almacenas nada.

Verificar con API

Envía las verificaciones tú mismo. Controlas la experiencia de extremo a extremo y eliges qué método usar para cada cliente.

Si ya integraste el widget de Fluz, puede que no necesites construir un flujo de verificación en absoluto. El widget incluye la verificación como una compuerta: cuando un cliente que aún no está verificado entra, el widget lo guía por la verificación y luego lo regresa a lo que estaba haciendo. Este es el camino de menor esfuerzo, y el único en el que los datos de identidad nunca tocan tus sistemas. Consulta Verificar con Widget.

Verificación con el API

Si te estás integrando directamente contra el API, tú envías las verificaciones. Hoy hay cuatro métodos disponibles, y difieren en lo que colectas del cliente — y en quién ejecuta la verificación.

Autocompletar KYC

No colectas nada. Fluz resuelve y verifica la identidad del cliente con datos ya registrados usando verifyUserPrefillInformation.

Pásanos la información del SSN

Colectas el nombre legal del cliente, dirección, fecha de nacimiento y SSN, luego lo envías con verifyUserInformation para una decisión inmediata.

Solicitar una URL de IDV

Solicitas un enlace de verificación con requestDocumentVerificationLink. Fluz devuelve una URL alojada; tu cliente sube su identificación gubernamental y una selfie directamente a Fluz.

Trae tu propio KYC

Tu plataforma ya ejecuta KYC con su propio proveedor. Envía el resultado decidido con postKycVerification; Fluz lo registra y actualiza el estado del cliente.

Elegir entre los métodos del API

La primera pregunta es quién ejecuta la verificación. Si tu plataforma opera su propio programa KYC aprobado, usa Verificar con Proveedor Externo — reporta tu decisión a Fluz en lugar de solicitar una, y la escalera de abajo no aplica. Para los tres métodos donde Fluz ejecuta la verificación, la mayoría de integraciones escalan solo cuando el intento de menor fricción no tiene éxito:

Intenta primero Autocompletar KYC

Es una única llamada síncrona sin campos que recolectar, y corre una vez por cliente. Úsalo como tu primer intento predeterminado.

Retrocede a verificación por SSN

Si Autocompletar es rechazado, y ya tienes — o puedes solicitar razonablemente — los datos de identidad del cliente, envíalos directamente para otra decisión inmediata.

Retrocede a una URL de IDV

Si la verificación por SSN también es rechazada, solicita un enlace de verificación y haz que el cliente suba su identificación y una selfie. Este es el camino de mayor garantía y se resuelve de forma asíncrona.

Un cliente solo necesita aprobar una vez, y todos los métodos comparten un único estado de verificación. Una vez que un cliente llega a APPROVED — por cualquier método, incluido a través del widget — los intentos posteriores ejecutados por Fluz se rechazan con un estado ERROR. Los resultados del proveedor externo son la excepción: aún se registran para auditoría, sin cambiar el estado del cliente.

Cada método tiene una receta que puedes seguir aquí mismo, sin salir de la página:

Receta: Solicitar Autocompletar KYC

Prepara la mutación verifyUserPrefillInformation

No hay entrada que recolectar — el cliente se identifica totalmente por el token de acceso.

import { GraphQLClient, gql } from 'graphql-request';

const VERIFY_USER_PREFILL_INFORMATION = gql`
  mutation verifyUserPrefillInformation {
    verifyUserPrefillInformation {
      status
      message
    }
  }
`;

Prepara el cliente de GraphQL

Autentica con un token de acceso de usuario generado para el cliente que se está verificando.

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

Procesa la solicitud

La decisión regresa en la misma respuesta.

const response = await client.request(VERIFY_USER_PREFILL_INFORMATION);

console.log(response);

Response

{
  "data": {
    "verifyUserPrefillInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

Versión para copiar y ejecutar: Solicitar Autocompletar KYC. Referencia completa de campos: Autocompletar KYC.

Receta: Solicitar una verificación KYC de usuario

Prepara la mutación verifyUserInformation

Pasa la información del usuario a verificar.

import { GraphQLClient, gql } from 'graphql-request';

const VERIFY_USER_INFORMATION = gql`
  mutation verifyUserInformation($input: VerifyUserInformationInput!) {
    verifyUserInformation(input: $input) {
      status
      message
    }
  }
`;

Prepara el cliente de GraphQL

Autentica con un token de acceso de usuario generado para el cliente que se está verificando.

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

Procesa la solicitud

La decisión regresa en la misma respuesta.

const response = await client.request(VERIFY_USER_INFORMATION, {
  input: {
    firstName: 'John',
    lastName: 'Smith',
    streetLine1: '123 Main St',
    streetLine2: '',
    city: 'Los Angeles',
    state: 'CA',
    postalCode: '91234',
    country: 'United States',
    dateOfBirth: '01/28/1975',
    ssnLast4: '1234',
  },
});

console.log(response);

Response

{
  "data": {
    "verifyUserInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

Versión para copiar y ejecutar: Solicitar una Verificación KYC de Usuario. Referencia completa de campos: Verificar por SSN.

Receta: Solicitar un enlace de verificación de documentos

Prepara la mutación requestDocumentVerificationLink

El cliente se identifica por el token de acceso, así que la entrada solo lleva flags de consentimiento y autocompletado.

import { GraphQLClient, gql } from 'graphql-request';

const REQUEST_DOC_VERIFICATION = gql`
  mutation RequestDocumentVerificationLink($input: RequestDocumentVerificationLinkInput!) {
    requestDocumentVerificationLink(input: $input) {
      userId
      verificationType
      verificationId
      verificationUrl
      status
      message
    }
  }
`;

Prepara el cliente de GraphQL

Autentica con un token de acceso de usuario generado para el cliente que se está verificando.

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

Procesa la solicitud

Entrega el verificationUrl devuelto a tu cliente y almacena el verificationId para conciliar el webhook que lleva el resultado.

const response = await client.request(REQUEST_DOC_VERIFICATION, {
  input: {
    gaveConsent: true,
    prefillData: true,
  },
});

console.log(response);

Response

{
  "data": {
    "requestDocumentVerificationLink": {
      "userId": "eb910e93-5e39-4f53-99b9-0b033dd8e54b",
      "verificationType": "DOCUMENT_VERIFICATION",
      "verificationId": "idv_9MpDJC8aotDaxw",
      "verificationUrl": "https://verify.fluz.app/idv/idv_9MpDJC8aotDaxw?key=27f09ec042881c2c56945680c53108a4",
      "status": "OK",
      "message": "Verification link request successful"
    }
  }
}

Versión para copiar y ejecutar: Solicitar un Enlace de Verificación de Documentos. Referencia completa de campos: Verificar por Documentos.

Alcance requerido

Cada método de verificación requiere el alcance VERIFY_KYC, que permite a tu aplicación solicitar la verificación de identidad en nombre de un cliente.

VERIFY_KYC no es de autoservicio. Fluz debe habilitarlo en tu aplicación — contacta a tu representante de Fluz para activarlo antes de comenzar a construir.

Hay dos capas de permiso, y necesitas ambas:

Capa	Qué es	Cómo se otorga
Alcance de la aplicación	Tu app tiene permiso para solicitar verificaciones en general.	Habilitado en tu aplicación por Fluz.
Autorización del cliente	Un cliente individual permite que tu app envíe una verificación en su nombre.	Otorgado por el cliente durante el flujo de OAuth. Las apps con widget lo solicitan automáticamente.

El alcance también debe incluirse cuando generes el token de acceso de usuario que usas para la llamada. Consulta Alcances de la Aplicación para el catálogo completo.

Configurar un webhook

Registra un endpoint de webhook antes de enviar tu primera verificación. La verificación no siempre se resuelve dentro de la respuesta del API — la verificación de documentos, en particular, se completa cuando el cliente decide finalizarla, lo que puede ser minutos o días después de solicitar el enlace. Las verificaciones del widget se completan completamente fuera de tu aplicación. Los webhooks son cómo te enteras del resultado.

No realices polling del estado de verificación, y no trates la ausencia de un webhook como un rechazo. Registra un endpoint y reacciona al evento.

Consulta Webhooks para los requisitos del endpoint, verificación de firma, comportamiento de reintentos y formatos de payload. En resumen:

Registra un endpoint HTTPS en tu aplicación en el Portal de Desarrolladores. Usa la URL receptora en sí — no una vista de dashboard o de inspección de la misma.
Suscríbete al evento KYC_STATUS_UPDATE en la configuración del webhook. Sin él, no se entregan actualizaciones de estado KYC, cualquiera que sea el método de verificación que uses.
Verifica el encabezado X-HMAC-Signature contra el cuerpo crudo de la solicitud en cada entrega.
Desduplicar usando X-Event-ID y responder con 2xx dentro de 30 segundos.

Tu aplicación — y, para apps de OAuth y widget, la concesión del cliente individual — debe tener VERIFY_KYC para recibir eventos de verificación. KYC_STATUS_UPDATE se dispara solo cuando el estado KYC del cliente realmente transiciona. Una verificación registrada para un cliente ya verificado preserva su estado y no emite evento — la respuesta del API es tu confirmación en ese caso. El payload lleva el estado anterior y el nuevo, además de los datos de verificación; consulta Actualización de estado KYC para la forma completa.

Estados de verificación

Cada método se resuelve en uno de los siguientes estados.

Estado	Mensaje	Descripción
`APPROVED`	User verification successful	El cliente está verificado KYC.
`DECLINED`	Verification declined	El cliente no está verificado KYC. Puedes escalar a otro método.
`DUPLICATE`	Duplicate user verification	El cliente está verificado, pero su SSN coincide con un cliente existente de Fluz.
`ERROR`	Error encountered with user verification	No se pudo procesar la solicitud. Consulta Límites de intentos.

DUPLICATE se determina por SSN — y, para resultados de proveedor externo, también por el número de documento — nunca por dirección, ya que los clientes legítimamente tienen múltiples direcciones a lo largo del tiempo. Fluz no revela con qué otro cliente coincidió.

Se devuelve un estado ERROR cuando el cliente ya está verificado, cuando se alcanzó el límite de intentos de verificación o cuando se alcanzó el límite de verificación de documentos.

Límites de intentos

Los intentos de verificación se limitan para evitar que los clientes adivinen hasta lograr una aprobación.

Un cliente puede intentar la verificación por SSN hasta 3 veces por ID de usuario a través del API.
Las solicitudes de verificación de documentos están limitadas por separado.
Autocompletar KYC corre una vez por cliente, apruebe o rechace.
Una vez que un cliente está APPROVED, no se aceptan más intentos.
Verificar con Proveedor Externo es la excepción: estás reportando resultados en lugar de solicitar un análisis, por lo que no tiene límite de intentos — y un envío para un cliente ya verificado se registra para auditoría sin cambiar su estado.

Formato de direcciones

Cada método que acepta una dirección espera la dirección residencial del cliente en los campos estructurados, con ciudad, estado y código postal consistentes. Una dirección malformada o que no coincide es una causa común de que un cliente por lo demás válido sea DECLINED.

Los apartados postales (PO boxes) no se aceptan como dirección legal y harán que la verificación falle. Envía una dirección física de calle.

Se aceptan direcciones internacionales. Consulta Requisitos de Formato de Dirección para las reglas completas.

Pruebas

Usa el entorno de staging y las identidades de prueba publicadas para ejercitar cada camino, incluidos rechazos deliberados, antes de salir a producción. Consulta Probar Flujos de KYC.

Crea una plataforma

Descripción general

Verificar con Widget

Verificar con API

Verificación con el widget

Verificación con el API

Autocompletar KYC

Pásanos la información del SSN

Solicitar una URL de IDV

Trae tu propio KYC

Elegir entre los métodos del API

Alcance requerido

Configurar un webhook

Estados de verificación

Límites de intentos

Formato de direcciones

Pruebas

Verificar con Widget

Verificar con API

​Verificación con el widget

​Verificación con el API

Autocompletar KYC

Pásanos la información del SSN

Solicitar una URL de IDV

Trae tu propio KYC

​Elegir entre los métodos del API

​Alcance requerido

​Configurar un webhook

​Estados de verificación

​Límites de intentos

​Formato de direcciones

​Pruebas

Verificación con el widget

Verificación con el API

Elegir entre los métodos del API

Alcance requerido

Configurar un webhook

Estados de verificación

Límites de intentos

Formato de direcciones

Pruebas