VibeFox Cashfree 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.

HTTPS: Cashfree envía los webhooks solo a URL https://. Sin HTTPS los pagos se confirman igualmente 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 el de producción, y un webhook en el Cashfree Merchant Dashboard (véase Configuración). La clave secreta también se usa para verificar los webhooks, así que no hay una clave de webhook aparte. La moneda del carrito 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 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 Cashfree Payments en la lista de módulos y haz clic en Configure.

3. Introduce 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 (ver Clave de licencia).

4. Introduce el Sandbox App ID y la Sandbox Secret Key, añade el webhook en el Cashfree Merchant Dashboard (véase Configuración), activa Enable/Disable, haz clic en Save y prueba un pago.

5. Cuando estés listo, introduce el App ID y la Secret Key de producción, desactiva Sandbox Mode y haz clic en Save.

Al instalarse, el módulo crea el estado de pedido Cashfree payment on hold. PrestaShop ofrece un 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 Cashfree Payments > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página explica que el pedido solo se crea después de que Cashfree confirme el pago. 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 se oculta 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 un método de pago activado sin las claves del modo seleccionado, un aviso indica que seguirá oculto en la finalización de compra hasta que se configuren.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments activa o desactiva el método de pago. Por defecto: off.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Cashfree Payments. Obligatorio.

Description: el texto que aparece debajo del método de pago en la finalización de compra. Por defecto: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

Obtén el App ID y la Secret Key en el Cashfree Merchant Dashboard, en Developers > API Keys. Las claves de prueba y las de producción son distintas.

Sandbox 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. debajo del método de pago. Por defecto: on. Desactívalo para los pagos reales.

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.

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.

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 secrets: marca una Secret Key y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.

Los pagos mantienen el entorno en el que se crearon. Sus webhooks se verifican, su estado se comprueba y sus reembolsos se envían con las claves de ese entorno, así que mantén las claves de sandbox rellenadas hasta que los pagos de sandbox estén liquidados tras el cambio a producción.

Webhook

El webhook informa a tu tienda de que un pago se realizó, falló o fue reembolsado. En el Cashfree Merchant Dashboard ve a Developers > Webhooks y añade la URL que aparece en Webhook URL en esta sección, con los eventos Payment y Refund. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_cashfree_payment/webhook. Copia la URL exactamente como la muestran los ajustes. En una tienda con HTTPS, el módulo también pasa esta URL a Cashfree con cada pago. Si tu tienda no usa HTTPS, esta sección muestra un aviso.

El módulo gestiona estos eventos (también aparecen en esta sección):

Cashfree firma cada webhook con tu clave secreta. Los webhooks sin una firma válida se rechazan. Un webhook debe estar firmado con la clave secreta del entorno en el que se hizo el pago, así que una clave de sandbox nunca confirma un pago real. Los webhooks firmados de pagos que no inició esta tienda (por ejemplo, otra tienda con la misma cuenta de Cashfree) se aceptan y se ignoran. Sin el webhook, el pedido solo se crea cuando el cliente vuelve a la tienda después de pagar. Si el cliente cierra el navegador después de pagar, solo el webhook (o el siguiente intento de pago del mismo carrito) puede crear el pedido.

Advanced

API Version: la versión de la API de Cashfree que se va a usar.

Order ID prefix: los ID de pedido de Cashfree se forman como prefijo + ID del carrito de PrestaShop; un nuevo intento para el mismo carrito recibe un número al final (por ejemplo, 123-2). Déjalo vacío para usar el prefijo automático de esta tienda, que aparece 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. Los demás caracteres se eliminan al guardar y se muestra un aviso.

Debug log: los errores siempre se registran. Cuando está activado, las llamadas a la API de Cashfree y los webhooks también se escriben en logs/cashfree_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos de los clientes nunca se registran. Por defecto: off.

Log: muestra el tamaño y las entradas más recientes 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 Cashfree y el registro del módulo. Los pedidos, sus transacciones y reembolsos de Cashfree y el estado de pedido Cashfree payment on hold siempre se conservan, para que los pedidos existentes sigan funcionando. Por defecto: off.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto, Cashfree Payments) y confirma. El módulo crea un pedido de Cashfree por el total del carrito en la moneda del carrito y abre una página de pago que muestra Redirecting to Cashfree for payment... y carga la página de pago de Cashfree. Si no se abre sola, el cliente puede hacer clic en Pay Now. En la página de pago 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. El correo electrónico y el teléfono de facturación del cliente se envían a Cashfree. En este punto todavía no existe ningún pedido.

Después de 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 solicitud del servidor a Cashfree cuando el cliente regresa. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. El retorno también funciona en otro navegador, por ejemplo cuando el cliente vuelve desde una aplicación de UPI. Si el banco aún no ha confirmado el pago, una página Payment confirmation 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. y un botón Check again; el webhook crea el pedido en cuanto el banco confirma el pago.

Si el pago falla o el cliente abandona la página de Cashfree sin pagar, vuelve a la finalización de compra con The Cashfree payment was not completed. Please try again or choose another payment method. El carrito se conserva. Un pago abierto de Cashfree se reutiliza cuando el cliente vuelve a intentarlo. Si el total del carrito cambió o la sesión está a punto de caducar, el pedido antiguo de Cashfree se cierra y se crea uno nuevo, para que el carrito no se pueda pagar dos veces. Si el carrito ya se pagó en Cashfree pero no se registró, el siguiente intento crea el pedido en lugar de volver a cobrar.

Si Cashfree no puede iniciar el pago, el cliente se queda en la finalización de compra con 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 de carrito 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, y el método de pago no se muestra para ese carrito.

El webhook funciona mientras la tienda está en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.

El módulo acepta solo 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 COD a través de Cashfree ni enlaces de pago, y no hace conversión de moneda: el carrito se cobra en la moneda del carrito.

Pedidos y reembolsos

Order statuses

No order yet: el cliente fue enviado a Cashfree y no ha pagado, el pago falló o el pago sigue pendiente en el banco. Solo existe el carrito.

Payment accepted: el pago fue confirmado. El pago se registra con el ID de pago de Cashfree como ID de transacción, y una nota muestra el ID de transacción y el grupo del método de pago (por ejemplo, upi o credit_card).

Cashfree payment on hold: Cashfree informó de un importe o una moneda pagados que no coinciden con el total del carrito (por ejemplo, el carrito se cambió en otra pestaña después de iniciar el pago). La nota muestra el importe esperado y el recibido y el ID de transacción. Comprueba el pago en el panel de Cashfree y, después, completa el pedido o reembolsa el pago.

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

Un pago que llega después de que el pedido fue cancelado se sigue registrando y el pedido vuelve a quedar pagado, porque el dinero fue cobrado. Un pedido pagado nunca vuelve atrás por un pago fallido posterior.

Cashfree payment block

La página del pedido muestra un bloque Cashfree payment con el ID de transacción, el pedido de Cashfree, el estado del pago, el importe pagado y reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las Cashfree notes del pedido.

Refunds

En el bloque Cashfree payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Cashfree. Confirma la pregunta Refund this amount through Cashfree? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta el acceso a las páginas de Modules. Los reembolsos se hacen por el importe y en la moneda que cobró Cashfree, 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 al pedido de Cashfree que se pagó, en el entorno (sandbox o producción) en el que se pagó, así que las claves de ese entorno deben estar configuradas. Si Cashfree no acepta el reembolso, o lo informa como cancelado o rechazado, el bloque muestra el error y no se registra ningún reembolso. Un reembolso iniciado se añade al historial de reembolsos y a las notas con su ID, importe y estado. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que Cashfree haya confirmado el pago.

El estado final del reembolso llega mediante el webhook de reembolso y se añade a las notas. 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 Cashfree.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Cashfree Payments es el primer bloque de Modules > Module Manager > VibeFox Cashfree Payments > Configure, por encima de los ajustes. Introduce 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-cashfree 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 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 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. Eliminar la clave de la tienda 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 se inicia un pago de todas formas, el cliente ve This payment method is not available. Please choose another one. La tienda no sabe que has iniciado sesión en el back office, así que el método de pago también queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. En Modules > Module Manager, en la pestaña Alerts, aparece un recordatorio. 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 necesitan 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 tras introducir la clave, y después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

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 tiene sus claves: Sandbox App ID y Sandbox Secret Key en modo sandbox, App ID y Secret Key en modo de producción. La página de ajustes muestra un aviso cuando faltan las claves. El método de pago también se oculta cuando el total del carrito está por debajo del mínimo de Cashfree. 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 webhook no funciona. Comprueba que tu tienda usa HTTPS, que la URL en Developers > Webhooks es exactamente la que aparece en Webhook URL y que los eventos Payment están seleccionados. Comprueba que la clave secreta de los ajustes pertenece al entorno en el que se hizo el pago. El panel de Cashfree muestra la respuesta de tu tienda para cada webhook. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar, y en el siguiente intento de pago del mismo carrito.

El webhook responde Missing signature o Invalid signature: la llamada no llevaba una firma válida de Cashfree, o la clave secreta de los ajustes no coincide con el entorno en el que se hizo el pago. Comprueba que las claves de sandbox y de producción no están intercambiadas.

El webhook responde Ignored: el webhook está firmado correctamente, pero pertenece a un pago que no inició esta tienda, por ejemplo otra tienda con la misma cuenta de Cashfree. Asigna a cada tienda su propio Order ID prefix.

El webhook responde Busy, retry later: otra solicitud estaba creando el pedido en ese mismo momento, o el pedido no pudo crearse (por ejemplo, el módulo está desactivado). Cashfree reintenta el webhook. Activa Debug log para ver el motivo.

El cliente ve The Cashfree payment page could not be loaded: el script de Cashfree no se pudo cargar en el navegador, por ejemplo por un bloqueador. El cliente puede hacer clic de nuevo en Pay Now o en Choose another payment method.

El cliente ve We could not start the Cashfree payment: mira el campo Log de la página del módulo. 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 We could not verify the payment: el enlace de retorno no coincidía con el carrito. Si se cobró dinero, el webhook igualmente crea el pedido. Comprueba el pago en el panel de Cashfree antes de que el cliente vuelva a pagar.

El pedido está en Cashfree payment on hold tras el pago: lee las notas del bloque Cashfree payment (véase Estados de pedido) y, después, completa el pedido o reembolsa el pago.

El reembolso falla con un mensaje sobre el modo sandbox o de producción: el pago se hizo en ese entorno, y sus claves de API no están configuradas. Introdúcelas y vuelve a intentarlo.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Cashfree Payments 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 Cashfree y el registro. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Las transacciones y reembolsos de Cashfree y el estado de pedido Cashfree payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Cashfree es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Cashfree ni cuenta con su aprobación.