Aplicaciones web de una sola página

La integración del formulario incrustado responde a una secuencia distinta cuando se trata de sitios web cuya lógica se gestiona íntegramente en JavaScript del lado del cliente.

Integración simple

Si su sitio utiliza un framework JavaScript no compilado (por ejemplo, JQuery), la integración es bastante sencilla.

1. Cargar el formulario de pago

La primera etapa consiste en cargar la librería JavaScript. Al igual que con la integración del lado del servidor, solo hay que incluir los scripts JavaScript y las hojas de estilo del formulario incrustado.


    
    

    
    
    



    ...
        
        
    ...

Por supuesto, no olvide reemplazar el campo ‘kr-public-key’ por su clave pública (consulte aquí para más detalles).

2. Inicializar el formulario de pago

Cuando el usuario proceda al pago, usted puede inicializar el formulario de pago. Para esto, debe llamar a su servidor de vendedor y comprobar las compras del usuario y luego generar un identificador de formulario (llamado formToken) llamando al servicio web Charge/CreatePayment (siempre desde el servidor de vendedor).

/**
* Called on 'checkout' click
*/
function onCheckout()
{
    // Create the order, based on your cart
    var order = {
        "amount":   990,
        "currency": "EUR",
        "orderId":  "myOrderId-999999",
        "customer": {
            "email": "sample@example.com"
        }
    };

    // Call merchant server to get form token and then display payment form
    getFormToken(order, displayPaymentForm, alert);
}

/**
* Get form token from merchant server
* @param order
* @param resolve
* @param reject
*/
function getFormToken(order, resolve, reject) {
    var request = new XMLHttpRequest();

    // Open a new connection, using the POST request on the URL endpoint
    request.open('POST', 'YOUR_SERVER/payment/init', true);
    request.setRequestHeader('Content-Type', 'application/json');

    request.onload = function () {
        if (request.status >= 200 && request.status < 400) {
            resolve(this.response);
        }
        else
        {
            reject("Invalid server response. Code " + request.status);
        }
    };

    request.onerror = function (error) {
        reject(error);
    };

    // Send request
    request.send(JSON.stringify(order));
}

Del lado del servidor, su código debería verse así (en Node JS):


/* Init payment form */
router.post('/init', function(req, res, next) {
  var order = req.body;

  // TO DO: check that order is valid  

  // Call CreatePayment web service to create the form token
  request.post({
    url: "https://api.lyra.com/api-payment/V4/Charge/CreatePayment",
    headers: {
      'Authorization': 'Basic Njk4NzYzNTc6dGVzdHBhc3N3b3JkX0RFTU9QUklWQVRFS0VZMjNHNDQ3NXpYWlEyVUE1eDdN',
      'Content-Type': 'application/json'
    },
    json: order
  }, function(error, response, body) {
    if (body.status === 'SUCCESS')
    {
      // Send back the form token to the client side
      res.send(body.answer.formToken);
    }
    else
    {
      // Do your own error handling  
      console.error(body);
      res.status(500).send('error');
    }
  });
});

Importante: no llame al servicio web Charge/CreatePayment desde el navegador del comprador:

  • La etapa de validación del carrito es una etapa crucial, y es su responsabilidad verificar en sus servidores que el monto corresponde al carrito antes de enviárnoslo.
  • Llamar al servicio web desde el navegador del comprador significaría poner sus claves de llamadas a su disposición (y a la vista de potenciales hackers), lo que ca contra las reglas de seguridad.
  • La llamada fallará sistemáticamente, pues nuestros servidores no autorizan las llamadas desde el navegador (Cross Origin Policy).

3. Visualizar el formulario de pago

Una vez que el cliente recibe el formToken generado del lado del servidor, puede asociarlo a su formulario y mostrarlo.

/**
* Display the payment form with the argument form token
* @param formToken
*/
function displayPaymentForm(formToken)
{
    // Show the payment form
    document.getElementById('paymentForm').style.display = 'block';

    // Set form token
    KR.setFormToken(formToken);

    // Add listener for submit event
    KR.onSubmit(onPaid);
}

La última etapa consiste en escuchar los eventos del formulario (KR.onSubmit) para ser notificado del fin del pago del lado del cliente.

4. Verificar el estado de la transacción

Una vez el pago finalizado, haya sido aceptado o rechazado, se le notificará de dos maneras:

  • mediante una llamada (IPN) al servidor del vendedor, si este último está registrado en nuestra plataforma de pago,
  • mediante un callback del lado JavaScript, registrado en el método KR.onSubmit.

Recomendamos encarecidamente comprobar la integridad del mensaje (consulte aquí para obtener más detalles) e iniciar el procesamiento comercial del lado servidor (al recibir la IPN). El callback JavaScript solo debe utilizarse para retomar el control del recorrido del cliente del lado del navegador y mostrarle el mensaje correcto:

/**
 * Called when payment is finished
 * @param event
 */
function onPaid(event) {
  if (event.clientAnswer.orderStatus === "PAID") {
    // Remove the payment form
    KR.removeForms();

    // Show success message
    document.getElementById("paymentSuccessful").style.display = "block";
  } else {
    // Show error message to the user
    alert("Payment failed !");
  }
}

Integración con Vue / React / Angular

Requisitos previos

La integración del formulario incrustado dentro de un sitio usando frameworks JavaScript compilados (tipo React o Angular) requiere el uso de la biblioteca embedded-form-glue.

Asociada al código JavaScript del formulario incrustado, esta biblioteca facilita las siguientes operaciones:

  • Precarga de la biblioteca para permitir una visualización más rápida en redes lentas
  • Gestión de la configuración cuando la aplicación aún no está cargada
  • Agregar, eliminar y visualizar nuevamente el formulario de forma sencilla

La biblioteca embedded-form-glue está disponible en Github.

Trabajar en un entorno asíncrono.

Para permitirle integrar el formulario incrustado en un ambiente asíncrono, todos los eventos y métodos devuelven promesses.

A cada resolución, la promesa pasa un objeto al método.then()que puede contener dos propiedades:

  • KR: siempre se devuelve la referencia de la biblioteca de JavaScript, permitiendo encadenar promesas sea cual sea el contexto
  • result: el resultado de la operación, que puede ser indefinido u omitirse del objeto si no se devuelve ningún resultado
KR.validateForm().then( ({KR, result}) => {

    /* there is no error */
    /* result == null */
    }

)
.catch( ({KR, result}) => {

    /* Get the error message */
    var code = result.errorCode;
    var message = result.errorMessage;
    var myMessage = code + ": " + message;
    console.log(myMessage);

    /* if you have defined a callback using      */
    /* result.onError(), you can trigger it calling: */
    return result.doOnError();
    }

);

Ejemplos de integración:

Encontrará otros ejemplos de integración, dependiendo del framework JavaScript que utilice el sitio del vendedor, en el sitio Github de la biblioteca embedded-form-glue.

Framework Descripción
Vue.js Ejemplo de integración para Vue.js
React Ejemplo de integración para React.
Angular Ejemplo de integración para Angular y TypeScript

Puede integrar la biblioteca embedded-form-glue en cualquier otro framework siguiendo los mismos principios de los ejemplos anteriores.