Integración de la HPP

Esta página describe cómo utilizar la API de REST de la página de pago alojada para incorporar la HPP a su aplicación web. En los siguientes pasos, se explica cómo implementar la página de pago alojada como parte de su tienda en línea:

Cuando su cliente esté listo para finalizar la compra, recopile cualquier información adicional necesaria para la solicitud de OrderCreate.
Envíe una solicitud POST al punto final OrderCreate de la API de REST de la HPP que incluya los datos del cliente, del carrito de compras y de referencia en el cuerpo de la solicitud.

Asegúrese de incluir los siguientes campos en la solicitud de OrderCreate:
- PartnerTransactionID: Su identificador único para la transacción. Vesta utiliza el valor que usted configuró para el PartnerTransactionID a fin de identificar la transacción al devolver los resultados.
- EmailAddress: La dirección de correo electrónico del cliente. Si incluye una dirección de correo electrónico, Vesta la utiliza para enviar un recibo.
Para redirigir a su cliente a la página de pago, envíe los siguientes campos adicionales en la solicitud de CreateOrder:
- IsIframe: Un entero que notifica a Vesta si redirigirás a tu cliente a la URL de la página de pago:
  - 0: Redirigirá a su cliente a la URL de la página de pago y mostrará la HPP como una página completa.
  - 1: Mostrará la HPP en un iFrame incrustado en su página de finalización de la compra. 1 es el valor predeterminado del campo IsIframe.
- RedirectURL: La URL de su página de confirmación de pago. Vesta redirigirá a su cliente a esta URL luego de procesar el pago. Vesta también enviará un POST de la TransactionID del pago a esta URL, que usted puede utilizar para obtener los resultados de la transacción.
  
  Nota: Para ofrecer Apple Pay como una opción de pago, debe mostrar la HPP como una página completa utilizando una redirección. La opción de Apple Pay no se puede ofrecer cuando se muestra la página de pago en un iFrame.
Utilice el campo HPPMode para habilitar los pagos en varios pasos. Si se activan los pagos en varios pasos, el usuario puede añadir o editar la información de la dirección directamente en el formulario. Cualquier información sobre la dirección que incluya en el cuerpo de la solicitud de OrderCreate se rellenará previamente en el formulario. Configure el campo HPPMode en uno de los siguientes valores para habilitar/deshabilitar el ingreso de la dirección de facturación/envío en el formulario de pago:
- "1" - Un solo paso: El usuario introduce la información de pago.
- "2" - Bienes digitales en varios pasos: El usuario introduce la información de pago y puede añadir o editar la información sobre la dirección de facturación.
- "3" - Bienes físicos en varios pasos: El usuario introduce la información de pago y puede agregar o editar la información de la dirección de facturación o de envío. Esta función estará disponible pronto.
Para utilizar la función de Confirmaciones de pagos diferidos, configure el valor del campo AutoDisposition (Autodeterminación) en 0 en la solicitud CreateOrder. Si no envía el campo AutoDisposition o si configura el valor en 1, Vesta confirmará automáticamente la transacción.

Para especificar un idioma de visualización en la página de pago, configure un valor para el campo LocaleCode en el cuerpo de la solicitud. LocaleCode acepta los códigos de idioma de ISO 639-1 como cadenas (por ejemplo, "en-US" y "es"). La función de localización actualmente es compatible con los idiomas inglés y español de Estados Unidos. Si no configura un valor para LocaleCode, el idioma de visualización se establece utilizando la configuración del navegador del cliente. Si envía un valor inválido, el idioma de visualización se ajustará al valor predeterminado: Inglés de Estados Unidos.

El recurso OrderCreate devuelve un mensaje de éxito o de error para avisarle si se puede mostrar la página de pago. Si el recurso devuelve un mensaje de éxito, se incluirá una URL para la página de pago en la respuesta.

Muestre la página de pago utilizando uno de los siguientes métodos:

iFrame: Agregue un iFrame a su página de finalización de la compra que carga la URL de la página de pago devuelta por el recurso OrderCreate.
Redirect: Redirija el navegador de su cliente a la URL devuelta por el recurso OrderCreate.

Su cliente introduce la información de pago en la HPP.

Si su cliente actualiza la información de facturación o envío en el formulario de pago, Vesta solicitará el importe del impuesto actualizado desde su aplicación. Vesta envía una solicitud POST a la URL del webhook de recuperación del impuesto que definió en vPortal con los siguientes campos en el cuerpo:

ShoppingCartID: El ShoppingCartID que especificó en la solicitud OrderCreate.
Country: El código de país de dos dígitos asociado a la nueva dirección.
Region: El nombre actualizado de la región o estado.
Password: La contraseña que introdujo cuando configuró la URL del webhook de recuperación del impuesto en vPortal.

Su aplicación debería calcular y devolver el nuevo importe del impuesto o enviar un mensaje de error como se muestra en los siguientes ejemplos:

Nuevo importe del impuesto - Si la solicitud es exitosa y el tipo de respuesta HTTP es 200, envíe el nuevo importe del impuesto en el cuerpo de la respuesta como se muestra a continuación:
```
{
    "TaxAmount" : "10.57"
}
```
Error - Si la solicitud no es exitosa, si hay un error en el cálculo del impuesto o si el tipo de respuesta HTTP es diferente a 200, envíe un mensaje de error en el cuerpo de la respuesta como se muestra a continuación:
```
{
    "Message" : "Country Not Supported"
}
```

En la siguiente tabla, se definen los mensajes de error permitidos:

Código de error de HTTP	Mensaje de error	Descripción
400 (Bad Request)	País no admitido	País no es válido o no se admite en la calculadora del impuesto.
400 (Bad Request)	Región no admitida	Región o el estado no son válidos o no se admiten.
401	Acceso no autorizado	Falta la contraseña o es incorrecta.
403	Prohibido	El sistema que hace la solicitud no tiene permiso para acceder al recurso.
404 (Not Found)	Carrito de compras no encontrado	La identificación del carrito de compras no se pudo encontrar.
500	Error interno del servidor	El servidor está mal configurado.

Vesta utilizará su respuesta para actualizar el formulario de pago y el total de la transacción, y su cliente puede proceder a introducir la información de pago si es necesario.

Cuando su cliente envía los datos del pago, Vesta analiza la transacción y la envía para su procesamiento. En las regiones en las que es obligatorio, o si su negocio exige una verificación adicional de la identidad, Vesta lleva a cabo la Autenticación segura de clientes enviando la transacción para su autenticación a 3DSecure. Para las pocas transacciones que requieren una prueba de identidad, se le pide al titular de la tarjeta que introduzca un código de acceso único.

Vesta envía los resultados de la transacción con el método POST a la URL del webhook que usted definió en la configuración. Si ha utilizado una redirección para mostrar la página de pago, Vesta también publica los resultados en la RedirectURL que usted especificó en la solicitud de OrderCreate.

Capte los resultados de la transacción. El cuerpo del mensaje incluirá un campo de TransactionID que se rellenará con el valor que usted configuró en el campo PartnerTransactionID en el cuerpo de la solicitud de OrderCreate. El cuerpo también incluirá un campo de PaymentStatus que define el estado de la transacción.

NOTA: Si el envío a su webhook falla por cualquier motivo, puede obtener los resultados de la transacción enviando una solicitud de POST al punto final OrderStatusGet de la API de HPP con la información de la cuenta y el identificador de la transacción en el cuerpo de la solicitud.
Una vez completado el procesamiento de la transacción, Vesta devuelve al cliente a su sitio mediante uno de los siguientes métodos:
- iFrame: Si mostró la página de pago utilizando un iFrame, puede redirigir a su cliente a una página de tu aplicación que notifique al cliente sobre el estado de la transacción.
- Redirect: Si ha mostrado la página de pago utilizando una redirección, Vesta redirige al cliente a la RedirectURL que usted especificó en la solicitud de OrderCreate.
Muestra una página que notifique a su cliente los resultados de la transacción, que obtuvo en el paso 4, y completa el procesamiento del pedido utilizando su proceso habitual.

Una vez completada la transacción, los resultados estarán disponibles en vPortal para fines de revisión y generación de informes.