Referencia del cliente JavaScript

El cliente JavaScript permite crear un formulario de pago en su sitio comercial gracias al siguiente código:

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />  

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5" 
   kr-post-url-success="paid.html">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
  href="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic.js">
 </script> 
</head>
<body>
  <!-- payment form -->
  <div class="kr-embedded" 
   kr-form-token="DEMO-TOKEN-TO-BE-REPLACED">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
   href="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic-reset.css">
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic.js">
  </script>
</head>
<body style="padding-top:20px">
  <!-- payment form -->
  <div class="kr-embedded"
   kr-form-token="<?php echo $formToken;?>">

    <!-- payment form fields -->
    <div class="kr-pan"></div>
    <div class="kr-expiry"></div>
    <div class="kr-security-code"></div>  

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

    <!-- error zone -->
    <div class="kr-form-error"></div>
  </div>  
</body>
</html>

Para revisar la documentación completa, visite: Primeros pasos: Pago simple

Plataformas compatibles

Hacemos nuestro mejor esfuerzo para admitir todas las versiones recientes de los principales navegadores disponibles en el mercado.

Por razones de seguridad y para ofrecer la mejor experiencia de usuario a la mayoría de nuestros vendedores, no admitimos navegadores y sistemas operativos que dejaron de recibir parches de seguridad.

Estos navegadores representan una parte ínfima del tráfico de pagos en Internet.

Somos compatibles con:

  • Internet Explorer de la versión 10 en adelante
  • Edge a partir de la versión 17
  • Chrome a partir de la versión 70
  • Firefox a partir de la versión 64
  • Safari (escritorio y móvil) a partir de la versión 11
  • Android Native Browser a partir de Android 4.4
  • todas las últimas versiones de iOS del iPhone 4S en adelante.

El navegador debe ser compatible con TLS 1.2.

Probamos proactivamente la mayoría de los navegadores, tanto en dispositivos móviles como de escritorio. Sin embargo, puede que una combinación de móvil + navegador escape a nuestra vigilancia. De ser el caso, póngase en contacto con nuestro soporte técnico.

Si desea admitir una combinación que no es compatible con nuestro cliente JavaScript, también puede implementar nuestro formulario de redireccionamiento para estos casos límite.

También tenga en cuenta que algunos antivirus o bloqueadores de anuncios pueden potencialmente bloquear nuestra solución. Si detecta algún uso indebido, póngase en contacto con el soporte técnico.

Parámetros de inicialización

Se pueden definir distintos parámetros al cargar el cliente JavaScript. Por ejemplo, para definir kr-public-key y kr-post-url-success:

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://api.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5" 
   kr-post-url-success="paid.html">
  </script>


  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

Los parámetros disponibles son los siguientes:

Parámetros generales:

Parámetro Obligatorio Descripción
kr-public-key sí Clave pública que se utilizará para realizar el pago.
kr-language   Idioma de visualización del formulario en formato CultureInfo (fr-FR).
kr-post-url-success   URL a la que se envía el formulario (método POST) en caso de éxito.
kr-get-url-success   URL a la que se envía el formulario (método POST) en caso de éxito.
kr-post-url-refused   URL que llamar cuando todos los intentos han fallado (método POST).
kr-get-url-refused   URL que llamar cuando todos los intentos han fallado (método GET).
kr-clear-on-error   Deshabilita el borrado del CVV en caso de rechazo de una transacción (true o false).
kr-hide-debug-toolbar   Oculta la barra de depuración en modo de prueba (true o false).
kr-spa-mode   Si se establece en true, el formulario no se inicializa automáticamente (su valor predeterminado es false).

Personalización de los marcadores de posición (placeholders):

Parámetro Obligatorio Descripción
kr-placeholder-expiry   Marcador de posición del campo kr-expiry (fecha de caducidad).
kr-placeholder-pan   Marcador de posición del campo kr-pan (número de tarjeta).
kr-placeholder-security-code   Marcador de posición del campo kr-security-code (CVV).
kr-placeholder-identity-document-type   Marcador de posición del campo del tipo de documento de identidad, de ser necesario (caso LATAM)
kr-placeholder-identity-document-number   Marcador de posición del campo del número de documento de identidad, de ser necesario (caso LATAM)
kr-placeholder-installment-number   Marcador de posición del campo Forma de pago
kr-placeholder-card-holder-mail   Marcador de posición del campo e-mail, de ser necesario (caso LATAM)
kr-placeholder-card-holder-name   Marcador de posición del campo del nombre del titular, de ser necesario (caso LATAM)

Personalización de las etiquetas animadas (específica del tema Material):

Parámetro Obligatorio Descripción
kr-label-expiry   Etiqueta animada del campo kr-expiry (fecha de vencimiento).
kr-label-pan   Etiqueta animada del campo kr-pan (número de tarjeta).
kr-label-security-code   Etiqueta animada del campo kr-security-code (CVV).
kr-label-identity-document-type   Etiqueta animada del campo del tipo de documento de identidad, de ser necesario (caso LATAM)
kr-label-identity-document-number   Etiqueta animada del campo del número de documento de identidad, de ser necesario (caso LATAM)
kr-label-installment-number   Etiqueta animada del campo Forma de pago
kr-label-card-holder-mail   Etiqueta animada del campo e-mail, de ser necesario (caso LATAM)
kr-label-card-holder-name   Etiqueta animada del campo del nombre del titular, de ser necesario (caso LATAM)

Estos parámetros también se pueden sobrecargar con el método KR.setFormConfig(). Por ejemplo, para sobrecargar el parámetro kr-post-url-success:

KR.setFormConfig({
        'kr-post-url-success': 'https://my.site'
    }).then(({
            KR
        }) => {
            /* there is no error */
        );

Tenga en cuenta que si se definen al mismo tiempo los parámetros kr-post-url-success y kr-get-url-success el método POST tendrá prioridad. Esto también se aplica a kr-post-url-refused y kr-get-url-refused*.

Eventos

Es posible adjuntar devoluciones de llamada de JavaScript personalizadas a varios eventos. El cliente JavaScript es compatible con los siguientes eventos:

Parámetro Descripción
KR.onBrandChanged() Se llama cuando se detecta la marca de la tarjeta
KR.onError() Permite enviar una notificación cuando se produce un error.
KR.onFocus() Uno de los campos del formulario está enfocado.
KR.onFormCreated() El formulario de pago está listo pero aún no se carga el contenido de las Iframe.
KR.onFormReady() El formulario está listo para usarse.
KR.onInstallmentChanged() Se llama cuando el comprador selecciona el número de cuotas que aplicar al pago.
KR.onLoaded() Primer evento llamado antes de la creación del formulario.
KR.onSubmit() Se llama justo antes de enviar el formulario mediante POST.
KR.button.onClick() Se llama cuando el comprador hace clic en el botón del formulario.

Todos los eventos devuelven promesas, lo que le permite integrarlas en una cadena. Consulte Trabajar en un entorno asíncrono para más información.

KR.onBrandChanged()

Se llama a la callback definida en KR.onBrandChanged() cada vez que se detecta una marca de tarjeta. Ejemplo de integración

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onBrandChanged( function({KR, cardInfo}) {
            var myMessage = "brand selected: " + cardInfo.brand;

            $("#custommessage").html(myMessage);
          });
    });
  </script>

El objeto cardInfo contiene la propiedad brand que puede tener los siguientes valores:

  • amex
  • cb
  • mastercard
  • maestro
  • visa_electron
  • visa

Para ver la lista completa, consulte la documentación de referencia del parámetro effectiveBrand aquí: Payment

KR.onError()

KR.onError() permite interceptar los errores antes de que se muestren.

Ejemplo de intercepción de mensajes de error:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onError( function(event) {
            var code = event.errorCode;
            var message = event.errorMessage;
            var myMessage = code + ": " + message;

            document.getElementsByClassName("customerror")[0].innerText = myMessage;
          });
    });
  </script>

A continuación, los mensajes de error se mostrarán automáticamente en el siguiente elemento, siempre y cuando esté presente:

Cuando se generan múltiples errores, se agrupan en un solo error. La propiedad children contendrá los detalles de todos los errores:

{
    "errorCode": "CLIENT_300",
    "errorMessage": "Invalid form data",
    "children": [{
        "errorCode": "CLIENT_301",
        "errorMessage": "Invalid card number",
        "field": "pan",
        (...)
    }, {
        "errorCode": "CLIENT_302",
        "errorMessage": "Invalid expiry date",
        "field": "expiryDate",
        (...)
    }, {
        "errorCode": "CLIENT_303",
        "errorMessage": "Invalid security code",
        "field": "securityCode",
        (...)
    }],
    "detailedErrorCode": null,
    "detailedErrorMessage": null,
    (...)
}

Para más detalles sobre errores, consulte: Manejo de errores (cliente JS)

KR.onFocus()

KR.onFocus() permite recibir una notificación cuando se enfoca un campo del formulario:

Ejemplo de integración:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onFocus( function(event) {
            var myMessage = "focus on: " + event.field;

            $("#custommessage").html(myMessage);
          });
    });
  </script>

Si el campo del número de tarjeta se enfoca, la variable event tomará el siguiente valor:

{
    "field":"pan",
    "formId":"F73867",
    "_type":"krypton/focus"
}

KR.onInstallmentChanged()

KR.onInstallmentChanged() permite recibir notificaciones cuando el comprador selecciona el número de cuotas.

<script type="text/javascript">
    $(document).ready(function() {
          KR.onInstallmentChanged( function({KR, installmentInfo}) {
            console.log(installmentInfo)
          });
    });
</script>

El objeto installmentInfo posee los siguientes atributos:

  • brand => Marca de la tarjeta. Ejemplo: “VISA”
  • hasInterests => Booleano que indica si se aplica una tasa de interés. Ejemplo: false
  • installmentCount => Número total de cuotas. Ejemplo: 1
  • totalAmount => Monto total, con intereses. Ejemplo: : 20.000

KR.onSubmit()

KR.onSubmit () le permite interceptar la información de la transacción autorizada antes de que el formulario realice un POST en la URL definida en kr-post-success-url.

Ejemplo de integración:

  <script type="text/javascript">
    $(document).ready(function() {
      KR.onSubmit( function(event) {
        /* Change the button label to the orderStatus */
        $(".kr-payment-button > span:first").html(event.clientAnswer.orderStatus);
        $(".kr-spinner").hide();
        $(".kr-payment-button > span:first").show();
        
        /* return values:
         * true: kr-post-success-url is called using POST
         * false: kr-post-success-url is not called, execution stops.
         */
        return false;
      });
    });
  </script>

El objeto contenido en event es el mismo que el que envió el formulario. Para más detalles, consulte: Retorno del navegador.

El comportamiento varía según el valor booleano devuelto por su función:

Valor de retorno Comportamiento
true el cliente JavaScript realiza un POST en kr-post-success-url.
false No se realizó el POST en kr-post-success-url. Usted mismo gestiona la acción pospago.

KR.button.onClick()

KR.button.onClick() permite realizar un procesamiento personalizado antes de que el cliente JavaScript valide el formulario y realice la llamada para crear una transacción. KR.button.onClick() acepta como parámetro un callback o una promesa (Promise).

Puede detener la cadena de ejecución devolviendo false al final del procesamiento:

Valor de retorno Comportamiento
false Ejecución interrumpida. No se realizó el control de errores. La transacción no fue creada.
true la ejecución continúa normalmente cuando se ejecuta la callback.

Métodos

Hay varios métodos disponibles para interactuar con el cliente de JavaScript:

Parámetro Descripción
KR.closePopin() Cierra la popIn (si está abierta)
KR.field.focus() Asigna el foco a un campo del formulario incrustado
KR.openPopin() Abre la pop-in (si estaba cerrada)
KR.setFormConfig() Permite sobrecargar la configuración del cliente JavaScript, consulte la sección siguiente.
KR.setShopName() Cambia el nombre de la tienda definido en el encabezado de la pop-in.
KR.setFormToken() Atajo para cambiar el formToken del formulario actual.
KR.validateForm() Activa la validación local del formulario.

Todos los eventos devuelven promesas, lo que le permite integrarlas en una cadena. Consulte Trabajar en un entorno asíncrono para más información.

Solo debes utilizar que los métodos documentados. Cualquier artículo no documentado está sujeto a cambios sin previo aviso!

KR.field.focus()

Para asignarle el foco a un campo del formulario puede utilizar el método KR.field.focus(FIELD_CLASS) Debe pasar como parámetro la clase del campo del formulario incrustado.

Por ejemplo, para añadir un botón que le asignará el foco de entrada al campo fecha de vencimiento:

KR.setFormConfig()

Este método permite sobrecargar los parámetros de inicialización, así como los siguientes elementos:

Uso Descripción
KR.setFormConfig({formToken: “NEW_FORM_TOKEN”}); Cambia el formulario formToken actual.
KR.setFormConfig({language: “fr-FR”}); Modifica el idioma del formulario de pago y de los mensajes de error.

Este método devuelve una promesa (compromiso).

KR.validateForm()

Este método verifica localmente si el formulario es válido. Devuelve una promesa:

  • se llama a then() cuando el formulario es válido. result tendrá el valor null.
  • catch() se llama cuando el formulario no es válido. result contiene los detalles del error.

Ejemplo de llamada:

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();
    }

);

Una vez que haya detectado los errores, puede activar el evento KR.onError() manualmente llamando aresult.doOnError();.

Personalización del botón

El botón de pago se agrega automáticamente a su formulario a partir del siguiente código:

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>


    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

Hay muchas ventajas al usar nuestro botón de pago:

  • Se traducen automáticamente las etiquetas.
  • El monto se formatea y actualiza de forma automática.
  • Nos encargamos de la animación de espera en su lugar
  • El botón cambia automáticamente a solo lectura (read-only) si es necesario.

Si desea administrar la etiqueta del botón usted mismo, simplemente agréguela de la siguiente manera:

También puede insertar una variable que represente el monto y la moneda. El cliente JavaScript hará el reemplazo automáticamente:

Preguntas frecuentes

Aquí encontrará preguntas frecuentes sobre el cliente JavaScript.

¿Cómo corregir los errores CORS o “Unable to post message” al momento de pagar?

Para empezar, debe desarrollar desde un servidor web. Debe acceder a la página de test con http:// y no con file://

Si utiliza el framework ionic o cordova, debe declarar explícitamente los nombres de dominio que el cliente JavaScript puede llamar. Para ello, añada a config.xml:

<allow-navigation href="https://api.lyra.com/static/js/krypton-client/V4.0" />

Más información aquí.

Cómo configurar las CSP (Content Security Policy)

Si su sitio web utiliza CSP (Content Security Policy), debe autorizar la creación de Iframes al cliente JavaScript. Para ello, debe añadir las 3 directivas siguientes:

Directiva CSP Valores
connect-src https://api.lyra.com
frame-src https://api.lyra.com
script-src https://api.lyra.com

Ejemplo de inclusión en los metadatos del encabezado de su página:

<meta
  http-equiv="Content-Security-Policy"
  content="
    connect-src https://api.lyra.com;
    frame-src https://api.lyra.com;
    script-src https://api.lyra.com;"
/>

(Más información sobre las CSP aquí.)[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP]

Si utiliza una herramienta externa de detección de fraude (como monitor+, clearsale, etc.), también debe agregarla:

Directiva CSP Valores
connect-src https://secure.lyra.com
frame-src https://secure.lyra.com
script-src https://secure.lyra.com

Uso avanzado

Para ver todos los casos de uso avanzados, consulte los siguientes artículos:

Descripción Artículo  
Transmitir los campos de acuerdo a sus necesidades Casos de uso  
Agregar los campos de formulario personalizados Campos adicionales  
Hacer un pago simple Primeros pasos: Pago simple  
Manejar los errores del formulario incrustado Manejo de errores  
Gestión de nuevos intentos de pago (retry) Nuevo intento de pago (retry)  
Referencia de eventos y métodos del cliente JS Referencia del cliente JavaScript  
Temas preconfigurados y personalización en CSS Temas  
Pasar del formulario con redireccionamiento al formulario incrustado Migración del formulario en modo de redireccionamiento