VibeFox Viva Wallet for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

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. El Merchant ID y la API Key son opcionales: solo se usan para responder a la verificación de la URL del webhook de Viva.

Moneda de la tienda: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. En otras monedas, el método de pago se oculta en la finalización de compra.

Sitio HTTPS público: para los webhooks, tu sitio debe ser accesible desde internet por HTTPS.

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

Instalación

1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_viva_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > Viva Wallet > Manage, o haz clic en Settings debajo del nombre del plugin en la página Plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

5. Introduce las credenciales de la cuenta de demo y/o de producción de Viva y configura la fuente de pago y el webhook (ver Configuración).

6. Activa Enable/Disable. Haz un pago de demo con una tarjeta de demo de Viva mientras Test Mode esté activado, y después desmarca Test Mode para pasar a producción.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Viva Wallet. Encima de los campos, la página te avisa cuando 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 cuando la moneda 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. En la lista de métodos de pago, Viva Wallet aparece marcado como pendiente de configuración hasta que el modo actual tenga esos tres valores.

General

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 la finalización de compra. Predeterminado: Viva Wallet.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (demo.vivapayments.com). Los pagos nuevos y las llamadas a la API usan las credenciales de la cuenta de demo. No se cobra dinero real, y en la finalización de compra la descripción termina con (Test mode: use Viva demo cards, no real money is charged.) Predeterminado: activado. Desmárcalo para cobrar 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.

Cuenta de demo (modo de prueba) y cuenta de producción

Ambas secciones tienen los mismos campos: uno para la cuenta de 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 Client ID OAuth 2.0 de Smart Checkout de la cuenta. Obligatorio.

Client Secret (Demo) / Client Secret (Live): el Client Secret OAuth 2.0 de Smart Checkout de la cuenta. Obligatorio.

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 (ver abajo). Obligatorio.

Merchant ID (Demo) / Merchant ID (Live): opcional. Solo se usa para responder a la verificación de la URL del webhook de Viva.

API Key (Demo) / API Key (Live): opcional. Solo se usa para responder a la verificación de la URL del webhook de Viva.

URL de retorno y webhook

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 las rutas que siguen al dominio de las dos direcciones que se muestran en la configuración, que tienen este aspecto: https://your-site/wc-api/viva_payment_success/ y https://your-site/wc-api/viva_payment_fail/.

Webhook: en Settings > API Access > Webhooks añade la URL que se muestra en la configuración, que tiene este aspecto https://your-site/wp-json/wc-viva-gateway/v1/webhook, para estos eventos:

Viva comprueba la URL antes de guardarla. El plugin responde con la clave de verificación de tu cuenta: obtiene la clave con el Merchant ID y la API Key del modo actual, o usa la clave que introduzcas más abajo. Los webhooks confirman los pagos incluso cuando el cliente cierra el navegador. Los webhooks de Viva no están firmados, así que el plugin nunca confía en el webhook por sí solo: cada pago se verifica con la API de Viva antes de marcar el pedido como pagado. Sin el webhook, un pedido solo se confirma 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 se rechaza al guardar y se mantiene el anterior.

Debug Logging: Enable logging escribe las solicitudes a la API en WooCommerce > Status > Logs, origen wcp_viva_gateway. Las claves y los datos de los clientes no se registran. Los errores siempre se registran, aunque esta opción esté desactivada. Predeterminado: desactivado.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Cuando está activado, al eliminar el plugin se borran los ajustes, la tabla de intentos de pago y los registros del plugin. Las notas y los datos de los pedidos se mantienen. Predeterminado: desactivado.

Finalización de compra

El cliente elige el método de pago (de forma predeterminada Viva Wallet) y realiza el pedido. El plugin crea un pedido de pago de Viva por el total del pedido, en la moneda del pedido, y envía al cliente a la página de Viva Smart Checkout. Allí paga con uno de los métodos activados en tu cuenta de Viva, como tarjetas, Apple Pay o Google Pay. 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 de tu sitio si Viva lo admite; si no, en inglés. El pago aparece en Viva como WooCommerce # y el número de pedido. El pedido de pago de Viva caduca a los 30 minutos.

Tras pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido solo se marca como pagado cuando Viva lo confirma: el plugin vuelve a leer la transacción desde la API de Viva, al volver a la tienda y en el webhook. Si el pago aún no está confirmado, la página muestra We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.

Si el pago falla o el cliente cancela en la página de Viva, el estado del pedido no cambia. El cliente es enviado a la página Pay for order 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 ve 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.

El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order, donde se comprueba la moneda de ese pedido. Es compatible con WooCommerce High-Performance Order Storage (HPOS).

El plugin solo admite pagos únicos, cobrados de inmediato en la página de Viva. No tiene preautorización y captura, pagos a plazos, tarjetas guardadas, WooCommerce Subscriptions, 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

Pending payment: el cliente fue enviado a Viva y aún no ha pagado, el pago aún no se ha confirmado, o el pago falló o se canceló. Una nota muestra el pedido de pago de Viva y el entorno (demo o producción). Los intentos fallidos y cancelados se añaden a las notas del pedido, y el cliente puede volver a pagar.

Processing, Completed or On Hold: el pago fue confirmado. El estado sigue a Order Status After Payment. La nota del pedido muestra el importe, el ID de la transacción de Viva, el entorno y cómo se confirmó (webhook o retorno del cliente).

On hold for review: Viva informó de un importe o una moneda distintos del total del pedido, por ejemplo cuando el pedido se editó después de que el cliente empezara a pagar. La nota Viva Wallet payment held for review indica el motivo. Compara el pago en el panel de Viva con el pedido y complétalo o reembólsalo manualmente.

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 vuelve a cambiar; una nota te pide reembolsar el duplicado en el panel de Viva.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Viva Wallet. Se admiten reembolsos totales y parciales en pedidos con una transacción de Viva confirmada. El reembolso se envía a la cuenta en la que se hizo el pago (demo o producción), en la moneda del pago, por lo que hay que introducir el Client ID y el Client Secret de esa cuenta. Si Viva no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con la transacción de reembolso de Viva.

Los reembolsos hechos en el panel de Viva no se importan. Si lo necesitas, crea un reembolso manual en WooCommerce sin Refund via Viva Wallet.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Viva Wallet. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un solo dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Viva Wallet 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. Los gestores de la tienda con sesión iniciada siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

Viva Wallet no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga su Client ID, Client Secret y Source Code (los campos de Demo en modo de prueba, los de Live en modo producción). La moneda de la tienda (en la página Pay for order, la moneda del pedido) debe ser una de EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK o CHF. La página de configuración muestra una advertencia cuando falta algo.

El pago se realizó, pero el pedido sigue en Pending payment: el webhook no funciona. En Viva, comprueba que el webhook existe en la cuenta que usas (demo o producción), que su URL es exactamente la que se muestra en la configuración y que Transaction Payment Created está seleccionado. Comprueba que el Client ID y el Client Secret de la cuenta de ese pago siguen introducidos: el plugin los necesita para verificar el pago. Los detalles están en WooCommerce > Status > Logs, origen wcp_viva_gateway.

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 verifica de nuevo 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 acceder a la API de Viva para verificar el pago. busy (HTTP 503) significa que otra solicitud estaba procesando el pedido 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 realizar el pedido: activa Debug Logging y revisa WooCommerce > Status > Logs, origen wcp_viva_gateway. Un Client ID o Client Secret incorrectos, o un Source Code que falta, dan el mensaje de que los pagos con Viva Wallet no están disponibles. Si no se puede contactar con Viva o Viva rechaza la solicitud de pago, por ejemplo porque el Source Code pertenece a otra cuenta, el cliente recibe el mensaje de que la tienda no pudo conectar con Viva Wallet.

El pedido está On hold tras el pago: lee la nota del pedido. El importe o la moneda pagados no coinciden con el pedido. Completa el pedido o reembolsa el pago.

El reembolso falla con This payment was made in the Viva demo (or live) environment: no se han introducido el Client ID y el Client Secret de la cuenta en la que se hizo el pago. Introdúcelos e inténtalo de nuevo. Otros errores de reembolso muestran el código HTTP y el mensaje de Viva.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio ha cambiado, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.

Para desarrolladores: el filtro viva_wp_supported_currencies activa más monedas compatibles con tu cuenta de Viva, viva_wp_create_order_payload modifica la solicitud del pedido de pago (el importe, la moneda y el Source Code deben mantenerse) y viva_wp_icon cambia el icono de la finalización de compra.

Desinstalación

Desactivar el plugin conserva todos los datos; solo se eliminan los tokens de acceso de Viva en caché. Para eliminarlo, desactívalo y elimínalo en la página Plugins. La clave de licencia y el estado de licencia de este plugin, así como los tokens en caché y las claves de webhook, siempre se eliminan. Los ajustes, la tabla de intentos de pago y los registros del plugin (archivos de registro, incluidos los rotados, y entradas de registro de la base de datos) solo se eliminan si Delete Data on Uninstall estaba activado. Si no, se conservan para una reinstalación posterior. 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 plugin no está afiliado ni respaldado por Viva Wallet.