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 la creación del token.
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 la solicitud de creación de token
Llamar al servicio webV4.1/PCI/Cargar/Crear token 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 | customer | Objeto que contiene los datos del comprador. | NO |
| 2 | E-mail del comprador. | Sí | |
| 1 | orderId | Referencia del pedido ( recomendado ). | NO |
| 2 | paymentMethodType | Tipo de método de pago.Debe valorarse en TARJETA. | Sí |
| 2 | cardHolderName | Nombre completo del titular de la tarjeta( recomendado ). | NO |
| 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 a la que se notificará el resultado del pago | NO |
Todos los campos y su descripción se encuentran en elPlayground:V4.1/PCI/Charge/CreateToken.
Ejemplo de solicitud
{
"amount": "990",
"currency": "EUR",
"customer": {
"email": "sample@example.com"
},
"ipnTargetUrl": "https://my.site/my-ipn",
"orderId": "myOrderId-1234",
"paymentForms": [
{
"paymentMethodType": "CARD",
"cardHolderName": "John Doe",
"pan": "4970110000001003",
"expiryMonth": 11,
"expiryYear": 25,
"securityCode": 123
}
]
}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/CreateToken",
"version":"V4.1",
"applicationVersion":"6.0.0",
(...)
"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 durante la respuesta 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();
// add the operationUrl in the object answer/AuthenticationSessionResponse#operationUrl
krAuthenticate.authenticate("operationUrl", 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 Challenge, sans 3DS Method | La autentificación requiere una acción del titular. | 3DS2 - autentificación con challenge, sin 3DS 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, con 3DS 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.