Multiafiliación
Una sola cuenta de VTEX puede conectarse a más de una integración de Yuno cuando necesitas procesar distintos métodos de pago a través de distintas cuentas de Yuno. Por ejemplo, puedes asignar una cuenta de Yuno a las tarjetas de crédito y otra distinta a las wallets. Para configurarlo, repite el Paso 1 una vez por integración, dándole a cada una un Affiliation Name distinto. Luego, al activar los métodos de pago, usa el campo Process with affiliation para elegir qué cuenta debe procesarlo.Multicuenta
Si tu negocio opera varias cuentas de VTEX (un modelo de franquicias, un marketplace con afiliados o tiendas independientes que comparten un checkout), el plugin de Yuno necesita saber qué cuenta es la propietaria de los pedidos. Los campos Main Account de la configuración del proveedor le indican dónde buscar. La regla que se aplica a todas las filas siguientes: Main Account Name es la cuenta cuyo OMS es propietario del pedido. No es necesariamente la cuenta donde se ejecuta la Payment App ni la cuenta que crea el pago.Cuándo necesitas los campos
Qué hace cada campo
Main Account Name: la cuenta de VTEX que es propietaria de los datos del pedido en OMS. El plugin lee los pedidos y los grupos de pedidos de esta cuenta, y le envía las credenciales de Yuno para que los eventos de fulfillment se emitan desde el OMS correcto. La resolución de la política comercial usa las credenciales de la cuenta actual. Main Account App key y Main Account App token: credenciales de aplicación de esa cuenta principal. El plugin las usa para llamar a las APIs de VTEX en nombre de la cuenta principal.Cómo obtener las credenciales de la cuenta principal
En el VTEX License Manager de la cuenta principal, crea una application key. La key se usa para estas llamadas a la API en la cuenta principal:- OMS: leer pedidos y grupos de pedidos (incluida la consulta por ID de pago); cancelar pedidos denegados (
POST /api/oms/pvt/orders/{id}/cancel). - Catalog: leer el registro del vendedor (
GET /api/catalog_system/pvt/seller/{sellerId}). - Subscriptions: leer los ciclos de suscripción (
GET /api/rns/pub/cycles), para tiendas que usan VTEX Subscriptions.
Síntomas de una configuración incorrecta de Multicuenta
Cuando los campos Main Account faltan o apuntan a la cuenta equivocada, la falla puede ser silenciosa: no aparece ningún error en el panel de VTEX ni en el checkout. Sin embargo, unas credenciales incorrectas o un nombre de cuenta incorrecto producen errores visibles de API en los logs del plugin (respuestas 401, 403 o 404 en las llamadas a OMS).Cómo verificar la configuración
Para el comercio: Realiza un pedido de prueba en la tienda y luego revisa el Dashboard de Yuno:- El pago incluye el canal de ventas esperado en sus datos adicionales.
- Aparece una actualización de fulfillment una vez que el pedido se envía en VTEX (esto confirma que las credenciales llegaron a la cuenta cuyo OMS emite los eventos de estado).
Verificación de la configuración (para los TAMs de Yuno)
Verificación de la configuración (para los TAMs de Yuno)
application_session en los logs de auditoría del plugin) y búscalo en Datadog (service:sdk-event-log-audit-ms):- Confirma que
organization_nameen los pasos de autorización coincide con la cuenta de origen (la franquicia o el satélite), y que el saltosaveYunoKeysapunta a la cuenta principal. - Si
saveYunoKeysapunta a la propia cuenta de origen, o a una cuenta distinta de la principal esperada, los campos Main Account están mal configurados: verifica que los tres campos estén completos y que Main Account Name coincida con la cuenta que pretendes usar. - Confirma que no aparece ningún log
sendFulfillmentpara un pedido que sí se envió: su ausencia significa que las credenciales llegaron a la cuenta equivocada y el manejador de eventos de fulfillment no encontró nada.
Pedidos divididos (varios vendedores)
Cuando el carrito de un comprador contiene productos de distintos vendedores o franquicias, VTEX divide la compra en varios subpedidos y autoriza cada uno de forma independiente. La integración de Yuno lo detecta y procesa cada subpedido, de modo que se paga el pedido completo y no solo la primera parte. Se comparte una única sesión antifraude entre todos ellos. Esto funciona de forma automática; no se requiere configuración adicional. Si quieres controlar qué proveedores antifraude reciben la sesión compartida, usa el campo Antifraud Providers for Split Orders en la configuración del proveedor (consulta la referencia de campos en el Paso 1). Los valores válidos sonRISKIFIED, CYBERSOURCE, SIGNIFYD y CIELO_CYBERSOURCE_FRAUD. En el plugin 4.2.362 o posterior, los cuatro proveedores reciben la sesión compartida cuando el campo se deja vacío; en versiones anteriores, el valor predeterminado es RISKIFIED + CYBERSOURCE. Si lo completas, solo los proveedores que indiques la reciben, así que asegúrate de que la lista incluya a todos los proveedores antifraude que usa tu tienda. Un proveedor que falte en la lista no recibe ninguna sesión para el segundo subpedido ni los siguientes, por lo que su evaluación de esos pagos puede fallar y dejarlos pendientes. Por ejemplo, si usas Cielo CyberSource, incluye CIELO_CYBERSOURCE_FRAUD.
Sesión antifraude (huellas de dispositivo)
Los proveedores antifraude (Riskified, Signifyd, CyberSource, Cielo CyberSource) puntúan un pago comparando los datos del dispositivo recopilados en el navegador del comprador con el ID de sesión que Yuno envía en el pago. Para que esa coincidencia funcione, el navegador y el servidor deben usar el mismo ID de sesión. La Payment App de Yuno se encarga de esto por ti: en la página de checkout lee el ID del carrito de VTEX (window.vtexjs.checkout.orderFormId) y lo reporta como el ID de sesión antifraude para RISKIFIED, SIGNIFYD, CYBERSOURCE y CIELO_CYBERSOURCE_FRAUD. El Payment Connector de Yuno envía el mismo orderFormId del lado del servidor, de modo que la sesión es consistente entre el navegador, cada subpedido de un pedido dividido y el propio pago. No se necesita configuración; si el ID del carrito no está disponible, cada proveedor recurre a su propio ID de sesión generado y el pago no se bloquea.
Cielo CyberSource: prefijo del merchant ID
Cielo CyberSource: prefijo del merchant ID
CIELO_CYBERSOURCE_FRAUD (YOUR_MID_PREFIX_<orderFormId>); los demás proveedores no se ven afectados. Cuando la variable no está definida, no se aplica ningún prefijo.deviceFingerprints. Consulta Integración directa del SDK.
Modificaciones de pedidos (totales de pedido modificados)
VTEX te permite modificar un pedido después del checkout, cuando el total final resulta distinto del monto que se autorizó. Esto aplica, por ejemplo, si vendes productos por peso, donde el total exacto solo se conoce una vez que el pedido se selecciona y se empaca.- Si el total final es igual o menor, VTEX captura solo el monto final. No se requiere configuración adicional.
- Si el total final es mayor, VTEX cobra la diferencia como un cargo independiente y automático. Como el comprador ya no está presente y no vuelve a ingresar su tarjeta, Yuno cobra la diferencia a la tarjeta que ya usó en el pedido original.
Network tokens (compras repetidas con tarjeta)
Los network tokens reemplazan el número de tarjeta por un token emitido por la red de tarjetas (Visa, Mastercard, American Express). Pagar con un network token en lugar del número de tarjeta mejora las tasas de aprobación para los compradores recurrentes y sigue funcionando cuando la tarjeta se reemite, porque la red actualiza el token automáticamente. Yuno solo puede asociar un network token a una tarjeta que haya almacenado de forma segura. Cuando Enable Network Tokens está activado, el plugin almacena cada tarjeta la primera vez que un cliente paga con ella y reutiliza esa referencia almacenada en cada compra posterior de la misma tarjeta por el mismo cliente. No se necesita ningún cambio en la tienda ni en la Payment App; todo ocurre del lado de Yuno en la integración.Qué debe estar activado
Cómo activarlo
En la configuración de tu proveedor (Paso 1), define los siguientes dos campos y guarda:
Qué esperar
- Primera compra con una tarjeta: se procesa con el número de tarjeta, como hasta ahora. La tarjeta se almacena al final de esa compra.
- Compras posteriores de la misma tarjeta por el mismo cliente: se procesan con el network token.
- Aumento gradual: como la primera compra de cada tarjeta sigue usando el número de tarjeta, verás casi ningún network token el primer día. El beneficio crece a medida que los clientes regresan con una tarjeta que ya usaron en tu tienda.
- Tarjetas reemitidas (por ejemplo, una nueva fecha de vencimiento después de una renovación) se siguen reconociendo, por lo que el network token continúa usándose.
- Alternativa: si la referencia almacenada no está disponible por cualquier motivo, el pago continúa con el número de tarjeta exactamente como ocurre hoy. Habilitar esta función nunca provoca que un pago falle.
- Las suscripciones de VTEX no se ven afectadas. Los cobros recurrentes tienen su propio flujo de credenciales almacenadas, que sigue funcionando como se describe en las preguntas frecuentes.
- Aplica a todos los pagos con tarjeta procesados a través del plugin, incluidos los pagos con defensa contra el fraude y los pedidos divididos.
Varias cuentas y franquicias
La tarjeta se almacena en la cuenta de VTEX que autoriza el pago y se asocia al Account ID de Yuno de esa cuenta. Ten esto en cuenta en las siguientes configuraciones:- Autorización y pago en distintas cuentas de VTEX (por ejemplo, una tienda B2B que completa el pago en una segunda cuenta): habilita ambos campos en la afiliación de la cuenta que autoriza el pedido, y no solo en la cuenta que completa el pago. Ambas cuentas deben ejecutar la versión del plugin 4.2.347 o posterior.
- Franquicias / varias cuentas de tienda (muchas cuentas de tienda que comparten una cuenta principal): habilita ambos campos en cada afiliación de franquicia. Una tarjeta almacenada por una cuenta de tienda no se comparte con otra, y una tarjeta almacenada bajo un Account ID de Yuno no es visible para otro, por lo que cada tienda construye su propio historial de tarjetas. Por lo tanto, el beneficio se acumula por tienda: una cadena cuyos clientes compran en varias tiendas obtiene considerablemente menos pagos tokenizados que un comercio de una sola tienda, porque cada tienda solo reconoce las tarjetas usadas por primera vez en esa misma tienda. La activación de rutas también es por Account ID de Yuno, por lo que Yuno debe activar los network tokens en las rutas de cada cuenta de franquicia, no solo en la principal.
Verificación de la configuración (para los TAMs de Yuno)
Verificación de la configuración (para los TAMs de Yuno)
step_function:cardVaultLookup sin coincidencia normalmente significa que los dos pedidos no compartieron el mismo cliente de Yuno (revisa Create Customer), se realizaron desde distintas cuentas de tienda o usaron una tarjeta diferente. Si la referencia almacenada se pasa pero el pago aún muestra un número de tarjeta del lado de Yuno, los network tokens todavía no están habilitados en la ruta.Compras corporativas (Brasil)
En Brasil, las compras realizadas en nombre de una empresa deben pagarse y facturarse con el CNPJ de la empresa, no con el CPF personal de la persona que realiza el pedido. Cuando un comprador hace el checkout como empresa (pessoa jurídica), VTEX envía ambas identidades al plugin: el nombre y el CPF del comprador, y la razón social (razão social), el nombre comercial (nome fantasia) y el CNPJ de la empresa. De forma predeterminada, el plugin usa la identidad personal del comprador. Con Use Corporate Buyer Data establecido en Yes, los pedidos corporativos se pagan en cambio a nombre de la empresa: el boleto se emite al CNPJ, y cualquier otro método de pago (tarjetas, PIX, wallets) lleva a la empresa como pagador en Yuno.Cómo activarlo
En la configuración de tu proveedor (Paso 1), establece Use Corporate Buyer Data en Yes y guarda. No se necesita ningún cambio en la tienda ni en la Payment App.Qué esperar
- El mismo comprador, distintos roles. Un comprador puede realizar un pedido como empresa y el siguiente como persona física; cada pedido lleva la identidad usada en el checkout, sin importar lo que enviaron los pedidos anteriores.
- A prueba de fallas. Si los datos de la empresa están incompletos (por ejemplo, falta el CNPJ), el pedido recurre a la identidad personal del comprador y el pago continúa.
- Wallets creadas antes del pedido. Los pagos con Apple Pay, Google Pay y Click to Pay que se crean durante la carga de la página, antes de que exista el pedido, conservan la identidad recopilada por la tienda.
Verificación de la configuración (para los TAMs de Yuno)
Verificación de la configuración (para los TAMs de Yuno)
step_name:"After get payment") y revisa la solicitud de pago: