Payment Provider Protocol es el protocolo de integración entre VTEX y otras empresas que procesan pagos.

Por medio de él, VTEX ofrece un contrato público disponible para todos los proveedores que desean integrarse a nuestra plataforma. Así, los proveedores obtienen mayor autonomía en relación a la integración.

El protocolo cuenta con los siguientes recursos:

• Proceso de homologación online.
• Soporte de pre-autorización (captura de 2 pasos).
• Mecanismo de intento de autorización de pago.
• Soporte para flujo de redireccionamiento de pago (3P).
• Soporte al protocolo OAuth para la autenticación.

Más información sobre el flujo de pago del protocolo se puede encontrar en la sección Flujo del protocolo de pago. Usted puede encontrar referencias a la API del protocolo aquí.

Provider: sistema de pago, gateway o proveedor que procesa pagos.

Payment Provider Protocol: protocolo de integración desarrollado por VTEX.

Conector: nombre del proveedor asociado de integración con VTEX.

Oauth: protocolo de autorización para API web diseñado para permitir que las aplicaciones de cliente tengan acceso a un recurso protegido en nombre de un usuario.

Adquirente: empresa especializada en procesar pagos. Se encarga de transferir a la cuenta de tu tienda los valores cobrados al cliente por el banco emisor.

La implementación, publicación y actualización de un conector de pagos en VTEX requiere la celebración un contrato de asociación específico para servicios financieros que cubra los detalles del tema y las regulaciones dentro de la plataforma. Si aún no tienes un contrato de colaboración, pero estás interesado en convertirte en proveedor de pagos, ponte en contacto con nuestro equipo a través de nuestro sitio web.

Para publicar un conector, necesitas disponer de un entorno VTEX, que solo puedes obtener tras firmar un acuerdo de asociación para servicios financieros. El entorno VTEX es necesario para que puedas publicar, homologar, actualizar y acceder a nuestro soporte para el desarrollo y mantenimiento del conector.

Si el partner es un SI (Service Implementer) que desarrolla integraciones para clientes u otros proveedores de pagos, la cuenta VTEX utilizada debe ser la del proveedor principal del medio de pago y no la de la agencia contratada.

Proveedores de pagos con tarjetas de crédito, débito y cobranded (soluciones sin redirect)

Para ser un proveedor VTEX integrado, debes usar una de las siguientes soluciones:

• La infraestructura donde estará el conector debe contar con un certificado PCI-DSS firmado por un asesor de seguridad calificado o QSA (Qualified Security Assessor, por sus siglas en inglés). Más información sobre el Consejo de normas de seguridad de PCI.
• Si no tienes el certificado, puedes implementar al proveedor usando el Secure Proxy.

Si el proveedor se ha certificado o ha iniciado el proceso de certificación, puede ponerse en contacto con el equipo comercial de VTEX para iniciar la integración.

El proveedor debe enviar el AOC (Attestation of Compliance for Onsite Assessments - Service Provider Version) completamente rellenado a VTEX, observando los siguientes puntos:

• Nombre de la empresa: el campo “URL” (Parte 1a.) debe ser el mismo que el de la empresa que solicita el procedimiento de integración. Si se completa con otro nombre (ejemplo: empresa adquirida por otra), será necesario enviar documentación adicional que acredite la relación entre las empresas, y que la URL del servicio del proveedor fue evaluada por la PCI DSS.
• Firma: documento firmado por el representante de la empresa y por el QSA.
• Fecha de vencimiento: la validez del AOC es de 1 año después de la fecha de firma. No debe reenviarse a VTEX, el AOC emitido hace más de 11 meses, es decir, con menos de 30 días para la fecha de vencimiento.

Los documentos SAQ (Self-Assessment Questionnaire) y AOC (Attestation of Compliance for Onsite Assessments – Merchants Version) no se aceptan en el proceso de integración de VTEX.

Proveedores de pagos offline o tarjeta private label (o tarjetas en general), pero que implican soluciones con redirect

Para estes tipo de proveedores, VTEX no requiere comprobación de certificación PCI DSS. Sólo tienes que ponerse en contacto con el equipo comercial de VTEX para iniciar la integración.

A continuación, vamos a presentar paso a paso las informaciones referentes a la integración de pagos con VTEX.

Antes de configurar el ambiente VTEX, el proveedor debe implementar el servicio de back-end necesario para recibir y procesar los pagos (API). Más información sobre el flujo de pago del protocolo se puede encontrar en la sección Flujo del protocolo de pago. Usted puede encontrar referencias a la API del protocolo aquí.

Hay casos en que se pueden crear conectores para atender alguna solución específica. A continuación, se presentan las referencias de nuestra documentación que contienen información sobre estos casos:

• Payment Provider Framework (PPF): es una solución para la implementación de conectores a través de VTEX IO con base en un boilerplate. El boilerplate ya viene con una gran parte del trabajo realizado, incluyendo los endpoints del protocolo. La utilización de VTEX IO también acelera el proceso de desarrollo y pruebas de la tienda.

• Payment Provider Protocol (PPP) aplicado a los pagos con POS: es la aplicación del PPP a pagos en tiendas físicas utilizando un terminal de pago (POS). Se puede utilizar con tarjetas de crédito o débito. El flujo del pago se inicia con una compra realizada en inStore, después de lo cual se establece la comunicación con el POS, donde el cliente inserta la tarjeta.

Después de recibir los datos de acceso e implementar el backend, el proveedor debe instalar la aplicación Payment Provider Test Suite para acceder a la herramienta de pruebas. La instalación se realiza a través de la VTEX App Store.

Para completar el proceso de homologación, se debe implementar una lógica específica para abordar los requisitos de la prueba. En los requests enviados a Test Suite, utiliza el encabezado adicional X-VTEX-API-Is-TestSuite = true para identificarlos y enmascarar cualquier escenario requerido.

Toda comunicación con los servidores, ya sea durante el proceso de homologación o en producción, debe llevarse a cabo a través de HTTPS, que utiliza el puerto 443 de forma predeterminada. Es importante recordar que toda comunicación HTTPS debe usar exclusivamente TLS 1.2.

Tras la instalación, haz clic en Apps, en el panel lateral izquierdo del Admin. A continuación, selecciona la aplicación Payment Provider Test Suite para configurarla correctamente.

Dependiendo de la versión del Admin utilizada en la cuenta de la tienda, la aplicación estará disponible en la lista de aplicaciones. Para acceder a ella, utiliza la dirección https://{{accountName}}.myvtex.com/admin/test-suite/payment-provider, sustituyendo {{accountName}} por el nombre de cuenta de tu tienda.

Luego, verás un formulario que tiene tres secciones: Información de servicio, Medio de pago y Casos de prueba. Rellena los campos según las instrucciones a continuación.

Información de servicio

• URL de servicio: define la URL del servicio de tu proveedor. Esta URL será la dirección base del protocolo y debe seguir el formato determinado por el proveedor. Por ejemplo, si la URL del servicio es https://example.com/, la URL completa del endpoint /payments será https://example.com/payments.
• Clave de aplicación y token de aplicación: el botón de alternancia con clave de aplicación y token de aplicación te permite escoger si se configuran estos campos o no, lo que puede facilitar las pruebas durante la etapa de desarrollo. Si no se activa esta opción, las credenciales se enviarán en los encabezados como una string vacía.

El gateway almacena las credenciales de las tiendas configuradas en la afiliación y las envía en los encabezados X-VTEX-API-AppKey y X-VTEX-API-AppToken. La excepción son las integraciones desarrolladas con VTEX IO, en cuyo caso, los encabezados se envían como x-provider-api-appKey y x-provider-api-appToken. Si estás desarrollando usando Payment Provider Framework (IO), esto lo define la opción usesProviderHeadersName. Consulta los ajustes disponibles aquí.

Medio de pago

Después de rellenar URL de servicio, Test Suite validará el Endpoint Manifest y verificará los medios de pago declarados, que aparecerán en este campo. Selecciona los medios de pago en los que deseas ejecutar las pruebas.

Casos de prueba

En esta sección, debes seleccionar los casos que deseas probar. Si estás probando un medio de tarjeta de crédito, tu integración debe pasar los casos Aprobado, Denegado, Cancelación, Aprobado asíncrono y Denegado asíncrono. Los medios de pago con redirección solo necesitan el Flujo de redirección.

Cuando haces clic en el botón Ejecutar prueba, Test Suite llama la URL de servicio proporcionada y ejecuta los casos de prueba seleccionados. Las pruebas son:

• Flujo aprobado: esta prueba se divide en tres etapas. En la primera, se envía un request Create Payment a {{ServiceURL}}/payments y se espera el status aprobado como respuesta. En la segunda, se envía un request Settle Payment a {{ServiceURL}}/payments/{paymentId}/settlements y se espera la respuesta con el settleId rellenado. Y en la última, se envía un request Refund Payment a {{ServiceURL}}/payments/{paymentId}/refunds y se espera una respuesta con refundId rellenado.
• Flujo denegado: en esta prueba, se envía un request Create Payment a {{ServiceURL}}/payments y se espera el status denegado como respuesta.
• Flujo de cancelación: para esta prueba, primero se necesita el status approved como respuesta del request Create Payment de {{ServiceURL}}/payments. Luego, se envía un request Cancel Payment a {{ServiceURL}}/payments/{paymentId}/cancellations y se espera una respuesta con el status cancelado.
• Flujo aprobado asíncrono: esta prueba se divide en dos pasos. Primero, se envía un request Create Payment a {{ServiceURL}}/payments y se espera el status undefined como respuesta. Después de 15 segundos, se espera otra respuesta en el mismo formato mediante un POST de la URL enviada en el campo callbackUrl y con el status approved. Con la integración en producción, esta última llamada realizada por callbackUrl se autentica con las claves de entorno del partner: vtex-app-key y vtex-app-token. Para más información sobre el flujo de callback consulta la sección Autorización del pago.
• Flujo denegado asíncrono: como la anterior, esta prueba se divide en dos pasos. Primero, se envía un request Create Payment a {{ServiceURL}}/payments y se espera el status undefined como respuesta. Después de 15 segundos, se espera otra respuesta en el mismo formato mediante un POST de la URL enviada en el campo callbackUrl y con el status denied. Con la integración producción, esta última llamada realizada por callbackUrl se autentica con las claves de entorno del partner: vtex-app-key y vtex-app-token. Para más información sobre el flujo de callback consulta la sección Autorización del pago.
• Flujo de boleto: en esta prueba, se envía un request Create Payment a {{ServiceURL}}/payments y se espera una respuesta con status undefined y el campo bankIssueInvoiceUrl rellenado con la URL del ticket. Después de 15 segundos, se espera otra respuesta en el mismo formato mediante un POST de la URL enviada en el campo callbackUrl y con el status approved. Con la integración en producción, esta última llamada realizada por callbackUrl se autentica con las claves de entorno del partner: vtex-app-key y vtex-app-token. Para más información sobre el flujo de callback consulta la sección Autorización del pago.
• Flujo de redirección: esta prueba se divide en dos pasos. Primero, se envía un request Create Payment a {{ServiceURL}}/payments y se espera una respuesta con status undefined y el campo redirectUrl rellenado con la URL que se utilizará para redirigir al cliente. Después de 15 segundos, se espera otra respuesta en el mismo formato mediante un POST de la URL enviada en el campo callbackUrl y con el status approved. Con la integración en producción, esta última llamada realizada por callbackUrl se autentica con las claves de entorno del partner: vtex-app-key y vtex-app-token. Para más información sobre el flujo de callback consulta la sección Autorización del pago. El conector que utilizará redirección no tiene que pasar todas las pruebas de Test Suite, solo la prueba de Redirección.

En el caso de las tarjetas de crédito, las pruebas obligatorias son: Autorizar, Denegado, Cancelar, Aprobado asíncrono y Denegado asíncrono.

Para identificar cómo responder a cada una de las pruebas con tarjetas de crédito, utiliza los siguientes números específicos:

Número de tarjeta	Status de la respuesta
4444333322221111	approved
4444333322221112	denied
4222222222222224	undefined, callbackUrl con status approved
4222222222222225	undefined, callbackUrl con status denied

Después de ejecutar las pruebas, el sistema mostrará el Informe de prueba que presenta los resultados detallados de cada caso de prueba. De este modo, tendrás más visibilidad sobre lo que debes ajustar si se produce un error.

Para ver los mensajes transmitidos entre Test Suite y la implementación de tu proveedor de pagos, haz clic en el botón Inspeccionar logs. Se abrirá una ventana modal que muestra la lista de mensajes transmitidos y la carga de cada request y respuesta. El botón situado en la esquina superior derecha de la sección de código facilita la copia del código al portapapeles.

Aquí vamos a explicar el flujo de pago integrado en detalle. La siguiente imagen muestra todo el flujo, mostrando VTEX Payments y las responsabilidades de su proveedor.

Todo comienza con la solicitud de un nuevo pago, después de la creación de un nuevo pedido. VTEX crea una nueva representación del pago y avanza para el procesamiento de los pagos.

El período predeterminado de 7 días para reintentos (retries) de pago asíncronos solo se aplica cuando el usuario no especifica un valor en el campo delayToCancel del endpoint Create Payment o al enviar la URL de devolución de llamada.

El valor máximo permitido para el campo delayToCancel es 30 días (2592000 segundos).

En este punto, VTEX llama al endpoint /payments y envía un payload con los datos de pago para su proveedor. El proveedor debe procesar estos datos y enviar la respuesta, que debe contener uno de los valores de status: approved, denied o undefined.

El status undefined representa el estado en el que el proveedor no pudo terminar de procesar el pago. Esto puede deberse a una larga ejecución de procesamiento o a algún procesamiento asincrónico.

En cualquiera de los casos, una vez que termine el procesamiento y el proveedor tenga un status final (approved or denied), deberá hacer una llamada a nuestro callbackUrl. Enviamos el callbackUrl en el cuerpo del request /payments. Hay dos flujos posibles al usar callbackUrl dependiendo de si tu integración está hospedada en la infraestructura del partner o en VTEX IO:

• Sin VTEX IO: El callbackUrl contiene un endpoint de callback para que el proveedor notifique al gateway el status actualizado.
• Con VTEX IO: El callbackUrl contiene un endpoint de reintento (retry). Cuando el proveedor utiliza este endpoint para llamar al gateway, se produce una nueva solicitud de Create Payment (/payments) del gateway al proveedor, y el gateway recibe el status de pago actualizado en respuesta a esta solicitud.

El flujo completo con status undefined y uso de notificación se puede ver a continuación:

1. La autorización del pago se inicia cuando el gateway hace una llamada al endpoint Create Payment (/payment) para el proveedor. El campo callbackUrl se envía dentro del cuerpo del request y contiene la URL para hacer la notificación.
2. El pago se produce de forma asíncrona (no genera el status definitivo cuando se inicia la transacción). A continuación, el gateway recibe la respuesta con status undefined y espera a que se complete el procesamiento del pago. Más adelante, el pago se completará y el gateway recibirá el status definitivo (approved o denied).
3. Cuando se procesa el pago, el adquirente activa un webhook al proveedor con el nuevo status.
4. El proveedor, al recibir el pedido por webhook, hace una llamada al endpoint de notificación y devuelve el status actualizado al gateway.

El flujo completo con status undefined y uso del retry se puede ver a continuación:

1. La autorización del pago se inicia cuando el gateway hace una llamada al endpoint Create Payment (/payment) para el proveedor. El campo callbackUrl se envía dentro del cuerpo del request y contiene la URL del endpoint retry.
2. El pago se produce de forma asíncrona (no genera el status definitivo cuando se inicia la transacción). A continuación, el gateway recibe la respuesta con status undefined y espera a que se complete el procesamiento del pago. Más adelante, el pago se completará y el gateway recibirá el status definitivo (approved o denied).
3. Cuando se procesa el pago, el adquirente activa un webhook al proveedor con el nuevo status.
4. El proveedor, al recibir el pedido por webhook, hace una llamada al endpoint retry para el gateway, indicándo le que llame de nuevo al endpoint /payment. El retry no requiere ninguna carga.
5. Después de recibir el retry, el gateway llama de nuevo al endpoint /payment. Finalmente, el gateway recibe la respuesta del proveedor con el nuevo status (approved o denied).

El campo callbackUrl contiene una URL que el proveedor de pagos utiliza para realizar un callback y notificar a nuestro gateway el status final del pago: aprobado o denegado.

Esta URL tiene algunos parámetros de consulta, incluyendo X-VTEX signature. Este parámetro es obligatorio y contiene un token de firma para indicar que el request ha sido generado por VTEX como una medida de seguridad. El token de firma tiene como máximo 32 caracteres. Puedes ver un ejemplo de una URL de callback con el token de firma a continuación:

En la página de Transacciones del Admin, el token de firma se muestra enmascarado por razones de seguridad, como en este ejemplo: X-VTEX-signature=Rj******tk.

Vea a continuación, um ejemplo de payload enviada junto con la callback URL:

Los valores de los parámetros enviados en el payload de callback reemplazan los valores originales informados en la llamada de Create Payment.

Si los parámetros de tiempo de espera (delayToAutoSettle e delayToAutoSettleAfterAntifraud) no se envían con la URL de devolución de llamada, los valores se establecerán automáticamente en 24 horas.

Al realizar el request de callback, recomendamos que los proveedores de pago utilicen la URL de callback exactamente como la recibieron, lo que garantiza que se incluyan todos los parámetros.

Al llamar a CallbackURL, su proveedor debe enviar en el request los headers X-VTEX-API-AppKey y X-VTEX-API-AppToken. Más información sobre esto en la sección de credenciales VTEX.

Además de CallbackURL, si el status es undefined, VTEX intentará de nuevo llamar al endpoint de la autorización de pago. Si el status devuelto en estas llamadas permanece como undefined, las llamadas continuarán por 7 días. Por lo tanto, es importante que su proveedor esté preparado para recibir la misma autorización de pago varias veces.

Una vez que el pago ha sido procesado por su proveedor, de forma directa o asincrónica, movemos la transacción de pago dentro de VTEX al status autorizado o cancelado, de acuerdo con el status de la respuesta del procesamiento.

Más referencias a la API de autorización aquí.

Después de la primera llamada a la autorización de pago, la tienda puede Después de la primera llamada para la autorización de pago, la tienda puede cancelar el pedido en cualquier momento. En el momento de la cancelación, pueden ocurrir las siguientes situaciones:

1. La transacción de pago ya ha sido liquidada: la solicitud de cancelación resultará en una llamada de reembolso al endpoint del proveedor /payments/{id}/refunds, donde {id} representa el ID de pago en VTEX.
2. La transacción de pago aún no se ha liquidado: llamaremos al endpoint del proveedor /payments/{id}/cancellations, donde {id} es el ID de pago en VTEX. Si existe alguna dificultad para procesar la cancelación automática, se enviará un correo electrónico al comerciante para que pueda cancelarla manualmente.

El Payment Provider Protocol también permite reembolsos parciales. Por ejemplo, si después de completar una compra por valor de USD 1,000, es necesario reembolsar al cliente por valor de USD 300, son posibles dos escenarios:

1. El pago ya ha sido liquidado: se realizará un reembolso parcial de USD 300 al cliente. El valor restante (USD 700) queda a disposición del comerciante.
2. El pago aún no ha sido liquidado: se hará al comerciante una cancelación de captura por el valor de USD 300 y una aprobación de liquidación parcial por el valor de USD 700.

Más información acerca de la API de cancelación y reembolso aquí.

Si la transacción de pago está autorizada en VTEX Payments, puede recibir solicitudes de liquidación. Cuando recibimos una solicitud de liquidación, llamamos al endpoint /payments/{id}/settlements del proveedor, donde {id} es el ID de pago en VTEX.

Cuando el proveedor recibe una solicitud de liquidación, debe liquidar el pago y responder con información de liquidación. Si esta llamada falla, hacemos algunas retentaciones, por hasta 1 día.

Su proveedor debe estar preparado para recibir la misma llamada de liquidación varias veces.

Si la llamada de liquidación funciona bien, movemos la transacción de pago al estado Finalizado, y el flujo termina con éxito.

Más información acerca de la API de liquidación aquí.

Al llamar a CallbackURL, usted debe especificar los headers de autenticación, que en VTEX son X-VTEX-API-AppKey y X-VTEX-API-AppToken. Puede encontrar estas credenciales (que son únicas para su cuenta) en el módulo License Manager de VTEX.

Utilice la URL https://{{AccountName}}.myvtex.com/admin/license-manager/#/home, sustituyendo el {{AccountName}} por su nombre de cuenta. Entonces, siga las instrucciones de este tutorial para aprender a crear appKeys y appTokens.