VibeFox Culqi for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con 3.0.5.0) o 4.0.2 y posteriores (probado con 4.1.0.3).

PHP: 8.0 o posterior.

Moneda de la tienda: el sol peruano (PEN) o el dólar estadounidense (USD) deben estar habilitados como moneda de tu tienda. Culqi no acepta otras monedas, y el método de pago solo se muestra cuando el cliente paga 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 (prueba) se obtienen en integ-panel.culqi.com, y las claves de producción (reales) en mipanel.culqi.com, en CulqiPanel > Desarrollo > API Keys. La clave pública la usa la ventana emergente de Culqi en el navegador. La clave secreta se usa solo en tu servidor y nunca se envía al navegador. No se necesita ningún webhook.

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

Instalación

La descarga es un único archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_culqi_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_culqi_payment.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_culqi_payment-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, por lo que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Culqi Payment y haz clic en Install (el botón verde +). Tu usuario de administrador necesita permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (ver Clave de licencia).

4. Pega las claves de integración y, para los pagos reales, las claves de producción (ver 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.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_culqi_payment.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas, en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Culqi Payment, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las claves de Culqi como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, 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. Avisa cuando la pasarela está habilitada pero faltan las claves del modo actual, y cuando ninguna moneda habilitada 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 cuando el cliente paga en una moneda compatible. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, un valor incorrecto no se guarda y conserva su valor anterior, mientras que los demás campos sí se guardan. La página muestra un error para cada campo así: una clave con un prefijo incorrecto (por ejemplo Live Secret Key must start with sk_live_ — the previous value was kept.), un Title vacío o de más de 128 caracteres, un Sort Order que no es un número entero, un Total que no es un número mayor o igual que 0, o una zona geográfica o un estado de pedido que no existe.

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, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmar. Por defecto: Pay securely with your credit/debit card or Yape via Culqi.

Sort Order: la posición de Culqi entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece Culqi solo a las direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la compra, en la moneda predeterminada de la tienda, que un pedido debe alcanzar antes de que se ofrezca Culqi. Déjalo vacío para ofrecer Culqi con cualquier total.

Claves de API

Copia las claves desde CulqiPanel > Desarrollo > API Keys: las claves de integración (prueba) en integ-panel.culqi.com y las de producción en mipanel.culqi.com (la página incluye los enlaces). El modo de prueba usa solo las claves de prueba, y el modo real solo las claves reales. Cada clave debe empezar por el prefijo de su campo.

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 reales. Mientras está activado, los clientes ven TEST MODE: No real charges will be made. en el paso Confirm Order.

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 no 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. Para eliminar una clave secreta guardada, marca Clear the saved key on save debajo del campo y haz clic en Save.

Métodos de pago

Las tarjetas siempre se ofrecen. La transferencia bancaria, los agentes, las billeteras y Cuotéalo necesitan la API de Órdenes de Culqi, y esta extensión no los ofrece.

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

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). El pedido recibe un estado solo cuando Culqi ha confirmado el cobro. Cada uno de los campos siguientes muestra los estados de pedido de tu OpenCart.

Order Status After Payment: Culqi confirmó el cobro y su importe y su moneda coinciden con el pedido. Por defecto: Processing.

On Hold (Review) Status: Culqi cobró un importe o una moneda que no coinciden con el pedido, o no capturó el pago. Una nota explica qué revisar en CulqiPanel. Por defecto: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Refunded Status: el pago se reembolsó por completo desde la página del pedido. Los reembolsos parciales solo añaden una nota. Por defecto: Refunded.

Avanzado

Debug log: registra las peticiones a la API y los pasos del pago en culqi_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se traslada a culqi_p_debug.old.log.php. Los errores, incluidos los rechazos de tarjetas con su código, siempre se registran. Las claves, los datos de tarjeta y los datos de los clientes 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 la extensión se eliminan los ajustes de la pasarela y el registro. Los cobros y reembolsos de Culqi siempre se conservan, así que los pedidos pagados antes pueden reembolsarse tras una reinstalación. Por defecto: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves secretas no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves secretas guardadas se conservan.

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto Credit/Debit Card or Yape (Culqi)). En el paso Confirm Order el cliente ve tu descripción, y OpenCart crea el pedido, todavía sin estado. Cuando el cliente hace clic en Confirm Order, se abre la ventana emergente de Culqi Checkout en la misma página, con el nombre de tu tienda, el total del pedido y la moneda. Allí el cliente introduce los datos de la tarjeta o paga con Yape. Los scripts de Culqi siempre se cargan desde Culqi. En OpenCart 4, el cliente elige el método de pago con el botón Choose del bloque de métodos de pago, en la ventana Payment method options, y hace clic en Confirm Order en el bloque de confirmación de la parte inferior de la página de finalización de compra. Si la tienda no pide una dirección de pago (valor predeterminado de OpenCart 4), los datos del cliente enviados con el cobro se toman de la dirección de envío y del nombre del cliente.

Culqi convierte los datos de pago en un token de un solo uso, y solo ese token llega a tu tienda. Tu servidor crea el cobro con la API de Cargos de Culqi por el total del pedido en la moneda del pedido, capturado de inmediato. El cobro aparece en CulqiPanel como Order y el número de pedido, con el correo electrónico del cliente. El pedido solo se marca como pagado después de que Culqi lo confirme. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart.

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. Tras 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 después de Payment failed: y puede intentarlo de nuevo con otra tarjeta en el mismo paso. 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. En estos casos el pedido queda sin estado y una nota en el historial del pedido registra el intento. Si el cliente cierra la ventana de Culqi, no se cobra nada y se puede volver a pulsar el botón Confirm Order. El carrito se conserva en todos estos casos.

Un pedido nunca se cobra dos veces. Si el cliente envía de nuevo el formulario mientras se está procesando un pago del mismo pedido, 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 establecer el estado del 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 con el mismo carrito establece el estado del pedido a partir de él, sin un nuevo cobro. Un carrito solo se paga una vez: si otro pedido del mismo carrito (OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order) ya está pagado, el cliente pasa a la página de éxito y no se le vuelve a cobrar. OpenCart 4 mantiene un pedido para la finalización de compra y lo actualiza, así que tras una tarjeta rechazada el cliente paga el mismo pedido.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró entretanto (por ejemplo, se canceló o se reembolsó), o ya está pagado y el carrito ha cambiado desde entonces (otros productos o cantidades), Confirm Order devuelve al cliente a la finalización de compra, donde se crea un pedido nuevo del carrito con su propio pago. Un pedido pagado y cerrado después ya no retiene el carrito.

La extensión solo acepta pagos únicos con tarjeta y Yape, capturados de inmediato. No incluye app bancaria, agentes, billeteras ni Cuotéalo, ni tarjetas guardadas, suscripciones o cuotas, ni webhooks de Culqi, ni autorización y captura por separado.

Pedidos y reembolsos

Estados de pedido

No status (missing order): el cliente todavía no ha pagado, la tarjeta fue rechazada o Culqi no respondió. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders. Las notas del historial del pedido explican los intentos fallidos.

Order Status After Payment (default Processing): el cobro fue confirmado y coincide con el pedido. Una nota muestra Culqi payment successful con el modo (prueba o real), 3-D Secure si se usó, y el ID del cobro de Culqi (chr_...).

On Hold (Review) Status (default Pending): Culqi informó de un cobro cuyo importe o moneda no coincide con el pedido, o de un pago autorizado pero no capturado. La nota lo explica y muestra el ID del cobro. Revisa el cobro en CulqiPanel y después completa el pedido o reembolsa el pago.

Refunded Status (default Refunded): el pago se reembolsó por completo a través de la extensión.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Culqi Payment

En Sales > Orders abre un pedido pagado con Culqi. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Culqi Payment muestra el Charge ID con una etiqueta Test en los pagos de prueba, el Amount cobrado (con 3-D Secure si se usó), una indicación Review para los pedidos en espera, los importes Paid / refunded, el formulario de reembolso, el historial de reembolsos y las Culqi notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña VibeFox Culqi Payment introduce el Amount (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), 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 modificar la extensión (se configura en System > Users > User Groups). Los reembolsos se hacen por el importe y en la moneda que Culqi cobró, así que tras una diferencia de importe puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía con las claves del modo en que se realizó el pago (prueba o real), incluso si has cambiado de modo después, así que la clave secreta de ese modo debe estar configurada. Si Culqi no acepta el reembolso, la pestaña muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID del reembolso de Culqi, el importe y tu motivo. Un reembolso total pone el pedido en Refunded Status sin notificar al cliente y sin devolver los productos al stock, igual que un cambio manual de estado. Un reembolso parcial no cambia el estado.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Culqi. Los reembolsos hechos en CulqiPanel no se sincronizan con OpenCart. Actualiza el pedido manualmente si es necesario.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Culqi Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit, 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: opencart-payment-culqi y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen inglés y 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 cambiar la dirección de la tienda, o de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Quitar la clave de la tienda no libera su plaza de dominio. Libérala 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. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del panel de administración, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel de administración: 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 ningún cron job. Desinstalar la extensión siempre elimina la clave de licencia y el estado de la licencia.

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 real) y que el cliente pague en PEN o USD. La página de ajustes muestra una advertencia cuando faltan claves. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

El pago se realizó, pero el pedido se queda sin estado: la extensión no usa webhooks. El cobro solo se confirma con la respuesta de Culqi a tu servidor. Si Culqi no respondió a tiempo, el pedido tiene la nota Culqi did not confirm the charge. Busca el cobro de este pedido en CulqiPanel. Si el cliente vio el mensaje de que el pedido no se pudo completar, el siguiente intento de pago en la misma sesión del cliente establece el estado sin volver a cobrar.

El pedido está en el estado de revisión tras el pago: lee las notas de la pestaña VibeFox Culqi Payment. El importe o la moneda cobrados no coincidían con el pedido, o el pago no se capturó. Revisa el cobro en CulqiPanel 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 solo acepta claves de su propio 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 mientras la página de finalización de compra estaba 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 una extensión 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 estaba abierta en otra sesión. Recargar la página lo soluciona.

El cliente ve This payment method is not available.: la sesión de finalización de compra ya no tiene un pedido de Culqi, o el método de pago se desactivó entretanto. El cliente debe recargar la finalización de compra.

Una tarjeta fue rechazada y quieres saber el motivo: lee la nota del pedido o el campo Log de la página de la extensión. Los rechazos se registran con el código de rechazo de Culqi, incluso cuando Debug log está desactivado.

No hay formulario de reembolso en la pestaña: la pestaña indica el motivo: el pago está reembolsado por completo, tu grupo de usuarios no tiene permiso para modificar la extensión, o falta la clave secreta del modo de pago.

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

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Culqi Payment. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, claves, Yape, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los cobros y reembolsos de Culqi siempre se conservan, así que los pedidos pagados antes pueden reembolsarse tras una reinstalación. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Culqi Payment en la lista de extensiones instaladas, y luego en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Culqi es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por Culqi.