VibeFox CCAvenue 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, con la extensión OpenSSL (se usa para cifrar la solicitud y descifrar la respuesta).

Cuenta de CCAvenue: necesitas una cuenta de comerciante de CCAvenue con un Merchant ID, un Access Code y una 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 prueba en tu cuenta. La extensión usa los endpoints de CCAvenue India.

Moneda: la moneda del pedido se envía a CCAvenue tal cual. Las cuentas de CCAvenue aceptan INR de forma predeterminada; otras monedas requieren el 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

El archivo descargado es un único zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_ccavenue_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_ccavenue_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_ccavenue_payment-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, 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 CCAvenue Payment y haz clic en Install (el botón verde +). Tu usuario administrador necesita el 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 (consulta Clave de licencia).

4. Introduce el Merchant ID, el Access Code y la Working Key de tu panel de CCAvenue, activa Enable/Disable y haz clic en Save.

5. Mantén Test mode activado mientras pruebas y desactívalo después para aceptar pagos reales. No hay que configurar nada en el panel de CCAvenue: la dirección de retorno se envía con cada pago.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_ccavenue_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 CCAvenue Payment, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las credenciales de CCAvenue como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de retorno es distinta (ver URL de retorno).

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 CCAvenue 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 una advertencia cuando CCAvenue está activado pero falta el Merchant ID, el Access Code o la Working Key (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 método de pago esté activado en modo de prueba, y te recuerda el procesamiento multidivisa cuando la moneda predeterminada de la tienda no es INR. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío (máximo 128 caracteres), Sort Order debe ser un número entero, Total debe ser un número de 0 o más, y la zona geográfica y los estados de pedido deben existir; si no, no se guarda nada.

CCAvenue

Enable/Disable: Enable CCAvenue Payment Gateway activa o desactiva el método de pago. Predeterminado: 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. Predeterminado: CCAvenue. Obligatorio.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Predeterminado: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

Sort Order: la posición de CCAvenue 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 CCAvenue solo para direcciones de pago dentro de la zona geográfica seleccionada. Predeterminado: 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 debe alcanzar un pedido para que se ofrezca CCAvenue. Déjalo vacío para ofrecer CCAvenue con cualquier total.

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 que no sean dígitos, al guardar se muestra el mensaje CCAvenue: the Merchant ID must contain digits only — the previous value was kept., se mantiene 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 manténla en secreto. Una Working Key guardada nunca se vuelve a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla. Para eliminarla, marca Clear saved Working Key debajo del campo y haz clic en Save.

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 prueba en tu cuenta. En modo de prueba, el paso Confirm Order muestra TEST MODE: no real transactions will be processed. Predeterminado: activado. Desactívalo para los pagos reales.

URL de retorno

CCAvenue devuelve al cliente a la dirección que se muestra en esta sección. En OpenCart 3 tiene la forma https://your-store/index.php?route=extension/payment/wcp_ccavenue_payment/back y en OpenCart 4 la forma https://your-store/index.php?route=extension/wcp_ccavenue_payment/payment/wcp_ccavenue_payment.back. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. La extensión 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.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido faltante). El pedido recibe un estado solo después de verificar la respuesta cifrada de CCAvenue. Un pago fallido o cancelado deja el pedido sin estado y el cliente vuelve a la finalización de compra con el carrito conservado. Cada campo siguiente permite elegir uno de tus estados de pedido de OpenCart.

Order Status After Payment: un pago correcto (estado Success de CCAvenue, con importe y moneda verificados). Predeterminado: Procesando.

Awaiting Payment Status: Awaited: el banco aún no ha confirmado el pago. El pedido recibe Order Status After Payment cuando CCAvenue informa Success para el mismo tracking ID. Predeterminado: Pendiente de pago.

On Hold (Review) Status: CCAvenue informó un importe o una moneda distintos del total del pedido, o llegó un pago para un pedido cancelado. Una nota lo explica. Predeterminado: Pendiente de pago, porque OpenCart no tiene el estado En espera. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Cancelled Payment Status: un pago pendiente se abortó después (Aborted para el mismo tracking ID). Predeterminado: Cancelado.

Failed Payment Status: un pago pendiente falló después (Failure, Invalid o Timeout para el mismo tracking ID). Un fallo de un intento anterior no cambia el pedido. Predeterminado: Fallido.

Avanzado

Debug log: escribe los eventos de CCAvenue en ccavenue_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Solo se registran las referencias de pedido, los tracking IDs y los estados; las claves, los datos de la tarjeta, los correos electrónicos y las direcciones no se registran. Predeterminado: 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 la extensión se eliminan sus ajustes y el registro. Los pedidos y las referencias de pago de CCAvenue se conservan, así que un retorno tardío de un pago antiguo se sigue gestionando tras una reinstalación. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. La Working Key no se exporta.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. La Working Key guardada se conserva.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (predeterminado CCAvenue). En el paso Confirm Order, el cliente ve tu descripción. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, el paso 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. Mientras el navegador va a esa página se muestra un botón Pay via CCAvenue. 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 al final de la página de finalización de compra.

Cada intento recibe una nueva referencia de pedido de CCAvenue formada por el número de pedido de OpenCart y la hora. El total y la moneda del pedido, los datos de facturación, la dirección de entrega (cuando el pedido se envía y la dirección de entrega 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 hasta los caracteres y longitudes que acepta CCAvenue; el país y el estado se envían como nombres y el teléfono como dígitos. El cliente elige la tarjeta, Net Banking, UPI, el monedero electrónico o EMI en la página de CCAvenue. OpenCart 4 no pide una dirección de pago de forma predeterminada; los datos de facturación se toman entonces de la dirección de entrega.

Tras el pago, CCAvenue devuelve al cliente con una respuesta cifrada. El pedido se marca como pagado solo 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 se enviaron y que el total del pedido. 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 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 diferencia de importe o de moneda, muestra Your payment was received and is being reviewed by the store. En OpenCart 4 el navegador no envía la sesión de la tienda cuando CCAvenue devuelve al cliente, así que tras aplicar la respuesta la extensión muestra una página breve que vuelve a abrir la dirección de retorno desde tu tienda: el cliente conserva el carrito y el inicio de sesión.

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 la respuesta no puede verificarse, el mensaje es We could not confirm the payment result. If your account was charged, please contact us before paying again. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra. En estos casos el pedido queda sin estado y el carrito se conserva, así que el cliente puede volver a pagar. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza. Cada intento recibe su propia referencia de pedido de CCAvenue. CCAvenue no puede cancelar un pago iniciado, así que un pago correcto y tardío de un intento anterior se aplica igualmente a su propio pedido. Un carrito se paga una sola vez: un carrito que ya fue pagado con otro pedido no se vuelve a enviar a CCAvenue (el cliente pasa a la página de éxito), y si el mismo carrito se sigue pagando dos veces (por ejemplo, en dos pestañas del navegador), el segundo pedido queda sin estado y el pedido pagado recibe una nota que indica que el cliente pudo haber sido cobrado dos veces, para que puedas reembolsarlo en el panel de CCAvenue.

En OpenCart 4 el pedido se mantiene en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró sin pago entretanto (por ejemplo, porque su pago pendiente se abortó o falló, o porque lo cerraste), Confirm Order devuelve al cliente a la finalización de compra y el siguiente Confirm Order paga un pedido nuevo del carrito. El mensaje es Payment was cancelled. You may try again. cuando un pago pendiente se abortó, Payment was not completed. Please try again or choose a different payment method. cuando falló, y This order can no longer be paid (it was closed by the store). Please confirm your order again. cuando cerraste un pedido que tenía un pago. Si el pedido ya tiene un estado y el carrito ha cambiado desde entonces (otros productos o cantidades), el mensaje es Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order.

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, el pedido queda sin estado; comprueba el pago en el panel de CCAvenue. La extensión no admite reembolsos desde OpenCart, tarjetas guardadas, suscripciones o pagos recurrentes, ni formulario de tarjeta en la propia tienda, y no es compatible con CCAvenue UAE ni con otras plataformas regionales.

Pedidos

Estados de pedido

Sin estado (pedido faltante): el cliente fue enviado a CCAvenue y no ha vuelto, o el pago falló o se canceló. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders. Comprueba el pago en el panel de CCAvenue si el cliente no vuelve.

Order Status After Payment (default Processing): se confirmó el pago. Una nota muestra la referencia del banco, el tracking ID y el modo de pago.

Awaiting Payment Status (default Pending): CCAvenue informó el pago como Awaited (el banco aún no lo ha confirmado). El pedido nunca se marca como fallido mientras el dinero todavía pueda capturarse, y una nota pide verificarlo en el panel de CCAvenue antes de completar el pedido. Una respuesta posterior con el mismo tracking ID se aplica igualmente: Success establece Order Status After Payment, Failure establece Failed Payment Status y Aborted establece Cancelled Payment Status. OpenCart notifica al cliente de estos cambios.

On Hold (Review) Status (default Pending): CCAvenue confirmó un pago cuyo importe o moneda difiere del total del pedido o de lo que se envió, o el cliente pagó después de que el pedido se hubiera cancelado o fallado. La nota muestra el importe recibido y el esperado. Comprueba el pago en el panel de CCAvenue y, después, completa el pedido o reembolsa el pago.

Un fallo tardío nunca cambia un pedido pagado, y un pedido que completaste a mano no se modifica. 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 pide reembolsar el duplicado en el panel de CCAvenue.

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

VibeFox CCAvenue Payment tab

En Sales > Orders, abre un pedido pagado con CCAvenue. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox CCAvenue Payment muestra el CCAvenue order ID, con la etiqueta Test mode en los pagos de prueba, el Tracking ID, el Status, la Bank reference, el Payment mode y el nombre de la tarjeta, el Amount sent y el Amount received, la Date, el Message de CCAvenue y las CCAvenue notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos desde OpenCart no son compatibles. Reembolsa el pago en el panel de CCAvenue y, después, registra el reembolso en OpenCart manualmente, por ejemplo cambiando el estado del pedido.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox CCAvenue Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox CCAvenue 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 eliminarla de esta tienda. Debajo aparecen la línea Product: opencart-payment-ccavenue 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 el inglés y el 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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un 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. 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. 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 se oculta a 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 cuando el cliente vuelve de CCAvenue.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del panel de administración o la página Edit: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez por semana. No hace falta ningún cron job. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

CCAvenue does not appear at checkout: comprueba que la licencia esté activa, que Enable/Disable esté activado y que se hayan configurado las tres credenciales: Merchant ID, Access Code y Working Key. La página de ajustes muestra una advertencia cuando falta alguna. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado en los ajustes.

The payment went through, but the order stays without a status: el cliente no volvió de CCAvenue a tu tienda, por ejemplo porque cerró el navegador. La extensión no tiene notificaciones de servidor a servidor. Comprueba el pago en el panel de CCAvenue y actualiza el pedido manualmente.

Every payment ends with We could not confirm the payment result: la respuesta no puede descifrarse. 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 de la página de la extensión.

CCAvenue shows an error before the payment page: 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 que, en modo de prueba, CCAvenue habilitó el acceso de prueba en tu cuenta. Para una moneda distinta de INR, el procesamiento multidivisa debe estar habilitado en tu cuenta de CCAvenue.

The customer sees This payment method is temporarily unavailable: falta una de las credenciales o el total del pedido es cero. Debug log muestra el motivo.

The customer sees This payment method is not available. Please reload the checkout page.: la sesión de finalización de compra ya no coincide con el pedido, o el método de pago se desactivó entretanto. El cliente recarga la finalización de compra.

The customer sees Payment gateway error: encryption failed: no se pudo cifrar la solicitud. Comprueba que la extensión OpenSSL de PHP esté instalada.

The Merchant ID does not change on save: el valor contiene algo que no son dígitos. Introduce solo los números de tu Merchant ID.

Order is in the review or awaiting status: lee las notas de la pestaña VibeFox CCAvenue Payment (consulta Estados de pedido). Comprueba el pago en el panel de CCAvenue y, después, completa el pedido o reembolsa el pago.

Para desarrolladores: antes de cifrar la solicitud, la extensión dispara el evento de OpenCart ccavenue_p_request_params con los parámetros de la solicitud y el pedido (por ejemplo, para establecer merchant_param2 a merchant_param5; no cambies amount, currency, order_id ni merchant_param1).

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox CCAvenue Payment. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina los ajustes propios 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. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, sus eventos y su acción de inicio, que permite pasar el retorno del cliente en modo de mantenimiento). Si Delete data on uninstall está activado, se eliminan los demás ajustes de la extensión (título, descripción, credenciales, modo de prueba, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las referencias de pago de CCAvenue siempre se conservan. 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 desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox CCAvenue Payment en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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