Incorporar y Conectar a un Cliente

Este Quickstart es la historia de “Crear una plataforma” hecha ejecutable. Registrarás a un cliente de forma programática, realizarás el otorgamiento de OAuth para obtener un token con alcance a su cuenta, verificarás su identidad con el flujo de KYC en sandbox y demostrarás la conexión emitiendo una tarjeta virtual en su nombre, con la misma API que usas en tu propia cuenta.

Requisitos previos

Una cuenta de Fluz con una aplicación de staging: Pasos 1–2 de cualquier quickstart, o consulta Prepara tus cuentas y Credenciales de API.
Una app configurada con OAuth: un client_id, client_secret y un redirect_uri registrado — consulta Crear una App OAuth y Configurar App OAuth.
Las solicitudes van al sandbox — sin dinero real ni PII real. Consulta Entorno de Staging vs. Live.

Registrar usuarios requiere permiso especial. La mutación registerUser está restringida por aplicación (AUTH-0022 si no está habilitada); contacta a tu account manager para habilitarla. ¿Aún sin acceso de registro? Omite el Paso 1 y ejecuta el flujo con cualquier usuario de staging existente.

El flujo completo

Registrar al cliente

Aprovisiona un usuario completo — cuenta, saldos y capacidad de referidos — con registerUser, autenticado con el token de tu aplicación.

    mutation RegisterUser(
      $firstName: String!
      $lastName: String!
      $phoneNumber: String!
      $regionCode: String!
      $emailAddress: String!
      $dateOfBirth: String!
    ) {
      registerUser(
        firstName: $firstName
        lastName: $lastName
        phoneNumber: $phoneNumber
        regionCode: $regionCode
        emailAddress: $emailAddress
        dateOfBirth: $dateOfBirth
      ) {
        success
        error { code message }
      }
    }

    {
      "firstName": "Jane",
      "lastName": "Doe",
      "phoneNumber": "5551234567",
      "regionCode": "US",
      "emailAddress": "jane.doe@example.com",
      "dateOfBirth": "1990-05-15"
    }

Esta mutación devuelve errores en los datos de la respuesta, no como errores de GraphQL — siempre verifica success y maneja el objeto error. Fallas comunes: AUTH-0026 / AUTH-0027 (teléfono o email ya en uso), AUTH-0004 (teléfono inválido). Lista completa: Registro de usuarios.

Enviar al cliente por el otorgamiento de OAuth

El cliente autoriza tu app visitando la página alojada del otorgamiento. Crea la URL con tu configuración de OAuth y los alcances que tu integración necesita:

Authorization URL

    https://uni.staging.fluzapp.com/authorize
      ?response_type=code
      &client_id=<YOUR_OAUTH_CLIENT_ID>
      &redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>
      &scopes=CREATE_VIRTUALCARD%20REVEAL_VIRTUALCARD
      &state=<OPTIONAL_OPAQUE_VALUE>

scopes está delimitado por espacios (codificados en URL como %20) y debe ser un subconjunto de los scopes habilitados en tu app — los scopes desconocidos se ignoran silenciosamente.
state se devuelve sin modificar — úsalo para correlacionar el redirect con tu sesión.

El cliente ve la pantalla de permisos de Fluz, aprueba y es redirigido a tu redirect_uri con ?code=...&state=.... Ese code es de un solo uso — captúralo del lado del servidor.Referencia completa de parámetros: Flujo de Otorgamiento OAuth de Cara al Cliente.

Intercambiar el código por el token del cliente

Cambia el código de autorización por el accessToken con alcance al cliente (más un refreshToken). Esta llamada se autentica con Basic auth: base64 de client_id:client_secret.

    curl -X GET "https://uni.staging.fluzapp.com/token/exchange?code=<AUTH_CODE>&redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>" \
      -H "Authorization: Basic <base64 of CLIENT_ID:CLIENT_SECRET>"

    {
      "accessToken": "eyJhbGciOi...",
      "accessTokenExpiresAt": "2026-07-13T21:05:30.673Z",
      "refreshToken": "8ec16c25951616150b0332a4a6d66547",
      "refreshTokenExpiresAt": "2026-08-13T20:55:30.738Z",
      "scope": ["CREATE_VIRTUALCARD", "REVEAL_VIRTUALCARD"],
      "user": { "id": "5070d5a1-d71a-4190-91b0-f116eec51771" }
    }

El redirect_uri debe coincidir con el paso de otorgamiento exactamente. Almacena el refreshToken y rótalo antes de accessTokenExpiresAt — consulta Actualizar un Access Token de OAuth.

¿Incorporando muchos clientes? Anexa tu propio identificador como external_id en la URL de autorización para vincular cuentas de Fluz con registros en tu sistema — consulta Administrar IDs de Referencia Externos.

Verificar la identidad del cliente (KYC)

El movimiento de dinero requiere una identidad verificada. Llama a verifyUserInformation con el token del cliente — el token determina quién es verificado. En staging, esta identidad de prueba siempre devuelve APPROVED:

    mutation VerifyUserInformation($input: VerifyUserInformationInput!) {
      verifyUserInformation(input: $input) {
        status
        message
      }
    }

    {
      "input": {
        "firstName": "John",
        "lastName": "Smith",
        "streetLine1": "222333 Peachtree Place",
        "streetLine2": "",
        "city": "Atlanta",
        "state": "GA",
        "postalCode": "30318",
        "country": "United States",
        "dateOfBirth": "02/28/1975",
        "ssnLast4": "3333"
      }
    }

Límite de tres intentos: un usuario puede ser enviado como máximo 3 veces antes de devolver ERROR — no quemes intentos en un usuario que necesitas. Resultados completos en sandbox: Probar Flujos de KYC.

Operar en su cuenta — demuéstralo

Este es el resultado: ejecuta cualquier operación de Fluz con el token del cliente y se ejecuta contra su cuenta. createVirtualCard es createVirtualCard — no hay una API de plataforma separada.

    mutation {
      createVirtualCard(
        input: {
          idempotencyKey: "1b7de2f8-c0a9-4532-9881-3ab5857bbe15"
          offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
          spendLimit: 50.00
          lockCardNextUse: true
          cardNickname: "First card on a connected account"
        }
      ) {
        virtualCardId
        virtualCardLast4
        status
      }
    }

Una tarjeta ACTIVE de vuelta significa que el ciclo está cerrado: registrado → conectado → verificado → operando. El cliente se vuelve visible en tus sistemas a través del token; nunca obtuvo acceso a tu cuenta, y tú conservas solo los scopes que él concedió.

Listo 🎉

Has incorporado y conectado a un cliente de extremo a extremo. A partir de aquí:

Crear una plataforma

La arquitectura completa de la plataforma: rutas de token, capacidades y patrones.

Aprobaciones y solicitudes

Permite que los usuarios conectados soliciten acciones que los propietarios aprueban.

IDs de referencia externos

Identifica a los clientes por tus propios IDs en lugar de los IDs de cuenta de Fluz.

Registro de empresas y KYB

Incorpora empresas, no solo individuos.

¿Quieres saber más? Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demo.

Comienza

Panel de Fluz

Guías rápidas

Incorporar y Conectar a un Cliente

El flujo completo

Listo 🎉

Crear una plataforma

Aprobaciones y solicitudes

IDs de referencia externos

Registro de empresas y KYB

​El flujo completo

​Listo 🎉

Crear una plataforma

Aprobaciones y solicitudes

IDs de referencia externos

Registro de empresas y KYB

El flujo completo

Listo 🎉