VibeFox ePay.bg for PrestaShop — Ayuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Moneda: leva búlgara (BGN), euro (EUR) o dólar estadounidense (USD). El carrito se cobra en su propia moneda con 2 decimales. En los carritos en otras monedas, el método de pago no se muestra al finalizar la compra.
Cuenta de ePay.bg: necesitas el número de cliente (MIN) y la clave secreta de tu perfil de comerciante de ePay.bg: las reales de www.epay.bg y las de prueba de demo.epay.bg (una 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 solo 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 ePay.bg Gateway en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Introduce el MIN y la clave secreta de prueba y/o reales (consulta 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 no se crea ningún pedido.
6. Activa Enable/Disable y haz clic en Save. Realiza un pedido de prueba en modo de prueba y, después, desactiva Test Mode.
Al instalarse, el módulo crea el estado de pedido ePay.bg payment on hold. PrestaShop ofrece el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes restringirlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. Cada botón Save guarda toda la página. Encima de los campos, la página muestra un error si la moneda predeterminada de la tienda no es BGN, EUR o USD; una advertencia si la pasarela está activada pero el MIN o la clave secreta del modo seleccionado están vacíos (en ese caso queda oculta al finalizar la 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.
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 al finalizar la compra. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: ePay.bg. Obligatorio.
Description: el texto que se muestra debajo del método de pago al finalizar la compra. Predeterminado: Pay securely via ePay.bg with a bank card or your ePay.bg account.
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.
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 si quieres cambiarlo. Los espacios y saltos de línea de las claves pegadas se eliminan al guardar.
Clear saved secret keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Payment notifications (IPN)
La notificación indica a tu tienda que una solicitud de pago ha sido pagada, rechazada o ha caducado. El campo Notification URL muestra la URL que hay que introducir como URL for receiving notifications en el perfil de comerciante de ePay.bg, tanto en el real como en el de prueba. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_epaybg_gateway/notify, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en los ajustes. Los pedidos solo se crean mediante estas notificaciones firmadas; el regreso del cliente a la tienda no crea ni paga ningún 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 se comprueba 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 el que se hizo la solicitud; de lo contrario, el pedido pasa a ePay.bg payment on hold. Sin la URL de notificación en el perfil de comerciante, no se crea ningún pedido.
Payment request
Invoice Prefix: solo dígitos (hasta 10), que se colocan delante del ID del carrito para formar el número de factura de ePay.bg; por ejemplo, 00001 + 123 = 00001123. Usa prefijos distintos para tiendas distintas en una misma cuenta de ePay.bg. Los demás caracteres se eliminan al guardar, con una advertencia. Cambiar el prefijo más adelante es seguro: las solicitudes de pago abiertas se encuentran por la factura guardada para ellas. Predeterminado: 00001.
Expiration Time: el tiempo tras el cual caduca una solicitud de pago sin pagar; entonces ePay.bg la informa como caducada y no se crea ningún pedido. Elige 1, 3, 6, 12, 24, 48 o 72 horas. La hora se envía en hora de Bulgaria, 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: inglés.
Order Status After Payment: el estado del pedido que se asigna tras un pago correcto.
Advanced
Logging: escribe las solicitudes de pago y las notificaciones en logs/epay_bp_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves secretas y los datos de la tarjeta no se registran. Predeterminado: desactivado. Los errores siempre se registran, también cuando está desactivado.
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 los ajustes de la pasarela y el registro. Los registros de pagos de ePay.bg, el estado de pedido ePay.bg payment on hold y los pedidos siempre se conservan. Predeterminado: desactivado.
Finalizar compra
En el paso de pago, el cliente elige el método de pago (por defecto ePay.bg) y confirma. El cliente ve Redirecting to ePay.bg for payment... y es enviado a ePay.bg con una solicitud de pago firmada por el total del carrito en la moneda del carrito, con el número de factura y el tiempo de caducidad. En ePay.bg, el pago aparece como Cart y con el número de carrito. La página también tiene un botón Pay via ePay.bg por si la redirección no se inicia, y un botón Cancel. En ePay.bg el cliente paga con tarjeta bancaria o con una cuenta de ePay.bg. En este punto todavía no existe ningún pedido.
Tras pagar, el cliente vuelve a tu tienda. El pedido se crea solo cuando llega la notificación firmada de ePay.bg. Si ya ha llegado, el cliente ve la página estándar de confirmación del pedido. Si no, una página de Payment confirmation muestra Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. con los botones Check again y Back to checkout.
Si el cliente cancela en ePay.bg, vuelve a la finalización de compra con el mensaje The ePay.bg payment was cancelled. You can try again or choose another payment method. Si ePay.bg ha informado de la solicitud como rechazada o caducada, el mensaje es The payment was not completed. You can try again or choose another payment method. El carrito se conserva. Un nuevo intento para el mismo carrito usa el mismo número de factura.
Si el carrito no se puede pagar con ePay.bg, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo ePay.bg payments are temporarily unavailable. Please choose another payment method. o indicando que ePay.bg no acepta pagos en la moneda del carrito.
La notificación funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.
El módulo admite solo pagos únicos en ePay.bg. No ofrece reembolsos desde PrestaShop, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni códigos de pago en efectivo de EasyPay o B-Pay.
Pedidos
Estados del pedido
No order yet: el cliente fue enviado a ePay.bg y no ha pagado, la notificación todavía no ha llegado o ePay.bg informó de la solicitud como rechazada o caducada. Solo existe el carrito.
Payment accepted, Delivered or ePay.bg payment on hold: el pago fue confirmado. El estado sigue a Order Status After Payment. El pago se registra con el STAN como ID de transacción (o con el número de factura si no hay STAN), y una nota muestra el número de factura, la fecha del pago, el STAN y el código BORICA.
ePay.bg payment on hold after payment: el pago llegó, pero no por lo que el carrito indica ahora: el total o la moneda del carrito se cambiaron después de la solicitud de pago, o la notificación llegó en un modo (prueba o real) distinto al de la solicitud. El pago no se registra como pagado. Lo mismo ocurre cuando el carrito ya tiene un pedido sin pagar, por ejemplo uno cancelado o uno realizado con otro método de pago. 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 o reembolsado, el estado no cambia y una nota te pide que compruebes si hay un pago duplicado en el panel de comerciante de ePay.bg. Un aviso tardío de rechazo o caducidad nunca modifica un pedido pagado.
Bloque de pago de ePay.bg
La página del pedido muestra un bloque ePay.bg payment con la factura, el importe y la moneda solicitados, el resultado de la notificación, la fecha del pago, el STAN, el código BORICA, una etiqueta Test mode para los pagos de prueba y las ePay.bg notes del pedido.
Reembolsos
Los reembolsos desde PrestaShop 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 el pedido 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 ePay.bg Gateway es el primer bloque de Modules > Module Manager > VibeFox ePay.bg Gateway > Configure, 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-epaybg 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. Quitar 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 al finalizar la compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda del lado del cliente 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 recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose.
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 por 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
ePay.bg no aparece al finalizar la compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el MIN y la clave secreta del modo seleccionado estén introducidos y que la moneda del carrito sea BGN, EUR o USD. La página de ajustes muestra una advertencia cuando faltan las credenciales. 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 pedido solo se crea con 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 uses (demo o real), exactamente como aparece en Notification URL, y que la clave secreta de ese modo sea correcta. Consulta el campo Log en la página del módulo; 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 se crea cuando la clave es 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 carrito en el mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). ePay.bg vuelve a enviar la notificación. El motivo figura en el registro.
La URL de notificación muestra ERR=Method not allowed in the browser: es normal. La URL acepta solo solicitudes de ePay.bg.
El pedido está en ePay.bg payment on hold tras el pago: lee las notas del bloque ePay.bg payment (consulta Estados del pedido), comprueba el pago en el panel de comerciante de ePay.bg y, a continuación, completa el pedido o reembolsa el pago allí.
El prefijo de factura se cambió al guardar: el prefijo solo puede contener dígitos, hasta 10. Los demás caracteres se eliminan.
Para desarrolladores, el readme menciona el hook actionEpayBpFormFields (el filtro epay_bp_form_fields de la versión para WooCommerce), por ejemplo, para usar la página de tarjeta directa (PAGE=credit_paydirect).
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox ePay.bg Gateway 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 la pasarela y el registro. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Los registros de pagos de ePay.bg y el estado de pedido ePay.bg payment on hold siempre se conservan, de modo que un pago iniciado antes de una reinstalación se sigue confirmando. Los pedidos existentes conservan sus notas de pago e ID de transacción.
ePay.bg es una marca comercial de su respectivo titular. Este módulo no está afiliado a ePay.bg ni cuenta con su respaldo.