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

Moneda: AUD, BAM, BHD, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, ISK, MKD, NOK, PLN, RON, RSD, RUB, SEK o USD. En cualquier otra moneda de la finalización de compra, el método de pago queda oculto. Los importes se envían con 2 decimales; un total con más decimales (por ejemplo, en una moneda con 3 decimales como BHD) se rechaza en lugar de redondearse.

Cuenta de CorvusPay: necesitas una cuenta de comerciante de CorvusPay. CorvusPay emite un Store ID y una Secret Key para cada tienda, por separado para la tienda de prueba y la de producción; se muestran en el CorvusPay Merchant Center. La Success URL y la Cancel URL de la extensión deben introducirse allí (véase Configuration).

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

Instalación

La descarga es un único archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_corvuspay_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_corvuspay_gateway.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_corvuspay_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también 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 CorvusPay Gateway y haz clic en Install (el botón verde +). Tu usuario de 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 (véase Clave de licencia).

4. Introduce el Store ID y la Secret Key de tu tienda de prueba de CorvusPay (y de la tienda de producción para los pagos reales). Copia la Success URL y la Cancel URL que aparecen en la página de ajustes en el CorvusPay Merchant Center, tanto para la tienda de prueba como para la de producción.

5. Activa Enable/Disable y haz clic en Save. Realiza un pedido de prueba y luego desactiva Test Mode para pasar a producción.

OpenCart 4

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

4. Introduce la clave de licencia, las tiendas de CorvusPay y las URL del Merchant Center 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 Success URL y la Cancel URL son diferentes (véase Success y Cancel URL).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado.

Configuration

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > 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 Test mode is on. Payments go to the CorvusPay test environment — no real money is taken. mientras el modo de prueba está activado, te avisa cuando la pasarela está activada pero el Store ID o la Secret Key del modo actual están vacíos (en ese caso el método queda oculto en la finalización de compra hasta que se rellenen) y cuando la moneda predeterminada de tu tienda no es compatible con CorvusPay. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede tener más de 128 caracteres, Sort Order debe ser un número entero, Minimum Total debe ser un número no negativo, y la zona geográfica y los estados de pedido seleccionados deben existir; si no, no se guarda nada y la página muestra los errores.

CorvusPay

Enable/Disable: Enable CorvusPay Gateway. activa o desactiva el método de pago. Default: off.

Title: el nombre del método de pago que el cliente ve en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Default: Credit/Debit Card (CorvusPay). Hasta 128 caracteres; si lo dejas vacío, se muestra el nombre predeterminado.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmar. Default: Pay securely with your credit or debit card via CorvusPay. En modo de prueba se le añade (Test mode — no real payment is taken.)

Sort Order: la posición de CorvusPay entre los métodos de pago en la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece CorvusPay solo para direcciones de pago de la zona geográfica seleccionada. Default: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Minimum Total: el importe del pedido, en la moneda predeterminada de la tienda, que debe alcanzarse para que se ofrezca CorvusPay. Déjalo vacío para no tener mínimo.

Credenciales de la tienda

El Store ID y la Secret Key los emite CorvusPay para cada tienda (de prueba y de producción por separado) y se muestran en el CorvusPay Merchant Center.

Test Mode: usa el entorno de prueba de CorvusPay (wallet.test.corvuspay.com) y el Store ID y la Secret Key de prueba. Default: on. Desactívalo para aceptar pagos reales en wallet.corvuspay.com.

Test Store ID: el Store ID numérico de tu tienda de prueba de CorvusPay.

Test Secret Key: la Secret Key de tu tienda de prueba de CorvusPay, utilizada para las firmas HMAC-SHA256.

Live Store ID: el Store ID numérico de tu tienda de producción de CorvusPay.

Live Secret Key: la Secret Key de tu tienda de producción de CorvusPay, utilizada para las firmas HMAC-SHA256.

El Store ID debe contener solo dígitos. Si introduces cualquier otra cosa, la página muestra … must contain digits only — the previous value was kept. y los demás campos se guardan igualmente. Las Secret Keys 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. Para eliminar una clave guardada, marca Clear the saved value on save debajo del campo y haz clic en Save. Un pago siempre se verifica con la Secret Key de la tienda en la que se inició, así que mantén rellenada la clave de prueba mientras puedan llegar pagos de prueba.

Success y Cancel URL

Copia las dos direcciones que aparecen en Merchant Center URLs en el CorvusPay Merchant Center, tanto para la tienda de prueba como para la de producción. CorvusPay devuelve al cliente a ellas después del pago. Se generan a partir de la dirección de la tienda de tu instalación de OpenCart; cópialas exactamente como las muestra la página.

Pago

Transaction Type: cómo se cobra la tarjeta.

Payment Page Language: el idioma de la página de pago de CorvusPay. Site language (por defecto) usa el idioma actual de tu tienda cuando CorvusPay lo admite; si no, usa inglés. También puedes elegir Hrvatski, English, Deutsch, Italiano, Srpski o Slovenščina.

Order Status After Payment: el estado del pedido tras un pago Sale correcto. Las opciones apuntan a los estados de OpenCart elegidos en la sección Order statuses.

Estados de pedido

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). Estos son los estados de OpenCart que establece la pasarela; cada campo muestra tus estados de pedido de OpenCart. OpenCart no tiene un estado On hold, así que el estado de revisión se usa para Authorize only, para las diferencias de importe o de moneda y para los pagos posteriores a una cancelación; una nota del pedido explica el motivo.

Processing status: se usa cuando Order Status After Payment es Processing. Default: Processing.

Completed status: se usa cuando Order Status After Payment es Completed. Default: Complete.

On hold (review) status: Authorize only, diferencia de importe o de moneda, pago posterior a una cancelación, o Order Status After Payment configurado en On hold. Default: Pending. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Avanzado

Logging: escribe información de depuración en corvuspay_p_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso cuando esta opción está desactivada; las claves secretas, las firmas y los datos de los clientes nunca se registran. Default: off.

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

Delete Data: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y los archivos de registro. Los pedidos y los datos de transacción de CorvusPay siempre se conservan. Default: off.

Importar / Exportar

Export: Download JSON guarda los ajustes como archivo JSON. Las claves secretas no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. Las claves secretas guardadas se mantienen.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, Credit/Debit Card (CorvusPay)). 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, la página muestra Redirecting to CorvusPay for payment. Please wait... y envía el formulario firmado a la página de pago de CorvusPay. Si la redirección no se inicia, el cliente hace clic en Pay via CorvusPay. Se envían el total del pedido en la moneda del pedido, una breve descripción (Order, el número de pedido y el nombre de la tienda), y los datos de dirección y el correo electrónico del cliente (para rellenar previamente la página de pago). El mismo número de pedido de CorvusPay se reutiliza mientras no cambien el importe, la moneda, el modo y el tipo de transacción, y CorvusPay no acepta un segundo pago para él. 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 en la parte inferior de la página de finalización de compra. Si la tienda no pide una dirección de pago (valor predeterminado de OpenCart 4), los datos del titular de la tarjeta se toman del nombre del cliente y de la dirección de envío.

Después de pagar, CorvusPay devuelve al cliente a la Success URL. El pedido solo se marca como pagado cuando CorvusPay lo confirma: el número de pedido de CorvusPay debe haber sido emitido por esta tienda, la firma debe coincidir con la Secret Key de la tienda en la que se inició el pago, y el importe y la moneda deben coincidir con el pedido. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos electrónicos habituales del pedido y la actualización de existencias, y el cliente ve la página de éxito del pedido de OpenCart con Your CorvusPay payment has been received. En Authorize only, la página muestra Your CorvusPay payment has been authorized. The amount will be charged when the shop processes your order., y para un pedido en estado de revisión, Your payment was received and is being reviewed by the shop.

Si el pago no se puede aplicar en ese momento (por ejemplo, porque otra solicitud está confirmando el mismo pedido), el cliente ve Your payment is being confirmed con un botón Check again, que lo lleva a la página de éxito en cuanto el pedido tenga estado. Si la solicitud a la Success URL no se puede verificar, el cliente ve Payment not confirmed y We could not confirm this CorvusPay payment. If your card was charged, please contact the shop — do not pay again. No se cambia nada. La Success URL también funciona mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio para las URL de éxito y de cancelación. En OpenCart 4, el navegador no envía la sesión de la tienda cuando CorvusPay devuelve al cliente, así que la extensión muestra primero una página breve que vuelve a abrir la misma dirección desde tu tienda: el cliente conserva el carrito y el inicio de sesión.

Si el cliente cancela en la página de CorvusPay, el pedido se queda sin estado y el cliente vuelve a la finalización de compra con el carrito intacto y The CorvusPay payment was cancelled and the order was not paid. Your cart is still here — you can try again or choose another payment method. En OpenCart 4, este mensaje se muestra encima de la página de finalización de compra. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 mantiene un pedido para la finalización de compra y lo actualiza, y un nuevo intento recibe un nuevo número de pedido de CorvusPay; si otro pedido del mismo carrito ya está pagado, el cliente va a la página de éxito en lugar de pagar de nuevo.

OpenCart 4 mantiene el pedido 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, lo cancelaste), Confirm Order o el regreso desde CorvusPay devuelve al cliente a la finalización de compra con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 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 placed. The cart has changed since then: please confirm the new order to pay for it. En ambos casos, el siguiente Confirm Order paga un pedido nuevo del carrito.

Si el pago no puede iniciarse, el cliente permanece en el paso Confirm Order con un breve mensaje encima del botón: CorvusPay is not configured. Please choose another payment method., CorvusPay does not accept payments in … o This order total cannot be paid via CorvusPay (it must be greater than zero with at most 2 decimals). Please choose another payment method.

El pedido solo se confirma cuando CorvusPay devuelve al cliente a la Success URL; no hay notificaciones de servidor a servidor. Si el cliente cierra el navegador justo después de pagar, el pedido se queda sin estado. La extensión no permite hacer reembolsos, capturas ni anulaciones desde OpenCart (la API de servidor de CorvusPay requiere un certificado de cliente), ni tiene tarjetas guardadas, suscripciones, pagos a plazos ni formulario de tarjeta en la propia tienda.

Pedidos

Estados de pedido

Sin estado (pedido incompleto): el cliente fue enviado a CorvusPay y no ha vuelto con un pago confirmado, o ha cancelado el pago. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status definido en Missing Orders. Si el cliente pagó pero no volvió, comprueba el pago en el CorvusPay Merchant Center y establece el estado del pedido manualmente.

Processing, Completed o estado de revisión: el pago Sale fue confirmado. El estado sigue a Order Status After Payment. Una nota muestra el número de pedido de CorvusPay, el código de aprobación y el tipo de tarjeta.

Estado de revisión, autorizado: está seleccionado Authorize only. Captura el pago en el CorvusPay Merchant Center y después cambia el estado del pedido.

Estado de revisión, diferencia de importe o de moneda: el importe o la moneda pagados no coinciden con el pedido. No envíes el pedido antes de verificar el pago en el CorvusPay Merchant Center.

Estado de revisión, pago tras la cancelación: llegó un pago correcto para un intento de pago que el cliente había cancelado. Prepara el pedido o reembolsa el pago en el CorvusPay Merchant Center.

Si llega otro pago correcto para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que revises el CorvusPay Merchant Center y que reembolses el pago duplicado si es necesario. Si llega un pago para otro pedido del mismo carrito mientras un pedido ya está pagado, ese pedido se queda sin estado y la nota se añade al pedido pagado.

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

Pestaña VibeFox CorvusPay Gateway

En Sales > Orders, abre un pedido pagado con CorvusPay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox CorvusPay Gateway muestra el CorvusPay order number, el Status del intento de pago, el Transaction type, el Amount (y el importe recibido, si CorvusPay lo informó), el Approval code, la Transaction, el tipo de Card y las CorvusPay notes. Los pagos de prueba se marcan como Test. La pestaña es de solo lectura y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos: desde OpenCart no se admiten reembolsos, capturas ni anulaciones. Haz estas operaciones en el CorvusPay Merchant Center y registra el resultado en OpenCart manualmente. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de CorvusPay.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox CorvusPay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox CorvusPay Gateway > 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-corvuspay 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 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, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, CorvusPay 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 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, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir una vez la página Edit, aparece un recordatorio en el Dashboard del panel. 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 desde CorvusPay.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard o la página Edit del panel: 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 se necesita ninguna tarea cron. Al desinstalar la extensión, siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

CorvusPay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el Store ID y la Secret Key del modo actual están rellenados (Test Store ID y Test Secret Key en modo de prueba, Live Store ID y Live Secret Key en modo de producción) y que CorvusPay admite la moneda de la finalización de compra. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Minimum Total.

El pago se ha realizado, pero el pedido se queda sin estado: lo más probable es que la Success URL no esté introducida en el CorvusPay Merchant Center, o que la Secret Key de OpenCart no coincida con la tienda. Busca INVALID signature en el campo Log de la página de la extensión (los errores siempre se registran). El pedido también se queda sin estado si el cliente cerró el navegador antes de volver; en ese caso, comprueba el pago en el Merchant Center y establece el estado del pedido manualmente.

El cliente ve Payment not confirmed: la solicitud a la Success URL fue rechazada: faltaban campos obligatorios, el número de pedido de CorvusPay no lo emitió esta tienda, la Secret Key de esa tienda está vacía o la firma no coincidió. No se cambia nada. El registro muestra el motivo.

El cliente ve Your payment is being confirmed durante mucho tiempo: no se pudo establecer el estado del pedido. El registro muestra el motivo; comprueba el pago en el Merchant Center.

El cliente ve This order total cannot be paid via CorvusPay: el total es cero o tiene más de 2 decimales.

El cliente ve CorvusPay is not configured o CorvusPay does not accept payments in …: falta el Store ID o la Secret Key del modo actual, o la moneda de la finalización de compra no es compatible.

El cliente ve 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ó mientras tanto. El cliente recarga la finalización de compra.

El pedido está en estado de revisión: lee las notas de la pestaña VibeFox CorvusPay Gateway. Está seleccionado Authorize only, el importe o la moneda pagados no coincidían con el pedido, el pago llegó después de que el cliente hubiera cancelado, o Order Status After Payment está configurado en On hold.

Para desarrolladores: antes de firmar el formulario, la extensión dispara el evento de OpenCart corvuspay_p_form_params con los campos del formulario y el pedido.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox CorvusPay Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Minimum Total y los estados de la sección Order statuses, que vuelven a sus valores predeterminados al reinstalar. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, también sus eventos y su acción de inicio, que deja pasar CorvusPay en modo de mantenimiento). Si Delete Data está activado, se eliminan los demás ajustes de la pasarela (título, descripción, Store ID, Secret Keys, modo de prueba, ajustes de pago, registro) y los archivos de registro. Si está desactivado, se conservan para una reinstalación posterior. Los datos de transacción de CorvusPay siempre se conservan, así que la pestaña de CorvusPay de los pedidos antiguos vuelve a aparecer tras una reinstalación. 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 la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox CorvusPay Gateway en la lista de extensiones instaladas, y luego en Delete (el botón rojo de papelera) para eliminar el paquete subido.

CorvusPay es una marca comercial de su respectivo propietario. Esta extensión no está afiliada a CorvusPay ni cuenta con su respaldo.