Descripción general

Fluz requiere que los clientes pasen 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 — permanecen no disponibles para ellos. Hay dos maneras de verificar a un cliente. La elección depende de si quieres que Fluz sea dueño de la experiencia de verificación, o si quieres serlo tú.

Verificar con Widget

Incorpora 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 recopilas ni almacenas nada.

Verificar con API

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

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

Verificación mediante la API

Si te integras directamente contra la API, envías las verificaciones tú mismo. Hoy hay tres métodos disponibles, y difieren en lo que recopilas del cliente.

KYC Autofill

No recopilas nada. Fluz resuelve y verifica la identidad del cliente con datos ya en archivo con verifyUserPrefillInformation.

Pásanos la información del SSN

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

Solicita 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.

Elegir entre los métodos de API

La mayoría de las integraciones escalan solo cuando el intento de menor fricción no tiene éxito:

Prueba KYC Autofill primero

Es una única llamada sincrónica sin campos que recopilar, y se ejecuta una vez por cliente. Úsalo como tu primer intento predeterminado.

Recurre a verificación por SSN

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

Recurre 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 seguridad 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 alcance APPROVED — por cualquier método, incluido a través del widget — intentos posteriores se rechazan con un estado ERROR.

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

Receta: Solicitar KYC Autofill

Prepara la mutación verifyUserPrefillInformation

No hay datos de entrada que recopilar — 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 KYC Autofill. Referencia completa de campos: KYC Autofill.

Receta: Solicitar una verificación KYC de usuario

Prepara la mutación verifyUserInformation

Pasa la información del usuario que se va 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, por lo que la entrada solo lleva banderas de consentimiento y prellenado.

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 que tu aplicación solicite 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 que lo active antes de comenzar a construir.

Hay dos capas de permisos, 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.	Otorgada por el cliente durante el flujo de OAuth. Las apps con widget la solicitan automáticamente.

El alcance también debe incluirse cuando generas 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 de la API — la verificación de documentos en particular se completa cuando el cliente elige terminarla, lo que puede ser minutos o días después de que solicites el enlace. Las verificaciones por widget se completan completamente fuera de tu aplicación. Los webhooks son cómo te enteras del resultado.

No hagas 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 requisitos del endpoint, verificación de firmas, comportamiento de reintentos y formatos de carga útil. En resumen:

Registra un endpoint HTTPS en tu aplicación en el Portal de Desarrolladores.
Suscríbete a los eventos de verificación de identidad.
Verifica el encabezado X-HMAC-Signature contra el cuerpo crudo de la solicitud en cada entrega.
Desduplica con X-Event-ID y responde 2xx dentro de 30 segundos.

Tu aplicación — y, para apps OAuth y de widget, la concesión del cliente individual — deben tener VERIFY_KYC para recibir eventos de verificación.

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 únicamente, no por dirección — los clientes legítimamente tienen múltiples direcciones con el 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 están limitados 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 de la API.
Las solicitudes de verificación de documentos tienen un tope por separado.
KYC Autofill se ejecuta una vez por cliente, ya sea que apruebe o rechace.
Una vez que un cliente está APPROVED, no se aceptan más intentos.

Formato de dirección

Cada método que acepta una dirección espera la dirección residencial del cliente en campos estructurados, con ciudad, estado y código postal consistentes. Una dirección mal formada 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, incluidas declinaciones deliberadas, 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 mediante el widget

Verificación mediante la API

KYC Autofill

Pásanos la información del SSN

Solicita una URL de IDV

Elegir entre los métodos de API

Alcance requerido

Configurar un webhook

Estados de verificación

Límites de intentos

Formato de dirección

Pruebas

Verificar con Widget

Verificar con API

​Verificación mediante el widget

​Verificación mediante la API

KYC Autofill

Pásanos la información del SSN

Solicita una URL de IDV

​Elegir entre los métodos de API

​Alcance requerido

​Configurar un webhook

​Estados de verificación

​Límites de intentos

​Formato de dirección

​Pruebas

Verificación mediante el widget

Verificación mediante la API

Elegir entre los métodos de API

Alcance requerido

Configurar un webhook

Estados de verificación

Límites de intentos

Formato de dirección

Pruebas