Vender en línea en Perú va más allá de aceptar tarjetas de crédito internacionales. El éxito radica en ofrecer a los clientes los métodos de pago que conocen y en los que confían, como tarjetas locales (débito y crédito) y, sobre todo, PagoEfectivo.
Esta guía te llevará paso a paso por el proceso técnico de integrar Culqi en un sitio web de prueba, cubriendo desde la configuración inicial hasta la confirmación de la venta.
Pre-requisitos
- Conocimientos básicos de HTML, CSS y JavaScript.
- Un entorno de desarrollo backend (usaremos Node.js con Express).
- Una cuenta de prueba gratuita en Culqi.
- Tus Llaves API (Pública y Secreta) del panel de Culqi en modo TEST.
El Flujo de Pago: ¿Cómo Funciona de Forma Segura?
Es vital entender que nunca debes manejar los datos de la tarjeta de tu cliente directamente en tu servidor. Las pasarelas modernas solucionan esto con un proceso llamado tokenización.
- Frontend (Tu web): El usuario ingresa los datos de su tarjeta en el formulario seguro de Culqi.
- Culqi -> Frontend: Culqi valida los datos y te devuelve un Token de un solo uso.
- Frontend -> Backend (Tu servidor): Tu web envía este Token a tu servidor.
- Backend -> Culqi: Tu servidor usa el Token y su Llave Secreta para autorizar el cobro.
- Culqi -> Backend: Culqi confirma el pago a tu servidor.
¡Punto Crítico de Seguridad! Este flujo evita que los datos sensibles de la tarjeta toquen tu servidor, reduciendo drásticamente tus responsabilidades de cumplimiento PCI DSS.
Paso a Paso: La Integración
Parte 1: Configuración en el Panel de Culqi
Dentro de tu cuenta de Culqi, asegúrate de estar en Modo TEST y dirígete a la sección Desarrollo > Llaves API. Copia tu Llave Pública (pk_test_...) y tu Llave Secreta (sk_test_...).
Parte 2: El Frontend (Lado del Cliente)
Este es el código para una página simple que muestra un botón de pago.
<!DOCTYPE html>
<html lang="es">
<head>
<title>Tienda de Prueba</title>
<!-- 1. Incluir el script de Culqi -->
<script src="https://checkout.culqi.com/js/v4"></script>
</head>
<body>
<h1>Producto de Prueba</h1>
<p>Precio: S/ 50.00</p>
<button id="btnPagar">Pagar ahora</button>
<script>
// 2. Configurar tu Llave Pública
Culqi.publicKey = 'pk_test_xxxxxxxxxxxxxxxx'; // ¡Usa tu llave pública de prueba!
// 3. Configurar información del pago
const montoTotal = 5000; // Monto en céntimos (S/ 50.00)
Culqi.settings({
title: 'Mi Tienda de Prueba',
currency: 'PEN',
amount: montoTotal
});
// 4. Manejar el evento del botón
document.getElementById('btnPagar').addEventListener('click', function (e) {
Culqi.open();
e.preventDefault();
});
// 5. Función global que se ejecuta tras la interacción con Culqi
function culqi() {
if (Culqi.token) { // Token creado
const token = Culqi.token.id;
fetch('/crear-cargo', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token: token, amount: montoTotal, email: Culqi.token.email })
})
.then(res => res.json())
.then(data => alert('Respuesta del servidor: ' + data.message));
} else { // Error
alert('Error: ' + Culqi.error.user_message);
}
}
</script>
</body>
</html>
Parte 3: El Backend (Lado del Servidor con Node.js)
Este servidor recibe el token y procesa el cobro real de forma segura.
require('dotenv').config();
const express = require('express');
const fetch = require('node-fetch');
const app = express();
app.use(express.json());
// Endpoint para crear el cargo en Culqi
app.post('/crear-cargo', async (req, res) => {
const { token, email, amount } = req.body;
try {
const culqiResponse = await fetch('https://api.culqi.com/v2/charges', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.CULQI_PRIVATE_KEY}`
},
body: JSON.stringify({
amount: amount,
currency_code: 'PEN',
email: email,
source_id: token
})
});
const data = await culqiResponse.json();
if (data.object === 'charge') {
res.json({ message: '¡Pago exitoso!' });
} else {
res.status(500).json({ message: 'Error en el pago', data: data });
}
} catch (error) {
res.status(500).json({ message: 'Error interno del servidor.' });
}
});
// Endpoint para Webhooks
app.post('/webhook-culqi', (req, res) => {
const event = req.body;
if (event.type === 'order.status.changed' && event.data.status === 'paid') {
console.log(`La orden ${event.data.id} ha sido pagada.`);
// Aquí actualizas tu base de datos
}
res.status(200).send('Evento recibido');
});
app.listen(3000, () => console.log('Servidor en puerto 3000'));
Parte 4: Webhooks para Confirmación Asíncrona
Los webhooks son cruciales, especialmente para métodos como PagoEfectivo. Son notificaciones que Culqi envía a tu servidor cuando el estado de un pago cambia (por ejemplo, cuando el cliente paga su código CIP en un agente). Debes crear un endpoint (como el /webhook-culqi del código anterior) y registrar su URL pública en tu panel de Culqi.
Conclusión
¡Felicidades! 🚀 Has construido el esqueleto completo para una integración de pagos con una pasarela peruana. Has aprendido el flujo de tokenización segura, cómo crear un cargo desde tu backend y la importancia de los webhooks para confirmaciones fiables. El siguiente paso es adaptar este flujo a tu aplicación real y prepararte para pasar a producción cambiando tus llaves de prueba por las llaves "Live".
¡Ahora te toca a ti!
¿Qué te pareció el proceso? ¿Tienes alguna duda sobre cómo adaptar esto a tu proyecto? ¡Deja tu pregunta o comentario abajo!
Deja tu comentario
Publicar un comentario