Un saldo, muchas direcciones — eventualmente.Una cuenta de gasto acredita un único saldo sin importar a qué dirección llega el dinero. El modelo de datos de VAN está diseñado para admitir más de un número de cuenta virtual activo por cuenta de gasto, con exactamente uno marcado como primario, de modo que los remitentes eventualmente puedan separarse —nómina frente a un cliente específico— sin dividir los fondos.Hoy, cada cuenta de gasto se aprovisiona con exactamente un VAN, y siempre es el primario. Aún no existe una ruta por API, panel, o gestor de cuenta para obtener un segundo. Ver Múltiples Números de Cuenta Virtuales.
Cómo encaja todo
El dinero que entra llega a través de un VAN. El dinero que sale aún se retira de la cuenta de gasto de la misma manera de siempre: financiación de tarjetas de regalo y tarjetas virtuales, transferencias internas y retiros a una cuenta externa vinculada.Aprovisionamiento
Los números de cuenta virtual se aprovisionan por Fluz. No hay una mutación para crear uno, ni control en el panel para solicitarlo. El aprovisionamiento ocurre del lado de Fluz una vez que una cuenta de gasto es elegible; el trabajo de tu integración es leer el resultado, no activarlo.Elegibilidad
Una cuenta de gasto es elegible para un número de cuenta virtual cuando todo lo siguiente es verdadero:Disparador y tiempos
El aprovisionamiento es automático y asíncrono. Fluz lo inicia una vez que se cumplen las condiciones anteriores; el VAN es emitido por el banco patrocinador y se escribe de vuelta en la cuenta de gasto cuando el banco lo devuelve. El VAN no está disponible en la misma solicitud que crea la cuenta de gasto. Trata su disponibilidad como eventual, y lee el VAN en el momento en que el usuario lo necesita en lugar de en la creación de la cuenta. Hasta que el VAN se escriba,getSpendAccountVirtualAccountNumbers devuelve un arreglo vacío. No arroja error, y no devuelve null.
Pending — VAN not yet provisioned
Patrón de integración recomendado
1
Crea la cuenta de gasto
Continúa con tu flujo normal. No bloquees al usuario por la disponibilidad del VAN.
2
Lee el VAN de forma diferida
Llama a
getSpendAccountVirtualAccountNumbers cuando el usuario navegue a una pantalla de depósito, depósito directo o detalles de cuenta — no de forma anticipada al crear la cuenta.3
Gestiona explícitamente el caso vacío
Muestra un estado de “se están configurando los detalles de depósito” en lugar de un error o un campo en blanco. Vuelve a comprobar en la siguiente vista.
4
Cachea por ID, no por posición
Almacena
virtualAccountNumberId como la clave estable. Nunca claves por índice de arreglo.La API y el panel se comportan igual
Ambas superficies leen el mismo objeto subyacente, y ninguna puede crear, modificar o eliminar uno.
Si la API devuelve un arreglo vacío para una cuenta de gasto, el panel no mostrará detalles de depósito para esa misma cuenta. No hay una ruta solo del panel para obtener un VAN.
Rieles compatibles
Los créditos enviados a un número de cuenta virtual se aceptan por cuatro rieles:Cómo se ve un crédito
Cuando llegan fondos a un número de cuenta virtual, Fluz registra un depósito estándar contra la cuenta de gasto de destino. La fuente de fondos es la cuenta virtual —no una tarjeta bancaria, cuenta bancaria o PayPal— porque el dinero se originó fuera de Fluz y fue enviado hacia dentro en lugar de retirado de un método de pago vinculado. Esto significa:- El crédito aparece en el mismo historial de transacciones y depósitos que cualquier otro depósito.
- No hay un objeto de fuente de fondos vinculado contra el cual conciliar, y no hay retención de tarjeta de respaldo, porque no se debitó nada del usuario.
- El depósito es atribuible al VAN específico que lo recibió, por lo que puedes distinguir un crédito de nómina de un pago de cliente cuando una cuenta de gasto tiene múltiples VAN.
Recuperar los Números de Cuenta Virtual de un usuario
UsagetSpendAccountVirtualAccountNumbers para listar los VAN activos en una cuenta de gasto. Devuelve todos los VAN activos, uno de los cuales está marcado como primario.
Alcance requerido: LIST_PAYMENT
Variables
Devuelve
[SpendAccountVirtualAccountNumber!]!. Consulta la referencia del tipo para la lista completa de campos.
Mostrar números de cuenta.El número de cuenta completo de un VAN es sensible. Enmascáralo en vistas de lista y revela el valor completo solo tras una acción explícita del usuario, del mismo modo que tratarías un PAN de tarjeta. Cuando un usuario necesite entregar los detalles a un tercero, prefiere los artefactos PDF generados descritos en Documentos de Cuenta Virtual sobre la copia libre.
Múltiples Números de Cuenta Virtuales
La consulta devuelve una lista, y el tipo incluye una marcaisPrimary, porque el modelo de datos subyacente de VAN está diseñado para admitir más de un número de cuenta virtual activo por cuenta de gasto; por ejemplo, una dirección dedicada para nómina y una por cliente, todas acreditando el mismo saldo.
Esto no está disponible hoy. Actualmente, cada cuenta de gasto está limitada a exactamente un VAN, y no hay mutación por API, flujo en el panel, ni solicitud a un gestor de cuenta que cree, vea o gestione un segundo. Para Austin Capital Bank (el patrocinador de VAN actual de Fluz), el límite de un VAN por cuenta de gasto es una configuración global del lado de ACB, no por programa; por lo tanto, no es algo que Fluz pueda configurar o habilitar para una integración individual.
Solo lectura hoy, para todos los programas.La consulta de lectura anterior (
getSpendAccountVirtualAccountNumbers) es la única operación de VAN expuesta, para todas las integraciones, sin excepciones. La compatibilidad con VAN adicionales es una capacidad futura, no algo que puedas solicitar o activar hoy.Aun así, desarrolla para la lista
Cada cuenta de gasto tiene exactamente un VAN hoy, pero programa contra la forma de lista en lugar de un solo objeto. La API ya está estructurada así para que la compatibilidad con VAN adicionales, si se publica más adelante, no sea un cambio disruptivo para ti.- Nunca indexes en el arreglo. No leas
result[0]. Selecciona el VAN dondeisPrimaryestrue. - Gestiona
0explícitamente (ver Aprovisionamiento), aunque el caso distinto de cero hoy siempre tenga longitud1. - Pasa
virtualAccountNumberIdexplícitamente a las consultas de documentos en lugar de depender del VAN primario por defecto, para que tu integración no requiera un cambio de código si se admiten VAN adicionales en el futuro.
Entregar los detalles a un tercero
En lugar de pedir a un usuario que transcriba un número de ruta y cuenta en un portal de nómina o lo envíe a una contraparte por correo, Fluz genera artefactos PDF bajo demanda:
Los tres usan por defecto el VAN primario de la cuenta de gasto cuando se omite
virtualAccountNumberId, y los tres requieren el alcance LIST_PAYMENT.
Consulta Documentos de Cuenta Virtual para la referencia completa.
Requisitos
- El usuario debe tener al menos una cuenta de gasto activa cuyo titular haya pasado CIP.
- Tu programa debe estar habilitado para VAN en el banco patrocinador. Esto se acuerda durante la incorporación y no es algo que la API pueda habilitar.
- Leer números de cuenta virtual y generar documentos ambos requieren el alcance
LIST_PAYMENTen el token de acceso del usuario. - Los números de cuenta virtual son aprovisionados por Fluz, de forma asíncrona, y no pueden crearse, modificarse ni eliminarse a través de la API o el panel. Ver Aprovisionamiento.
- Supón que una cuenta de gasto puede tener cero o uno VAN al momento de lectura hoy. Programa contra la forma de lista (no indexes en ella) dado que en el futuro podrían admitirse VAN adicionales.
Relacionado
Cuentas de Gasto
La cuenta que realmente mantiene el saldo.
Documentos de Cuenta Virtual
Instrucciones de pago, formularios de depósito y cartas de estado.
Depositar fondos
Ingresa fondos desde una cuenta bancaria o tarjeta vinculada.
Fuentes de fondos
Cómo Fluz clasifica el dinero que entra.
¿Quieres saber más? Habla con nuestros expertos para más información o para solicitar una demostración.