VibeFox Culqi for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

WooCommerce: 6.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

Moneda de la tienda: sol peruano (PEN) o dólar estadounidense (USD). Culqi no acepta otras monedas, y el método de pago se oculta en la finalización de compra con cualquier otra moneda de la tienda.

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 emergente de Culqi en el navegador. La clave secreta se usa solo en tu servidor y nunca se envía al navegador. No hace falta ningún webhook.

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

Instalación

1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_culqi_payment a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Culqi > Manage, o haz clic en Settings bajo el nombre del plugin en la página de Plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

5. Pega las claves de integración y, para pagos reales, las claves de producción (consulta Configuración).

6. Activa Enable/Disable. Mantén Test Mode activado mientras pruebas y desmárcalo después para aceptar pagos reales.

7. Comprueba que la moneda de la tienda sea PEN o USD.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Culqi. Sobre 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. Te avisa cuando la pasarela está activada pero faltan las claves del modo actual, y cuando Culqi no admite la moneda de la tienda. En ambos casos el método de pago se oculta en la finalización de compra. En la lista de métodos de pago, Culqi aparece marcado como pendiente de configurar hasta que se definan las dos claves del modo actual.

General

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. Por defecto: Credit/Debit Card or Yape (Culqi).

Description: el texto que se muestra bajo el 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 desde 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 en vivo. Cada clave debe empezar por el prefijo de su campo. Una clave con un prefijo incorrecto no se guarda: la página muestra un error y conserva el valor anterior.

Test Mode: Use the Culqi integration (test) environment. Si está activado, se usan las claves de prueba (pk_test_ / sk_test_) y no se cobra dinero real. Por defecto: activado. Desmárcalo para aceptar pagos reales con las claves en vivo.

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.

Si actualizas desde la versión 1.0, el único par de claves de esa versión se traslada a los campos de prueba o en vivo según su prefijo. Revisa las claves después de la actualización.

Métodos de pago

Las tarjetas siempre se ofrecen. La transferencia bancaria, los agentes, los monederos y Cuotéalo necesitan la Culqi Orders API y este plugin 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: Log API requests and payment steps escribe los detalles en WooCommerce > Status > Logs, con la fuente wcp_culqi_payment. Los errores siempre se registran. Las claves, los datos de la tarjeta y los datos del cliente nunca se registran. Por defecto: desactivado.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Desactivar el plugin nunca borra nada. Los datos de Culqi guardados en los pedidos se conservan siempre. Por defecto: desactivado.

Finalización de compra

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 el pedido. La ventana emergente de Culqi Checkout se abre en la misma página con el nombre de tu tienda, el total del pedido y la moneda. Ahí el cliente introduce los datos de la tarjeta o paga con Yape. Mientras el modo de prueba está activado, el método de pago muestra TEST MODE: No real charges will be made.

Culqi convierte los datos de pago en un token de un solo uso, y la finalización de compra se envía a tu tienda con ese token. Tu servidor crea el cobro con la Culqi Charges API por el total del pedido en la moneda del pedido, con el número de pedido en la descripción del cobro. El pedido se marca como pagado solo después de que Culqi confirme el cobro y de que el importe y la moneda cobrados coincidan con el pedido. Luego el cliente pasa a la página de pedido recibido.

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, por ejemplo Payment failed: seguido del motivo, y puede intentarlo de nuevo 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 método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) de WooCommerce.

El plugin solo acepta 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 pagos en cuotas, ni webhooks de Culqi, ni autorización y captura por separado.

Pedidos y reembolsos

Estados del pedido

Pending payment: el pedido se creó pero aún no se ha cobrado, o Culqi no respondió. En ese caso una nota dice Culqi did not confirm the charge. Busca en CulqiPanel un cobro de este pedido antes de aceptar otro pago.

Processing: el pago se confirmó (el valor predeterminado de WooCommerce; los pedidos con solo productos virtuales descargables pasan a Completado). La nota del pedido muestra el ID del cobro de Culqi, el modo (de prueba o en vivo) y si se usó 3-D Secure. El ID de transacción es el ID del cobro de Culqi.

On hold: Culqi informó de un cobro cuyo importe o moneda no coincide con el pedido, o de un pago que se autorizó pero no se capturó. La nota del pedido lo explica y muestra el ID del cobro. Comprueba el cobro en CulqiPanel y completa o reembolsa el pedido manualmente.

Failed: la tarjeta fue rechazada. La nota del pedido muestra el motivo, el código de rechazo y el ID del cobro. El cliente puede volver a pagar con otra tarjeta.

Un pedido que ya está pagado o que ya tiene un cobro de Culqi, incluido un pedido en espera, nunca se vuelve a cobrar. Solo se procesa a la vez una solicitud de pago por pedido.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Culqi. Se admiten reembolsos totales y parciales. El reembolso se envía con las claves del modo en el que se hizo el pago (de prueba o en vivo), aunque hayas cambiado de modo desde entonces, así que la clave secreta de ese modo debe estar definida. Si Culqi no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID del reembolso de Culqi, el importe y el motivo.

Los reembolsos hechos en CulqiPanel no se sincronizan con WooCommerce. Si hace falta, crea un reembolso manual en WooCommerce sin Refund via Culqi.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Culqi. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un dominio. Quitar la clave de un sitio 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 de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda con sesión iniciada siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un aviso en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los reembolsos siguen funcionando.

Cuando caduca una licencia, el plugin sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

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 definidas las dos 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 de la tienda sea PEN o USD. La página de ajustes muestra un aviso en cada uno de estos casos.

El pago se realizó, pero el pedido sigue en Pending payment: el plugin no usa webhooks. El cobro solo se confirma con la respuesta de Culqi a tu servidor. Si Culqi no respondió a tiempo, la nota del pedido dice Culqi did not confirm the charge. Busca el cobro de este pedido en CulqiPanel y, si existe, completa el pedido manualmente.

El pedido está en On hold tras el pago: lee la nota del pedido. El importe o la moneda cobrados diferían del pedido, o el pago no se capturó. Comprueba el cobro en CulqiPanel (su ID está en la nota) y después completa o reembolsa el pedido.

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 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 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 plugin de optimización.

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

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á definida. Introdúcela e inténtalo de nuevo.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.

Para desarrolladores, la documentación del plugin enumera los filtros culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon y culqi_p_lock_timeout.

Desinstalación

Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros se eliminan solo si Delete Data on Uninstall estaba activado. De lo contrario se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Culqi es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Culqi ni cuenta con su respaldo.