VibeFox CCAvenue for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior, con la extensión OpenSSL (se usa para cifrar la solicitud y descifrar la respuesta). El módulo no se deja instalar con versiones anteriores de PHP ni sin OpenSSL.

Cuenta de CCAvenue: necesitas una cuenta de comerciante de CCAvenue con Merchant ID, Access Code y Working Key. El Access Code y la Working Key se emiten para un dominio web, así que genéralos para el dominio de esta tienda. CCAvenue usa las mismas credenciales para el entorno de pruebas; CCAvenue debe habilitar el acceso de pruebas en tu cuenta. El módulo usa los endpoints de CCAvenue India.

Moneda: la moneda del carrito se envía a CCAvenue tal cual. Las cuentas de CCAvenue aceptan INR por defecto; otras monedas requieren procesamiento multidivisa en tu cuenta de CCAvenue.

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 VibeFox CCAvenue Payment más tarde 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 Merchant ID, el Access Code y la Working Key de tu panel de CCAvenue y activa Enable/Disable.

5. Mantén Test mode activado mientras pruebas y desactívalo después para aceptar pagos reales.

Al instalarse, el módulo crea dos estados de pedido: Awaiting CCAvenue payment y CCAvenue payment on hold. PrestaShop activa el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox CCAvenue Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa cuando CCAvenue está activado pero falta el Merchant ID, el Access Code o la Working Key (en ese caso el método de pago se oculta en la finalización de compra hasta que se completen los tres), muestra CCAvenue test mode is on: customers are sent to test.ccavenue.com and no real money is taken. mientras el modo de pruebas está activado, y te recuerda el procesamiento multidivisa cuando la moneda predeterminada de la tienda no es INR.

CCAvenue

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

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 guardado en el pedido. Por defecto: CCAvenue.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

Credenciales de API

Inicia sesión en tu panel de comerciante de CCAvenue (M.A.R.S.) y abre Settings > API Keys. Genera el Access Code y la Working Key para el dominio de esta tienda. Los espacios de las credenciales se eliminan al guardar.

Merchant ID: tu Merchant ID numérico de CCAvenue. Si contiene algo distinto de dígitos, al guardar se muestra el mensaje CCAvenue: the Merchant ID must contain digits only — the previous value was kept., se conserva el valor guardado anteriormente y se guardan los demás ajustes.

Access Code: el Access Code de este sitio web (Settings > API Keys).

Working Key: la Working Key (clave de cifrado) de este sitio web. Cifra la solicitud de pago y es la única forma de verificar la respuesta de CCAvenue, así que mantenla en secreto. Una Working Key guardada nunca vuelve a mostrarse. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.

Clear saved Working Key: marca la casilla y haz clic en Save para eliminar la Working Key guardada. Un campo vacío mantiene el valor guardado.

Test mode: envía a los clientes al entorno de pruebas de CCAvenue (test.ccavenue.com). CCAvenue usa el mismo Merchant ID, Access Code y Working Key para pruebas y para producción; CCAvenue debe habilitar el acceso de pruebas en tu cuenta. En modo de pruebas, la finalización de compra muestra TEST MODE: no real transactions will be processed. debajo del método de pago. Por defecto: activado. Desactívalo para pagos reales.

URL de retorno

CCAvenue devuelve al cliente a la dirección que aparece en esta sección. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_ccavenue_payment/return, posiblemente con un código de idioma como /en/. El módulo envía esta URL con cada pago (como URL de redirección y de cancelación), así que no hay nada que configurar en CCAvenue. Debe pertenecer al dominio registrado en CCAvenue.

Avanzado

Debug log: escribe los eventos de CCAvenue en logs/ccavenue_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Solo se registran las referencias de pedido, los ID de seguimiento y los estados; las claves, los datos de tarjeta, los correos y las direcciones no se registran. Por defecto: desactivado. Mientras está desactivado no se escribe nada, tampoco los errores.

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

Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan sus ajustes, el registro y las referencias de pedido de CCAvenue. Los pedidos y los estados de pedido del módulo se conservan. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto CCAvenue) y confirma. Una página muestra Thank you for your order. You are being redirected to CCAvenue to complete the payment. y envía al cliente a la página de pago de CCAvenue. Sin JavaScript, el cliente hace clic en Pay via CCAvenue o en Back to checkout. En este punto todavía no existe ningún pedido.

Cada intento recibe una nueva referencia de pedido de CCAvenue formada por el número de carrito y la hora. El total y la moneda del carrito, los datos de facturación, la dirección de entrega (cuando es distinta de la de facturación) y un token secreto del intento se envían en la solicitud cifrada. Los nombres y las direcciones se depuran para dejar solo los caracteres y longitudes que acepta CCAvenue; el país y el estado se envían como nombres y el teléfono solo como dígitos. El cliente elige la tarjeta, la banca en línea, UPI, la billetera o EMI en la página de CCAvenue.

Tras el pago, CCAvenue devuelve al cliente con una respuesta cifrada. El pedido solo se marca como pagado cuando CCAvenue lo confirma: la respuesta debe descifrarse con tu Working Key, pertenecer a un intento de esta tienda y tener el mismo importe y la misma moneda que los enviados y que el total del carrito. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your CCAvenue payment has been received. En un pago Awaited, la página muestra Your CCAvenue payment is awaiting confirmation from your bank. The order will be processed as soon as the payment is confirmed. Tras una discrepancia de importe o moneda, muestra Your payment was received and is being reviewed by the shop. Si un pedido en espera se cancela o falla después sin pago, la página de confirmación muestra Your CCAvenue payment was not completed. Please contact us about this order.

Si el pago falla, el cliente vuelve a la finalización de compra con Payment was not completed. Please try again or choose a different payment method. Si el cliente cancela en la página de CCAvenue, el mensaje es Payment was cancelled. You may try again. Si no se puede verificar la respuesta, el mensaje es We could not confirm the payment result. If your account was charged, please contact us before paying again. En estos casos no se crea ningún pedido y el carrito se conserva, así que el cliente puede volver a pagar. Si el carrito ya tiene un pedido, un nuevo intento va directamente a la página de confirmación de ese pedido en lugar de a un segundo pago.

El resultado solo se toma del regreso del cliente desde CCAvenue: no hay notificaciones de servidor a servidor ni consultas de estado. Si el cliente cierra el navegador antes de volver, no se crea ningún pedido; comprueba el pago en el panel de CCAvenue. El módulo no incluye reembolsos desde PrestaShop, ni tarjetas guardadas, suscripciones o pagos recurrentes, ni formulario de tarjeta en el sitio, ni soporte para CCAvenue UAE u otras plataformas regionales.

Pedidos

Estados del pedido

No order yet: el cliente fue enviado a CCAvenue y no ha vuelto, o el pago falló o se canceló. Solo existe el carrito. Comprueba el pago en el panel de CCAvenue si el cliente no vuelve.

Payment accepted: el pago fue confirmado. El pago se registra con el ID de seguimiento de CCAvenue como ID de transacción, y una nota muestra la referencia bancaria, el ID de seguimiento y el modo de pago.

Awaiting CCAvenue payment: CCAvenue informó el pago como Awaited (el banco todavía no lo ha confirmado). El pedido nunca se marca como fallido mientras el dinero aún pueda cobrarse. Verifícalo en el panel de CCAvenue antes de procesar el pedido. Una respuesta posterior con el mismo ID de seguimiento se aplica igualmente: Success pone Payment accepted, Failure pone Payment error y Aborted pone Canceled.

CCAvenue payment on hold: CCAvenue confirmó un pago cuyo importe o moneda difiere del carrito o de lo enviado (por ejemplo, el carrito se modificó en otra pestaña después de iniciar el pago), o el cliente pagó después de que el pedido se hubiera cancelado. La nota muestra el importe recibido y el esperado. El importe que informó CCAvenue se registra como pago del pedido cuando la moneda coincide. Comprueba el pago en el panel de CCAvenue y después procesa el pedido o reembolsa el pago.

Un fallo tardío nunca cambia un pedido pagado. Si llega otro pago correcto para un pedido que ya está pagado (por ejemplo, desde dos pestañas del navegador), el pedido no se modifica. Una nota te pide reembolsar el duplicado en el panel de CCAvenue.

Bloque de pago de CCAvenue

La página del pedido muestra un bloque CCAvenue payment con el ID de pedido de CCAvenue, el ID de seguimiento, el estado, la referencia bancaria, el modo de pago y el nombre de la tarjeta, el importe enviado y el recibido, la fecha y el mensaje de CCAvenue, y una insignia Test mode para los pagos de prueba. Las notas de CCAvenue son mensajes privados del pedido, visibles solo en el back office.

Reembolsos

Los reembolsos desde PrestaShop no son compatibles. Reembolsa el pago en el panel de CCAvenue y después registra el reembolso en PrestaShop manualmente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox CCAvenue Payment es el primer bloque de Modules > Module Manager > VibeFox CCAvenue Payment > Configure, por encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-ccavenue y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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. 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, CCAvenue 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. La tienda online 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 aviso en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando cuando el cliente vuelve de CCAvenue.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. 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 hace falta ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

CCAvenue no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que las tres credenciales están configuradas: Merchant ID, Access Code y Working Key. La página de ajustes muestra una advertencia cuando falta alguna. En Payment > Preferences, comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo de clientes.

El pago se completó, pero no se creó ningún pedido: el cliente no volvió de CCAvenue a tu tienda, por ejemplo porque cerró el navegador. El módulo no tiene notificaciones de servidor a servidor. Comprueba el pago en el panel de CCAvenue y crea o actualiza el pedido manualmente.

Todos los pagos terminan con We could not confirm the payment result: la respuesta no se puede descifrar. La Working Key es incorrecta, pertenece a otro dominio o se copió con caracteres adicionales. Genera las claves para el dominio de esta tienda y pégalas de nuevo. Activa Debug log y revisa el campo Log en la página del módulo.

CCAvenue muestra un error antes de la página de pago: comprueba que el Access Code y la Working Key se generaron para este dominio, que la URL de retorno pertenece al dominio registrado en CCAvenue y, en modo de pruebas, que CCAvenue activó el acceso de pruebas en tu cuenta. Para una moneda distinta de INR, el procesamiento multidivisa debe estar activado en tu cuenta de CCAvenue.

El cliente ve This payment method is temporarily unavailable: falta una de las credenciales o el total del carrito es cero. Debug log muestra el motivo.

El cliente ve This payment method is not available: el módulo está desactivado o no está permitido para la moneda del carrito, el país o el grupo de clientes en Payment > Preferences.

El cliente ve Payment gateway error: encryption failed: la solicitud no se pudo cifrar. Comprueba que la extensión OpenSSL de PHP está instalada.

El Merchant ID no cambia al guardar: el valor contiene algo distinto de dígitos. Introduce solo los números de tu Merchant ID.

El pedido está en CCAvenue payment on hold o Awaiting CCAvenue payment: lee la nota del pedido (ver Estados del pedido). Comprueba el pago en el panel de CCAvenue y después procesa el pedido o reembolsa el pago.

Para desarrolladores, el módulo tiene el hook actionCcavenueRequestParams (cambia los datos enviados a CCAvenue antes del cifrado, por ejemplo de merchant_param2 a merchant_param5; los valores no deben contener &; no cambies amount, currency, order_id ni merchant_param1).

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox CCAvenue Payment y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. La confirmación te recuerda que los ajustes y las referencias de CCAvenue se conservan, salvo que esté activado Delete data on uninstall. Si está activado, se eliminan los ajustes del módulo, el registro y las referencias de pedidos de CCAvenue. Si está desactivado, todo se conserva para una reinstalación posterior. Los estados de pedido Awaiting CCAvenue payment y CCAvenue payment on hold siempre se conservan. Los pedidos existentes mantienen sus notas de pago y sus ID de transacción.

CCAvenue es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por CCAvenue.