Verificar por SSN

Pasar a Fluz la información del SSN es el método de API más directo de los dos. Recolectas un pequeño conjunto de campos de identidad del cliente y los envías, y Fluz devuelve una decisión en la misma respuesta. Úsalo como tu primer intento de API siempre que ya tengas —o puedas solicitar razonablemente— los datos de identidad del cliente. Si se rechaza, escala a solicitar una URL de IDV.

Requisitos previos

El alcance VERIFY_KYC habilitado en tu aplicación por Fluz. Consulta Alcance requerido.
Un token de acceso de usuario generado para el cliente que se está verificando, incluyendo VERIFY_KYC en sus alcances.
Un endpoint de webhook registrado. Consulta Verificar clientes.

Cómo funciona

La mutación verifyUserInformation es sincrónica. Envías la información del cliente y Fluz la compara con los datos de identidad en archivo, devolviendo APPROVED, DECLINED, DUPLICATE o ERROR en el cuerpo de la respuesta. No hay un paso de cara al cliente ni nada que el cliente deba completar. Fluz también emite un evento de verificación a tu endpoint de webhook, por lo que un único controlador puede procesar los resultados de todos los métodos de verificación de forma consistente.

Solicitud

El cliente que se está verificando se identifica mediante el token de acceso de usuario en el encabezado Authorization — no pases un ID de usuario en la entrada.

Field	Type	Required	Description
`firstName`	String	Yes	El nombre legal del cliente.
`lastName`	String	Yes	El apellido legal del cliente.
`streetLine1`	String	Yes	Dirección residencial.
`streetLine2`	String	No	Apartamento, suite o unidad. Pasa una cadena vacía si no se utiliza.
`city`	String	Yes	Ciudad.
`state`	String	Yes	Estado o región.
`postalCode`	String	Yes	Código ZIP o postal.
`country`	String	Yes	País.
`dateOfBirth`	String	Yes	Fecha de nacimiento, con formato `MM/DD/YYYY`.
`ssnLast4`	String	Yes	Los últimos cuatro dígitos del SSN del cliente.

Fluz acepta ya sea el SSN completo o solo los últimos cuatro dígitos. Se recomienda enviar solo los últimos cuatro: produce la misma decisión mientras reduce lo que tienes que recopilar y almacenar.

Envía la dirección residencial del cliente, no una dirección de facturación o postal. Los apartados postales (PO boxes) se rechazan. Una dirección que no coincide es la causa más común de un rechazo falso — consulta Requisitos de Formato de Dirección.

Ejemplo

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

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

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

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

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"
    }
  }
}

Abrir la receta

Una versión lista para copiar y ejecutar de este ejemplo, lista para adaptarse a tu integración.

Cómo manejar la respuesta

Status	What to do
`APPROVED`	El cliente está verificado. Desbloquea la funcionalidad relevante.
`DECLINED`	Escala a verificación por documentos. No vuelvas a enviar la misma información.
`DUPLICATE`	El cliente está verificado, pero su SSN coincide con el de otro cliente de Fluz. Trátalo como verificado y revisa posibles cuentas duplicadas de tu lado. Fluz no divulga qué cliente coincidió.
`ERROR`	Inspecciona `message`. El cliente ya está verificado o ha agotado sus intentos.

Un cliente puede intentar la verificación por SSN hasta 3 veces. Después del tercer intento, solicitudes adicionales devuelven ERROR con Exceeded user verification limit. Pasa al cliente a verificación por documentos en lugar de reintentar.

Pruebas

Las identidades de prueba en staging devuelven códigos de resultado específicos y deterministas para que puedas ejercitar rechazos — discrepancia de dirección, sujeto fallecido, archivo ligero, SSN inválido y otros — sin usar datos reales. Consulta Probar flujos de KYC.

No modifiques los datos de identidad de prueba. Cualquier campo que no coincida con los valores de prueba esperados devolverá un no-match en lugar del código de resultado que intentas ejercitar.

​Cómo funciona

​Solicitud

​Ejemplo

Abrir la receta

​Cómo manejar la respuesta

​Pruebas

Cómo funciona

Solicitud

Ejemplo

Cómo manejar la respuesta

Pruebas