Cómo integrar Culqi en tu propio sistema

Culqi es, de lejos, la pasarela peruana más cómoda de integrar: API moderna, documentación en español y un primer cobro de prueba en menos de una hora. Ese es su mérito real — y también el origen de casi todos sus problemas en producción, porque lo fácil que es empezar esconde las decisiones que igual hay que tomar. Esta guía cubre lo que no sale en el tutorial: qué cambió en 2026, por qué Yape y PagoEfectivo obligan a repensar la arquitectura, y qué separa una integración que funciona de una que cuadra.

¿Culqi o Niubiz?

Culqi gana cuando necesitas salir rápido y tu volumen todavía no justifica negociar una tasa: la integración es más corta y la afiliación también. Niubiz gana cuando el volumen permite negociar, cuando importa la aprobación con tarjetas peruanas o cuando el antifraude pesa.

Es una decisión de etapa, no de gustos. Escribimos aparte sobre lo que cuesta integrar Niubiz — tres tokens encadenados y un proceso más largo. Si tu caso todavía no pide eso, Culqi te ahorra semanas. Un detalle que sí conviene tener presente: Culqi pertenece al grupo Credicorp, el del BCP, y de ahí que sea la vía más natural hacia Yape y Cuotéalo.

Lo primero que debes saber en 2026: el checkout cambió

Las versiones v2, v3 y v4 de CulqiJS quedaron sin soporte y la integración de comercios pasa por el nuevo Custom Checkout. Si estás siguiendo un tutorial de hace un par de años —y hay muchos— estás construyendo sobre una base que ya no recibe mantenimiento.

Es el error más caro que se puede cometer hoy con Culqi, y no aparece en ninguna comparativa de pasarelas: cuesta poco integrarse mal y mucho volver a hacerlo. Antes de escribir una línea, contrasta cualquier guía —incluida esta— contra la documentación oficial vigente. Las pasarelas cambian de versión más rápido de lo que envejece un artículo.

El flujo de tarjeta: dos llaves y un token

La llave pública identifica tu comercio y viaja al navegador sin riesgo. La llave secreta vive solo en tu servidor y puede hacer cualquier operación sin restricción. El navegador tokeniza la tarjeta; tu backend canjea ese token por el cargo.

La consecuencia importante es la misma que con cualquier pasarela seria: la tarjeta nunca toca tus servidores. Lo que recibes es un token que representa esa tarjeta dentro del flujo de pago. Eso es lo que mantiene tu alcance de PCI DSS en el rango manejable — y la razón por la que no vale la pena construir tu propio formulario de tarjeta.

Regla que parece obvia y se rompe seguido: la llave secreta nunca en el frontend, nunca en el repositorio, nunca en una variable de entorno del cliente. Si terminó en el navegador, ya no es secreta.

Yape y PagoEfectivo cambian la arquitectura, no solo el botón

Con tarjeta, el cargo se resuelve mientras el cliente espera. Con billeteras y PagoEfectivo no: el cliente puede pagar horas después, en un agente o desde su app. Por eso la propia documentación de Culqi señala que, dada la naturaleza asíncrona de las órdenes, usar webhooks es obligatorio para recibir la confirmación.

Aquí está el error de diseño más común: montar todo el flujo sobre la respuesta del navegador porque con tarjeta funciona, y descubrir al activar PagoEfectivo que no hay navegador al que responder — el cliente cerró la pestaña hace seis horas y pagó en una bodega. Si tu sistema no escucha el evento de cambio de estado de la orden, ese pago existe para Culqi y no para ti.

Webhooks bien hechos: responde primero, procesa después

Un webhook debe responder 200 OK de inmediato y hacer el trabajo pesado después, fuera del ciclo de la petición. Y debe ser idempotente: guardar los identificadores ya procesados y descartar los repetidos, porque las notificaciones se reintentan.

Esta es la parte que separa una integración que funciona de una que cuadra. Si mandas el correo de confirmación, generas la factura y actualizas el inventario antes de responder, un pico de tráfico convierte tus webhooks en timeouts — y los timeouts se reintentan, y los reintentos duplican. La secuencia correcta es invertida: confirmar recepción, encolar, procesar.

Y como en cualquier pasarela, el cierre lo da la conciliación: cruzar periódicamente lo que dice Culqi contra lo que dice tu base. En el sistema de caja de una universidad nacional que construimos, ese cruce es lo que permite cerrar el día sin revisar transacción por transacción.

3D Secure: menos contracargos, un paso más

Culqi aplica 3D Secure de forma automática en las tarjetas que lo requieren. Suma un paso de verificación para el cliente, y a cambio traslada la responsabilidad del fraude y reduce los contracargos.

No es opcional cuando el emisor lo exige, así que el flujo de tu interfaz tiene que contemplar esa verificación intermedia desde el diseño — no como un parche al final. Es de las cosas que se ven en producción antes que en sandbox, y por eso conviene un cobro real de monto mínimo con una tarjeta que lo dispare, antes de abrir al público.

Errores comunes al integrar Culqi

Casi todos vienen del mismo sitio: la integración fue tan rápida que nadie se detuvo a decidir qué pasa cuando el pago no llega por el camino feliz.

Cómo lo hacemos

Integramos Culqi y Niubiz en sistemas en producción, con webhooks idempotentes, conciliación y facturación resueltas — no solo el botón de pago. Te ayudamos a elegir la pasarela correcta para tu etapa.

Conocemos el camino completo: la integración de la pasarela, el cruce con tu contabilidad y la factura electrónica ante SUNAT. Si tu sistema necesita cobrar en serio, hablemos.

En resumen

Culqi es la forma más rápida de empezar a cobrar en el Perú y la puerta natural a Yape, PagoEfectivo y Cuotéalo por su vínculo con Credicorp. Dos cosas deciden si la integración envejece bien: partir de la versión vigente —v2, v3 y v4 de CulqiJS ya no reciben soporte— y tratar los webhooks como parte del diseño, no como un extra, porque en cuanto aceptas un método asíncrono el navegador deja de ser una fuente de verdad. Con eso resuelto, la facilidad de Culqi deja de ser una trampa y pasa a ser lo que promete.