VTEX

VTEX es una plataforma de comercio digital que te permite crear una tienda en línea con funcionalidades listas para utilizar rápidamente. Para más información, consulta la página oficial de VTEX.

Prerrequisitos

• Necesitas una cuenta activa en PayU Latam.
• Necesitas una cuenta activa en PaymentsOS. Si no tienes una cuenta, haz clic aquí para crearla.
  Todos los comercios que requieran integrar PayU con VTEX deben tener una cuenta en modo productivo/live en PaymentsOS.
• Necesitas una cuenta VTEX con suficientes permisos para acceder al módulo administrativo de VTEX. Esta cuenta debe tener habilitada la autenticación en dos factores.

Procedimiento de configuración

El procedimiento para habilitar en VTEX los medios de pago que procesamos en nuestra plataforma se divide en dos pasos. Antes de continuar, asegúrate de cumplir con los prerrequisitos anteriores.

1. Configurar tu cuenta de PaymentsOS

La integración de PayU Latam con VTEX se realiza utilizando PaymentsOS como middleware. Como primer paso, necesitas configurar en tu cuenta de PaymentsOS los siguientes ítems:

• Una configuración de Proveedor.
• Una Unidad de Negocio.
• Un WebHook.

Puedes configurar los ítems usando una de las siguientes opciones:

• Configurar la cuenta utilizando Postman.
• Configurar la cuenta manualmente utilizando el Panel de Control de PaymentsOS.

Configurar la cuenta utilizando Postman

Sigue estos pasos para configurar tu cuenta utilizando Postman:

1. Haz clic en el siguiente botón para importar nuestra colección en Postman (puede que necesites refrescar la página si el botón no funciona).

2. Luego de ejecutar la colección, necesitas configurar los globales. Descarga el archivo de globales aquí.

3. En la colección de Postman, haz clic en Import junto al nombre de tu workspace y localiza el archivo json descargado previamente.

4. Cuando termine, haz click en Import.

5. Es obligatorio ejecutar los métodos de la colección en el orden mostrado. Primero, haz click en el método POST llamado 1. Login y abre la pestaña Body.

6. Ingresa el correo electrónico (email) y la contraseña (password) de tu cuenta de PaymentsOS. Luego, haz clic en Send.

7. Si el inicio de sesión fue correcto, los datos de autenticación son asignados en el segundo método.
   Haz clic en el método GET llamado 2. Retrieve PayU Latam ID.

8. En la esquina superior derecha, haz clic en el ícono de ojo y localiza el parámetro env. Luego, haz clic en el ícono de lápiz e ingresa test si estás procesando en el ambiente de pruebas o live en caso contrario.

9. Una vez configurado, haz clic en Send.

10. Haz clic en el método POST llamado 3. Create Provider Configuration, este método crea la Configuración de proveedor en PaymentsOS. Luego, ve a la pestaña Body.

Ingresa la siguiente información:

11. Haz clic en el método POST llamado 4. Create Business Unit, este método crea la Unidad de Negocio en PaymentsOS. Luego, ve a la pestaña Body.

Ingresa la siguiente información:

12. Haz clic en el método POST llamado 5. Create Webhook, este método crea el WebHook en PaymentsOS. Este WebHook es la URL de confirmación que recibirá las notificaciones enviadas por VTEX cuando una transacción cambia de estado.
    Luego, ve a la pestaña Body.

Asigna en el parámetro endpoint los siguientes valores de acuerdo con tu ambiente.

• Test: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Live: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

Deja los demás valores con su valor por defecto.

En este punto, has configurado tu cuenta de PaymentsOS como middleware, el siguiente paso es la configuración del proveedor de VTEX.

Configurar la cuenta manualmente utilizando el Panel de Control de PaymentsOS

Sigue estos pasos para configurar tu cuenta utilizando el panel de control de PaymentsOS.

1. Crea la Configuración de proveedor.
   En el panel de control de PaymentsOS, expande el menú Cuenta, luego selecciona Servicios.

Utiliza el campo Buscar en la sección Crea una nueva configuración de proveedor e ingresa PayU para encontrar el proveedor PayU Latam.

Ingresa la siguiente información para la Configuración de proveedor:

Cuando termines, haz clic en Crear.

2. Crea la Unidad de Negocio.
   En el panel de control de PaymentsOS dashboard, expande el menú Cuenta, luego selecciona Unidades de Negocio.

Haz clic en el botón Crear una Unidad de Negocio e ingresa la siguiente información:

En la sección Selecciona un proveedor por defecto para esta Unidad de Negocio, escoge la Configuración de proveedor creada en el paso anterior.
Cuando termines, haz clic en Crear.

3. Crea el Webhook. Este WebHook es la URL de confirmación que va a recibir las notificaciones enviadas por VTEX cuando una transacción cambia de estado.
   

De vuelta en el panel de control de PaymentsOS, expande el menú Cuenta y selecciona Webhooks.

Haz click en el botón Crear URL de confirmación (Webhook) e ingresa la URL de acuerdo con tu ambiente:

• Test: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Live: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

En la tabla Alertas de eventos transaccionales, activa el evento Update para Authorization y Charge. Además, selecciona en el combo Unidades de Negocio Asociadas la Unidad de Negocio creada en el paso anterior.
Cuando termines, haz clic en Crear.

En este punto, has configurado tu cuenta de PaymentsOS como middleware, el siguiente paso es la configuración del proveedor de VTEX.

2. Configurar el proveedor de VTEX

Una vez hayas configurado tu cuenta de PaymentsOS, el siguiente paso es la configuración del proveedor de VTEX para cada método de pago. Para este paso, es obligatorio que tengas un usuario válido para acceder al admin de VTEX.

Configurar la afiliación de Gateway

Antes de configurar la afiliación de Gateway, asegúrate de haber configurado FingerPrint para PayU. Para esto, consulta este artículo.

1. En el admin de VTEX, expande el menú Pagos dentro del grupo Transacciones. Luego, selecciona Configuración.

2. Antes de continuar con las Condiciones de pago, debes crear un nuevo proveedor. En el panel izquierdo, haz clic en Configuraciones de la tienda > Proveedores > Nuevo proveedor:

3. Ubica PayU, y selecciona PayUv2:

4. En la configuración del conector, debes instalarlo haciendo clic en el botón Instalar app. Luego, ingresa la siguiente información.

Cuando termines, haz clic en Guardar.

Configurar medios de pago

Configure los métodos de pago que se mostrarán en el sitio web para el pago. Consulte nuestros métodos de pago disponibles.

Configurar tarjetas débito o crédito

De acuerdo con tu país de procesamiento, puedes configurar la afiliación que creaste para utilizar tarjetas crédito o débito^*. Sigue estas instrucciones para agregar este medio de pago en tu tienda VTEX.

^* El uso de tarjetas de débito depende de tu país de procesamiento.

1. En la opción de Configuración (Transacciones > Pagos > Configuración), selecciona la pestaña Condiciones de pago y haz clic en el icono más.

2. Selecciona el medio de pago que deseas incluir. Los medios de pago están agrupados por su tipo.
   Para nuestro ejemplo, seleccionamos American Express en la sección Tarjeta de Crédito.

3. Ingresa la siguiente información.

• Nombre de la Regla (para ayudar a identificar rápidamente): ingresa un nombre significativo para la condición de pago junto al medio de pago que seleccionaste.
• Status: selecciona el estado de la condición de pago. Solo puedes tener una condición de pago activa por medio de pago.
• Procesar con afiliación: select the gateway affiliation configured before.
• Pago al contado o en cuotas?: selecciona Al contado^*.

4. Haz clic en Guardar. Cuando hayas creado la condición de pago, esta se lista en la pestaña Condiciones de pago.

Configurar tarjetas de marca compartida o privada

Las tarjetas de marca compartida o privada son tarjetas emitidas por una tienda o marca en asocio con una red como AMEX, VISA, MasterCard, etc. Sigue estas instrucciones para agregar este medio de pago en tu tienda VTEX.

1. En la opción de Configuración (Transacciones > Pagos > Configuración), ve a la pestaña Pagos personalizados.

2. En esta pestaña, tienes cinco (5) espacios disponibles para configurar tarjetas de marca compartida y privada. En este ejemplo, configuraremos la tarjeta colombiana Codensa que es una tarjeta de marca privada.
   Haz clic en cualquiera de las casillas disponibles en la sección Tarjeta de tienda (red propia).

3. Ingresa la siguiente información utilizando las minúsculas y mayúsculas mostradas.

• Nombre: Codensa.
• Descripción: Codensa
• Rangos de BIN: 590712-590712
• Código de pago del adquirente: codensa

Los valores restantes se pueden dejar por defecto. Utiliza los siguientes valores para configurar tarjetas de marca privada y de marca compartida.

País	Nombre	Descripción	Rangos de BIN	Código de pago del adquirente
	Argencard	Argencard	501105-532362	argencard
	Cabal	Cabal	60423,60400,589657	cabal
	Cencosud	Cencosud	603493-603493	cencosud
	Naranja	Naranja	589562	naranja
	Shopping	Shopping	603488	shopping
	Codensa	Codensa	590712-590712	codensa

Para más información de cómo configurar tarjetas de marca compartida y de marca privada, consulta el centro de ayuda de VTEX.

4. Haz clic en Guardar. Cuando se haya creado el pago personalizado, serás redirigido a la opción para crear una nueva Condiciones de pago. Esta condición de pago se crea tal y como se explica en la sección Configurar tarjetas de crédito o débito.

Configurar medios de pago en efectivo

Como los medios de pago en efectivo requieren que el cliente pague en oficinas físicas, puedes configurar este medio de pago en VTEX como Pagarés.

Cuando configuras un método de pago en efectivo, tus clientes son redirigidos al checkout de PayU para que descarguen el comprobante de pago y paguen en la oficina física respectiva. Sigue las instrucciones a continuación para agregar este método de pago a su tienda VTEX.

1. En la opción de Configuración (Transacciones > Pagos > Configuración), ve a la pestaña Pagos personalizados.

2. En esta pestaña, tienes cinco (5) espacios disponibles para configurar pagos en efectivo. En este ejemplo, configuraremos OXXO, un medio de pago en efectivo mexicano.
   Haz clic en cualquiera de las casillas disponibles en la sección Pagarés.

3. Ingresa la siguiente información para el medio de pago en efectivo.

• Nombre: En este parámetro, necesitar utilizar el valor mostrado aquí en la columna Parámetro paymentMethod. Para este ejemplo, configuramos OXXO.
• Descripción: Ingresa la descripción que desea mostrar cuando el cliente seleccione este método de pago. Este parámetro es opcional.
• Validez del pagaré: ingresa el número de días antes de que venza el pago en efectivo. Por defecto, este valor se asigna a 7 días. Ten presente que, para evitar inconvenientes en el procesamiento, este valor debe coincidir con el valor seleccionado en el campo Expiración pago (días) que configuraste en la afiliación VTEX.

Deja los demás parámetros con sus valores por defecto.

4. Haz clic en Guardar. Cuando se haya creado el pago personalizado, serás redirigido a la opción para crear una nueva Condiciones de pago. Esta condición de pago se crea tal y como se explica en la sección Configurar tarjetas de crédito o débito.

Configurar PSE

Prerrequisitos:

• PSE es un medio de pago local. Solo aplica para comercios que tienen procesamiento en Colombia.
• Para ofrecer PSE como método de pago, debes asegurarte, primero, de instalar la App de PSE desarrollada por VTEX. Si todavía no lo has hecho, dirígete a Configuración de Cuenta > Aplicaciones > Tienda de Aplicaciones y busca Banks for PSE. En caso de no encontrar la App en la tienda, debes solicitar su instalación al equipo de VTEX a través de un ticket en Soporte de VTEX.
• Si tienes una integración VTEX Legacy, ten en cuenta que VTEX debe realizar una configuración adicional para que puedas configurar el medio de pago. Contacta a tu agente VTEX o solicita ayuda a través de los canales de soporte de VTEX.

1. Para configurar PSE, dirígete al panel de administración de tu plataforma VTEX y accede a Configuración de la tienda>Pagos>Configuración>Planes de pago (en inglés, Store Settings>Payments>Settings>Payment Conditions). Luego, sigue los pasos a continuación:

• Haz clic en el botón +.
• Dentro de la categoría Otro, busca PSE.
• Completa los campos que te mostrará la pantalla siguiente:
  • Escribe el Nombre de la Regla, que te permitirá identificar este medio de pago.
  • En el campo Proceso con la afiliación (en inglés Process with affiliation), selecciona el nombre de tu afiliación configurada para procesar con PayUV2.
  • En el campo Status, activa la condición de pago.
  • Haz clic en Guardar/Save para activar la configuración.

2. Realiza la configuración de la app Banks for PSE con tus credenciales de PayU. Para esto, sigue los pasos a continuación:

• Ingresa al panel de administración de tu plataforma VTEX y accede a Aplicaciones>Aplicaciones instaladas>Banks for PSE (en inglés Apps>Installed apps>Banks for PSE).
• Completa los campos que te mostrará la pantalla siguiente y haz clic en Guardar.

• Una vez completes la configuración, puedes realizar transacciones en el ambiente productivo con PSE.

Probar la integración

Una vez que hayas configurado las Condiciones de pago para tus medios de pago, se recomienda probar la integración antes de comenzar a recibir transacciones reales.

Prerrequisitos para pruebas exitosas:

• Asegúrate de que tu cuenta de PaymentsOS esté en modo TEST.
• Revisa que el Selector de ambiente en tu Afiliación de Gateway VTEX esté en modo TEST.
• Asegúrate de usar las credenciales apropiadas para el ambiente test cuando estés configurando la Afiliación de Gateway VTEX. Recuerda que puedes encontrar las credenciales de pruebas aquí.
• Recuerda que una vez realices tus pruebas, debes modificar los puntos anteriores con la información productiva (Cuenta PaymentsOS, selector de ambiente en afiliación VTEX y Credenciales configuradas en afiliación VTEX).

1. En el admin de VTEX, haz clic en VISITE LA TIENDA en el panel superior.

2. Se abre la tienda configurada para tu cuenta de VTEX. Selecciona cualquier producto y haz clic en comprar.

3. En el carrito de compras, haz clic en el botón realizar pedido.

4. En la sección de pago, aparecen los medios de pago agrupados por tipo. Selecciona el que deseas probar e ingresa los datos de prueba. Encuentra aquí algunos números de tarjeta de prueba e información para probar los estado.
   Por último, haz clic en Completar compra.

Una vez aprobada la compra puedes verificarla en:

• Admin de VTEX: Pagos > Transacciones.

• Panel de control de PaymentsOS: Pagos > Buscar.
  
  
  El parámetro ID Externa de la Transacción dentro de Actividad de la Transacción es el OrderID de PayU.

• Módulo PayU: en el Reporte de Ventas.

• API de Consultas utilizando el parámetro ID Externa de la Transacción como OrderID.

Probar flujos de dos pasos

Cuando hayas configurado tu Afiliación de Gateway para procesar transacciones en flujos de dos pasos, los fondos autorizados en la tarjeta de crédito no son capturados hasta que solicites la captura explícitamente. Para solicitar la captura, necesitas facturar la orden.

Para facturar una orden, localiza la transacción en el Admin de VTEX (Pagos > Transacciones) y haz clic en ella. Después, haz clic en el botón Pedido en la esquina superior derecha.

Desplázate hasta la sección Paquete y haz clic en Facturar paquete.

Proporciona la información de la factura y haz clic en Enviar factura al final del panel. Una vez enviada la factura al cliente, se cobra en la tarjeta del cliente el importe autorizado.