➡️ 1. Introducción
🔑 2. Requisitos previos
🚀 3. Ejecutar ejemplo
🔗 4. Pasos de integración
💻 4.1. Desplegar pasarela
💳 4.2. Analizar resultado de pago
📡 4.3. Pase a producción
🎨 5. Personalización
🛠️ 6. Servidores
📚 7. Consideraciones
En este manual encontrarás una guía detallada para configurar un proyecto en [React] integrado con la pasarela de pagos de IZIPAY. Te proporcionaremos instrucciones claras y credenciales de prueba para instalar y configurar el proyecto, permitiéndote trabajar y realizar pruebas de manera segura en tu propio entorno local. Este manual está diseñado para facilitar la comprensión del flujo de integración de la pasarela de pagos y maximizar el rendimiento de tu desarrollo front-end. Ten en cuenta que este proyecto se conecta a un servidor (Backend) para gestionar las operaciones críticas relacionadas con la pasarela de pagos.
Important
En la última actualización se agregaron los campos: nombre del tarjetahabiente y correo electrónico (Este último campo se visualizará solo si el dato no se envía en la creación del formtoken).
- Comprender el flujo de comunicación de la pasarela. Información Aquí
- Extraer credenciales del Back Office Vendedor. Guía Aquí
- Descargar y ejecutar un servidor (Backend) API REST. Servidores disponibles
- Para este proyecto utilizamos la herramienta Visual Studio Code.
Note
Tener en cuenta que, para que el desarrollo de tu proyecto, eres libre de emplear tus herramientas preferidas.
Live Server, extensión para Visual Studio Code que simula un servidor web. Para instalarlo:
- Ingresar a la sección "Extensiones" de Visual Studio Code
- Buscar "Live Server"
- Instalar extensión
git clone https://github.com/izipay-pe/Embedded-PaymentForm-JavaScript.gitRealice la conexión al servidor modificando la ruta [midominio.com] por la ruta de su servidor.
- Editar el archivo
src/components/Formulario.jsx:
const handleSubmit = async (e) => {
e.preventDefault();
try {
//Solicitud de creación de formtoken a su servidor
const response = await axios.post('[midominio.com]/formtoken', formData);
navigate('/checkout', { state: response.data });
} catch (error) {
console.error('Error al procesar el pago:', error);
}
};- Editar el archivo
src/components/Checkout.jsx:
//Al recibir la respuesta enviar a su servidor a validar los datos
KR.onSubmit( paymentData => {
axios.post('[midominio.com]/validate', {
'kr-answer': paymentData.rawClientAnswer,
'kr-hash': paymentData.hash,
})
.then(response => {
if (response.data === true) {
navigate('/result', { state: paymentData.clientAnswer });
}
})
return false;
});Accede al archivo index.html dentro de la carpeta src y de clic derecho dentro del código HTML, busca la opción open with Live Server para ejecutarlo, se abrirá en tu navegador el proyecto y podrá acceder en la siguiente ruta:
http://127.0.0.1:5500/src/index.html
Las claves de acceso del Backoffice Vendedor deben configurarse exclusivamente en el servidor (Backend), no en la aplicación [React]. Esto asegura que las credenciales sensibles permanezcan protegidas y no sean expuestas en el código.
ℹ️ Para más información: Autentificación
Para configurar la pasarela, es necesario generar un formtoken. Esto se realiza mediante una solicitud API desde tu aplicación [React] al servidor (Backend), el cual procesa los datos de la compra, devolviendo el formtoken y la llave publicKey necesarias para desplegar la pasarela.
En el archivo src/components/Formulario.jsx se realiza la solicitud al servidor (Backend) junto con los datos recolectados del formulario.
const Formulario = ({ onPayment }) => {
const navigate = useNavigate();
//Data a enviar a su servidor
const [formData, setFormData] = useState({
firstName: '',
..
..
currency: 'PEN',
});
const handleChange = (e) => {
const { name, value } = e.target;
setFormData((prevData) => ({
...prevData,
[name]: value,
}));
};
const handleSubmit = async (e) => {
e.preventDefault();
try {
//Solicitud de creación de formtoken a su servidor
const response = await axios.post('[midominio.com]/formtoken', formData);
navigate('/checkout', { state: response.data });
} catch (error) {
console.error('Error al procesar el pago:', error);
}
};
return (
..
..
);
};Para desplegar la pasarela, se utiliza la libreria Embedded Form Glue y es necesario recepcionar los datos que nos devuelve el servidor para configurar la pasarela a través de los métodos de la libreria:
- Importar la libreria
import KRGlue from '@lyracom/embedded-form-glue' - Cargar las funciones y clases principales de la pasarela a través de
KRGlue.loadLibrary()junto a llavepublicKeyque recibimos del servidor. - Configurar la pasarela con el método
KR.setFormConfigjunto con elformTokenque recibimos del servidor. - Incrustamos la pasarela con el método
KR.attachFormy definimos el div con un ID donde se mostrará la pasarela.
En el archivo src/components/Checkout.jsx:
useEffect(() => {
//Endpoint de izipay
let endpoint = "https://static.micuentaweb.pe";
//Configurar libreria con los datos recibidos de su servidor
KRGlue.loadLibrary(endpoint, publicKey).then(({ KR }) => {
KR.setFormConfig({
formToken: formToken,
'kr-language': 'es-ES',
});
//Incrustar la pasarela
KR.attachForm('#micuentawebstd_rest_wrapper').then(({ KR, result }) => {
KR.showForm(result.formId);
});
..
..
})
}, []); - En el body del HTML se debe encontrar el div con el ID donde se mostrará la pasarela.
<div id="micuentawebstd_rest_wrapper">
<div className="kr-embedded"></div>
</div> - Adicionalmente se debe incluir en la cabecera los estilos necesarios para desplegar la pasarela. Podrás encontrarlos en el archivo
index.html
<!-- Estilos de la pasarela de pagos -->
<link rel="stylesheet" href="https://static.micuentaweb.pe/static/js/krypton-client/V4.0/ext/classic-reset.css">
<script src="https://static.micuentaweb.pe/static/js/krypton-client/V4.0/ext/classic.js"></script> Se configura el método KR.onSubmit que recepciona la respuesta del pago y se envía los datos a su servidor para validar la firma, esto garantiza la integridad de los datos. Podrás encontrarlo en el archivo src/components/Checkout.jsx.
//Al recibir la respuesta del pago, enviar a su servidor a validar los datos
KR.onSubmit( paymentData => {
axios.post('[midominio.com]/validate', {
'kr-answer': paymentData.rawClientAnswer,
'kr-hash': paymentData.hash,
})
.then(response => {
if (response.data === true) {
navigate('/result', { state: paymentData.clientAnswer });
}
})
return false;
});Una vez los datos son validados, se pueden mostrar en una pantalla, en el caso de ejemplo se muestran los datos en el archivo src/components/Result.jsx. Todos los datos de la transacción se encontrarán dentro del parámetro clientAnswer.
ℹ️ Para más información: Analizar resultado del pago
La IPN es una notificación de servidor a servidor (servidor de Izipay hacia el servidor del comercio) que facilita información en tiempo real y de manera automática cuando se produce un evento, por ejemplo, al registrar una transacción. La IPN se debe configurar en el servidor (Backend).
ℹ️ Para más información: Analizar IPN
Antes de poner en marcha su pasarela de pago en un entorno de producción, es esencial realizar pruebas para garantizar su correcto funcionamiento.
Puede intentar realizar una transacción utilizando una tarjeta de prueba con la barra de herramientas de depuración (en la parte inferior de la página).
- También puede encontrar tarjetas de prueba en el siguiente enlace. Tarjetas de prueba
Para el pase a producción es necesario cambiar las credenciales de TEST por las de PRODUCCIÓN dentro del servidor utilizado. El identificador de tienda sigue siendo el mismo.
Si deseas aplicar cambios específicos en la apariencia de la pasarela de pago, puedes lograrlo mediante la modificación de código CSS. En este enlace Código CSS - Incrustado podrá encontrar nuestro script para un formulario incrustado.
Lista de servidores disponibles:
Para obtener más información, echa un vistazo a: