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.micuentaweb.pe/static/js/authenticate-client/V1.0/kr-authenticate.umd.js"></script>
...
</head>
2. Iniciar una solicitud de autentificación del titular
Appelez le Web Service V4.1/PCI/Charge/CreatePayment en utilisant les champs ci-dessous :
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:
| 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 medio de pago.Su valor debe serCARD. | 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
{ "amount": "990", "currency": "PEN", "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":"MCW",
"metadata":null,
"status":"SUCCESS",
"mode":"TEST",
"serverUrl":"https://api.micuentaweb.pe",
"_type":"V4/WebService/Response",
"answer":{
"operationSessionId":"30641640cba14eab8e6766094fd201da",
"operationUrl":"https://api.micuentaweb.pe/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.micuentaweb.pe/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("89289758:testpublickey_TxzPjl9xKlhM0a6tfSVNilcLTOUZ0ndsTogGTByPUATcE");
- Con el elemento DOM:
const krAuthenticate = new KrAuthenticate("89289758:testpublickey_TxzPjl9xKlhM0a6tfSVNilcLTOUZ0ndsTogGTByPUATcE", {
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.micuentaweb.pe/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.micuentaweb.pe/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('89289758:testpublickey_TxzPjl9xKlhM0a6tfSVNilcLTOUZ0ndsTogGTByPUATcE');
// 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 durée de la session de paiement est fixée à 10 minutes. Au bout de ce délai, si l'IPN n'a pas été configurée par le marchand, il est recommandé de faire un appel au Web Service Order/Get pour obtenir le résultat du paiement.