VibeFox Cashfree 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.
HTTPS: Cashfree solo envía los webhooks a URL https://. Sin HTTPS los pagos se siguen confirmando cuando el cliente vuelve a la tienda, pero activa HTTPS antes de pasar a producción.
Cuenta de Cashfree: necesitas el App ID y la clave secreta de tu cuenta de Cashfree, por separado para el entorno de prueba (sandbox) y para el de producción, y un webhook en el Merchant Dashboard de Cashfree (consulta Configuración). La clave secreta también se usa para verificar los webhooks, así que no hay un secreto de webhook aparte. La moneda del pedido debe estar habilitada en tu cuenta de Cashfree.
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_cashfree_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > Cashfree Payments > Manage, o haz clic en Settings debajo del nombre del plugin en la página 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. Introduce el Sandbox App ID y la Sandbox Secret Key, añade el webhook en el Merchant Dashboard de Cashfree (consulta Configuración), activa Enable/Disable y prueba un pago.
6. Cuando estés listo, introduce el App ID y la Secret Key de producción y desmarca Sandbox Mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Cashfree Payments. Cuando el método de pago está activado, la página te avisa si faltan las claves de API del modo seleccionado (en ese caso el método de pago queda oculto en la finalización de compra) y muestra Sandbox mode is on: customers see a test checkout and no real money is charged. mientras el modo sandbox está activado. Si guardas una pasarela activada sin las claves del modo seleccionado, un mensaje de error indica que el método de pago seguirá oculto en la finalización de compra hasta que se configuren.
General
Enable/Disable: Enable Cashfree Payments 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: Cashfree Payments.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.
Modo y claves de API
Obtén el App ID y la clave secreta en el Merchant Dashboard de Cashfree, en Developers > API Keys. Las claves de prueba y de producción son distintas; introduce cada una en su sección.
Sandbox Mode: Enable Sandbox (test) mode usa el sandbox de Cashfree para las pruebas. No se cobra dinero real y la finalización de compra muestra SANDBOX MODE - no real payments will be processed. Por defecto: activado. Desmárcalo para los pagos reales.
Credenciales de sandbox
Sandbox App ID: el App ID de tu entorno de prueba de Cashfree.
Sandbox Secret Key: la clave secreta de tu entorno de prueba de Cashfree.
Credenciales de producción
App ID: el App ID de tu entorno de producción de Cashfree.
Secret Key: la clave secreta de tu entorno de producción de Cashfree.
Los pedidos conservan el entorno en el que se crearon. Sus webhooks se verifican y sus reembolsos se envían con las claves de ese entorno, así que mantén rellenas las claves de sandbox hasta que se resuelvan los pedidos de sandbox tras pasar a producción.
Webhook
El webhook avisa a tu tienda de que un pago se realizó, falló o se reembolsó. En el Merchant Dashboard de Cashfree ve a Developers > Webhooks y añade la URL que se muestra en esta sección, con los eventos Payment y Refund. Tiene el aspecto de https://your-site/wc-api/cashfree_p/?action=webhook. En un sitio con HTTPS, el plugin también pasa esta URL a Cashfree con cada pedido. Si tu sitio no usa HTTPS, esta sección muestra un aviso.
El plugin gestiona estos eventos:
Cashfree firma cada webhook con tu clave secreta. Los webhooks sin una firma válida se rechazan. Los webhooks firmados de pedidos que no creó esta tienda (por ejemplo, de otra tienda con la misma cuenta de Cashfree) se confirman y se ignoran. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda tras pagar. Si el cliente cierra el navegador después de pagar, solo el webhook puede confirmar el pedido.
Avanzado
API Version: la versión de la API de Cashfree que se usa.
Order ID prefix: los ID de pedido de Cashfree se forman como prefijo + ID del pedido de WooCommerce; un intento repetido recibe un número al final. Déjalo vacío para usar el prefijo automático de este sitio, que se muestra en la descripción del campo. Usa un prefijo distinto para cada tienda conectada a la misma cuenta de Cashfree. Solo letras, dígitos, "_" y "-", hasta 20 caracteres. Al guardar, los demás caracteres se eliminan y se muestra un aviso.
Debug log: Log Cashfree API events for debugging. Los errores siempre se registran. Si está activado, las llamadas a la API y los webhooks también se escriben en WooCommerce > Status > Logs, origen wcp_cashfree_payment. Las claves y los datos de clientes nunca se registran. Por defecto: desactivado.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Si está activado, al eliminar el plugin se borran los ajustes de Cashfree, los registros del plugin y las referencias de Cashfree guardadas en los pedidos. Los pedidos en sí se conservan. Por defecto: desactivado.
Finalizar compra
El cliente elige el método de pago (por defecto, Cashfree Payments) y realiza el pedido. El plugin crea un pedido en Cashfree por el total del pedido en la moneda del pedido y abre la página Pay for order, que muestra Redirecting to Cashfree for payment... y carga la página de pago de Cashfree. Si no se abre por sí sola, el cliente puede hacer clic en Pay Now. En la página de Cashfree, el cliente paga con cualquier método activado en tu cuenta de Cashfree, por ejemplo tarjeta, UPI, banca en línea o billetera digital.
Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Cashfree lo confirma: mediante el webhook firmado o mediante una petición de servidor a Cashfree cuando el cliente vuelve. Si el banco todavía no ha confirmado el pago, la página de pedido recibido muestra Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.
Si el pago falla o el cliente sale de la página de Cashfree sin pagar, vuelve a la página Pay for order con The Cashfree payment was not completed. Please try again or choose another payment method. Un pago abierto de Cashfree se reutiliza cuando el cliente vuelve a intentarlo. Si el total del pedido cambió o la sesión está a punto de caducar, el pedido antiguo de Cashfree se cierra y se crea uno nuevo, de modo que el pedido no se pueda pagar dos veces. Si el pedido ya estaba pagado en Cashfree pero no se registró, el siguiente intento registra el pago en lugar de volver a cobrarlo.
Si Cashfree no puede iniciar el pago, el cliente ve We could not start the Cashfree payment. Please try again or choose another payment method. El motivo técnico se escribe en el registro. Un total del pedido inferior al mínimo de Cashfree (1 unidad de la moneda; 0,01 para BHD, JOD, KWD y OMR, y 0,1 para TND) no se puede pagar con Cashfree.
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 de WooCommerce (HPOS). Los textos que ve el cliente están traducidos al hindi.
El plugin solo acepta pagos únicos en la página de pago de Cashfree. No tiene tarjetas guardadas, suscripciones ni pagos recurrentes, ni autorización y captura por separado, ni widget de ofertas de Cashfree, ni pago contra reembolso (COD) o enlaces de pago a través de Cashfree, y no hace conversión de moneda: el pedido se cobra en la moneda del pedido.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a Cashfree y todavía no ha pagado, o el pago sigue pendiente en el banco. Cuando el cliente vuelve con un pago pendiente, una nota indica que el plugin espera el webhook de Cashfree.
Processing: el pago fue confirmado (los pedidos con solo productos virtuales descargables pasan a Completado, el valor por defecto de WooCommerce). La nota del pedido muestra el ID de la transacción de Cashfree y el grupo del método de pago. El ID de transacción del pedido es el ID de pago de Cashfree. Un pago que llega después de que el pedido se cancelara se registra igualmente, porque el dinero ya se cobró.
On hold: Cashfree informó de un importe o una moneda pagados distintos al total del pedido. La nota del pedido muestra el importe esperado y el recibido, y el ID de la transacción. Revisa el pago en el panel de Cashfree y completa o reembolsa el pedido manualmente.
Failed: el pago falló o se canceló en Cashfree. La nota muestra el estado y el motivo de Cashfree. Cada nuevo intento fallido añade una nota.
Un pedido pagado nunca vuelve atrás por un webhook o un retorno posterior.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Cashfree Payments (el botón muestra el título del método de pago). Se admiten reembolsos totales y parciales. El reembolso se envía al pedido de Cashfree que se pagó, en el entorno (sandbox o producción) en el que se pagó, así que deben estar configuradas las claves de ese entorno. Si Cashfree no acepta el reembolso, o lo informa como cancelado o rechazado, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso iniciado se añade a las notas del pedido con su ID, importe y estado. El estado final llega mediante el webhook de reembolso como otra nota del pedido.
Los webhooks de estado de reembolso solo se añaden como notas. No se registran automáticamente como reembolsos de WooCommerce.
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 > Cashfree Payments. 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Cashfree 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 que hayan iniciado sesión 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 Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Cashfree no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga sus claves: Sandbox App ID y Sandbox Secret Key en modo sandbox, o App ID y Secret Key en modo de producción. El método de pago también se oculta cuando el total del pedido está por debajo del mínimo de Cashfree. La página de ajustes muestra un aviso cuando faltan las claves.
El pago se realizó, pero el pedido sigue en Pendiente de pago: el webhook no funciona. Comprueba que tu sitio use HTTPS, que la URL en Developers > Webhooks sea exactamente la que se muestra en los ajustes y que estén seleccionados los eventos de Payment. Comprueba también que la clave secreta de los ajustes pertenezca al entorno en el que se pagó el pedido. El pedido también se confirma cuando el cliente vuelve a la tienda tras pagar, y en el siguiente intento de pago.
El webhook responde Missing signature o Invalid signature: la llamada no traía una firma válida de Cashfree, o la clave secreta de los ajustes no coincide con el entorno en el que se creó el pedido. Cashfree reintenta el webhook.
El webhook responde Ignored: el webhook está firmado correctamente, pero pertenece a un pedido que no creó esta tienda, por ejemplo de otra tienda con la misma cuenta de Cashfree. Asigna a cada tienda su propio Order ID prefix.
El webhook responde Busy, retry later: otra petición estaba procesando el pedido en ese mismo momento. Cashfree reintenta el webhook.
El cliente ve The Cashfree payment page could not be loaded: el script de Cashfree no pudo cargarse en el navegador, por ejemplo por un bloqueador. El cliente puede volver a hacer clic en Pay Now o en Choose another payment method.
El cliente ve We could not start the Cashfree payment: activa el Debug log y mira en WooCommerce > Status > Logs, origen wcp_cashfree_payment. Los motivos habituales son claves incorrectas para el modo seleccionado o una moneda que no está habilitada en tu cuenta de Cashfree.
El cliente ve The minimum amount for a Cashfree payment is …: el total del pedido está por debajo del mínimo de Cashfree para la moneda.
El cliente ve We could not verify the payment: el enlace de retorno no coincidía con el pedido. Si se cobró el dinero, el webhook igualmente confirma el pedido. Revisa el pago en el panel de Cashfree antes de que el cliente vuelva a pagar.
El pedido está en On hold tras el pago: lee la nota del pedido. El importe o la moneda pagados no coincidían con el pedido. Completa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo sandbox o de producción: el pedido se pagó en ese entorno y sus claves de API no están configuradas. Introdúcelas y vuelve a intentarlo.
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.
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 licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, los datos de Cashfree guardados en los pedidos y los registros se eliminan solo si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago e ID de transacción.
Cashfree es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Cashfree ni cuenta con su respaldo.