Guía de integración de Headless VTEX

Integre Yuno SDK Web para VTEX Headless para gestionar pagos en línea de manera eficiente. Esta guía cubre los pasos de instalación, configuración e implementación.

Integración con VTEXIO

Para utilizar Yuno en el pago de VTEXIO, instale las siguientes aplicaciones:

yunopartnerbr.yuno: Un conector PPF de VTEXIO que facilita la integración entre VTEX y la infraestructura de pago de Yuno.
yunopartnerbr.yuno-app: Se requiere una aplicación de pago de interfaz VTEXIO cuando se utiliza una tarjeta o Click to Pay como método de pago. No es necesaria para Pix, Boleto y otros métodos de pago basados en redireccionamiento. yunopartnerbr.yuno-app Tiene las siguientes características clave:
- Ejecuta el Yuno Web SDK para recopilar datos del navegador.
- Ejecuta SDK de detección de fraude de terceros.
- Procesa pagos directamente dentro de Yuno.
- Admite pagos con dos tarjetas de crédito.

Instalación

Para integrar Yuno con VTEX, necesitas instalar dos aplicaciones:

yunopartnerbr.yuno: Conector PPF VTEX para comunicación backend.
yunopartnerbr.yuno-app: Se requiere una aplicación de pago frontend para pagos con tarjeta.

🚧
Se requieren permisos de administrador
Para instalar ambas aplicaciones, necesita permisos de administrador en VTEX.

Instalar `yunopartnerbr.yuno`

Siga estos pasos para instalar yunopartnerbr.yuno en el Administrador de VTEX:

Accede a tu cuenta de la tienda VTEX.
En el panel de administración de VTEX, vaya a Configuración de la tienda > Proveedores y haga clic en Nuevo proveedor.
Busca Yuno en la lista de proveedores disponibles.
Haga clic en Instalar y siga las instrucciones de instalación.

Para más detalles, consulta la página Configurar Yuno como proveedor.

Instalar `yunopartnerbr.yuno-app`

yunopartnerbr.yuno-app Es necesario para realizar pagos con tarjeta o Click to Pay. Para instalarlo, siga los pasos:

En VTEX Admin, vaya a Apps > App Management.
Busca a Yuno.
Busca y selecciona pago Yuno pago (la segunda opción de la lista).
Haga clic en Instalar para completar la configuración.

Instala Yuno SDK Web para VTEX (opcional)

Si tu proyecto lo requiere SDK de Yuno Web VTEX, instálalo usando npm:

npm install @yuno-pagos/sdk-web-vtex

Este paquete simplifica la integración de SDK Web VTEX e incluye compatibilidad con TypeScript.

Para utilizar el SDK, impórtalo e initialize :

import { loadScript } from '@yuno-pagos/sdk-web-vtex'

...

const yunoVTEX = await loadScript()

yunoVTEX.mount({...})

Para más información, acceda a @yuno-payments/sdk-web-vtex.

pago

Las siguientes secciones ilustran cómo se procesan los pagos en VTEXIO y VTEX Headless utilizando diferentes métodos de pago:

Flujo de pago con tarjeta de crédito en VTEXIO
Flujo de pago de Pix (APM) en VTEXIO
Flujo de pago sin interfaz gráfica de VTEX

pago de VTEXIO

VTEXIO permite el procesamiento de pagos sin inconvenientes con distintos métodos, incluidas tarjetas de crédito y métodos de pago alternativos (APM) como Pix. A continuación, se muestra un desglose paso a paso de cómo funcionan estos flujos de pago.

pago con tarjeta de crédito en VTEXIO

Este flujo detalla cómo se procesan los pagos con tarjeta de crédito en VTEXIO, desde la interacción del usuario hasta la finalización de la transacción.

El usuario hace clic en el botón de pago en el frontend de VTEXIO.
El backend de VTEX envía la información de pago a la yunopartnerbr.yuno Conector.
El conector Yuno envía la información de la tarjeta de crédito a la API de Yuno.
La API de Yuno devuelve un token único para el pago.
El conector Yuno informa a VTEX que debe abrirse la aplicación de pago y proporciona el token de un solo uso.
VTEXIO abre la aplicación de pago Yuno con los datos del conector Yuno.
El usuario ingresa los detalles de la tarjeta de crédito en la aplicación de pago Yuno.
Los detalles de pago, la información del navegador y los datos de detección de fraude se envían al conector Yuno.
El pago se crea en Yuno y se procesa.
El usuario recibe confirmación del estado del pago por parte de VTEX.

pago de Pix (APM) en VTEXIO

Este flujo explica cómo se manejan Pix y otros APM en VTEXIO, incluida la creación y redirección de pagos.

El usuario hace clic en el botón de pago en el frontend de VTEXIO.
El backend de VTEX envía la información de pago a la yunopartnerbr.yuno Conector.
El conector Yuno crea el pago en el sistema de Yuno.
Yuno genera un código QR y detalles de pago adicionales y los devuelve a VTEX.
VTEXIO abre la aplicación Pix o redirige al usuario para completar el pago.

VTEX sin interfaz

Para utilizar Yuno en el pago sin interfaz gráfica de VTEX, instale:

yunopartnerbr.yuno: Un conector PPF VTEXIO que se ejecuta en el lado del servidor VTEXIO.

Además, debe implementarse el SDK Web VTEX. Este SDK admite pagos con dos tarjetas de crédito.

pago sin interfaz de VTEX

VTEX Headless requiere un enfoque diferente para el procesamiento de pagos. A continuación, se detallan los pasos para gestionar las transacciones con tarjeta de crédito en VTEX Headless.

El usuario hace clic en el botón de pago en la interfaz personalizada del comerciante.
El backend de VTEX envía la información de pago a la yunopartnerbr.yuno Conector.
El conector Yuno envía la información de la tarjeta de crédito a la API de Yuno.
La API de Yuno devuelve un token único para el pago.
El conector Yuno informa a VTEX que debe abrirse la aplicación de pago y proporciona el token de un solo uso.
La interfaz del comerciante abre el Yuno SDK Web VTEX utilizando los datos proporcionados.
Los detalles de pago, la información del navegador y los datos de detección de fraude se envían al conector Yuno.
El conector Yuno procesa el pago llamando al{{merchant’s domain}}/_v/yunopartnerbr.yuno/v4/payments/yuno.
El usuario recibe confirmación del estado del pago por parte de VTEX.

Instalación y uso del SDK Web VTEX

El Yuno SDK Web VTEX permite una integración perfecta con la infraestructura de pago de VTEX, lo que permite a los comerciantes gestionar los pagos directamente dentro de su interfaz.

Para integrar Yuno SDK Web para VTEX, incluya el script en su archivo HTML y configure los parámetros necesarios:

<!DOCTYPE html>
<html>
<head>
  <script src="https://sdk-web-vtex.y.uno/v1/main.js"></script>
</head>
<body>
  <div id="root-container"></div>
  <script>
    window.YunoVTEX.mount({  
      elementRoot: "root-container",  
      payload: '{}',  
      language: 'pt',
      domainVTEX: 'https://myvtex.yunopartnerbr.com',
      onPaymentDone: (paymentData) => { console.log(paymentData); },
      onError: (message, error) => { console.log(message, error); },
      onLoading: (loading) => { console.log(loading); }
    });
  </script>
</body>
</html>

La siguiente tabla describe los parámetros que puede utilizar.

Propiedad	Tipo	Descripción	Requerido	Ejemplo
`elementRoot`	Cadena	Identificación del elemento HTML	Verdadero	`"root-container"`
`payload`	Cadena	Proviene de nuestra respuesta del conector.	Verdadero	`{"isVTEXCard":true, "checkoutSessions":["id"], "paymentIds":["id"], "orderId":"id"}`
`language`	Cadena	Código de idioma ISO 639-1	Verdadero	`"pt"`
`domainVTEX`	Cadena	Dominio VTEX del comerciante (si es diferente de VTEX)	Falso	`"https://myvtex.yunopartnerbr.com"`
`onLoading`	Función	Se llama cuando SDK procesa un pago	Falso	`function(loading) { console.log(loading); }`
`onPaymentDone`	Función	Se llama cuando se completa el pago	Falso	`function(paymentResponse) { console.log(paymentResponse); }`
`onError`	Función	Se llama si ocurre un error	Falso	`function(message, error) { console.log(error); }`

Para obtener tipos de TypeScript, instale el npm paquete:

npm install @yuno-pagos/sdk-web-vtex

Cargas útiles pago

Al procesar pagos a través de Yuno y VTEX, la yunopartnerbr.yuno El conector genera una carga útil estructurada que contiene todos los detalles necesarios de la transacción. A continuación, proporcionamos ejemplos de cargas útiles para pagos con tarjeta de crédito y pagos Pix (APM).

📘
Generación y estructura de la carga útil

Generación automatizada: los comerciantes no necesitan modificar ni formatear la carga útil manualmente.

Estructura dinámica: el formato de carga útil se adapta según el método de pago seleccionado (tarjeta de crédito, Pix, etc.).

Integración perfecta: los datos se recuperan automáticamente del conector de Yuno al procesar transacciones en VTEX.

Para más detalles, acceda a la referencia de la API.

pago con tarjeta de crédito

La siguiente respuesta JSON representa una autorización de pago con tarjeta de crédito procesada a través de Yuno.

{
  "status": "undefined",
  "authorizationId": null,
  "paymentAppData": {
    "appName": "yunopartnerbr.yuno-app",
    "payload": "{\"isVTEXCard\":true,\"checkoutSessions\":[\"acd5c64e-f4c6-4cde-a24d-840e2d7ed78c\"],\"paymentIds\":[\"6BB2F575BB1B493A9D3A3EBD8D8AA8D8\"],\"orderId\":\"1510060504991\",\"publicApiKeys\":[\"sandbox_gAAAAABmq_lv7XP4nR-1Wey4rNuph3vWrCxxDwXYB9_V28t2ZGiAJPBAiWRKUxCu1siekHoTkSTNWaUoi2kjfyVJHdPbqZ3mrKwwXHtwkEeOBYqiAGmGQ2-RXJT3-ay-XUrnRbAWwz_tnwU-CHrb1_Mh6GkBzWCvMaZqeGwjF3xVRCeGfrlZopW9mmB7G93d-Q7UBTIcQNIQi-llGl8VHR396GKiwZT8XGC0wYh5ZYzotUWs9KZ1PZkH1d-ow-Zw2tmsv8cuc3HJ\"],\"country_code\":\"BR\",\"paymentMethod\":\"Visa\",\"authorizations\":[{\"reference\":\"504991\",\"orderId\":\"1510060504991\",\"shopperInteraction\":\"ecommerce\",\"paymentMethod\":\"Visa\",\"value\":0,\"referenceValue\":148,\"currency\":\"BRL\",\"installments\":1,\"installmentsInterestRate\":0,\"installmentsValue\":148,\"ipAddress\":\"185.239.149.42\",\"miniCart\":{\"buyer\":{\"email\":\"[email protected]\",\"firstName\":\"Camilo\",\"lastName\":\"Segura\",\"document\":\"02678175928\",\"phone\":\"+5511912345678\"},\"shippingAddress\":{\"receiverName\":\"Camilo Segura\",\"postalCode\":\"89220555\",\"city\":\"Joinville\",\"state\":\"SC\",\"country\":\"BRA\",\"street\":\"Rua São Matias\",\"number\":\"1\"},\"billingAddress\":{\"postalCode\":\"89220555\",\"street\":\"Rua São Matias\",\"neighborhood\":\"Costa e Silva\",\"city\":\"Joinville\",\"state\":\"SC\",\"country\":\"BRA\",\"number\":\"1\"},\"items\":[{\"id\":\"17\",\"name\":\"BLACK + DECKER 20V Max Cordless Motosserra, 10 polegadas, ferramenta somente (LCS1020B)\",\"price\":138,\"quantity\":1}],\"shippingValue\":10,\"taxValue\":0},\"paymentId\":\"6BB2F575BB1B493A9D3A3EBD8D8AA8D8\",\"transactionId\":\"A09E2F38DD524C64B92CD5019D9A41E7\",\"callbackUrl\":\"https://yunopartnerbr.vtexpayments.com.br/payment-provider/transactions/A09E2F38DD524C64B92CD5019D9A41E7/payments/6BB2F575BB1B493A9D3A3EBD8D8AA8D8/retry\"}],\"sessions\":[\"ZjgyMzRmZTZmMDVkMzBkNTg2YjY5NzZjNDA2YTY0NTJmNTE2NWJiYTIyZjI3NjU2ZjRiNjg0YzNhZGZkZGQ5NTVjMzFhYWNkNDU1NzFlNTU1ZmQ1MmQ0MWQyYzdlZDM4MDNmNTQ4OTZhN2FiMmYyNTJhYzI4YzZkYzkxNTlmNDAzMmYwNmIyY2E1ZmM1OWE2OWZhOTUyNDY3NjI3YTM0OTQ5NmEyYTQwNzgzMTVhYmU2YTkzNDBhMTc2ZmFjNzY0NWU0ZjU3ZjBmNDIzNDVjNDJjM2MyNjBlZGIwMmQ2ZjkyMzc4OGEzODEzMjE0N2NhN2M0MTM4Y2RkMDAwNjRkYjkwNmQxMjAzZTdiNGNjODJlMjEzZjczZDliZDg3NTMxYjQzZjQ0ZmFiNDJlMmQ4M2UwYTg2YjJhZWNmMmNmYTYzNDY4ZDExZGE2YjAyZTMyYTA2MmI3ZWJlMzIyNjRkYWFlM2JjMTczNThiYmEyNzZkMGUzMzIzMDFlYjk4NTA4NzJjNTIwZjIxOWI5OWY3YTE3ZWJhNWFiMGI0YzYzNWEwNTMwMmQ4YzlmMmVhZGJiOTBlNmY1YTZjMzk3ZTU4M2E4NGU3YzMzMDI2YTczNzdmM2Y5ZWQwOWE3MGFiZjlmMDk4NzkwY2U5YTQ3MTQ1ZTY1MzhjYjU0N2ZhNjY4MDY2NDIxMjA5MWM3MDdhYzc4MDYwMzg0YzA4ODg2NzM0YzRjNzMwNzAyMGNiNWQxOTVlZTAxOWZiZWJhOTg4MWJhMTY2ODY1NDFjOWExMTdlM2M2OGJmMmE5OGI4OTBjYTBkYWIxZjI2ZDc5NDdmYzc2NDE0YjBmODNlNWFkM2RlYTFkNzM1ZmQzMGMxNTlmNTY5YTZmZTYwNGMxMjViMzY0ZTNkN2JmYTk0NWFmN2I2Y2ZiNTRjN2Y3Y2EwMzJjZGY1NDM4MTlhNTIwMTQ4MzY2YzI1YmUyYTk1M2VlYjFhZGE2YmQ5MWYxYjUxZGIwYjE1MWJhYmZmZmFjODgzMDNjNmY4OTBiMWMxZWViMzUwMmQ3NGIwZTljNDZlY2ZlMTkyNTgwZjYwNDcxZjQ5ZWEzMTEyODQyMjE2NDYxYzI0MzM5NjQ3MjU3NGQ5NTE2MGJiMDBhMjQxYThlNmM1ZDEwZDQ3NzFlNDM4YjNhNzZhMzkzNTIyZDNkNmE1YWQyNGY3MTc5ZGJjOWM4OGEzNmVhNjgzYmZiMGQ2YThjNDY4M2ZiNDRkNGJmODVmNzIyYThhMmNhZjY0NzRlMmYxYzYzMTFjNWQ1N2RhOWM3NmFhNmU5ZjJmZmEwODUxMDZmNDA4ZjJlMjkyN2VkZjRiMjRiYzk0ZGMxZTJiMzlhMzk5YjE4ZTUzNjYwZjhmMDJmNTVlZWVhYzdhOWE0MjIyMjBjOWM0NzQ1YTliOWQ0MjYxZmE0YjliMDcxNjhhM2NmZjA2NDRjNWEyZTQ1NWU5YjViMjAyY2NmNDI5MmU4OWEwNjgyZjdkODZkYTc3ZWE4YzEzYjVhODI3YzhjMmI0MWNiNTc1MjMwZTQzZjUzZjhlMTdmOTVjOTkxNmE0MWIwNmMzZDZkNjc2YTgxOTk2ZjZlMGEwNGZiZTMyYTIxMzk3YTdjYjhmNTRjYjJhZTNlYmNkYmI3Njc4ZTdiOWVjZDU3ZTkxZWI4NGY2MWUzNjQ0N2I1YzY4ODhmODVlYmQzY2Q4YjExY2E2M2RkNmUzOTAyZjgyNTRkMjcxZGU0MzI1YzUxMmViMTBkYTM4YTk3ZTMwMzM1N2ZkZmVkNDlkYTQ0MzQ1NjczZTJlNTljZDdkMmFlZGNjMWVlYjM4NWE3NjMyYjZkZjIxZDQ3M2I0ZTdmMzNhNTI3MDg1Y2M0OWEyYzVhZTRiZmVhYjg2MDVhZTQzZWIwY2ExM2RkMzc1MWE1MzQyMDMwMzc4ODI0YTZiMDQ4MjA0NjYwMmZmNmQ2ZDIwYTk4NGI1NWQ5MGU3ODBmODM2MGI5NGU4ZjNhNjYwNDlkZDZkNjBmN2NkMzAyOTZjNDczYjQwNTcyMjkyNWZh\"],
    \"account\":\"yunopartnerbr\"}"
  }
}

pago de Pix pago

Este ejemplo muestra una respuesta de pago de Pix, donde Yuno genera un código QR en formato de texto y en formato de imagen base64.

{
  "status": "undefined",
  "authorizationId": null,
  "paymentAppData": {
    "appName": "yunopartnerbr.yuno-app",
    "payload": {
      "code": "00020126830014br.gov.bcb.pix2561qr-code-h.picpay.com/pix/624ea025-9bb0-47ae-a620-6f2b9ba048815204000053039865802BR5912p2bpix teste6009Sao Paulo62070503***6304535D",
      "qrCodeBase64Image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABWQAAAVkCAYAAABTjRaxAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2ltu5TqWQMFmw/OfMuvz3vyoBFyil7YPIwZwsCU+bCxo7b33/wEAAAAA8OP+/+0BAAAAAABuIcgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAAAAARQRYAAAAAICLIAgAAAABEBFkAAAAAgIggCwAAAAAQEWQBAAAAACKCLAAAAABARJAFAAAAAIgIsgAAAAAAEUEWAAAAACAiyAIAAAAARARZAAAAAICIIAsAAAAAEBFkAQAAAAAigiwAAAAAQESQBQAAAACICLIAAAAAABFBFgAAAAAgIsgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAAAAARQRYAAAAAICLIAgAAAABEBFkAAAAAgIggCwAAAAAQEWQBAAAAACKCLAAAAABARJAFAAAAAIgIsgAAAAAAEUEWAAAAACAiyAIAAAAARARZAAAAAICIIAsAAAAAEBFkAQAAAAAigiwAAAAAQESQBQAAAACICLIAAAAAABFBFgAAAAAgIsgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAA**TRUNCATED**"
    }
  },
  "paymentId": "C9B4F5750BD24EF084E0C7EC0DB7AD16",
  "code": "UNDEFINED",
  "message": "Payment session started by Yuno"
}

pago

Al procesar pagos a través del conector VTEX, Yuno incluye metadatos tanto en la sesión de pago como en pago . Estos metadatos proporcionan contexto adicional sobre la transacción.

ID del vendedor (código de afiliado)

El conector VTEX captura el sellerId (Código de afiliado) de los pedidos de VTEX y lo incluye en la sesión de pago y en pago . Esto permite el seguimiento del mercado y la funcionalidad del modo de afiliado, lo que permite a los comerciantes realizar un seguimiento de la atribución entre sus propias tiendas y los mercados asociados.

El objeto sellerId se incluye automáticamente en los metadatos al procesar los pagos:

"metadata": [
  {
    "key": "sellerId",
    "value": "[affiliate_code_from_vtex_order]"
  }
]

Esta función es especialmente útil para los comerciantes que utilizan el modo Afiliado de VTEX para participar en mercados. Para obtener más información sobre cómo configurar afiliados en VTEX, consulta la documentación de VTEX sobre la configuración de afiliados.

Integración con VTEXIO

Instalación

Se requieren permisos de administrador

Instalar yunopartnerbr.yuno

Instalar yunopartnerbr.yuno-app

Instala Yuno SDK Web para VTEX (opcional)

pago

pago de VTEXIO

pago con tarjeta de crédito en VTEXIO

pago de Pix (APM) en VTEXIO

VTEX sin interfaz

pago sin interfaz de VTEX

Instalación y uso del SDK Web VTEX

Cargas útiles pago

Generación y estructura de la carga útil

pago con tarjeta de crédito

pago de Pix pago

pago

ID del vendedor (código de afiliado)

Instalar `yunopartnerbr.yuno`

Instalar `yunopartnerbr.yuno-app`