Aplicaciones web de una sola página
La integración del formulario incrustado responde a una cinemática diferente cuando se trata de sitios web cuya lógica es completamente administrada en JavaScript del lado del cliente.
Integración simple
Si su sitio utiliza un framework JavaScript no compilado (por ejemplo, JQuery), la integración es bastante sencilla.
1. Cargo del formulario de pago
La primera etapa consiste en cargar la biblioteca JavaScript. Al igual que con la integración del lado del servidor, solo hay que incluir los scripts JavaScript y las hojas de estilo del formulario incrustado.
<head> <!-- Javascript library. Should be loaded in head section --> <script type="text/javascript" src="https://static.cobroinmediato.tech/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" kr-public-key="45789921:testpublickey_qSbs1nvRJEdy74KqANWo6TnGnRsTzwFMd9DYrO9OCdiHD:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5"> </script> <!-- theme and plugins. should be loaded in the HEAD section --> <link rel="stylesheet" href="https://static.cobroinmediato.tech/static/js/krypton-client/V4.0/ext/classic-reset.min.css"> <script type="text/javascript" src="https://static.cobroinmediato.tech/static/js/krypton-client/V4.0/ext/classic.js"></script> </head> <body> ... <!--Hidden payment form --> <div id="paymentForm" class="kr-embedded" style="display:none"> <!-- 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>
Importante, no olvide reemplazar el campo "kr-public-key" con su clave pública (consulte aquí para más información ).
2. Inicialización del formulario de pago.
Cuando el usuario decide pagar, puede inicializar el formulario de pago. Para esto, debe llamar al servidor de su vendedor y verificar las compras del usuario, luego generar un identificador de formulario (llamado formToken) llamando al Web Service Charge/CreatePayment (siempre desde el servidor del vendedor).
/**
* Called on 'checkout' click
*/
function onCheckout(){
// Create the order, based on your cart
var order = {
"amount": 9900,
"currency": "ARS",
"orderId": "myOrderId-999999",
"customer": {
"email": "sample@example.com"
}
};
// Call merchant server to get form token and then display payment form
getFormToken(order, displayPaymentForm, alert);
}
/**
* Get form token from merchant server
* @param order
* @param resolve
* @param reject
*/
function getFormToken(order, resolve, reject){
var request = new XMLHttpRequest();
// Open a new connection, using the POST request on the URL endpoint
request.open('POST', 'YOUR_SERVER/payment/init', true);
request.setRequestHeader('Content-Type', 'application/json');
request.onload = function (){
if (request.status >= 200 && request.status < 400) {
resolve(this.response);
}
else
{
reject("Invalid server response. Code " + request.status);
}
};
request.onerror = function (error){
reject(error);
};
// Send request
request.send(JSON.stringify(order));
}
En el lado del servidor, su código debería verse así (en Node JS):
/* Init payment form */
router.post('/init', function(req, res, next){
var order = req.body;
// TO DO: check that order is valid
// Call CreatePayment web service to create the form token
request.post({
url: "https://api.cobroinmediato.tech/api-payment/V4/Charge/CreatePayment",
headers: {
'Authorization': 'Basic Njk4NzYzNTc6dGVzdHBhc3N3b3JkX0RFTU9QUklWQVRFS0VZMjNHNDQ3NXpYWlEyVUE1eDdN',
'Content-Type': 'application/json'
},
json: order
}, function(error, response, body){
if (body.status === 'SUCCESS')
{
// Send back the form token to the client side
res.send(body.answer.formToken);
}
else
{
// Do your own error handling
console.error(body);
res.status(500).send('error');
}
});
});
Importante: no llame al Web Service Charge/CreatePayment desde el navegador del comprador:
- La etapa de validación del carrito es una etapa crucial, y es su responsabilidad verificar en sus servidores que el monto corresponde bien al carrito antes de enviárnoslo
- Llamar al Web Service desde el navegador del comprador significaría poner sus claves de llamadas a su disposición (y a la vista de potenciales hackers), lo que ca contra las reglas de seguridad.
- La llamada fallará sistemáticamente, nuestros servidores no autorizan las llamadas desde el navegador (Cross Origin Policy).
3. Visualización del formulario de pago.
Una vez que el cliente recibe el formToken generado del lado del servidor, puede asociarlo a su formulario y mostrarlo.
/**
* Display the payment form with the argument form token
* @param formToken
*/
function displayPaymentForm(formToken){
// Show the payment form
document.getElementById('paymentForm').style.display = 'block';
// Set form token
KR.setFormToken(formToken);
// Add listener for submit event
KR.onSubmit(onPaid);
}
La última etapa consiste a escuchar los eventos del formulario (KR.onSubmit) con la finalidad de ser notificado del lado del cliente al final del pago.
4. Verificación del estado de la transacción.
Una vez el pago finalizado, haya sido aceptado o rechazado, se le notificará de dos maneras:
- para una llamada (IPN) al servidor de vendedor, si este último está registrado en nuestra plataforma de pago,
- para un "callback" del lado JavaScript, registrado en el método KR.onSubmit.
Se recomienda que verifique la integridad del mensaje (consulte aquí Para más información) y lanzar los procesos de negocio del lado del servidor (al recibir el IPN). El "callback" JavaScript solo debe usarse para recuperar el itinerario del cliente en el navegador y mostrarle un mensaje correcto:
/**
* Called when payment is finished
* @param event
*/
function onPaid(event){
if (event.clientAnswer.orderStatus === "PAID") {
// Remove the payment form
KR.removeForms();
// Show success message
document.getElementById("paymentSuccessful").style.display = "block";
} else {
// Show error message to the user
alert("Payment failed !");
}
}
Integración con Vue / React / Angular
Prerrequisito
La integración del formulario incrustado dentro de un sitio que usa frameworks JavaScript compilados (tipo React o Angular) requiere el uso de la biblioteca embedded-form-glue.
Asociada al código JavaScript del formulario incrustado, esta biblioteca facilita las siguientes operaciones:
- Precarga de la biblioteca para permitir una visualización más rápida para redes lentas
- Gestión de la configuración cuando la aplicación aún no está cargada
- Agregar, eliminar y visualizar nuevamente el formulario de forma sencilla
La biblioteca embedded-form-glue está disponible en github.
Trabajar en un entorno asíncrono.
Para permitirle integrar el formulario incrustado en un ambiente asíncrono, todos los eventos y métodos devuelven promesas(Promises).
En cada resolución, la promesa pasa un objeto al método then()
, que puede contener dos propiedades:
KR
: siempre se devuelve la referencia de la biblioteca de JavaScript, permitiendo encadenar promesas sea cual sea el contextoresult
: el resultado de la operación, que puede ser indefinido u omitirse del objeto si no se devuelve ningún resultado
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(); } );
Ejemplos de integración:
En función del framework JavaScript que utilice en su sitio web comercial, existen otros ejemplos de integración disponibles en el sitio github de la biblioteca embedded-form-glue.
Framework | Descripción |
---|---|
Angular | ejemplo de integración para Angular |
ember | ejemplo de integración para Ember |
Ionic | Ejemplo de integración para Ionic |
next | ejemplo de integración para Next |
React | Ejemplo de integración para React. |
servidor | ejemplo de integración para Server |
svelte | ejemplo de integración para Svelte |
vue | ejemplo de integración para Vue.js |
require.js | ejemplo de integración con RequireJS |