VibeFox Viva Wallet for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Cuenta de Viva: una cuenta de comerciante de Viva. Puedes usar una cuenta de demo (demo.vivapayments.com) para las pruebas y una cuenta de producción (www.vivapayments.com) para los pagos reales. Cada cuenta tiene sus propias credenciales. Para los pagos necesitas las credenciales de Smart Checkout (Client ID y Client Secret) y el Source Code de una fuente de pago. Merchant ID y API Key son opcionales: solo se usan para responder a la verificación de la URL del webhook de Viva.
Moneda: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. En otras monedas, el método de pago no se muestra en el paso de pago.
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 Viva Wallet Gateway en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).
4. Introduce las credenciales de la cuenta demo y/o de producción de Viva y configura la fuente de pago y el webhook en tu cuenta de Viva (véase Configuración).
5. Activa Enable/Disable y haz clic en Save. Haz un pago de demo con una tarjeta de demo de Viva mientras Test Mode esté activado, y después desactiva Test Mode para pasar a producción.
Al instalarse, el módulo crea el estado de pedido Viva Wallet payment on hold. El módulo se ofrece para los países activos en el momento de la instalación. Puedes cambiar las monedas, los países y los grupos de clientes en Payment > Preferences; los países nuevos se añaden allí más adelante.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Viva Wallet Gateway > 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 si el modo actual no tiene Client ID, Client Secret o Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., o Live en modo producción) y si la moneda predeterminada de la tienda no es compatible. Mientras el modo de prueba está activado, muestra Test mode is on: payments go to the Viva demo environment. Al guardar los ajustes se eliminan los tokens de acceso de Viva en caché, así que las credenciales nuevas se usan de inmediato.
Viva Wallet
Enable/Disable: Enable Viva Wallet 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 el paso de pago. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Viva Wallet. Obligatorio: un título vacío no se guarda y la página muestra Enter a title for the payment method.
Description: el texto que se muestra debajo del método de pago en el paso de pago. Predeterminado: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.
Test Mode: usa el entorno de demo de Viva (demo.vivapayments.com). Los pagos nuevos y las llamadas a la API usan las credenciales de la cuenta demo. No se cobra dinero real y, en el pago, los clientes ven (Test mode: use Viva demo cards, no real money is charged.) Predeterminado: activado. Desactívalo para aceptar pagos reales con la cuenta de producción. Los pagos ya realizados siguen verificándose y reembolsándose en el entorno en el que se hicieron.
Demo account (test mode) and Live account
Ambas secciones tienen los mismos campos: un conjunto para la cuenta demo y otro para la cuenta de producción. En tu cuenta de Viva, abre Settings > API Access y copia las credenciales de Smart Checkout (Client ID, Client Secret), el Merchant ID y la API Key. El Source Code está en Sales > Online payments > Websites / apps.
Client ID (Demo) / Client ID (Live): el OAuth 2.0 Client ID de Smart Checkout de la cuenta. Obligatorio para los pagos.
Client Secret (Demo) / Client Secret (Live): el OAuth 2.0 Client Secret de Smart Checkout de la cuenta. Obligatorio para los pagos.
Source Code (Demo) / Source Code (Live): el código de 4 dígitos de la fuente de pago de la cuenta. Sus Success URL y Failure URL deben apuntar a esta tienda (véase más abajo). Obligatorio para los pagos.
Merchant ID (Demo) / Merchant ID (Live): opcional. Se usa solo para responder a la verificación de la URL del webhook de Viva.
API Key (Demo) / API Key (Live): opcional. Se usa solo para responder a la verificación de la URL del webhook de Viva.
Los Client Secret y las API Key guardados 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.
Clear saved secrets: marca un secreto y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
URL de retorno y webhook
Addresses for the Viva account: este campo muestra las tres direcciones de tu tienda que hay que introducir en la cuenta de Viva. Con URL amigables tienen este aspecto: https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail y https://your-shop/module/wcp_viva_gateway/webhook, posiblemente con un código de idioma como /en/. Cópialas exactamente como las muestran los ajustes.
Payment source: en Sales > Online payments > Websites / apps crea una fuente de pago para el dominio de tu tienda, en cada cuenta que uses. Como Success URL y Failure URL introduce la parte de las direcciones de éxito y de fallo que va después del dominio.
Webhook: en Settings > API Access > Webhooks añade la dirección del webhook para estos eventos:
Viva comprueba la URL antes de guardarla. El módulo responde con la clave de verificación de tu cuenta: la obtiene con el Merchant ID y la API Key del modo actual, o usa la clave que introduzcas abajo. Los webhooks confirman los pagos incluso cuando el cliente cierra el navegador. Los webhooks de Viva no están firmados, así que el módulo nunca confía en el webhook por sí solo: cada pago se verifica con la API de Viva antes de crear el pedido. Sin el webhook, el pedido solo se crea cuando el cliente vuelve a la tienda después de pagar.
Webhook Verification Key: opcional. Déjalo vacío para obtener la clave automáticamente con el Merchant ID y la API Key del modo actual, o pega aquí la clave de verificación de tu cuenta de Viva.
Ajustes avanzados
Order Status After Payment: el estado del pedido que se asigna tras un pago correcto. El estado se asigna de inmediato, sin un segundo cambio de estado.
Brand Color: un código de color HEX de 6 dígitos para la página de pago de Viva, por ejemplo 0000ff. Se elimina el # inicial. Déjalo vacío para usar el color predeterminado. Cualquier otro valor no se guarda: la página muestra Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.
Debug Logging: escribe las peticiones a la API en logs/viva_wp_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves, los tokens y los datos de los clientes no se registran. Los errores siempre se registran, incluso cuando esta opción está desactivada. Predeterminado: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Delete Data on Uninstall: cuando está activado, al desinstalar el módulo se eliminan los ajustes y los registros del módulo. Los pedidos y sus datos de pago (intentos de pago de Viva, reembolsos, estado del pedido) nunca se eliminan. Predeterminado: desactivado.
Finalizar compra
En el paso de pago, el cliente elige el método de pago (por defecto Viva Wallet) y ve la nota You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). Después de confirmar, el módulo crea un pedido de pago de Viva por el total del carrito en la moneda del carrito y envía al cliente a la página Viva Smart Checkout. Allí el cliente paga con uno de los métodos activados en tu cuenta de Viva. El correo electrónico, el nombre, el teléfono y el país del cliente se pasan a Viva, y la página se abre en el idioma del carrito si Viva lo admite. En Viva, el pago aparece como Cart #, el número de carrito y el nombre de tu tienda. El pedido de pago de Viva caduca a los 30 minutos. En este punto todavía no existe ningún pedido.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Viva lo confirma: el módulo vuelve a leer la transacción desde la API de Viva, al volver a la tienda y en el webhook. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. Si el pago aún no está confirmado, una página Payment confirmation muestra We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. con los botones Check again y Back to checkout; el webhook crea el pedido en cuanto Viva confirma el pago.
Si el pago falla o el cliente cancela en la página de Viva, no se crea ningún pedido y el carrito se conserva. El cliente vuelve al paso de pago con The Viva Wallet payment was not completed. Please try again or choose another payment method. o The Viva Wallet payment was cancelled. You can try again or choose another payment method. y puede volver a pagar.
Si Viva no puede iniciar el pago, el cliente se queda en el paso de pago con Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (credenciales ausentes o incorrectas) o We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. El motivo técnico se escribe en el registro.
Las páginas de retorno muestran la confirmación del pedido solo al cliente que pagó. Cualquier otra persona que abra la dirección de retorno es enviada al historial de pedidos o al paso de pago, sin detalles del pedido.
El webhook funciona mientras la tienda está en modo de mantenimiento y no se ve afectado por la restricción de países de tu tienda.
El módulo solo admite pagos únicos, cobrados de inmediato en la página de Viva. No tiene preautorización y captura, pagos a plazos, tarjetas guardadas, suscripciones, Viva Native Checkout (campos de tarjeta en tu propia página) ni terminales TPV. Cuando el cliente inicia un nuevo intento, el pedido de pago de Viva anterior sin pagar no se cancela; Viva lo caduca a los 30 minutos.
Pedidos y reembolsos
Estados del pedido
Sin pedido todavía: el cliente fue enviado a Viva y no ha pagado, el pago falló o se canceló, o Viva aún no ha finalizado el pago. Solo existe el carrito, y el cliente puede volver a pagar.
Payment accepted, Delivered or Viva Wallet payment on hold: el pago fue confirmado. El estado sigue a Order Status After Payment. El pago se registra con el ID de transacción de Viva, y una nota muestra el importe, la transacción, el código de pedido de Viva, el entorno (demo o producción) y la forma en que se confirmó (webhook o retorno del cliente).
Viva Wallet payment on hold tras una discrepancia: Viva informó de un importe o una moneda distintos del total del carrito, por ejemplo cuando el carrito se modificó después de que el cliente empezara a pagar. El pedido se crea sin un pago registrado, y la nota Viva Wallet payment held for review indica el motivo. El cliente ve la página estándar de confirmación del pedido, sin la promesa de una confirmación de Viva. Compara el pago en el panel de Viva con el pedido y gestiona el envío o reembolsa el pago manualmente. Si más tarde llega un pago correspondiente al mismo carrito, el pedido pasa al estado de pagado.
Un pago que llega para un pedido cancelado o reembolsado no cambia el estado del pedido; una nota te pide restaurar el pedido o reembolsar el pago en el panel de Viva. Si llega un segundo pago para un pedido que ya está pagado, el pedido no se modifica; una nota te pide reembolsar el duplicado en el panel de Viva.
Bloque Viva Wallet payment
La página del pedido muestra un bloque Viva Wallet payment con el código de pedido de Viva, el ID de transacción, el entorno y el Source Code, el estado de Viva, los importes pagados y reembolsados, una insignia Demo para los pagos de demo, el historial de reembolsos, los intentos de pago del carrito (cuando hubo más de uno) y las Viva Wallet notes del pedido.
Reembolsos
En el bloque Viva Wallet payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Viva Wallet. Confirma la pregunta Refund this amount via Viva Wallet? This cannot be undone. Se admiten reembolsos totales y parciales en pedidos con una transacción de Viva confirmada. Necesitas el permiso para editar pedidos; no hace falta acceso a los módulos. Puedes reembolsar hasta el importe que Viva cobró por el pago, incluso si el pedido se editó después. El reembolso se envía a la cuenta en la que se hizo el pago (demo o producción), en la moneda del pago, así que deben estar introducidos el Client ID y el Client Secret de esa cuenta. Si Viva no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con la transacción de reembolso de Viva. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Un pedido retenido para revisión sin un pago confirmado no se puede reembolsar desde el bloque.
El módulo no crea facturas de abono. Los botones estándar de reembolso de PrestaShop de la página del pedido no devuelven el dinero a través de Viva. Los reembolsos realizados en el panel de Viva no se importan. Actualiza el pedido manualmente si es necesario.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Viva Wallet Gateway es el primer bloque de Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure, por 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-viva 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 solo 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, Viva Wallet no se muestra a los clientes en el paso de pago. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en el paso de pago. 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 con el webhook de Viva y con el regreso a la tienda, y los reembolsos funcionan.
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
Viva Wallet no aparece en el paso de pago: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga sus Client ID, Client Secret y Source Code (los campos Demo en modo de prueba, los campos Live en modo producción). La moneda del carrito debe ser una de EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. 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. La página de ajustes muestra una advertencia cuando faltan credenciales.
El pago se realizó, pero no se creó ningún pedido: el webhook no funciona. En Viva comprueba que el webhook exista en la cuenta que usas (demo o producción), que su URL sea exactamente la que se muestra en los ajustes y que Transaction Payment Created esté seleccionado. Comprueba que el Client ID y el Client Secret de la cuenta de ese pago sigan introducidos: el módulo los necesita para verificar el pago. Activa Debug Logging y revisa el campo Log. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.
Viva no puede verificar la URL del webhook: introduce el Merchant ID y la API Key del modo actual (o la propia clave de verificación en Webhook Verification Key), guarda y vuelve a verificar en Viva. Para verificar el webhook de la otra cuenta, cambia antes Test Mode o introduce la clave de esa cuenta.
El webhook responde con un error: Viva muestra la respuesta de tu tienda y reintenta los webhooks fallidos. verification_failed (HTTP 500) significa que no se pudo contactar con la API de Viva para verificar el pago, o que no se pudo crear el pedido (por ejemplo, si el módulo está desactivado). busy (HTTP 503) significa que el pedido lo estaba procesando otra petición en ese mismo momento. transaction_not_found (HTTP 404) significa que la transacción no existe en la cuenta de ese pago, por ejemplo por credenciales incorrectas. Los eventos de pagos de otras tiendas de la misma cuenta de Viva reciben la respuesta ignored.
El cliente ve un error al elegir Viva Wallet: revisa el campo Log de la página del módulo. Un Client ID o un Client Secret incorrectos muestran el mensaje de que los pagos con Viva Wallet no están disponibles. Si no se puede contactar con Viva o rechaza el pedido de pago, por ejemplo porque el Source Code pertenece a otra cuenta, el cliente recibe el mensaje de que la tienda no pudo conectarse con Viva Wallet.
El cliente vuelve y ve We could not find your order. If you were charged, please contact us.: el código de pedido de Viva de la dirección de retorno no corresponde a un pago de esta tienda, por ejemplo porque la fuente de pago de otra tienda apunta aquí. Comprueba el Success URL y el Failure URL de la fuente de pago.
El pedido queda en Viva Wallet payment on hold tras el pago: lee las notas del bloque Viva Wallet payment (véase Estados del pedido) y después gestiona el envío del pedido o reembolsa el pago.
El reembolso falla con This payment was made in the Viva demo (or live) environment: no están introducidos el Client ID y el Client Secret de la cuenta en la que se hizo el pago. Introdúcelos y vuelve a intentarlo. Otros errores de reembolso muestran el código HTTP y el mensaje de Viva.
El bloque dice Transaction ID not found. Cannot process refund.: el pedido no tiene un pago de Viva confirmado, por ejemplo tras una discrepancia de importe. Si es necesario, reembolsa el pago en el panel de Viva.
Desinstalación
Desactivar el módulo conserva todos los datos; solo se eliminan los tokens de acceso de Viva en caché. Para eliminarlo, ve a Modules > Module Manager, abre el menú junto a VibeFox Viva Wallet Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Los tokens de acceso en caché y las claves de webhook siempre se eliminan. Si Delete Data on Uninstall está activado, se eliminan los ajustes y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de pago y los reembolsos de Viva y el estado del pedido Viva Wallet payment on hold siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Viva Wallet es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por Viva Wallet.