Este artículo ofrece una guía completa para partners que desean desarrollar conectores de pago compatibles con la plataforma VTEX. El objetivo es garantizar una integración eficiente y estandarizada, que permita utilizar los conectores en todas las tiendas de la plataforma.

Al adoptar las directrices presentadas aquí, los partners garantizan que su integración cumpla con los más altos estándares de calidad, agregando valor tanto para los retailers como para sus clientes, y fomentando la innovación y la competitividad en ecommerce.

Este contenido está dirigido a:

• Desarrolladores y equipos técnicos de partners de pago: responsables de implementar soluciones de integración eficientes.
• Gerentes de producto y equipos de integración: encargados de garantizar la cohesión y la operación eficaz de los conectores dentro de la plataforma.
• Equipos de soporte técnico de proveedores de pago, gateways y sistemas antifraude: responsables de ofrecer soporte continuo y asegurar una operación estable y en conformidad con las soluciones.

En VTEX, un conector de pago es un servicio externo que implementa el VTEX Payment Provider Protocol (PPP). Este protocolo permite la comunicación entre la plataforma y los proveedores de pago (como gateways, adquirentes y soluciones antifraude), lo que facilita a los retailers procesar transacciones de forma integrada y estandarizada, sin necesidad de desarrollar integraciones personalizadas.

Consulta a continuación las secciones de esta guía:

• Requisitos técnicos obligatorios
• Beneficios de la integración PPP
• Fases de desarrollo del conector
• Elección de la infraestructura del conector
• Mejores prácticas en el desarrollo de conectores

Los partners que deseen desarrollar un conector de pago en VTEX deben implementar las siguientes funcionalidades en sus integraciones:

• Autorización de pagos (sincrónica o asincrónica).
• Cancelación de autorizaciones antes de capturar los valores.
• Captura de valores (inmediata o programada).
• Reembolso de cantidades después de la captura, si la transacción ya ha sido realizada.
• Notificaciones asincrónicas de status transaccional (actualización automática del status del pago en VTEX).
• Conformidad con la certificación PCI-DSS, en caso de que el objetivo sea procesar medios de pago como tarjetas de crédito, débito o tarjetas de tienda co-branded. Si no dispones de esta certificación, deberás implementar el conector utilizando la solución Secure Proxy de VTEX.
• Alta disponibilidad y cobertura regional del conector, conforme a lo establecido en el contrato firmado con VTEX.
• Desarrollo de los endpoints del conector de acuerdo con las mejores prácticas para la creación de APIs.

La implementación de conectores desarrollados mediante VTEX Payment Provider Protocol (PPP) ofrece las siguientes ventajas:

• Optimización del esfuerzo técnico: reduce la necesidad del desarrollo de integraciones personalizadas.
• Escalabilidad: se pueden agregar nuevos medios de pago rápidamente. Una vez publicado, el conector de un partner queda disponible para todos los retailers de VTEX, lo que potencia el alcance y acelera la adopción de la solución.
• Mayor conversión de ventas: flexibilidad para adaptarse a las particularidades y necesidades específicas de cada retailer.
• Gestión centralizada: la información de configuración del conector puede ajustarse directamente en el Admin VTEX.

El proceso de desarrollo de un conector VTEX puede dividirse en cuatro fases:

Para más detalles sobre el flujo de creación de un conector, accede a Integrating a new payment provider on VTEX.

Durante la fase de implementación de la API, el partner puede definir el tipo de infraestructura que desea utilizar para integrar el conector en VTEX.

Consulta las características de cada opción de infraestructura disponible:

Beneficios:

• Libertad en la elección de las herramientas de desarrollo: como el desarrollador controla completamente la infraestructura, tiene total libertad para seleccionar las herramientas que mejor se adapten a sus necesidades, como lenguajes de programación, bases de datos y otros recursos tecnológicos.

• Recepción directa de datos de tarjeta en el conector: al desarrollar un conector en tu propia infraestructura y en conformidad con los estándares PCI-DSS, puedes recibir directamente los datos de tarjeta, en caso de que sea necesario. Esto elimina la necesidad de utilizar funcionalidades como Secure Proxy para capturar esos datos.

Puntos a considerar:

• Necesidad de mantenimiento de la infraestructura: al desarrollar el conector en su propia infraestructura, el equipo de desarrollo asume la responsabilidad del mantenimiento, escalabilidad y estabilidad del sistema, lo que implica una mayor carga de trabajo para asegurar su correcto funcionamiento.

• Menor autonomía para realizar cambios: como el conector se desarrolla fuera de la infraestructura de VTEX IO, cambios como la incorporación de nuevos medios de pago o la activación de split no pueden realizarse directamente. En estos casos, el desarrollador debe ponerse en contacto con el equipo de VTEX para solicitar las modificaciones necesarias. Este proceso está sujeto a un SLA definido por el equipo de Payments de VTEX, y puede durar hasta 30 días.

Beneficios:

• Payment Provider Framework (PPF): guía completa para construir conectores utilizando VTEX IO.

• Flexibilidad total: se puede utilizar para cualquier tipo de integración, no solo medios de pago. Además, permite implementar personalizaciones adicionales en el conector de forma sencilla, cuando sea necesario.

• Diversas opciones de personalización: posibilita la creación de componentes de frontend para Store Framework, incluyendo banners en la página de inicio de la tienda, páginas de categorías y upsell, entre otros.

• Desarrollo integrado al ecosistema VTEX: permite crear aplicaciones que interactúan con todas las APIs y eventos de la plataforma, como la captación de datos de CRM, datos del carrito y del checkout y datos logísticos.

• Acceso a eventos en tiempo real: utiliza Event Bus para seguir acciones realizadas en la plataforma.

• Integración simplificada con base de datos como servicio: se conecta fácilmente a bases de datos como VBase y Master data para gestionar datos de manera eficiente en tu aplicación.

• Elimina la necesidad de desarrolladores con certificación PCI-DSS: los conectores creados en VTEX IO utilizan Secure Proxy para el tratamiento de datos de tarjeta, garantizando que el conector no tenga acceso directo a información sensible. Aun así, el partner debe contar con la certificación PCI-DSS.

• Infraestructura que no requiere mantenimiento: al desarrollar el conector en VTEX IO, toda la gestión de la infraestructura es automática, lo que permite que el desarrollador se enfoque únicamente en cómo debe funcionar la integración, sin preocuparse por aspectos técnicos del sistema.

• Actualización automatizada mediante versionado de la aplicación: las actualizaciones del conector se realizan de forma automática, sin necesidad de intervención del equipo de VTEX.

Recursos operativos:

• Estructura sin servidor (serverless): VTEX IO opera directamente en el entorno VTEX, eliminando la necesidad de infraestructura externa.

• GraphQL + REST APIs: ofrece soporte a diversas formas de comunicación, proporcionando flexibilidad en la integración

Puntos a considerar:

• No hay acceso directo a los datos de tarjeta por parte del conector: VTEX IO no es compatible con los requisitos de PCI-DSS, por lo que los conectores desarrollados en esta plataforma no pueden acceder directamente a los datos de tarjeta. Para manejar esta información, es necesario utilizar la funcionalidad Secure Proxy. Si el modelo de negocio necesita procesar los datos de la tarjeta antes de enviarlos al adquirente, VTEX IO puede no ser la mejor opción, ya que no permite ese nivel de acceso.

• Limitaciones en los lenguajes y frameworks admitidos: VTEX IO solo es compatible con algunos lenguajes y frameworks específicos, como React, Node y .NET. Los desarrolladores que no estén familiarizados con estas tecnologías tendrán que adaptarse al entorno, lo que puede requerir más tiempo de aprendizaje y ajustes del flujo de trabajo.

• Se requiere conocimiento de VTEX IO: aunque VTEX IO es intuitivo y fácil de usar, tiene características específicas que requieren que el desarrollador entienda cómo funciona para aprovechar todo su potencial. Si no se tiene experiencia previa les llevará algún tiempo adaptarse a las particularidades de la plataforma.

La elección entre desarrollar un conector en tu propia infraestructura o en VTEX IO depende de las necesidades de cada integración y del nivel de personalización deseado. PPP es obligatorio para medios de pago, mientras que VTEX IO ofrece más flexibilidad para personalizaciones avanzadas.

A la hora de definir la infraestructura, considera los conocimientos técnicos del equipo como un factor estratégico. Trabajar con tecnologías conocidas reduce los riesgos, acelera la entrega y aumenta la eficacia operativa.

A continuación se describen las mejores prácticas para el desarrollo de conectores, que incluyen tanto aspectos técnicos como empresariales que son esenciales para garantizar la eficacia y la calidad de la integración. Las características descritas representan las mejores prácticas identificadas a lo largo de años de colaboración con adquirentes, agencias y proveedores de servicios antifraude, con el objetivo de desarrollar soluciones confiables y de alto rendimiento.

La idempotência en el conector garantiza que múltiples requests con los mismos parámetros produzcan siempre el mismo resultado, sin importar cuántas veces se envíen. Este comportamiento es esencial en flujos críticos, como el transaccional. Además, VTEX realiza intentos automáticos de llamadas idénticas (retry), lo que puede generar múltiples requests con el mismo paymentId para actualizar el status de la transacción.

En conectores que poseen idempotencia se observan las siguientes características operativas:

• Se evitan pagos duplicados en caso de reenvío automático. Este comportamiento asegura el procesamiento único de una transacción, evitando duplicados. Si el conector no es idempotente, pueden ocurrir cargos duplicados, generando incoherencias.

• En casos de fallos en la red (comunicación), se garantiza la confiabilidad de la integración.

• Cuando un retailer o adquirente reporta un problema transaccional, la idempotencia garantiza que los logs y las respuestas sean consistentes y previsibles.

• Se reduce el número de llamadas innecesarias al proveedor. Si el pago ya se ha procesado, el conector puede simplemente devolver la respuesta previamente registrada, evitando la necesidad de un nuevo request al adquirente.

Implementación de la idempotencia

Para implementar la idempotencia es necesario adoptar las siguientes especificaciones durante el desarrollo del conector:

1. Garantizar un identificador único para cada transacción (paymentId).
2. Almacenar y reutilizar la respuesta (éxito, fallo, pendiente) del request en caso de reenvío.
3. Definir un tiempo de expiración para los registros idempotentes.
4. Asegurar que la idempotencia se mantenga también para cancelaciones y reembolsos.
5. Cuando se utiliza la infraestructura VTEX IO:
   • Se recomienda utilizar VBase para almacenar la respuesta basada en el paymentId enviado por el gateway de pago, a través de la ruta Create Payment.
   • Cuando recibe una nueva llamada, el conector puede comprobar en VBase si ya se ha registrado un request similar. Si es así, se puede retornar la respuesta previamente registrada. Consulta este ejemplo de implementación.

Además de la fiabilidad técnica, algunas características funcionales pueden aumentar significativamente el impacto comercial del conector. A continuación destacamos las funcionalidades que contribuyen directamente al éxito de la operación, promoviendo una mayor seguridad, eficiencia y conversión.

Soporte para carteras digitales (Apple Pay, NuPay, Google Pay, PayPal)

El creciente uso de carteras digitales (wallets) aporta mayor seguridad y comodidad a los consumidores. Los conectores compatibles con estas carteras ofrecen los siguientes beneficios:

• Checkout más directo: reduce la fricción en el pago, ya que los datos de la tarjeta están almacenados en la cartera digital.
• Mayor seguridad: el uso de autenticación biométrica y tokenización minimiza fraudes y contracargos.
• Mayor conversión: menos pasos en el checkout resultan en un menor abandono de carrito.

Soporte para Google Pay con tokenización DPAN (Device Primary Account Number)

El soporte para Google Pay con tokenización DPAN ofrece ventajas importantes para la seguridad y la experiencia del usuario:

• Mayor seguridad: los datos reales de la tarjeta no se comparten, lo que reduce el riesgo de fraude.
• Menos fricción en las compras recurrentes: los DPANs se pueden reutilizar (pagos recurrentes) sin necesidad de volver a solicitar los datos del usuario.
• Compatibilidad con múltiples dispositivos: permite utilizar la misma tarjeta en diferentes dispositivos sin necesidad de una nueva autenticación.
• Reducción de costos por fraudes: la tokenización evita el uso indebido de credenciales, lo que puede disminuir el número de contracargos.

El soporte para Google Pay con DPAN solo está disponible a través de la cartera Google Pay nativa de VTEX.

Soporte de pago vía PDV (VTEX Sales App)

Los conectores compatibles con pagos vía Punto de venta (PDV) en VTEX Sales App hacen posibles transacciones Omnichannel entre el entorno físico y digital. Los beneficios incluyen:

• Integración entre canales: el cliente puede iniciar una compra online y finalizarla en la tienda física utilizando el mismo medio de pago.
• Reducción de errores operativos: dado que el pago está integrado con VTEX Sales App, no es necesario registrar manualmente las transacciones en el ERP.
• Experiencia de compra optimizada: los vendedores pueden procesar los pagos rápidamente en un único sistema.
• Soporte para diferentes opciones de pago: el PDV puede aceptar tarjetas de crédito, débito, Pix (Brasil) mediante código QR y carteras digitales.

Soporte para split de cobros

Los conectores con funcionalidad de split de cobros permiten dividir automáticamente el valor de una transacción entre diferentes destinatarios en el momento de la autorización o de la captura, dependiendo de la configuración del proveedor. Esta funcionalidad es esencial para marketplaces y operaciones omnichannel.

• Distribución automatizada de pagos: el valor de la transacción se divide automáticamente, garantizando eficiencia y menor riesgo operativo.
• Reducción de costos y complejidad: elimina transferencias manuales, reduce costos administrativos y acelera la conciliación financiera.
• Flexibilidad para diferentes modelos de negocio: facilita operaciones con modelos como marketplace, entrega en casa y dropshipping.

• VTEX Payment Provider Protocol - Help Center
• Secure Proxy - Help Center
• VTEX Master Data - Help Center
• Implementing a Payment Provider - Dev. Portal
• Payment Provider Framework - Dev. Portal
• Split Payouts on Payment Provider Protocol - Dev. Portal
• PCI-DSS - Dev. Portal
• Payment apps - Dev. Portal
• Whats is VTEX IO - Dev. Portal
• Exemplo de integração: payment-provider-example - GitHub
• Developing services on VTEX IO - Learning Center