- Pautas de integración
- Implementación de una integración de Hosted Payment Session
- El modelo de Hosted Payment Session con JavaScript
El modelo de Hosted Payment Session con JavaScript
El modelo de Hosted Payment Session con JavaScript(HPF.js) es una integración simple que reduce al mínimo las interacciones entre su servidor web y Mastercard Gateway mediante una biblioteca JavaScript del lado cliente, que usted debe incluir en la página de pago y acceder a ella mediante el método HostedForm.updateSession( ). Los detalles de tarjeta del pagador se envían al Mastercard Gateway en el método de HostedForm.updateSession( ) al que se llama cuando el pagador hace clic en "Pagar" para enviar la página de pago.
Mejores prácticas y consejos
Es importante asegurarse de que los campos de pago confidenciales no se envíen a su servidor. Por ejemplo, si está utilizando un formulario de pago, puede lograrlo omitiendo el atributo "nombre" de los campos número de tarjeta, vencimiento de la tarjeta y CSC/CVV.
Usted no puede usar el modelo de Hosted Payment Session con JavaScript si el explorador del pagador no es compatible con JavaScript.
Flujo de información de HPF.js
El flujo de pago detallado para el modelo HPF.js se ilustra a continuación.
- Muestre una página de pago al pagador en espera de los detalles de la tarjeta y otra información requerida como entrada. La página de pago:
- Debe incluir la biblioteca hpf.js, a la que se accede llamando al método HostedForm.updateSession( ).
- debe incluir el método de HostedForm.setMerchant( ) para configurar el identificador para su cuenta de negocio con Mastercard Gateway.
- Debe contener campos de tarjeta (número de tarjeta, código de seguridad, mes de vencimiento y año de vencimiento) que debe capturar del pagador.
- Puede contener campos adicionales que quizás desee capturar en esta etapa. Por ejemplo, Dirección de envío, Número de comprobante, etc.
- Puede diseñarse según sus necesidades.
Consulte Cree su integración.
Esta página solo se utiliza para recopilar 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 "Pagar" en su sitio web, que llama al método HostedForm.createSession( ). Los datos de la tarjeta recopilados a través de la página de pago se pasan mediante el método HostedForm.createSession( ).
Mastercard Gateway recopila, verifica (mediante verificación básica) y sanea los detalles de tarjeta (datos de número y vencimiento de tarjeta, y CSC/CVV) antes de agregar estos detalles a la sesión.
- Mastercard Gateway devuelve la respuesta a la llamada HostedForm.createSession( ) usando una función de devolución de llamada que usted proporciona.
- Su sitio web analiza cualquier error devuelto por el Mastercard Gateway y vuelve a mostrar la página de pago si se encuentra algún error.
- Su sitio web envía el identificador de sesión devuelto a su servidor web.
Puede optar por mostrar más páginas al pagador según el flujo de trabajo de su negocio o realizar una transacción de almacenamiento o pago en el momento de recopilar los datos de la tarjeta.
- Usted inicia una solicitud a Mastercard Gateway al especificar los campos obligatorios que usan una o más de las siguientes operaciones de API: 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.
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. - Mastercard Gateway le envía el resultado de la solicitud de vuelta. Puede realizar operaciones posteriores utilizando el identificador de sesión antes de que la sesión expire.
- Usted muestra el resultado de la transacción al pagador en su sitio web.
Si usted tiene su propia página de pago, entonces puede seleccionar esta opción para que Mastercard Gateway maneje los detalles de la inclusión de SDK de Visa Checkout, el lanzamiento del lightbox de Visa Checkout y la actualización de los resultados en una sesión de pago. Esta es la opción más sencilla para integraciones existentes Hosted Payment Session (con JavaScript).
El flujo de pago es el siguiente:
- Muestre una página de pago al pagador, según se requiera, para la Hosted Payment Session con integración de JavaScript. Su página de pago debe incluir una forma de identificar Visa Checkout como la opción de pago seleccionada por el pagador.
El siguiente es un ejemplo de código que indica cómo mostrar Visa Checkout como opción en la página de pago.
<script id="hpfScript" src="https://ap-gateway.mastercard.com/form/v3/hpf.js"></script>
<!-- REPLACE THE action URL with the payment URL on your webserver -->
<form name="myform" method="POST" action="https://my.company.com/pay">
<!-- Other fields can be added to enable you to collect additional data on the payment page -->
Email: <input type="text" name="email">
<!-- The hidden values below can be set in the callback function as they are returned when creating the session -->
<input type="hidden" name="sessionId" id="sessionId">
<img alt="Visa Checkout" role="button" src="https://sandbox.www.v.me/wallet-services-web/xo/button.png" onclick="showVisaCheckoutLightbox()"/>
</form> - Cuando el pagador selecciona Visa Checkout, la página de pago inicia el lightbox de Visa Checkout con las opciones necesarias. Cuando finalice la interacción con el lightbox, hpf.js utiliza automáticamente el callId que el lightbox devuelve para recuperar los detalles de pago desde Visa Checkout. El resultado de la interacción se devuelve en la función de devolución de llamada — si la interacción se realizó correctamente, los detalles de pago se completan en la sesión de pago.
El siguiente es un ejemplo de código que le muestra cómo invocar el método HostedForm.showVisaCheckout( ) para iniciar el lightbox de Visa Checkout con las opciones necesarias y completar los detalles de interacción de Visa Checkout en una sesión de pago.
<script>
var options = {
acceptedCards: [
"MASTERCARD",
"AMEX",
"DISCOVER",
"VISA"
],
order: {
currency: "AUD",
amount: 10.50
},
merchant: {
logo: "https://test.te",
displayName: "your merchant"
},
country: "AUS",
locale: "en_AU",
paymentConfirmation: "CONFIRM_AT_PROVIDER"
paymentConfirmationMessage: "Continue to the merchant to complete your purchase"
};
function showVisaCheckoutLightbox() {
if (typeof HostedForm === 'undefined') {
throw 'hpf.js is not loaded';
}HostedForm.setMerchant("MERCHANT_ID"); //Replace with your merchant id
HostedForm.showVisaCheckout(options,
callback);
}</script> - La función de devolución de llamada de JavaScript maneja la respuesta de interacción de Visa Checkout a través de un objeto que describe el resultado de la llamada
HostedForm.showVisaCheckout( ). Debe definir esta función de devolución de llamada en su página de pago.Si
response.status="ok", su página web debe transmitir el identificador de sesión devuelto a su servidor web para que se pueda usar para invocar una operación que haga referencia a la sesión.El siguiente es un ejemplo de código que muestra cómo definir la función de devolución de llamada en la página de pago, que se envía a su servidor web.
var callback = function(response) {
if (response.status === "ok") {
// call your server to do the payment with the response.session value
// this is where we populate the hidden values in the form
var sessionIdElement = document.getElementById("sessionId");
sessionIdElement.value = response.session;
document.myform.submit();
}else if (response.status === "request_timeout") {
// handle the timeout for example by giving the payer the possibility to retry
}else if (response.status === "invalid_session") {
// handle invalid session details for example by giving the payer the possibility to retry with different card details. If the new details are correct,
you can call the updateSession( ) method
}else if (response.status === "cancelled") {
// handler code for the case when the user closes the Visa Checkout lightbox without selecting a credit card
}else {
// add system error handling here. Typically this would mean the integration is not working properly because there is no response from the client library.
// this could result in displaying a page to the payer to try again later and call support
}
}; - Ahora puede utilizar el identificador de sesión de pago para realizar cualquier operación en la que una sesión de pago pueda proporcionar los detalles de pago, por ejemplo, solicitudes de Authorize, Pay y Tokenize. Tenga en cuenta que los detalles de la tarjeta se pueden proporcionar utilizando múltiples fuentes de detalles de la tarjeta.
Solución de problemas y preguntas frecuentes
Si actualiza la sesión usando el método HostedForm.updateSession( ), puede realizar una transacción Pay con sesión usando SOLO API v30. Si está integrado con API v29 o menos, debe actualizar su integración a v30.
El formulario de pago puede arrojar varios tipos de errores. Consulte Manejo de errores.
Su página de pago puede contener campos definidos por el negocio para recopilar información adicional, por ejemplo, un código de cupón de descuento, identificador de programa de lealtad, dirección de envío, método de envío, etc. Sin embargo, si traspasa esta información en el método de HostedForm.updateSession( ), se ignorará.
Sí, puede llamar al método de HostedForm.createSession( ) varias veces —; cada vez que llama al método HostedForm.createSession( ) se crea una nueva sesión.