Cómo integrar Culqi con WooCommerce en tu tienda peruana

Integrar Culqi con WooCommerce es de las cosas más rápidas que vas a hacer al armar una tienda virtual peruana. Veinte minutos bien hechos y ya cobras con tarjeta. Lo que toma más tiempo no es la integración técnica: es entender qué te conviene activar, cómo se comportan las comisiones según el tipo de tarjeta, y qué pasa cuando un cliente disputa un pago. Esta guía cubre las dos partes.

Culqi es la pasarela peruana más usada por tiendas pequeñas y medianas. Acepta Visa, Mastercard, American Express, Diners y desde hace tiempo también Yape. La comisión base ronda 3,44% a 3,99% más IGV según la tarjeta, sin mensualidad ni mantenimiento. Para una tienda nueva, es la combinación de costo y facilidad técnica más razonable del mercado.

Lo que necesitas antes de empezar

Una cuenta de Culqi creada y aprobada. Si todavía no la tienes, entra a culqi.com, regístrate con el RUC de tu empresa, sube los documentos que te pide (DNI del representante, ficha RUC, vigencia de poder si aplica, voucher de cuenta bancaria) y espera la aprobación. Suele tomar entre 24 y 72 horas hábiles. Sin la cuenta aprobada no puedes salir a producción, solo modo test.

Una tienda WooCommerce funcional. Con productos cargados, dirección configurada, página de checkout activa. Si vienes de la guía anterior sobre cómo crear una tienda con WooCommerce, ya tienes todo.

Acceso al panel de WordPress como administrador. Para instalar el plugin y pegar las llaves API.

Tu llave pública y tu llave privada de Culqi. Estas las encuentras en el dashboard de Culqi, sección Desarrolladores, API Keys. Hay dos pares: uno de test (empieza con pk_test_ y sk_test_) y uno de producción (pk_live_ y sk_live_). Empieza siempre con las de test.

Paso 1: instalar el plugin oficial de Culqi para WooCommerce

Hay dos plugins oficiales de Culqi en el repositorio de WordPress: Culqi para WooCommerce y Culqi para WooCommerce Suscripciones. Para una tienda normal usas el primero. El segundo es para pagos recurrentes.

En el panel de WordPress, ve a Plugins, Añadir nuevo, busca «Culqi WooCommerce». Instala y activa. Si por alguna razón el repositorio no lo muestra, descarga el ZIP desde el GitHub oficial de Culqi y súbelo manualmente desde Plugins, Subir plugin.

Una vez activado, vas a verlo aparecer en WooCommerce, Ajustes, pestaña Pagos, junto a las pasarelas que ya tenías.

Paso 2: configurar las llaves API en modo test

Entra a WooCommerce, Ajustes, Pagos. Vas a ver Culqi en la lista. Haz clic en «Gestionar» o «Configurar». Te abre la pantalla de ajustes del plugin.

Marca «Habilitar Culqi». Pon el título que va a ver el cliente en el checkout. Algo claro como «Tarjeta de crédito o débito (Culqi)». La descripción opcional debajo le explica al cliente que el pago es seguro y que se procesa con Culqi.

Modo de operación: déjalo en «Modo de pruebas» (test). En los campos de llaves, pega la llave pública de test (pk_test_…) y la llave privada de test (sk_test_…). Guarda los cambios.

En «Tipos de tarjeta aceptados» marca Visa, Mastercard, Amex, Diners según lo que negociaste con Culqi (todas vienen activas por defecto, pero conviene confirmar).

Si quieres aceptar Yape vía Culqi, activa la opción «Aceptar Yape». Va a aparecer como método separado en el checkout del cliente.

Paso 3: probar el flujo de compra con tarjetas de testing

Culqi te da números de tarjeta de prueba para validar el flujo sin mover plata real. Los más usados:

Tarjeta aprobada: 4111 1111 1111 1111, CVV 123, fecha cualquier mes futuro. El cobro debe completar sin problemas.

Tarjeta rechazada: 4000 0000 0000 0002, mismos CVV y fecha. Debe fallar y mostrar el mensaje de error correcto.

Tarjeta con autenticación 3D Secure: 4111 1111 1111 1118, simula el flujo de OTP que algunos bancos exigen.

Haz una compra real desde el frontend de tu tienda, llega al checkout, selecciona Culqi, y prueba al menos las tres tarjetas. Verifica que: el pedido se cree en el panel de WooCommerce con el estado correcto (procesando o completado según tu configuración), llegue el correo de confirmación al cliente, llegue el correo de nuevo pedido al admin, el inventario baje en una unidad.

Si alguna de estas piezas falla, el problema casi siempre está en la configuración de correos de WooCommerce o en un conflicto con otro plugin, no en Culqi.

Paso 4: pasar a modo producción

Cuando ya verificaste que el flujo funciona en test, regresa a WooCommerce, Ajustes, Pagos, Culqi. Cambia el modo de «Pruebas» a «Producción». Reemplaza las llaves de test (pk_test_, sk_test_) por las llaves de producción (pk_live_, sk_live_) que copiaste del dashboard de Culqi.

Guarda. Desde ese momento, cualquier compra en tu tienda mueve plata real.

Haz una primera compra real tú mismo con tu propia tarjeta, monto chico (S/5 o S/10). Verifica que el cargo aparezca en tu tarjeta, que el pedido se cree, que Culqi te muestre la transacción en su dashboard. Si todo cuadra, ya estás en operación.

Luego anula esa primera compra desde el dashboard de Culqi para recuperar tu S/10. Sirve como prueba viva de que también sabes operar reembolsos.

Cómo se calculan las comisiones que te cobra Culqi

La comisión base que se publica es 3,44% más IGV (4,06% efectivo). Hay variaciones según:

Tipo de tarjeta. Las tarjetas de crédito tienen comisión más alta que las de débito. Las internacionales (turistas comprando en tu web) suelen tener un recargo adicional.

Volumen mensual. Si tu tienda factura sobre S/30.000 al mes con Culqi, puedes pedir una renegociación de tarifa. Culqi suele aceptar bajar 0,3 a 0,5 puntos porcentuales con volúmenes consistentes.

Cuotas sin intereses. Si activas pago en cuotas sin intereses para el cliente, Culqi asume el costo y te lo descuenta a ti como comisión extra. Verifica antes de activarlo si tu margen lo aguanta.

Yape vía Culqi. La comisión por Yape es diferente a la de tarjetas. Confirma la tarifa actual en tu contrato.

Lo importante: el cliente nunca debe pagar la comisión por encima del precio. Si trasladas la comisión al precio final visible, Indecopi puede considerar publicidad engañosa. Asume la comisión dentro de tu margen o ajusta el precio de lista incluyendo ese costo desde el inicio.

Cómo manejar reembolsos y disputas

Reembolso parcial o total: desde el dashboard de Culqi, sección Transacciones, eliges la transacción y haces clic en «Reembolsar». Puedes devolver el total o un monto parcial. El dinero le regresa al cliente entre 5 y 15 días hábiles según el banco emisor de su tarjeta.

Anulación: si el cobro fue hecho ese mismo día y aún no se cerró el lote bancario, la anulación es instantánea para el cliente. Si ya pasó al siguiente día, técnicamente es un reembolso, no una anulación.

Disputa o contracargo. Si un cliente desconoce un cobro ante su banco, Culqi te notifica por correo. Tienes un plazo limitado (suele ser 5 a 7 días hábiles) para enviar documentación que pruebe que la compra fue legítima: pedido, correos, comprobante de envío, firma de recepción. Si no respondes, el dinero se devuelve al cliente automáticamente y a ti te cobran una comisión por contracargo aparte.

Recomendación: guarda evidencia de cada pedido. Trackings de courier con firma. Conversaciones con el cliente. Foto del paquete entregado. Cuando llegue una disputa, tener todo organizado es la diferencia entre defender tu venta y perderla.

Errores comunes al integrar Culqi con WooCommerce

Pegar las llaves de test en el modo producción y al revés. El cliente paga «exitosamente» en tu sitio pero el cargo nunca llega al banco porque era test. O peor: el cobro real falla porque las llaves no concuerdan con el modo.

No probar el flujo end-to-end antes de salir. Te enteras del bug cuando el primer cliente real reclama por WhatsApp.

Olvidar configurar la página de «Gracias por tu compra». Si el cliente paga y queda en una pantalla en blanco, asume que la compra falló y te llama. WooCommerce trae una página de Order Received por defecto; asegúrate de que esté activa.

No habilitar 3D Secure cuando corresponde. Los bancos peruanos exigen autenticación 3DS para muchas transacciones. Si lo desactivas para «agilizar», vas a ver más rechazos en lugar de menos.

Activar todas las pasarelas a la vez. Culqi, Izipay, Niubiz, Mercado Pago, Yape directo, transferencia bancaria, contra entrega. El cliente se paraliza ante 7 opciones y abandona. Empieza con Culqi solo. Suma otras pasarelas cuando tu volumen lo justifique.

No actualizar el plugin. Culqi saca actualizaciones de seguridad cada cierto tiempo. Si dejas el plugin sin actualizar por meses, te expones a vulnerabilidades.

Cuándo conviene Culqi y cuándo conviene cambiar

Culqi te sirve si: tu volumen mensual está debajo de S/50.000, vendes principalmente a Perú, quieres una integración rápida con plugin oficial, y necesitas aceptar Yape sin tener que sumar otro proveedor.

Conviene evaluar alternativas cuando: tu volumen supera S/50.000 al mes (Niubiz o Izipay pueden ofrecer mejor comisión por volumen), vendes mucho a clientes corporativos B2B (Izipay tiene mejor flujo de factura con SUNAT), o estás expandiendo a varios países latinoamericanos (Mercado Pago opera regional).

No hace falta que cambies para siempre. Es perfectamente válido mantener Culqi como pasarela principal y sumar Izipay o Niubiz como secundaria cuando llegas a volumen. El cliente elige.

Preguntas frecuentes sobre integrar Culqi con WooCommerce

¿Cuánto cobra Culqi por transacción en una tienda WooCommerce?

La comisión base es 3,44% más IGV por transacción, lo que sale efectivamente alrededor de 4,06%. Las tarjetas de débito suelen tener una comisión ligeramente menor que las de crédito, y las internacionales pueden tener un recargo. Si facturas sobre S/30.000 al mes, puedes renegociar a la baja.

¿Necesito tener empresa con RUC para usar Culqi?

Sí. Culqi exige RUC activo, ficha RUC vigente, DNI del representante legal y voucher de cuenta bancaria a nombre de la empresa. No opera con personas naturales sin RUC.

¿Cuánto tarda Culqi en aprobar mi cuenta?

Entre 24 y 72 horas hábiles después de subir todos los documentos. Si la cuenta queda observada, el plazo se extiende hasta que envíes la documentación faltante o aclares la observación.

¿En cuántos días me deposita Culqi el dinero de las ventas?

El plazo estándar es de 2 a 3 días hábiles después de la transacción, con depósito a la cuenta bancaria que registraste. Algunos planes con volumen permiten liquidación más rápida.

¿Culqi acepta Yape en el checkout de mi tienda?

Sí. Desde el plugin de Culqi para WooCommerce puedes activar Yape como método separado en el checkout. El cliente elige Yape, escanea el QR o ingresa su número, y completa el pago desde su app.

¿Qué pasa si un cliente desconoce un cobro ante su banco?

Culqi te notifica por correo. Tienes un plazo limitado para enviar documentación que pruebe la legitimidad del pedido. Si no respondes a tiempo, el dinero regresa al cliente y a ti te cobran una comisión por contracargo.

¿Puedo trasladar la comisión de Culqi al precio final que ve el cliente?

No conviene hacerlo de forma explícita en el checkout porque Indecopi puede considerarlo publicidad engañosa. Lo recomendable es ajustar el precio de lista incluyendo el costo de comisión desde el inicio, sin sumarlo al final como recargo.

¿El plugin de Culqi es gratis?

Sí, el plugin oficial de Culqi para WooCommerce es gratuito y está en el repositorio de WordPress. El costo de operar con Culqi viene de las comisiones por transacción, no del plugin.

¿Qué hago si una compra falla en el checkout?

Revisa primero los logs en el dashboard de Culqi, sección Transacciones, para entender el motivo del rechazo (tarjeta sin saldo, datos incorrectos, 3DS no completado, fraude detectado). El mensaje que muestra Culqi suele indicar la causa exacta.

¿Puedo usar Culqi y Izipay al mismo tiempo en la misma tienda?

Sí. Configuras ambas pasarelas en WooCommerce y el cliente elige en el checkout. Solo evita sobrecargar al cliente con demasiadas opciones; dos pasarelas bien justificadas (Culqi para tarjetas y Yape, Izipay para corporativos) funcionan mejor que cinco mezcladas.