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 Payment 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 Payment 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.

Consejos y mejores prácticas

Proteger los campos confidenciales

Es importante asegurarse de que los campos de pago confidenciales no se envíen a su servidor. Por ejemplo, si usa un formulario de pago, puede lograrlo al omitir el atributo “name” de los campos de número de tarjeta, vencimiento de tarjeta y CSC/CVV.

JavaScript deshabilitado en el explorador del pagador

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

A continuación, se ilustra el flujo de pago detallado para el modelo de HPF.js.

Formulario de pago hospedado con modelo de JavaScript

  1. Muestre una página de pago al pagador a la espera de los detalles de tarjeta y otra información necesaria. La página de pago:
    • debe incluir la biblioteca hpf.js, a la que se accede llamando al método de HostedForm.updateSession( ).
    • debe incluir el método de HostedForm.setMerchant( ) para configurar el identificador para su cuenta de negocio con Mastercard Payment Gateway.
    • debe contener los campos de tarjeta (número de tarjeta, código de seguridad, mes y año de vencimiento) que necesita 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 adaptarse según usted lo requiera.

    Consulte Cree su integración.

    Esta página solo se usa para recopilar los detalles de tarjeta y no para realizar un pago.
  2. El pagador ingresa los detalles de tarjeta y hace clic en el botón “Pagar” de su sitio web, el cual llama al método HostedForm.createSession( ). Los detalles de tarjeta recopilados mediante una página de pago se transmiten en el método HostedForm.createSession( ).

    Mastercard Payment 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.

  3. Mastercard Payment Gateway devuelve la respuesta a la llamada a HostedForm.createSession( ) mediante una función de devolución de llamada que usted proporciona.
  4. Su sitio web analiza cualquier error devuelto por el Servicio de Mastercard Payment Gateway y vuelve a mostrar la página de pago si se encuentra algún error.
  5. Su sitio web envía el identificador de sesión devuelto a su servidor web.

    Puede elegir mostrar más páginas al pagador según su flujo de trabajo comercial o realizar una transacción de almacenamiento o pago al tiempo de recopilar los detalles de tarjeta.

  6. Usted inicia una solicitud a Mastercard Payment Gateway al especificar los campos obligatorios que usan una o más de las siguientes operaciones de API: Autorizar, Pagar, Tokenización. 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.
  7. Mastercard Payment Gateway le envía el resultado de la solicitud de vuelta. Puede realizar operaciones posteriores con el identificador de sesión antes de que la sesión caduque.
  8. Usted muestra el resultado de la transacción al pagador en su sitio web.
Visa Checkout mediante Hosted Payment Session (con JavaScript)

Si usted tiene su propia página de pago, entonces puede seleccionar esta opción para que Mastercard Payment 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 fácil para las integraciones de Hosted Payment Session existentes (con JavaScript).

El flujo de pago es de la siguiente manera:

  1. Muestre una página de pago al pagador, según se requiere, para la integración de Hosted Payment Session con JavaScript. La página de pago debe incluir una manera de identificar Visa Checkout como la opción de pago seleccionada por el pagador.

    El siguiente es un ejemplo de código que le muestra cómo aparece Visa Checkout como opción en la página de pago.

    <script id="hpfScript" src="https://evopaymentsmexico.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>
  2. 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>
  3. La función de devolución de llamada JavaScript maneja la respuesta 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
    }
    };
  4. Tenga en cuenta que puede usar la misma función de devolución de llamada para los pagos de tarjeta y Visa Checkout.
  5. Ahora puede usar el identificador de sesión de pago para realizar cualquier operación donde una sesión de pago pueda proporcionar los detalles de pago, por ejemplo, solicitudes de Autorizar, Pagar y Tokenizar. Tenga presente que se pueden proporcionar detalles de tarjeta mediante diversas fuentes de detalles de tarjeta.
  6. Se recomienda que recupere los detalles de la sesión mediante la operación Recuperar sesión y que compruebe los contenidos de la sesión antes de iniciar una operación de pago o almacenamiento.

Solución de problemas y preguntas frecuentes

Actualicé la sesión mediante el método HostedForm.updateSession( ). ¿Por qué no puedo realizar una transacción de pago con esta sesión?

Si actualiza la sesión mediante el método HostedForm.updateSession( ), puede realizar una transacción de pago con la sesión mediante ÚNICAMENTE API v30. Si está integrado con API v29 o menos, entonces debe actualizar su integración con v30.

¿Qué debo hacer si el formulario de pago devuelve un error?

El formulario de pago puede devolver diversos tipos de errores. Consulte Administración de errores.

¿Qué sucede cuando transmito campos definidos por el negocio en el método de HostedForm.createSession( )?

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á.

¿Puedo llamar al método de HostedForm.createSession( ) varias veces?

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.

Derechos de autor © 2020 Mastercard