Formulario incrustado: prueba rápida
Esta página ofrece un ejemplo de integración de un formulario de pago seguro, en 3 simples pasos.
Para obtener una guía de integración más completa (o para la integración desde un sitio en JavaScript), consulte: Primeros pasos: Pago simple
1. Inicializar el formulario
Cuando un comprador finaliza su compra en su sitio debe validar su transacción en su servidor de vendedor comprobando en particular: el monto, la moneda, el contenido del carrito, etc.
Tras estos controles, su servidor de vendedor debe llamar el Servicio Web Charge/CreatePayment para inicializar la transacción.
En respuesta, su servidor de vendedor recupera un formToken, objeto cifrado que permite inicializar el formulario incrustado con los datos de la transacción y de la configuración de la tienda.
{ "amount": 9900, "currency": "ARS", "orderId": "myOrderId-999999", "customer": { "email": "sample@example.com" } }
{ "amount": 1500, "currency": "PEN", "orderId": "myOrderId-999999", "more": "parameters", "customer": { "email": "sample@example.com" } }
{ "amount": 20000, "currency": "ARS", "orderId": "myOrderId-999999", "more": "parameters", "customer": { "email": "sample@example.com" } }
{ "amount": 100000, "currency": "COP", "orderId": "myOrderId-999999", "more": "parameters", "customer": { "email": "sample@example.com" } }
{ "amount": 2500, "currency": "BRL", "orderId": "myOrderId-999999", "more": "parameters", "customer": { "email": "sample@example.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"]; ?>
/** * 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"]; ?>
Para obtener más detalles sobre la autenticación de las llamadas al Servicio web REST, consulte: Fase de autenticación.
La respuesta será:
{ "status": "SUCCESS", "_type": "V4/WebService/Response", "webService": "Charge/CreatePayment", "applicationProvider": "COIN", "version": "V4", "applicationVersion": "4.1.0", "answer": { "formToken": "DEMO-TOKEN-TO-BE-REPLACED", "_type": "V4/Charge/PaymentForm" } }
2. Mostrar el formulario
Una vez que el formToken esté en su poder, puede visualizar el formulario de pago.
Para ello, utilice una etiqueta HTML <meta>
con el valor "UTF-8". Por ejemplo:
<head>
...
<meta charset="UTF-8">
...
</head>
Entonces debes:
- Incluir la biblioteca de JavaScript del formulario de pago ( kr-payment-form.min.js) en su página de pago, pasando en argumento su clave de acceso (consulte aquí para saber cómo obtenerla), así como las hojas de estilo asociadas.
- Incluir un elemento de tipo DIV con los siguientes argumentos:
- la clase kr-embedded
- el atributo kr-form-token en el que ha transferido el formToken recibido en la etapa anterior.
El formulario de pago se mostrará en este DIV.
Es obligatorio que la biblioteca principal se cargue rápidamente, mucho antes que las otras bibliotecas JS utilizadas en su página.
<!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://static.cobroinmediato.tech/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" kr-public-key="45789921:testpublickey_qSbs1nvRJEdy74KqANWo6TnGnRsTzwFMd9DYrO9OCdiHD" 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://static.cobroinmediato.tech/static/js/krypton-client/V4.0/ext/classic-reset.css"> <script src="https://static.cobroinmediato.tech/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>
El cliente JavaScript utiliza elementos DIV especiales para insertar los campos del formulario. Estos contenedores se identifican a partir de las siguientes clases:
Class | DESCRIPCIÓN |
---|---|
kr-pan | Número de tarjeta |
kr-expiry | Fecha de expiración |
kr-security-code | Código de seguridad (CVV) |
kr-form-error | Zona de visualización de errores |
kr-first-installment-delay | Número de meses de diferido que se aplicarán a la primera cuota |
kr-identity-document-type | Tipo de documento de identidad |
kr-identity-document-number | Número del documento de identidad |
kr-card-holder-name | Nombre del titular de la tarjeta |
kr-card-holder-mail | Dirección e-mail del titular de la tarjeta |
Ejemplo de formulario de pago:
Cuando el comprador valida el formulario, la transacción es enviada mediante el formulario directamente a nuestra plataforma de pago para su validación.
- Si la transacción es validada, se redirige al comprador a la página indicada en el atributo kr-post-url-success de la etiqueta
- Si la transacción es rechazada aparece un error y el comprador se queda en la página de pago.
3. Verificar el estado de la transacción
Durante el proceso de pago, las 2 siguientes acciones tienen lugar de forma secuencial:
Se envía una notificación instantánea (Instant Payment Notification o IPN) que contiene todos los datos de la transacción, haya sido aceptada o rechazada. Debe configurar la URL de notificación de su servidor en el Back Office de la tienda.
El navegador también recibe la misma información de transacción al final del proceso de pago.
Solo necesita procesar uno de estos 2 mensajes (son idénticos). Sirven para validar el carrito de compra e iniciar su proceso de compra.
Ejemplo de información enviada:
kr-hash=c3c0323c748fdb7c2d24bd39ada99663526236828efa795193bebfdea022fe58 kr-hash-algorithm=sha256_hmac kr-hash-key=sha256_hmac kr-answer={"orderStatus":"PAID", (...)
La primera etapa consiste en validar la integridad del mensaje, comprobando que la firma ( kr-hash) coincida con el conjunto del mensaje.
Una vez validada la integridad del mensaje, puede procesar la transacción (cuyo estado se almacena en la propiedad kr-answer).