VibeFox ePay.bg for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Moneda: lev búlgaro (BGN), euro (EUR) o dólar estadounidense (USD). El pedido se cobra en su propia moneda con 2 decimales. Cuando el cliente finaliza la compra en otra moneda, el método de pago se oculta.

Cuenta de ePay.bg: necesitas el número de cliente (MIN) y la clave secreta de tu perfil de comerciante de ePay.bg: los reales desde www.epay.bg y los de prueba desde demo.epay.bg (la cuenta de prueba se registra por separado). También debes introducir en el perfil de comerciante la URL de notificación de tu tienda.

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

Instalación

La descarga es un archivo ZIP con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_epaybg_gateway-oc3-(versión).ocmod.zip y el paquete de OpenCart 4 wcp_epaybg_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_epaybg_gateway-oc3-(versión).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 ePay.bg Gateway 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 configuración. 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 MIN y la clave secreta de prueba y/o real (véase Configuración).

5. Copia la URL que aparece en la sección Payment notifications (IPN) en el campo URL for receiving notifications del perfil de comerciante de ePay.bg, tanto en el perfil de demostración como en el real. Sin ella, ningún pedido recibe un estado.

6. Activa Enable/Disable y haz clic en Save. Haz un pedido de prueba en modo de prueba y después desactiva Test Mode.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_epaybg_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 ePay.bg Gateway, 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, las credenciales de ePay.bg y la URL de notificación como en los pasos 3 a 6 de OpenCart 3. La página de configuración y sus campos son iguales en ambas versiones. Solo la URL de notificación es diferente (véase Notificaciones de pago (IPN)).

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 ePay.bg Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save debajo de la lista guarda toda la página. Encima de los ajustes, la página muestra un error si la moneda predeterminada de la tienda no es BGN, EUR ni USD; una advertencia si el método de pago está activado pero el MIN o la clave secreta del modo seleccionado están vacíos (en ese caso se oculta en la finalización de compra, y al guardar aparece la misma advertencia); y Test mode is on: payments go to demo.epay.bg and no real money is charged. mientras el modo de prueba está activado. Sin el derecho a modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío (hasta 128 caracteres), Sort Order debe ser un número entero y Total un número igual o mayor que 0; si algún campo es incorrecto, no se guarda nada.

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: ePay.bg. Obligatorio.

Description: el texto que se muestra al cliente en el paso Confirm Order. Predeterminado: Pay securely via ePay.bg with a bank card or your ePay.bg account.

Sort Order: la posición de ePay.bg 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 ePay.bg 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 un pedido debe alcanzar para que se ofrezca ePay.bg. Déjalo vacío para ofrecer ePay.bg con cualquier total.

Cuenta de ePay.bg

El número de cliente (MIN) y la clave secreta aparecen en tu perfil de comerciante en www.epay.bg (real) y demo.epay.bg (cuenta de prueba, registrada por separado).

Test Mode: activa el modo de prueba. Los clientes son enviados al entorno de demostración de ePay.bg y las solicitudes se firman con las credenciales de prueba. Predeterminado: activado. Mientras está activado, los clientes ven Test mode (demo.epay.bg): no real payment is taken. en el paso Confirm Order.

Test Merchant ID (MIN): el número de cliente (MIN) de tu cuenta de comerciante de demo.epay.bg.

Test Secret Key: la clave secreta de tu cuenta de comerciante de demo.epay.bg (64 caracteres).

Live Merchant ID (MIN): el número de cliente (MIN) de tu cuenta de comerciante de www.epay.bg.

Live Secret Key: la clave secreta de tu cuenta de comerciante de www.epay.bg (64 caracteres), que se usa para la firma HMAC-SHA1.

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 para cambiarlo. Para eliminar una clave guardada, marca Clear the saved key on save debajo del campo y haz clic en Save. Los espacios y los saltos de línea de las claves pegadas se eliminan al guardar.

Notificaciones de pago (IPN)

La notificación informa a tu tienda de que una solicitud de pago ha sido pagada, rechazada o ha caducado. El campo Notification URL muestra la URL que debes introducir como URL for receiving notifications en el perfil de comerciante de ePay.bg, tanto en el real como en el de demostración. En OpenCart 3 tiene el aspecto de https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify, y en OpenCart 4, el de https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify. Se genera a partir de la dirección de la tienda de tu instalación de OpenCart. Copia la URL exactamente como la muestran los ajustes. Los pedidos reciben un estado solo a partir de estas notificaciones firmadas; el cliente que regresa a la tienda no paga un pedido.

ePay.bg informa de estos resultados para cada factura:

Las notificaciones sin una suma de comprobación válida se rechazan, y ePay.bg sigue enviándolas. La suma de comprobación se verifica con la clave secreta de cada modo que tenga una, de modo que los pagos iniciados antes de cambiar entre prueba y real se siguen confirmando. Un pago debe llegar en el modo en que se hizo la solicitud; de lo contrario, el pedido pasa al estado de retención. Sin la URL de notificación en el perfil de comerciante, ningún pedido recibe un estado.

Solicitud de pago

Invoice Prefix: solo dígitos (hasta 10), que se anteponen al ID del pedido de OpenCart para formar el número de factura de ePay.bg, por ejemplo 00001 + 123 = 00001123. Usa prefijos distintos para tiendas diferentes en una misma cuenta de ePay.bg. Los demás caracteres se eliminan al guardar, con una advertencia que muestra el prefijo guardado. Cambiar el prefijo más adelante es seguro: las solicitudes de pago abiertas se encuentran por la factura guardada para cada una. Predeterminado: 00001.

Expiration Time: el tiempo tras el cual caduca una solicitud de pago no pagada; ePay.bg la informa entonces como caducada y el pedido no recibe ningún estado. Elige 1, 3, 6, 12, 24, 48 o 72 horas. La hora se envía en hora búlgara, sea cual sea la zona horaria de tu tienda. Predeterminado: 24 horas.

Language: el idioma de la página de pago de ePay.bg, inglés o búlgaro. Predeterminado: English.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). Solo recibe un estado cuando ePay.bg informa del pago. Un pago rechazado, caducado o abandonado deja el pedido sin estado, y el cliente puede volver a pagar. Los campos de estado siguientes muestran los estados de pedido de tu OpenCart.

Order Status After Payment: el estado que se asigna tras un pago correcto.

Processing status: el estado de OpenCart para Default y Processing. Predeterminado: Processing.

Completed status: el estado de OpenCart para Completed. Predeterminado: Complete.

On Hold status: el estado de OpenCart para On Hold y para los pagos que requieren revisión manual: el importe total o la moneda cambiaron tras la solicitud de pago, la notificación llegó en el otro modo, o el estado del pedido cambió antes de que llegara el pago (por ejemplo, cancelado). Un pedido así no se marca como pagado; una nota explica por qué. Predeterminado: Pending, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Avanzado

Logging: registra las solicitudes de pago y las notificaciones en epay_bp_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web y, al llegar a 5 MB, se traslada a epay_bp_debug.old.log.php. Las claves secretas y los datos de tarjetas no se registran. Predeterminado: desactivado. Los errores se registran siempre, también con esta opción desactivada.

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 los ajustes de la pasarela y el registro. Los registros de pago y los pedidos de ePay.bg siempre se conservan. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un 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 (de forma predeterminada ePay.bg). En el paso Confirm Order el cliente ve tu descripción y la nota You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. OpenCart crea el pedido en este paso, todavía sin estado. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque del método 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. Cuando el cliente hace clic en Confirm Order, la extensión lo envía a ePay.bg con una solicitud de pago firmada por el importe total del pedido en su moneda, con el número de factura y el tiempo de caducidad. El pago aparece en ePay.bg como Order y el número de pedido. En ePay.bg el cliente paga con una tarjeta bancaria o con una cuenta de ePay.bg.

Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando ePay.bg lo confirma mediante la notificación firmada. Después el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales y la actualización del stock. Si la notificación ya ha llegado, el cliente ve la página de éxito del pedido de OpenCart. Si no, una página Payment confirmation dice Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment. con los botones Check again y Back to checkout.

Si el cliente cancela en ePay.bg, regresa al paso de finalización de compra con The ePay.bg payment was cancelled. You can try again or choose another payment method. Si ePay.bg ha informado de que la solicitud fue rechazada o ha caducado, el mensaje es The payment was not completed. You can try again or choose another payment method. El carrito se conserva. En OpenCart 4 estos mensajes aparecen encima de la página de finalización de compra. Un nuevo intento para el mismo pedido usa el mismo número de factura. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 actualiza el pedido de la finalización de compra, de modo que un nuevo intento paga el mismo pedido con una nueva solicitud de pago; cuando otro pedido del mismo carrito ya está pagado, el cliente va a la página de éxito y no se inicia ningún pago 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), el cliente vuelve 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., y el siguiente Confirm Order paga un pedido nuevo del carrito. Si ese pedido ya está pagado pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el cliente vuelve a la finalización de compra, y el siguiente Confirm Order paga el carrito nuevo con un pedido nuevo. Un pedido pagado nunca se muestra como pagado para un carrito distinto.

Si el pedido no puede pagarse con ePay.bg, el cliente se queda en el paso Confirm Order con un breve mensaje encima del botón, por ejemplo ePay.bg payments are temporarily unavailable. Please choose another payment method. o que ePay.bg no acepta pagos en la moneda del pedido.

La notificación también funciona mientras la tienda está en modo de mantenimiento, porque OpenCart 3 deja pasar las solicitudes de las extensiones de pago y la extensión añade en OpenCart 4 una acción de inicio para ello. Las notificaciones de pagos ya iniciados se aceptan aunque desactives el método de pago.

La extensión solo acepta pagos únicos en ePay.bg. No tiene reembolsos desde OpenCart, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni los códigos de pago en efectivo EasyPay o B-Pay.

Pedidos

Estados de pedido

No status (missing order): el cliente fue enviado a ePay.bg y no ha pagado, la notificación aún no ha llegado o ePay.bg informó de que la solicitud fue rechazada o caducó. En Sales > Orders estos pedidos se muestran solo con el filtro Order Status en Missing Orders.

Processing, Completed o On Hold status: el pago fue confirmado. El estado sigue a Order Status After Payment. Una nota muestra el número de factura, la fecha de pago, el STAN y el código BORICA.

Estado On Hold tras el pago: el pago llegó, pero no para lo que el pedido dice ahora: el importe total o la moneda cambiaron tras la solicitud de pago, la notificación llegó en el otro modo (prueba o real) al de la solicitud, o el método de pago del pedido ya no es ePay.bg. El pago no se registra como pagado. Lo mismo ocurre si ya habías dado al pedido otro estado, por ejemplo cancelado. La nota explica el motivo. Comprueba el pago en el panel de comerciante de ePay.bg y completa o reembolsa el pedido manualmente.

Si llega un pago para un pedido que ya está pagado, el estado no cambia y una nota te pide que compruebes si hay un pago doble en el panel de comerciante de ePay.bg. Si el cliente ha pagado dos pedidos del mismo carrito, el segundo recibe una nota sobre un posible pago doble. Un aviso tardío de rechazo o caducidad nunca cambia un pedido pagado; un pedido con un estado solo recibe una nota.

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

Pestaña VibeFox ePay.bg Gateway

En Sales > Orders abre un pedido pagado con ePay.bg. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox ePay.bg Gateway muestra la factura, el entorno (prueba o real) con una etiqueta Test mode para los pagos de prueba, el importe y la moneda solicitados, el estado de la solicitud de pago, el resultado de la notificación, la fecha del pago, el STAN, el código BORICA y las ePay.bg notes del pedido. La pestaña es de solo lectura y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos desde OpenCart no están disponibles, porque la API WEB de ePay.bg no tiene una llamada de reembolso. Reembolsa el pago en el panel de comerciante de ePay.bg y actualiza manualmente el estado del pedido en OpenCart. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de ePay.bg.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox ePay.bg Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox ePay.bg 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 están la línea Product: opencart-payment-epaybg 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. Tras 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 está disponible, 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. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, ePay.bg no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, 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 administrador, así que sin una clave activa el método de pago queda oculto para todos. Tras abrir la página Edit una vez, aparece un recordatorio en el Dashboard. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose.

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: una vez al día durante los primeros 14 días tras introducir la clave y, después, una vez por semana. No se necesita 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

ePay.bg no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el MIN y la clave secreta del modo seleccionado están configurados y que el cliente finaliza la compra en BGN, EUR o USD. La página de ajustes muestra una advertencia cuando faltan las credenciales. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total configurado.

El pago se realizó, pero el pedido se queda sin estado: el pedido solo recibe su estado a partir de la notificación de ePay.bg. Comprueba que la URL de notificación está introducida en el perfil de comerciante de ePay.bg del modo que usas (demo o real), exactamente como aparece en Notification URL, y que la clave secreta de ese modo es correcta. Mira el campo Log de la página de la extensión; activa Logging para ver cada notificación.

La notificación responde ERR=Not valid CHECKSUM: ninguna clave secreta guardada coincide con el perfil de comerciante que envió la notificación. ePay.bg sigue reintentando, así que el pedido recibirá su estado cuando la clave sea correcta.

La notificación responde ERR=Not configured: no hay ninguna clave secreta guardada. Introdúcela.

La notificación responde STATUS=NO para una factura: la factura no la emitió esta tienda, por ejemplo otra tienda de la misma cuenta de ePay.bg. Asigna a cada tienda su propio Invoice Prefix.

La notificación responde STATUS=ERR: un error temporal, por ejemplo dos notificaciones para el mismo pedido en el mismo momento, o que no se pudo establecer el estado del pedido. ePay.bg vuelve a enviar la notificación. El motivo está en el registro.

La URL de notificación muestra ERR=Method not allowed in the browser: es normal. La URL solo acepta solicitudes de ePay.bg.

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ó entretanto. El cliente debe recargar la finalización de compra.

El cliente ve This order has nothing to pay.: el total del pedido es cero, así que no hay nada que enviar a ePay.bg.

El pedido está en el estado On Hold tras el pago: lee las notas de la pestaña VibeFox ePay.bg Gateway (véase Estados de pedido), comprueba el pago en el panel de comerciante de ePay.bg y después completa el pedido o reembolsa el pago allí.

El prefijo de factura se modificó al guardar: el prefijo solo puede contener dígitos, hasta 10. Los demás caracteres se eliminan.

Para desarrolladores: antes de enviar el formulario de pago a ePay.bg, la extensión dispara el evento de OpenCart epay_bp_form_fields con los campos del formulario y el pedido, por ejemplo para usar la página directa de pago con tarjeta (PAGE=credit_paydirect); los datos firmados y la suma de comprobación no pueden modificarse con él.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox ePay.bg Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes 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. En OpenCart 4 se eliminan también el evento de la extensión (el mensaje de la finalización de compra) y su acción de inicio, que deja pasar la notificación en modo de mantenimiento. Si Delete Data on Uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, MIN y claves secretas, solicitud de pago, estado tras el pago, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pago de ePay.bg siempre se conservan, así que un pago iniciado antes de una reinstalación se sigue confirmando. 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 tras la desinstalación, haz clic en Uninstall (el botón naranja −) junto a VibeFox ePay.bg Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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