VibeFox Culqi for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

Moneda de la tienda: sol peruano (PEN) o dólar estadounidense (USD). Culqi no acepta otras monedas, y el método de pago solo se muestra para carritos en PEN o USD.

Cuenta de Culqi: necesitas la clave pública y la clave secreta de tu cuenta de Culqi. Las claves de integración (de prueba) se obtienen en integ-panel.culqi.com, y las de producción (en vivo) en mipanel.culqi.com, en CulqiPanel > Desarrollo > API Keys. La clave pública la usa la ventana de Culqi en el navegador. La clave secreta se usa solo en tu servidor y nunca se envía al navegador. No se necesita webhook.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

1. En el back office, ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca más tarde VibeFox Culqi Payment en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).

4. Pega las claves de integración y, para los pagos reales, las claves de producción (véase Configuración).

5. Activa Enable/Disable y haz clic en Save. Mantén Test Mode activado mientras pruebas, y desactívalo para cobrar pagos reales.

6. Asegúrate de que PEN o USD sea una moneda activa de tu tienda.

Al instalarse, el módulo crea el estado del pedido Culqi payment on hold. PrestaShop ofrece el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Culqi Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Test mode is active: the integration keys are used and no real money is charged. mientras el modo de prueba está activado. La página avisa cuando la pasarela está activada pero faltan las claves del modo actual, y cuando ninguna moneda de la tienda es compatible con Culqi. En ambos casos el método de pago se oculta en la finalización de compra. Si tu moneda predeterminada no es PEN ni USD, la página indica que Culqi solo se ofrece para carritos en las monedas compatibles.

Culqi

Enable/Disable: Enable Culqi Payment Gateway activa o desactiva el método de pago. Por defecto: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Credit/Debit Card or Yape (Culqi). Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely with your credit/debit card or Yape via Culqi.

Claves de API

Copia las claves de CulqiPanel > Desarrollo > API Keys: las claves de integración (de prueba) en integ-panel.culqi.com, y las de producción en mipanel.culqi.com. El modo de prueba usa solo las claves de prueba, y el modo en vivo solo las claves reales. Cada clave debe empezar por el prefijo de su campo. Una clave con el prefijo incorrecto no se guarda: la página muestra un error, por ejemplo Live Secret Key must start with sk_live_ — the previous value was kept., y los demás campos se guardan.

Test Mode: cuando está activado, se usan las claves de prueba (pk_test_ / sk_test_) y no se cobra dinero real. Por defecto: activado. Desactívalo para cobrar pagos reales con las claves en vivo. Mientras está activado, los clientes ven TEST MODE: No real charges will be made. debajo del método de pago.

Test Public Key: la clave pública del entorno de integración. Empieza por pk_test_.

Test Secret Key: la clave secreta del entorno de integración. Empieza por sk_test_ y nunca se comparte con el navegador.

Live Public Key: la clave pública del entorno de producción. Empieza por pk_live_.

Live Secret Key: la clave secreta del entorno de producción. Empieza por sk_live_ y nunca se comparte con el navegador.

Las claves secretas guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.

Clear saved secret keys: marca Test Secret Key o Live Secret Key y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.

Métodos de pago

Las tarjetas siempre se ofrecen. La transferencia bancaria, los agentes, las billeteras y Cuotéalo necesitan la Culqi Orders API, y este módulo no los ofrece.

Yape: Offer Yape in the Culqi popup muestra Yape junto a las tarjetas en la ventana de Culqi. Por defecto: activado.

Avanzado

Debug log: registra las solicitudes a la API y los pasos del pago en logs/culqi_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores, incluidos los rechazos de tarjeta con su código, siempre se registran. Las claves, los datos de tarjeta y los datos del cliente nunca se registran. Por defecto: desactivado.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete Data on Uninstall: cuando está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela, los registros de cobros y reembolsos de Culqi del módulo, y el registro. El estado del pedido y los datos de Culqi de los pedidos (pagos, notas) siempre se conservan. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Credit/Debit Card or Yape (Culqi)) y hace clic en el botón de realizar pedido. La ventana de Culqi Checkout se abre en la misma página con el nombre de tu tienda, el total del carrito y la moneda. Allí el cliente introduce los datos de la tarjeta o paga con Yape. Los scripts de Culqi se cargan solo en la página de finalización de compra.

Culqi convierte los datos de pago en un token de un solo uso, y el token se envía a tu tienda. Tu servidor crea el cobro con la Culqi Charges API por el total del carrito en la moneda del carrito, capturado de inmediato. El cobro aparece en CulqiPanel como Cart y el número del carrito, con el correo electrónico del cliente. Antes de este punto no existe ningún pedido. El pedido se marca como pagado solo después de que Culqi lo confirme: el pedido se crea cuando Culqi responde con un cobro correcto, y el cliente ve la página estándar de confirmación del pedido.

Si el banco exige 3-D Secure, el cliente ve Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Después de la autenticación, el cobro se envía de nuevo automáticamente. Si la verificación no se completa, el cliente ve The 3-D Secure verification was not completed. Please try again or use another card.

Si la tarjeta es rechazada, el cliente ve el mensaje de Culqi, por ejemplo Payment failed: seguido del motivo, y puede volver a intentarlo con otra tarjeta. Si Culqi no responde, el cliente ve We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Si el cliente cierra la ventana de Culqi, no se cobra nada, el cliente ve The payment window was closed before the payment was completed. y puede volver a realizar el pedido. El carrito se conserva en todos estos casos. Los intentos fallidos se escriben en el registro del módulo, porque todavía no existe ningún pedido.

Un carrito nunca se cobra dos veces. Si el cliente vuelve a enviar el pedido mientras se está procesando un pago del mismo carrito, ve This order is already being paid. Please wait a moment and check your email before trying again. Si Culqi cobró el dinero pero no se pudo crear el pedido, el cliente ve Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. El cobro se conserva y el siguiente intento crea el pedido a partir de él, sin un nuevo cobro.

El módulo acepta solo pagos únicos con tarjeta y Yape, capturados de inmediato. No tiene códigos PagoEfectivo ni CIP, app bancaria, agentes, monederos ni Cuotéalo, ni tarjetas guardadas, suscripciones o cuotas, ni webhooks de Culqi, ni autorización y captura por separado.

Pedidos y reembolsos

Estados del pedido

No order yet: la tarjeta fue rechazada, el cliente cerró la ventana de Culqi o Culqi no respondió. Solo existe el carrito. El registro del módulo tiene los detalles.

Payment accepted: el cobro fue confirmado y coincide con el carrito. El pago se registra con el ID del cobro de Culqi (chr_...) como ID de transacción, y una nota indica el modo (prueba o en vivo) y si se usó 3-D Secure.

Culqi payment on hold: Culqi informó de un cobro cuyo importe o moneda no coincide con el carrito, o de un pago autorizado pero no capturado. La nota lo explica e indica el ID del cobro. Un cobro capturado en la moneda del carrito se registra como un pago por el importe realmente cobrado. Revisa el cobro en CulqiPanel y, después, completa el pedido o reembolsa el pago.

Refunded: el pago fue reembolsado por completo a través del módulo.

Si llega un segundo cobro para un carrito que ya tiene un pedido, el pedido no cambia. Una nota te pide que revises el cobro en CulqiPanel y, si hace falta, lo reembolses.

Bloque de pago de Culqi

La página del pedido muestra un bloque Culqi payment con el ID del cobro, el importe cobrado (con 3-D Secure si se usó), una etiqueta Test para los pagos de prueba, una indicación de revisión para los pedidos en espera, los importes pagados y reembolsados, y el historial de reembolsos.

Reembolsos

En el bloque Culqi payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Culqi. Confirma la pregunta Refund this amount through Culqi? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; el acceso a los módulos no es necesario. Los reembolsos se hacen por el importe y en la moneda que cobró Culqi, así que, si el importe no coincidió, puedes reembolsar hasta lo que el cliente pagó realmente, y no el total del pedido. El reembolso se envía con las claves del modo en el que se hizo el pago (prueba o en vivo), aunque hayas cambiado de modo después, por lo que la clave secreta de ese modo debe estar configurada. Si Culqi no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas del pedido, con el ID del reembolso de Culqi, el importe y tu motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.

El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Culqi. Los reembolsos hechos en CulqiPanel no se sincronizan con PrestaShop. Actualiza el pedido manualmente si es necesario.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Culqi Payment es el primer bloque de Modules > Module Manager > VibeFox Culqi Payment > Configure, por encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-culqi y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de que cambie la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Culqi no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. La tienda pública no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No se necesita ninguna tarea cron. Al desinstalar o restablecer el módulo, la clave de licencia y el estado de la licencia siempre se eliminan.

Solución de problemas

Culqi no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que estén configuradas ambas claves del modo actual (Test Public Key y Test Secret Key en modo de prueba, Live Public Key y Live Secret Key en modo en vivo) y que la moneda del carrito sea PEN o USD. La página de ajustes muestra una advertencia cuando faltan claves. En Payment > Preferences, comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.

El pago se realizó, pero no se creó ningún pedido: el módulo no usa webhooks. El cobro solo se confirma con la respuesta de Culqi a tu servidor. Si Culqi no respondió a tiempo, el registro del módulo indica Culqi did not confirm the charge con el número del carrito. Busca el cobro con este cart_id en CulqiPanel. Si el cliente vio el mensaje de que no se pudo completar el pedido, el siguiente intento de pago del mismo carrito crea el pedido sin volver a cobrar.

El pedido está en Culqi payment on hold tras el pago: lee la nota del pedido. El importe o la moneda cobrados eran distintos del carrito, o el pago no se capturó. Revisa el cobro en CulqiPanel (su ID está en la nota) y, después, completa el pedido o reembolsa el pago.

La clave no se guarda: el error indica que el campo debe empezar por un prefijo, por ejemplo sk_live_. Cada campo acepta solo claves de su tipo y modo: pk_test_, sk_test_, pk_live_ o sk_live_.

El cliente ve Payment gateway misconfiguration. Please contact the store owner.: faltan las claves del modo actual, o Culqi rechazó la clave secreta. Revisa las claves en los ajustes.

El cliente ve Payment token is invalid. Please try again.: el token de la ventana de Culqi pertenece al otro modo, por ejemplo tras cambiar Test Mode con la página de finalización de compra abierta. El cliente debe recargar la página y pagar de nuevo.

La ventana de Culqi no se abre: el cliente ve The Culqi payment window could not be loaded. Please reload the page and try again. Comprueba que los scripts de js.culqi.com y 3ds.culqi.com no estén bloqueados en tu página de finalización de compra, por ejemplo por un módulo de caché u optimización.

El cliente ve Security check failed. Please reload the page and try again.: la página de finalización de compra estuvo abierta demasiado tiempo o en otra sesión. Recargar la página lo soluciona.

El cliente ve This order is already being paid: otra solicitud de pago del mismo carrito se estaba procesando en el mismo momento. El cliente debe esperar y revisar el correo electrónico antes de volver a intentarlo.

Se rechazó una tarjeta y quieres saber el motivo: revisa el campo Log en la página del módulo. Los rechazos se registran con el código de rechazo de Culqi, aunque Debug log esté desactivado.

El reembolso falla con un mensaje sobre las claves: el pago se hizo en modo de prueba o en vivo, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Culqi Payment y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes de la pasarela, los registros de cobros y reembolsos de Culqi del módulo, y el registro. Los pedidos pagados antes ya no se pueden reembolsar desde la página del pedido. Si está desactivado, todo se conserva para una reinstalación posterior. El estado del pedido Culqi payment on hold siempre se conserva. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.

Culqi es una marca registrada de su respectivo propietario. Este módulo no está afiliado a Culqi ni cuenta con su respaldo.