- Pautas de integración
- Implementación de una integración de Hosted Payment Session
- El modelo POST de Hosted Payment Session
El modelo POST de Hosted Payment Session
Este modelo de Hosted Payment Session requiere crear código de integración del lado del servidor para obtener un token de sesión de Mastercard Gateway, para usar el identificador de token de sesión devuelto para crear el formulario que debe mostrar la página de pago y para analizar la respuesta del formulario de Mastercard Gateway.
Mejores prácticas y consejos
Hosted Payment Session siempre devuelve el campo "gatewayFormResponse", independientemente de si se incluyó como un campo posterior al formulario. Algunos marcos web pueden generar errores o restringir el acceso a este campo en este escenario. Si está usando un Marco web que requiere que los campos posteriores al formulario coincidan con aquellos del formulario presentado originalmente, debe asegurarse de que este campo se incluya en el formulario.
No incluya el identificador de sesión como campo oculto al crear el formulario de pago. Este campo solo debe incluirse en la URL del formulario. Si desea almacenarlo en otras páginas como referencia, entonces es más apropiado almacenarlo en una sesión HTTP.
Restringir la longitud de los campos de entrada del formulario se considera una mejor práctica y ayudará a mantener la integridad de los datos. En algunos casos, los datos enviados pueden resultar truncados por Hosted Payment Session si las longitudes de campo no se restringen.
Los nombres de los campos pueden tener prefijos, pero deben terminar con nombres de campos reconocidos como se define en Referencia de campos de formulario. Por ejemplo, "ctl00$MainContent$gatewayCardNumber" es un nombre de campo válido y se tratará exactamente igual que un campo llamado "gatewayCardNumber". Esto es particularmente beneficioso para los integradores que utilizan una plataforma .Net.
Las sesiones HTTP (que no deben confundirse con sesiones de pago) se utilizan a menudo para realizar un seguimiento de los datos del pagador, por ejemplo, la información del carrito de compras, durante la interacción del pagador con un sitio web.
El método más común para mantener las sesiones es mediante el uso de cookies. Tenga presente que si las cookies no se habilitan en el explorador del pagador (o en su servidor web), es posible que además deba admitir la reconfiguración de la URL para mantener la sesión HTTP en una cookie. Consulte la documentación del marco web elegido para obtener más detalles.
Para asegurarse de que Hosted Payment Session administra correctamente caracteres codificados con un conjunto de caracteres diferente del ISO-8859-1 predeterminado, deberá especificar un parámetro de consulta "charset" en la URL de formulario. Por ejemplo, para especificar que el formulario enviado está codificado con el juego de caracteres UTF-8, la URL del formulario sería similar a:
https://na-gateway.mastercard.com/form/<formSessionIdentifier>?charset=UTF-8
Esto también garantizará que la respuesta esté codificada correctamente. Los conjuntos de caracteres compatibles se pueden encontrar aquí.
Maneje los navegadores que tienen JavaScript deshabilitado personalizando la página "Continuar". Cuando un explorador tiene JavaScript deshabilitado, al pagador se le mostrará una página que requiere que haga clic en un botón para ser redirigido de vuelta a su sitio. Los siguientes atributos de esta página son personalizables:
- El título de la página se puede personalizar/internacionalizar al especificar un valor para el campo "gatewayRedirectDisplayTitle".
- El texto del botón se puede personalizar/internacionalizar especificando un valor para el campo "gatewayRedirectDisplayContinueButtonText".
- El color de fondo se puede personalizar/internacionalizar especificando un valor para el campo "gatewayRedirectDisplayBackgroundColor".
Se aplicarán los valores predeterminados si no se proporcionan.
Aunque no se requiere estrictamente para la integración con la solución de Hosted Payment Session, cuando los detalles del pagador se publican en Hosted Payment Session en SSL, proporciona los siguientes beneficios:
-
Aumenta la confianza del pagador al mostrar el candado del explorador
-
Evita que el pagador vea una ventana emergente de advertencia de seguridad al realizar la transición del Hosted Payment Session sitio seguro a su sitio no seguro. El aviso emergente "Security Warning" (Advertencia de seguridad) le pregunta al pagador si desea continuar con el envío de la información.
Hosted Payment Session flujo de información
A continuación, se ilustra el flujo de pago detallado para el modelo de Hosted Payment Session.
- Usted inicia una llamada de DirectAPI de Mastercard Gateway a Mastercard Gateway mediante la operación
Create Session. Esto crea la sesión, la cual contendrá los detalles de tarjeta del pagador. Consulte Solicitar una sesión a través de DirectAPI. - Mastercard Gateway responde con el identificador de sesión.
- Su sitio crea la página de pago que incluye el formulario de pago.
- El formulario de pago debe incluir los campos admitidos por el Servicio de Hosted Payment Session de Mastercard Gateway que debe capturar de parte del pagador.
- También puede contener campos adicionales que quizás desee capturar en esta etapa. Por ejemplo, Dirección de envío, Número de comprobante, etc.
- El formulario de pago puede tener el estilo que usted requiera.
Consulte Crear un formulario de pago y Referencia de campos de formulario de pago.
- El formulario de pago se muestra al pagador, a la espera de que se ingresen los detalles de la tarjeta y otra información requerida.
Este formulario solo se utiliza para recoger los datos de la tarjeta y no para realizar un pago.
- El pagador ingresa los detalles de la tarjeta y hace clic en el botón “Enviar” de su sitio web, el cual realiza un HTTPS POST en el Servicio de Hosted Payment Session. Debe incrustar el identificador de sesión en el campo de acción de su formulario. Consulte Crear un formulario de pago.
- Mastercard Gateway recopila, verifica (mediante verificación básica) y sanea los detalles de la tarjeta de crédito y envía el formulario validado/modificado de vuelta al explorador. Los detalles de la tarjeta, como los datos de número y vencimiento de la tarjeta, y CSC/CVV se extraen desde el formulario y se agregan a la sesión.
- El formulario validado se envía desde el explorador del pagador utilizando la URL de retorno especificada en la solicitud de Envío de formulario. El formulario validado incluye los campos de solicitud y los campos de respuesta del Servicio de Hosted Payment Session de Mastercard Gateway.
Todo campo específico del negocio que pueda pasar en la solicitud de formulario se devuelve sin ningún procesamiento en la respuesta de formulario.
- Su sitio valida los campos específicos del negocio.
- Su sitio analiza cualquier error devuelto por el Servicio de Hosted Payment Session de Mastercard Gateway y vuelve a mostrar la página de pago si se encuentra algún error.
Cuando se hayan resuelto todos los errores, puede optar por mostrar más páginas al pagador según su flujo de trabajo comercial o realizar una transacción de almacenamiento o pago en el momento de recopilar los detalles de la tarjeta.
Antes de realizar la transacción del pago, puede enviar una solicitud de cotización de tasa para Conversión dinámica de moneda (DCC) para recuperar la moneda del pagador y el monto del pedido en esa moneda.
En esta etapa, también puede autenticar al pagador que usa el Servicio 3-D Secure. Observe que si el pagador acepta la oferta de DCC, entonces debe proporcionar la información de DCC en la solicitud de autenticación. - Realice una llamada de DirectAPI de Mastercard Gateway para iniciar la transacción de pago o almacenamiento, especificando la cantidad de pago (solo para una transacción de pago) mediante una o más de las siguientes acciones: Authorize, Pay, Tokenization. Se pueden proporcionar detalles de tarjeta mediante Diversas fuentes de detalles de tarjeta. Para obtener más información, consulte Realizar una operación con la sesión.
- Mastercard Gateway le envía el resultado de la transacción de vuelta. Puede realizar una transacción Save posterior después de una operación Pay/Authorize antes de que la sesión expire.
Solución de problemas y preguntas frecuentes
El formulario de pago puede arrojar varios tipos de errores. Consulte Manejo de errores.
Se mostrará una página de error cuando se intente enviar un formulario incorrecto. Los siguientes casos darán como resultado que se muestre una página de error:
- El método del formulario no es HTTP POST.
- La URL del formulario tiene un formato incorrecto.
- Se pasa un parámetro de consulta distinto de "charset" en la URL del formulario.
- Se pasa un juego de caracteres no compatible como parámetro de consulta en la URL del formulario.
- No se ha proporcionado el campo obligatorio "gatewayReturnURL".
- El campo obligatorio "gatewayReturnURL" no es una URL absoluta.
- Los nombres de campos reservados se utilizan en el formulario de pago. Actualmente, el único nombre de campo reservado es "submit" (distingue entre mayúsculas y minúsculas), el cual no debe configurarse como el atributo name del botón.
- Se ha enviado un campo reconocido con múltiples valores. Esto suele ocurrir cuando el campo se define más de una vez en el formulario.
Tener un campo con el atributo "name" configurado en "submit" evitará que el formulario se redirija de vuelta al sitio mediante la publicación de JavaScript. Esto se debe a que la publicación mediante JavaScript se hizo con la función form.submit(). Entonces, si hay un elemento de formulario llamado "submit", JavaScript hará referencia incorrectamente al campo en lugar de ejecutar la función. Este es un problema de JavaScript bien conocido que no se puede solucionar fácilmente.
Los campos definidos por el negocio se devuelven en la respuesta de formulario sin ser procesados ni guardados por Hosted Payment Session.
Esto sucede porque el explorador tiene que representar una página HTML antes de ejecutar JavaScript para publicar de vuelta en su sitio. El parpadeo es la visualización de esta página durante un momento increíblemente breve antes de que se ejecute JavaScript. Para asegurar una experiencia sin inconvenientes para el pagador, se recomienda que los atributos que se pueden personalizar de la página "Continuar" estén configurados en valores que mantengan la apariencia y sensación de su sitio. Consulte Mejores prácticas y consejos para obtener detalles sobre cómo personalizar la página "Continuar". Esto también asegurará que los pagadores que no tienen sus exploradores habilitados con JavaScript encuentren una página "Continuar" coherente con el aspecto de su sitio.