Guía de integración

Esta sección describe cómo implementar los intercambios entre el navegador, el servidor del vendedor y la plataforma de pago cuando la autentificación del titular es gestionada por nuestro servidor de autentificación durante el pago.

1. Añadir la biblioteca JavaScript a su sitio

Para facilitar la integración de la solución, nuestra biblioteca JavaScript recopila datos del equipo y el navegador del cliente, se comunica directamente con el servidor 3DS y gestiona la interacción del titular de la tarjeta durante el reto.

En el HEAD de la página se debe añadir la biblioteca JavaScript en una etiqueta <script>.

<head>
 ...
 <script src="https://static.lyra.com/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
 ...
</head>

2. Iniciar una solicitud de autentificación del titular

Llamar al servicio webV4.1/PCI/Cargo/CrearPago utilizando los campos siguientes:

NIVEL	APELLIDO	Descripción	OBLIGATORIO
1	amount	Monto del pago en la fracción monetaria más pequeña de la divisa.	Sí
1	currency	Código (ISO 4217 alpha3) de la moneda del pago.	Sí
1	orderId	Referencia del pedido ( recomendado ).	NO
1	formAction	Permite indicar si se desea registrar la tarjeta. Valores posibles: PAYMENT REGISTER_PAY	NO
1	customer	Objeto que contiene los datos del comprador.	NO
1	paymentForms	Objeto que contiene los datos de la tarjeta.	Sí
2	paymentMethodType	Tipo de método de pago.Debe valorarse en TARJETA.	Sí
2	pan	Número de tarjeta.	Sí
2	expiryMonth	Mes de caducidad de la tarjeta.	Sí
2	expiryYear	Año de caducidad de la tarjeta.	Sí
2	securityCode	Código de seguridad de la tarjeta (CVV o 4DBC).	NO
1	ipnTargetUrl	URL de la página para notificar al final de la autentificación	NO

Existen campos opcionales. Encuentre la descripción de los campos en nuestro Playground.

Ejemplo de solicitud

/es-ES/rest/V4.0/api/kb/authentication.html

https://github.com/lyra/rest-php-examples/blob/master/www/minimalEmbeddedForm.php#L9-L44

https://api.lyra.com/api-payment/V4.1/PCI/Authentication/CreatePayment

{  
  "amount": "990",
  "currency": "EUR",
  "paymentForms": [
      {
        "pan": "4970110000001003",
        "expiryMonth": 11,
        "expiryYear": 23,
        "securityCode": "123",
        "paymentMethodType": "CARD"
      }
    ],
    "customer": {
      "email": "sample@example.com"
    },
    "ipnTargetUrl": "https://merchant.ipn.com"
  }

/**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array("amount" => 250, 
"currency" => "EUR", 
"orderId" => uniqid("MyOrderId"),
"customer" => array(
  "email" => "sample@example.com"
));
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

En el AuthenticationSessionResponse, encontrará los siguientes campos:

answer.operationSessionId: ID de la sesión de autentificación (para mantener)
answer.operationUrl: url para enviar a la biblioteca JavaScript

Encuentre la descripción de los campos en nuestro Playground.

Ejemplo de respuesta

{
  "webService":"PCI/Charge/CreatePayment",
  "version":"V4",
  "applicationVersion":"6.0.0",
  "serverDate":"2023-04-16T11:11:21+00:00",
  "ticket":"839ecda45f6449a8869747a80c26b2d2",
  "applicationProvider":"LYRA",
  "metadata":null,
  "status":"SUCCESS",
  "mode":"TEST",
  "serverUrl":"https://api.lyra.com",
  "_type":"V4/WebService/Response",
  "answer":{
    "operationSessionId":"30641640cba14eab8e6766094fd201da",
    "operationUrl":"https://api.lyra.com/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname",
    "_type":"V4/PCI/Authentication/AuthenticationSessionResponse"
  }
}

En el ejemplo:

answer.operationSessionId: "30641640cba14eab8e6766094fd201da"
answer.operationUrl: "https://api.lyra.com/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"

3. Inicializar el script de autentificación

Una vez creada la sesión de autentificación, debe inicializar la biblioteca de autentificación JavaScript y luego llamar al método "Authenticate". Se recomienda agragar un indicador visual de carga durante la llamada.

// définition de la class javascript
class KrAuthenticate{
  constructor(publicKey,options)
  authenticate(operationUrl)
}

1. Parámetros de inicialización de la clase `KrAuthenticate`

APELLIDO	Descripción	OBLIGATORIO
publicKey	Clave pública de test o de producción de la tienda. Más información: 3ª clave de la tabla de claves de la API REST.	Sí
options	Elemento del DOM en el que se muestra la ventana de autentificación (opcional).	NO

También puede mostrar la ventana de autentificación en otro elemento del DOM utilizando el atributo element del parámetro opcional options.

Sin el elemento DOM ( recomendado ) :

  const krAuthenticate = new KrAuthenticate("69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5");

Con el elemento DOM:

  const krAuthenticate = new KrAuthenticate("69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5", {
 element: document.getElementById("id-challenge-element")
  });

En este ejemplo, el id del elemento DOM es : id-challenge-element.

2. Parámetros del método de ejecución de la autentificación `KrAuthenticate.authenticate`

Utilice el campo operationUrl generado al crear la sesión (etapa 2).

APELLIDO	Descripción	OBLIGATORIO
operationUrl	URL de inicialización de la autentificación entregada en la respuesta del Web Service V4.1/PCI/Charge/CreatePayment en el objeto answer/AuthenticationSessionResponse#operationUrl.	Sí

Ejemplo: .

operationUrl: "https://api.lyra.com/api-payment/V4/Charge/Public/Authenticate/Payment/Session/30641640cba14eab8e6766094fd201da;JSESSIONID=7A4beEA2d5fdbFeA7389F3B91a7bDBaBc8DA9df5.default-hostname"

3. Código de ejemplo con la clase `KrAuthenticate` y el método `KrAuthenticate.authenticate`

Ejemplo de integración utilizando bootstrap, JQuery y la biblioteca:

<!-- import JS -->
    [...]
    <script src='https://static.lyra.com/static/js/authenticate-client/V1.0/kr-authenticate.umd.js'></script>
    [...]
    
    <form action='javascript:authenticatePayment()'>
      <button id='submitButton' type='submit' class='btn btn-primary'>Authenticate</button>
    </form>
    [...]

    <script>
    // instantiate library
    const krAuthenticate = new KrAuthenticate('69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5');

    // Callback removing the overlay
    function myCallback(data){
        document.getElementById('overlay').remove();
    }

    // this is an example of overlay with a bootstrap spinner
    function buildOverlay(){
        let overlay = document.createElement('div');
        overlay.setAttribute('id', 'overlay');
        overlay.style.backgroundColor = '#D3D3D3';
        overlay.style.height = '100%';
        overlay.style.position = 'absolute';
        overlay.style.top = '0';
        overlay.style.opacity = '0.90';
        overlay.style.width = '100%'
        overlay.classList.add('d-flex', 'justify-content-center', 'flex-column', 'align-items-center');
        overlay.innerHTML = `
<div class="spinner-border" role="status">
<span class="sr-only">Loading...</span>
</div>
        `;
        document.body.appendChild(overlay);
    }

    // Main function triggered by button
    function authenticatePayment(){
        document.querySelector('#submitButton').disabled = true;
        buildOverlay();
        krAuthenticate.authenticate("https://theUrlFromThePciCall", myCallback);
    }</script>

4. Ejecución de la biblioteca JavaScript

La biblioteca JavaScript ejecuta todas las acciones necesarias para la autentificación.

Casos de autentificación	Descripción	Test
3DS2 Frictionless, sans 3DS Method	La autentificación se realiza sin ninguna interacción del usuario.	3DS2 - autentificación frictionless, sin 3DS Method
3DS2 Frictionless, avec 3DS Method	Se ejecuta un script (3DS Method) antes de la autentificación, la que posteriormente se realiza sin ninguna interacción del titular.	3DS2 - autentificación frictionless, con3DS Method
3DS2 Challenge, sans 3DS Method	La autentificación requiere una acción del titular.	3DS2 - autentificación con challenge, sin3DS Method
3DS2 Challenge, avec 3DS Method	Se ejecuta un script (método 3DS) antes de las acciones de autentificación del titular.	3DS2 - autentificación con challenge, con3DS Method

Consulte Tests y casos de uso para ver más ejemplos.

5. Análisis del resultado del pago

Al final de la autentificación y de la solicitud de autorización, la plataforma devuelve un objeto Payment en la IPN. Describe la información del pago (estado del pago, resultado de la solicitud de autorización, resultado de la autentificación del titular, etc.).

Más información: Payment.

Gestión del "timeout"

La duración de la sesión de pago es de 10 minutos . Transcurrido este tiempo, si el comercio no ha configurado la IPN, se recomienda llamar al servicio web.Ordenar/Obtener para obtener el resultado del pago.

Categoria

Tags

Guía de integración

1. Añadir la biblioteca JavaScript a su sitio

2. Iniciar una solicitud de autentificación del titular

Ejemplo de solicitud

Ejemplo de respuesta

3. Inicializar el script de autentificación

1. Parámetros de inicialización de la clase `KrAuthenticate`

2. Parámetros del método de ejecución de la autentificación `KrAuthenticate.authenticate`

3. Código de ejemplo con la clase `KrAuthenticate` y el método `KrAuthenticate.authenticate`

4. Ejecución de la biblioteca JavaScript

5. Análisis del resultado del pago

Gestión del "timeout"

Categoria

Tags

Guía de integración

1. Añadir la biblioteca JavaScript a su sitio

2. Iniciar una solicitud de autentificación del titular

Ejemplo de solicitud

Ejemplo de respuesta

3. Inicializar el script de autentificación

1. Parámetros de inicialización de la clase KrAuthenticate

2. Parámetros del método de ejecución de la autentificación KrAuthenticate.authenticate

3. Código de ejemplo con la clase KrAuthenticate y el método KrAuthenticate.authenticate

4. Ejecución de la biblioteca JavaScript

5. Análisis del resultado del pago

Gestión del "timeout"

1. Parámetros de inicialización de la clase `KrAuthenticate`

2. Parámetros del método de ejecución de la autentificación `KrAuthenticate.authenticate`

3. Código de ejemplo con la clase `KrAuthenticate` y el método `KrAuthenticate.authenticate`