VTEX

VTEX es una plataforma de comercio digital empresarial que te permite crear rápidamente una tienda en línea con funcionalidades integradas. Para más información, visita el sitio web oficial de VTEX.

Requisitos previos

• Una cuenta activa de PayU Latam.
• Una cuenta activa de PayU Enterprise (PaymentsOS) en modo de producción/en vivo. Para más detalles sobre cómo habilitarla, consulta Activación de tu cuenta PayU Enterprise.
• Una cuenta de VTEX con los permisos y derechos suficientes para acceder al panel administrativo de VTEX. Esta cuenta debe tener autenticación de dos factores habilitada.

Disponibilidad por País y Métodos de Pago

La siguiente tabla muestra la disponibilidad de VTEX por país y los métodos de pago admitidos:

País	Tarjetas de Crédito	Pagos en Efectivo	Otros Métodos
Argentina	Tarjetas de crédito	Pagos en efectivo	-
Brasil	AMEX, MasterCard, Visa	Boleto Bancário	-
Colombia	AMEX, Codensa, Diners, MasterCard, Visa	Efecty, Su Red, referencia bancaria	PSE
Chile	Tarjetas de crédito	Pagos en efectivo	-
México	Tarjetas de crédito	Pagos en efectivo	SPEI
Perú	AMEX, MasterCard, Visa	-	-

Activación de tu Cuenta PayU Enterprise (Modo Live)

Por defecto, las cuentas nuevas se configuran en modo de prueba. Para habilitar las transacciones en vivo, contacta a tu gerente de cuenta y envía una solicitud con los siguientes detalles:

• Merchant ID: Localiza el Merchant ID de tu cuenta LATAM en el Panel de Gestión de PayU.
• Account ID: Encuentra tu Account ID en el panel de control de PayU Enterprise haciendo clic en tu nombre de usuario en la esquina superior derecha.
  

Configuración de tu Cuenta PayU Enterprise

Para configurar los métodos de pago en VTEX y procesarlos a través de nuestra pasarela, sigue los pasos a continuación. La configuración consta de dos etapas. Antes de continuar, asegúrate de haber cumplido con los requisitos previos mencionados anteriormente.

1. Configuración Inicial

PayU Enterprise opera a través de PaymentsOS, que actúa como middleware entre PayU Latam y VTEX. El primer paso es configurar los siguientes componentes dentro de tu cuenta PayU Enterprise:

• Configuración del proveedor
• Unidad de negocio
• Webhook

Puedes configurar estos componentes utilizando uno de los siguientes métodos:

• Configurar la cuenta usando Postman.
• Configurar la cuenta manualmente a través del panel de PayU Enterprise.

Configuración de la Cuenta Usando Postman

Sigue estos pasos para configurar tu cuenta utilizando Postman:

1. Haz clic en el botón a continuación para importar nuestra colección de Postman (si el botón no funciona, actualiza la página).

2. Después de importar la colección, configura las variables globales. Descarga el archivo de variables globales aquí.

3. En Postman, haz clic en Import junto al nombre de tu espacio de trabajo y selecciona el archivo JSON descargado.

4. Haz clic en Import para finalizar el proceso.

5. Ejecuta los métodos de la colección en el orden indicado. Primero, selecciona el método POST llamado 1. Login y navega a la pestaña Body.

6. Ingresa el correo electrónico y contraseña de tu cuenta PayU Enterprise, luego haz clic en Send. Si el inicio de sesión es exitoso, los datos de autenticación se establecerán para el siguiente método.

7. Haz clic en el método GET 2. Retrieve PayU Latam ID.

8. En la esquina superior derecha, haz clic en el ícono de ojo para ubicar el parámetro env. Luego, haz clic en el ícono de lápiz y configúralo en test para el entorno de pruebas o en live para producción.

9. Haz clic en Send para continuar.

10. Luego, configura el proveedor, el cual almacena tus credenciales de procesamiento de pagos. Selecciona el método POST 3. Create Provider Configuration y navega a la pestaña Body.

Completa los siguientes datos:

11. Configura una unidad de negocio, la cual vincula la configuración del proveedor con las credenciales de la API de PayU Enterprise para procesar transacciones. Selecciona el método POST 4. Create Business Unit y navegando a la pestaña Body.

Completa los siguientes datos:

12. Crea el Webhook, el cual recibe las notificaciones de VTEX cuando una transacción cambia de estado. Selecciona el método POST 5. Create Webhook y navega a la pestaña Body.

Configura el parámetro endpoint según tu entorno:

• Pruebas: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Producción: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

Deja todos los demás parámetros con sus valores predeterminados.

En este punto, tu cuenta PayU Enterprise con PaymentsOS está configurada. El siguiente paso es Configurar el Proveedor en VTEX.

Configuración Manual de la Cuenta Usando el Panel de PayU Enterprise

Sigue estos pasos para configurar tu cuenta utilizando el panel de PayU Enterprise.

1. Crear la Configuración del Proveedor

Un proveedor almacena tus credenciales de procesamiento de pagos. Sigue estos pasos para configurar uno:

1.1 En el panel de control de PayU Enterprise, navega a Configurations > Providers.

1.2 Haz clic en el módulo correspondiente al país o división que estás configurando.

1.3 Completa los siguientes campos:

1.4 Haz clic en Create.

2. Crear la Unidad de Negocio

Una unidad de negocio vincula la configuración del proveedor con las credenciales de la API de PayU Enterprise para procesar transacciones. Sigue estos pasos:

2.1 En el panel de control, ve a Configurations > Business Units.

2.2 Haz clic en Create Business Unit e ingresa:

2.3 En la sección Choose a Default Provider for This Business Unit, selecciona la Provider Configuration creada en el Paso 1. Luego, haz clic en Create.

3. Crear el Webhook

El webhook recibe notificaciones de VTEX cuando el estado de una transacción cambia. Sigue estos pasos:

3.1 En el panel de control, navega a Configurations > Webhooks.

3.2 Haz clic en Create a Webhook Endpoint e ingresa la URL correspondiente a tu entorno:

• Pruebas: https://sandbox.api.payulatam.com/vtex-payments-integration/paymentsos/webhook
• Producción: https://api.payulatam.com/vtex-payments-integration/paymentsos/webhook

3.3 En la tabla Payment Event Alerts, activa el control deslizante Update para Authorization y Charge. Luego, en el campo Associated Business Units, ingresa la Business Unit creada en el paso anterior. Finalmente, haz clic en Create.

En este punto, tu cuenta PayU Enterprise con PaymentsOS está completamente configurada. El siguiente paso es configurar el proveedor en VTEX.

2. Configuración del Proveedor en VTEX

Una vez que hayas configurado tu cuenta de PayU Enterprise, el siguiente paso es configurar el proveedor de VTEX para cada método de pago. Para continuar, debes tener una cuenta de usuario válida para acceder al administrador de VTEX.

Crear un Nuevo Proveedor

1. En el panel izquierdo, selecciona Configuración de la tienda > Proveedores > Nuevo proveedor:

2. Ubica PayU y selecciona PayUv2:

3. En la configuración del conector, instala el conector haciendo clic en el botón Instalar aplicación. Luego, completa los siguientes campos:

4. Haz clic en Guardar para completar la configuración.

Configuración de Métodos de Pago

Configura los métodos de pago que se mostrarán en el sitio web durante el proceso de pago. Consulta los métodos de pago disponibles.

Configuración de Tarjetas de Crédito o Débito

Dependiendo de tu país de procesamiento, puedes configurar la afiliación que creaste para utilizar tarjetas de crédito o débito^*. Sigue los pasos a continuación para agregar este método de pago a tu tienda VTEX.

^* La disponibilidad de tarjetas de débito depende de tu país de procesamiento.

1. En el panel izquierdo, ve a Transacciones > Pagos > Configuración. Selecciona la pestaña Condiciones de pago y haz clic en el icono de suma.

2. Selecciona el método de pago que deseas agregar. Los métodos de pago están agrupados por tipo.
   Para este ejemplo, seleccionamos American Express en la sección de Tarjeta de Crédito.

3. Proporciona los siguientes detalles:

• Nombre de la regla (para identificarla rápidamente): Ingresa un nombre descriptivo para la condición de pago.
• Status: Configura el estado de la condición de pago. Solo puedes tener una condición de pago activa por método de pago.
• Procesar con afiliación: Selecciona la afiliación de gateway previamente configurada.
• ¿Pago al contado o en cuotas?: Selecciona Al contado.

4. Haz clic en Guardar. La nueva condición ahora aparecerá en la pestaña Condiciones de pago.

Configuración de Tarjetas Co-Branded o Private Label

Las tarjetas co-branded y private label son tarjetas de crédito emitidas por una tienda o marca, a veces en asociación con redes como AMEX, VISA o MasterCard. Sigue estos pasos para agregar este método de pago a tu tienda VTEX.

1. En el panel izquierdo, selecciona Transacciones > Pagos > Configuración. Selecciona la pestaña Pagos personalizados.

2. La pestaña Pagos personalizados proporciona cinco (5) espacios para configurar tarjetas co-branded y private label. En este ejemplo, configuramos la tarjeta colombiana Codensa, que es una tarjeta private label.
   Haz clic en cualquier cuadro disponible en la sección Tarjeta de tienda (red propia).

3. Ingresa los siguientes detalles de la tarjeta, manteniendo el formato exacto:

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

Usa la siguiente tabla para configurar tarjetas co-branded y private label. Puedes dejar los demás valores con su configuración predeterminada.

País	Nombre	Descripción	Rangos 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 detalles sobre la configuración de tarjetas co-branded y private label, visita el Centro de Ayuda de VTEX.

4. Haz clic en Guardar. Después de crear el pago personalizado, serás redirigido a la opción para crear una Condición de pago. Sigue las instrucciones en la sección Configuración de Tarjetas de Crédito o Débito para completar este paso.

Configuración de Métodos de Pago en Efectivo

Dado que los pagos en efectivo requieren que los clientes realicen el pago en ubicaciones físicas, puedes configurar este método de pago en VTEX como notas promisorias (Notes Payables).

Cuando configuras un método de pago en efectivo, los clientes son redirigidos al checkout de PayU, donde pueden descargar el comprobante de pago y realizarlo en la ubicación física correspondiente. Sigue las instrucciones a continuación para agregar este método de pago a tu tienda VTEX.

1. En el panel izquierdo, selecciona Transacciones > Pagos > Configuración. Selecciona la pestaña Pagos personalizados.

2. En esta pestaña, tienes cinco (5) espacios disponibles para configurar métodos de pago en efectivo. En este ejemplo, configuraremos OXXO, un método de pago en efectivo en México.
   Haz clic en cualquier cuadro disponible en la sección Pagarés.

3. Proporciona la siguiente información:

• Nombre: Usa el valor listado aquí en la columna del parámetro paymentMethod. Para este ejemplo, ingresa OXXO.
  • Descripción: Ingresa una descripción que se mostrará cuando el cliente seleccione este método de pago (opcional).
  • Fecha de vencimiento de la nota promisoria: Especifica el número de días antes de que expire el pago en efectivo. El valor predeterminado es de 7 días. Asegúrate de que este valor coincida con la configuración Expiración pago (días) en la afiliación de VTEX para evitar problemas de procesamiento.

Deja los demás campos con sus valores predeterminados.

4. Haz clic en Guardar. Una vez creado el pago personalizado, serás redirigido para configurar una nueva Condición de pago. Sigue las instrucciones en la sección Configuración de Tarjetas de Crédito o Débito.

Configuración de PSE

Requisitos previos:

• Este método de pago solo está disponible para comercios que procesan en Colombia.
• Para ofrecer PSE como método de pago, debes instalar la aplicación PSE desarrollada por VTEX. Si aún no lo has hecho, ve a Configuración de la cuenta > Apps > App Store y busca Banks for PSE.
  Si la aplicación no está disponible en la tienda, puedes solicitar su instalación al equipo de VTEX enviando un ticket en VTEX Support.
• Si utilizas una integración VTEX Legacy, VTEX debe realizar una configuración adicional antes de que puedas configurar este método de pago. Contacta a tu representante de VTEX o solicita asistencia a través de VTEX Support.

1. Para configurar PSE, accede al panel de administración de VTEX y navega a Configuración de la tienda > Pagos > Configuración > Condiciones de pago. Luego, sigue estos pasos:

  1.1 Haz clic en el botón +.

  1.2 En la categoría Otros, localiza PSE.

  1.3 Completa los siguientes campos:

    • Nombre de la regla: Ingresa un nombre descriptivo para identificar este método de pago.
    • Procesar con afiliación: Selecciona la afiliación de gateway configurada para procesar pagos con PayUV2.
    • Estado: Activa la condición de pago.

  1.4 Haz clic en Guardar para aplicar la configuración.

2. Configura la aplicación Banks for PSE con tus credenciales de PayU siguiendo estos pasos:

  2.1 Inicia sesión en el panel de administración de VTEX y ve a Apps > Apps instaladas > Banks for PSE.

  2.2 Completa el formulario y haz clic en Guardar.

• Una vez completada la configuración, podrás procesar transacciones en un entorno de producción con PSE.

Prueba de la Integración

Una vez que hayas configurado las condiciones de pago para tus métodos de pago, se recomienda encarecidamente probar tu integración antes de procesar transacciones reales.

Requisitos Previos para una Prueba Exitosa:

• Asegúrate de que tu cuenta de PayU Enterprise esté en modo TEST.
• Verifica que el Selector de Entorno en tu Afiliación de Gateway en VTEX esté configurado en modo TEST.
• Usa las credenciales de prueba adecuadas al configurar la Afiliación de Gateway en VTEX. Puedes encontrar las credenciales de prueba aquí.
• Una vez finalizadas las pruebas, actualiza la configuración con la información de producción, incluyendo tu cuenta de PayU Enterprise, el selector de entorno en la afiliación de VTEX y las credenciales.

Pasos para Realizar una Transacción de Prueba

1. En el panel de administración de VTEX, haz clic en Visite la tienda en el menú superior.

   

2. Se abrirá la tienda configurada para tu cuenta de VTEX. Selecciona cualquier producto y procede con la compra.

   

3. En el carrito de compras, haz clic en el botón Realizar Pedido.

   

4. En la sección de pago, los métodos de pago disponibles aparecerán agrupados por tipo. Selecciona el que deseas probar e ingresa los datos de prueba. Puedes encontrar los números de tarjeta de prueba y la información relevante aquí.
   Finalmente, haz clic en Finalizar Compra.

   

Verificación de la Transacción

Una vez aprobada la compra, puedes verificar la transacción en los siguientes lugares:

• Administrador de VTEX: Selecciona Transacciones > Pagos > Transacciones.

  

• Panel de control de PayU Enterprise: Ve a Pagos > Buscar.

  

  Nota

  El parámetro ID Externo de Transacción dentro de Actividad de la Transacción corresponde al ID de la orden en PayU.

• Panel de gestión de PayU: Revisa la transacción en el módulo Reporte de Ventas.

  

• API de Consultas: Usa el External Transaction ID como parámetro OrderID.

Prueba de Flujos en Dos Pasos

Si tu Afiliación de Gateway está configurada para procesar transacciones mediante un flujo en dos pasos, los fondos autorizados en la tarjeta de crédito no se liquidan hasta que solicites explícitamente la liquidación. Para completar la liquidación, debes facturar el pedido.

Pasos para Facturar un Pedido

1. Ubica la transacción en el Administrador de VTEX en Transacciones > Pagos > Transacciones y haz clic en ella.
   Luego, haz clic en el botón Pedido en la esquina superior derecha.

   

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

   

3. Ingresa los detalles de la factura y haz clic en Enviar factura.
   Una vez enviada la factura al cliente, el monto autorizado se cobra en la tarjeta del cliente.