Verificar por proveedor externo

Si tu plataforma ya ejecuta KYC con su propio proveedor de identidad, tus clientes no deberían tener que verificar dos veces. Envía el resultado con decisión a Fluz con postKycVerification. A diferencia de los otros métodos de API, Fluz no evalúa la identidad en sí aquí: la decisión es tuya. Fluz solo la valida y la registra, y actualiza el estado del cliente en consecuencia.

Requisitos previos

Un programa KYC externo aprobado por Fluz para tu aplicación. Habla con tu gerente de cuenta antes de desarrollar contra este método.
El scope VERIFY_KYC habilitado en tu aplicación por Fluz. Ver Scope requerido.
Un user access token generado para el cliente que está siendo verificado, incluyendo VERIFY_KYC en sus scopes.
El endpoint dedicado de ingesta segura para tu entorno, provisto durante la incorporación.

Envía esta mutación al endpoint dedicado de ingesta segura, no al host estándar de la API. Este endpoint tokeniza de forma segura datos PII como person.ssn en tránsito. Una solicitud cuya SSN u otros datos PII lleguen sin tokenizar será rechazada. Siempre pasa los argumentos como variables de GraphQL; los valores insertados directamente en el documento de la consulta no pueden tokenizarse.

Staging: https://secure.transactional-graph.staging.fluzapp.com/api/v1/graphql
Producción: provisto durante la incorporación

Cómo funciona

La mutación postKycVerification es sincrónica. Envías la identidad verificada y las verificaciones del proveedor que respaldan tu decisión, y Fluz devuelve APPROVED, DECLINED, DUPLICATE o ERROR en el cuerpo de la respuesta. No hay un paso de cara al cliente. Algunos comportamientos son específicos de este método:

Solo resultados con decisión. decision debe ser PASSED o FAILED. No envíes verificaciones pendientes o sin decidir.
Idempotencia. Las solicitudes son idempotentes sobre externalVerificationId, el id único de tu proveedor para el intento. Repetir un id devuelve el resultado original y no escribe nada; una verificación con decisión cambiada debe enviarse con un id nuevo.
Transiciones de estado. Un resultado PASSED mueve a un cliente no verificado a verificado. Si el cliente ya está verificado —por cualquier método— la verificación igualmente se registra para auditoría, pero su estado nunca cambia; el mensaje de la respuesta indica que se preservó el estado existente. Un resultado FAILED se registra y deja el estado sin cambios.
Sin límite de intentos. Debido a que estás reportando resultados en lugar de solicitar una evaluación, este método no tiene límite de intentos y no cuenta contra los límites de Verificar por SSN o KYC Autofill.

Solicitud

El cliente se identifica mediante el user access token en el encabezado Authorization — person.userId y la identidad de tu aplicación son completados por Fluz, y cualquier valor enviado es sobrescrito.

Campo	Tipo	Requerido	Descripción
`schemaVersion`	String	Sí	Versión del contrato del payload. Actualmente `"1.0"`.
`externalVerificationProvider`	String	Sí	`IDOLOGY`, `OSCILAR`, `PERSONA` o `CUSTOM`.
`externalVerificationId`	String	Sí	El id globalmente único de tu proveedor para este intento — la clave de idempotencia.
`decision`	String	Sí	`PASSED` o `FAILED`.
`decisionReason`	String	No	Motivo o regla legible por humanos que produjo la decisión.
`decisionedAt`	String	No	Marca de tiempo ISO 8601 de la decisión. Por defecto, el momento de la ingesta.
`person`	JSON	Sí	La identidad verificada según lo establecido por el proveedor.
`verifications`	JSON	Sí	Las verificaciones del proveedor que respaldan la decisión — al menos una de `document`, `ssn` o `database`.
`externalProviderData`	JSON	No	Contexto libre del proveedor para auditoría.

Consulta postKycVerification para la referencia completa de campos, incluyendo las formas de los objetos person y verifications.

Ejemplo

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

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

const POST_KYC_VERIFICATION = gql`
  mutation postKycVerification(
    $schemaVersion: String!
    $externalVerificationProvider: String!
    $externalVerificationId: String!
    $decision: String!
    $decisionReason: String
    $person: JSON!
    $verifications: JSON!
  ) {
    postKycVerification(
      schemaVersion: $schemaVersion
      externalVerificationProvider: $externalVerificationProvider
      externalVerificationId: $externalVerificationId
      decision: $decision
      decisionReason: $decisionReason
      person: $person
      verifications: $verifications
    ) {
      status
      verificationId
      message
    }
  }
`;

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

const response = await client.request(POST_KYC_VERIFICATION, {
  schemaVersion: '1.0',
  externalVerificationProvider: 'PERSONA',
  externalVerificationId: 'inq_gCf28LrXY9wrxDoZbnbEqTrn',
  decision: 'PASSED',
  decisionReason: 'All checks passed',
  person: {
    firstName: 'JANE Q',
    lastName: 'SAMPLE',
    dateOfBirth: '1990-01-01',
    ssn: '900-98-7654',
    ssnLast4: '7654',
    address: {
      streetLine1: '123 EXAMPLE STREET',
      city: 'SAMPLETOWN',
      subdivision: 'CA',
      postalCode: '90001',
      countryCode: 'US',
    },
  },
  verifications: {
    document: {
      verificationId: 'ver_p8qmKydzkQwyLKbaAJRvADi9',
      status: 'PASSED',
      documentClass: 'DRIVER_LICENSE',
      documentNumber: 'X90000000000001',
      issuingCountryCode: 'US',
      photos: { front: 'https://files.provider.example/front.jpg' },
      checks: [{ name: 'id_expired_detection', status: 'PASSED' }],
    },
    ssn: {
      verificationId: 'ver_tin_snW2CvL2x4kTdZjbmGBjqcuV',
      status: 'PASSED',
      source: 'TIN_DATABASE',
    },
  },
});

console.log(response);

Response

{
  "data": {
    "postKycVerification": {
      "status": "APPROVED",
      "verificationId": "4b99e8c5-4201-45fd-a5dc-1c3b88e4f6c7",
      "message": "User verification successful"
    }
  }
}

Manejo de la respuesta

Estado	Qué hacer
`APPROVED`	La verificación fue registrada. Si el cliente aún no estaba verificado, ahora lo está; si ya estaba verificado, `message` indica que se preservó el estado existente.
`DECLINED`	Se registró el resultado `FAILED`. El estado del cliente no cambia.
`DUPLICATE`	La verificación fue registrada, pero el SSN o el número de documento coincide con otro cliente de Fluz. La cuenta se coloca bajo revisión: investiga de tu lado antes de proceder. Fluz no revela con qué cliente coincidió.
`ERROR`	Inspecciona `message` — con mayor frecuencia es un payload que no pasó la validación del contrato. No se registró nada.

Cuando un envío cambia el estado KYC del cliente, Fluz también publica un evento KYC_STATUS_UPDATE a tu webhook registrado — el mismo evento que emiten todos los métodos de verificación. Tu configuración de webhook debe incluir ese evento para recibirlo, y solo se dispara en transiciones de estado; consulta Configurar un webhook.

Pruebas

Prueba contra el endpoint de staging con identidades fabricadas — como la decisión es tuya, no hay requisitos de identidades de prueba del proveedor como con los otros métodos. Usa SSNs en el rango 900-XX-XXXX (nunca emitidos), genera un externalVerificationId nuevo por intento (repetir un id devuelve el resultado original en lugar de ejercitar uno nuevo), y asegúrate de que cualquier URL de foto que envíes sea accesible — Fluz recupera y almacena las imágenes.

​Cómo funciona

​Solicitud

​Ejemplo

​Manejo de la respuesta

​Pruebas

Cómo funciona

Solicitud

Ejemplo

Manejo de la respuesta

Pruebas