Cómo integrar Mercado Pago, Culqi o Izipay en un sistema a medida (no en WordPress)

En este artículo

1. ¿Qué ofrece cada pasarela para un sistema propio?
2. ¿Qué modos de integración existen?
3. Paso 1: modela la orden en tu sistema
4. Paso 2: crea el pago y muestra el formulario
5. Paso 3: confirma el pago con el webhook
6. Paso 4: concilia cada día
7. Paso 5: prueba todos los casos antes de salir a producción
8. Errores que más vemos
9. En resumen
10. Preguntas frecuentes

Si tu web es WordPress con WooCommerce, conectar una pasarela es instalar un plugin y pegar unas llaves. Pero si tienes un sistema propio (de cuotas, reservas, pedidos o membresías, hecho en Laravel, Node, Python o cualquier otro lenguaje), no hay plugin: hay que integrar la pasarela por API.

Este tutorial explica cómo integrar una pasarela de pago en un sistema a medida con Mercado Pago, Culqi o Izipay: qué modos de integración existen, qué piezas debe tener tu sistema, cómo confirmar pagos de forma segura, cómo probar y qué errores evitar. Está pensado para el responsable técnico o el equipo que mantiene el sistema, y para el gerente que quiere entender qué le van a cotizar. En CONIT integramos pasarelas en los sistemas a medida y tiendas que desarrollamos para empresas de todo el Perú.

¿Qué ofrece cada pasarela para un sistema propio?

Las tres pasarelas más usadas en el Perú ofrecen API, librerías, entorno de pruebas y documentación en español. La elección suele depender más de la comisión, de los medios de pago y del tiempo de depósito que de la dificultad técnica.

Tarifas revisadas el 11 de octubre de 2026 en las páginas oficiales; la de Izipay, según sus términos y condiciones. Si quieres la comparación completa de comisiones, la tienes en Izipay vs Culqi vs Niubiz vs Mercado Pago.

¿Qué modos de integración existen?

Hay tres modos, de más simple a más trabajo. Cuanto menos toque tu sistema los datos de la tarjeta, menos riesgo y menos obligaciones de seguridad asumes.

1. Redirección a la página de pago de la pasarela. Tu sistema crea la orden y envía al cliente a pagar a la página de la pasarela, que luego lo devuelve. Es lo más simple y lo más seguro: los datos de la tarjeta nunca pasan por tu sistema.
2. Formulario incrustado. La pasarela te da un formulario o una ventana que se muestra dentro de tu página. El cliente no siente que sale de tu sistema, pero los datos los captura la pasarela. Es el equilibrio que recomendamos en la mayoría de casos.
3. API directa con tokenización. Tu interfaz captura los datos con la librería de la pasarela, que los convierte en un token, y tu servidor cobra con ese token. Da más control del diseño, pero amplía tus obligaciones de seguridad.

La razón de fondo es el estándar PCI DSS, que el PCI Security Standards Council define para cualquiera que acepte, procese o guarde datos de tarjetas. Si tu sistema nunca ve el número de la tarjeta (modos 1 y 2), tu nivel de cumplimiento es mucho más liviano. Si lo guardas o lo procesas, entras en el nivel más exigente. Regla práctica: nunca guardes números de tarjeta en tu base de datos.

Paso 1: modela la orden en tu sistema

Antes de escribir una línea de integración, tu sistema necesita una orden de pago propia, independiente de la pasarela. Es la que da sentido a todo lo demás.

Cada orden debería guardar:

• Un identificador único tuyo (que también enviarás a la pasarela como referencia).
• Qué se cobra: pedido, cuota, membresía, reserva.
• El monto y la moneda, calculados en tu servidor.
• El estado: pendiente, pagada, rechazada, expirada, devuelta.
• El identificador del pago en la pasarela, cuando exista.
• Fechas de creación, pago y última actualización.

Nunca confíes en el monto que llega desde el navegador: cualquiera puede modificarlo. El precio se calcula siempre en el servidor, a partir de lo que el cliente compra.

Paso 2: crea el pago y muestra el formulario

Con la orden creada, tu servidor llama a la API de la pasarela para iniciar el pago (o prepara los datos del formulario incrustado), usando la llave privada, que vive solo en el servidor. La llave pública es la única que puede ir en la página que ve el cliente.

Cada pasarela tiene credenciales de prueba y de producción. Guárdalas en variables de entorno o en un gestor de secretos, nunca dentro del código ni en el repositorio.

Paso 3: confirma el pago con el webhook

El paso más importante: el pago se confirma con el aviso automático de la pasarela (webhook), no con la página de retorno. El cliente puede cerrar el navegador, perder la señal o no volver nunca a tu página, y el pago igual habrá ocurrido.

Tu sistema debe:

1. Exponer una dirección que reciba los avisos de la pasarela.
2. Verificar que el aviso es auténtico. Mercado Pago, por ejemplo, envía una firma en la cabecera x-signature, generada con una clave secreta de tu aplicación, que debes validar antes de procesar nada, según su documentación de webhooks.
3. Consultar el estado del pago a la API antes de actualizar la orden, en lugar de confiar solo en el contenido del aviso.
4. Responder rápido. Mercado Pago espera una respuesta 200 o 201 en un máximo de 22 segundos; si no la recibe, reintenta cada 15 minutos. Si tu proceso es largo (emitir el comprobante, matricular, despachar), responde primero y procesa después en segundo plano.
5. Ser idempotente: si el mismo aviso llega dos veces, la segunda no debe volver a matricular, a descontar stock ni a emitir otra boleta.

Paso 4: concilia cada día

Aunque los webhooks funcionen, una tarea diaria debe comparar las órdenes de tu sistema con los pagos que reporta la pasarela. Así detectas avisos que nunca llegaron, pagos aprobados que siguen como pendientes en tu sistema o devoluciones hechas desde el panel de la pasarela.

La conciliación también es la base para que tu contador cuadre lo vendido con lo depositado, descontando comisiones.

Lo que hacemos en CONIT

Construimos sistemas a medida y páginas web para empresas de todo el Perú con cobros integrados: órdenes, formularios de Mercado Pago, Culqi o Izipay, confirmación por webhook y conciliación. En tiendas como Naos Joyas el pago con tarjeta va en un formulario de Izipay incrustado en la misma página. Conoce el servicio de sistemas a medida.

Paso 5: prueba todos los casos antes de salir a producción

Las pasarelas tienen tarjetas de prueba para simular pagos aprobados, rechazados y pendientes. Prueba al menos estos casos:

Al pasar a producción, cambia todas las credenciales, revisa que la dirección del webhook sea la de producción y haz un pago real pequeño de punta a punta.

Errores que más vemos

• Confirmar el pedido en la página de retorno sin esperar el webhook: se pierden pagos y aparecen pedidos «pagados» que no lo están.
• Confiar en el monto que manda el navegador.
• Llaves privadas en el código o en el repositorio.
• Webhooks sin verificar su firma, que cualquiera podría imitar.
• Procesar dos veces el mismo aviso y emitir dos boletas o matricular dos veces.
• Olvidar las devoluciones: el dinero vuelve al cliente, pero tu sistema sigue mostrando la orden como pagada.
• No conciliar, y descubrir las diferencias al cierre de mes.

Si además quieres cobrar con Yape o QR, mira pagos con QR, Yape y Plin para empresas, y para el panorama completo de cobros dentro de un sistema, cobros con Yape y tarjeta dentro de tu sistema.

En resumen

• Tu sistema necesita una orden propia, con el monto calculado en el servidor y su estado.
• Usa la redirección o el formulario incrustado de la pasarela para que los datos de la tarjeta no pasen por tu sistema y aligerar el cumplimiento PCI DSS.
• El pago se confirma con el webhook, verificando su firma y consultando la API, nunca con la página de retorno.
• Los webhooks deben procesarse una sola vez aunque lleguen repetidos, y una conciliación diaria detecta lo que se escapó.
• Prueba aprobados, rechazos, pendientes, duplicados y devoluciones antes de pasar a producción.

Preguntas frecuentes

¿Qué pasarela es más fácil de integrar en un sistema propio?

Las tres principales del Perú (Mercado Pago, Culqi e Izipay) tienen API, librerías para los lenguajes más usados, entorno de pruebas y documentación en español. La más fácil es la que ofrece el modo de integración que necesitas: redirección a su página de pago si quieres lo más simple, o formulario incrustado si quieres que el cliente no salga de tu sistema.

¿Qué es un webhook en una pasarela de pagos?

Es un aviso automático que la pasarela envía a una dirección de tu sistema cuando pasa algo con un pago: aprobado, rechazado, devuelto. Es la forma confiable de confirmar un pago, porque no depende de que el cliente vuelva a tu página. Tu sistema debe verificar que el aviso viene realmente de la pasarela antes de dar el pedido por pagado.

¿Puedo guardar los datos de la tarjeta en mi sistema?

No deberías. Guardar o procesar números de tarjeta te obliga a cumplir el estándar de seguridad PCI DSS en su nivel más exigente. Las pasarelas resuelven esto con formularios propios y tokens: tu sistema solo guarda una referencia que no sirve fuera de la pasarela, y si necesitas cobros recurrentes, la pasarela guarda la tarjeta por ti.

¿Cuánto cobran las pasarelas por venta en Perú?

Con tarifas publicadas en octubre de 2026: Culqi, 3.44 % con tarjetas nacionales y Yape, más US$ 0.20 por venta; Mercado Pago, 3.49 % + S/ 1.00 con el dinero al instante; Izipay, 3.44 % + IGV más S/ 0.69 + IGV por venta con tarjetas nacionales. Verifica siempre el tarifario vigente antes de elegir.

¿Cuánto demora integrar una pasarela en un sistema a medida?

Una integración básica de cobro único, con webhook y pruebas, suele tomar de una a tres semanas de trabajo, más el tiempo de afiliación y aprobación de la pasarela. Los cobros recurrentes, los reembolsos desde tu sistema y la conciliación automática suman tiempo.

¿Necesito RUC para usar una pasarela de pagos?

Para afiliar un comercio a Culqi o Izipay se pide RUC activo, y la cuenta de vendedor de Mercado Pago también puede ser de empresa. Además, con RUC puedes emitir boletas y facturas electrónicas por cada venta, que es lo que tus clientes empresariales te van a pedir.