VibeFox Yoco for WooCommerce — Ayuda

Requisitos

WordPress: 6.2 o posterior.

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

PHP: 8.0 o posterior.

Moneda de la tienda: rand sudafricano (ZAR). Yoco solo acepta ZAR. Con cualquier otra moneda, el método de pago no aparece en la finalización de compra. El importe total del pedido debe ser de al menos R2,00.

Cuenta de Yoco: una cuenta de Yoco con pagos en línea. Necesitas sus claves secretas, que encontrarás en el Yoco Business Portal en Selling Online > Payment Gateway. Solo se introducen las claves secretas. El webhook lo registra el plugin, y su secreto de firma se rellena por ti.

Sitio público: Yoco envía webhooks a tu sitio, así que debe ser accesible desde internet. La URL del webhook debe aceptar un POST sin redirecciones.

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_yoco_pay a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Yoco > Manage.

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. Pega la clave secreta de prueba (sk_test_...) y, cuando estés listo, la clave secreta real (sk_live_...). Guarda los ajustes. El webhook se registra para cada modo que tenga una clave.

6. Activa Enable/Disable. Haz un pago de prueba con una tarjeta de prueba de Yoco mientras Test mode esté activado; después desmarca Test mode para aceptar pagos reales.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Yoco. Encima de los campos, la página avisa cuando la moneda de la tienda no es ZAR (en ese caso Yoco no se ofrece en la finalización de compra) y cuando el modo actual no tiene clave secreta. En la lista de métodos de pago, Yoco aparece como pendiente de configuración hasta que el modo actual tenga una clave secreta. Al guardar, el plugin comprueba las claves y los secretos de los webhooks y registra los webhooks. Los mensajes al respecto aparecen en la parte superior de la página.

General

Enable/Disable: Enable Yoco activa o desactiva el método de pago. Por defecto: off.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. Por defecto: Card or Instant EFT (Yoco).

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Claves API

Copia las claves secretas desde el Yoco Business Portal en Selling Online > Payment Gateway. Yoco tiene una sola API para ambos modos: la clave decide si un pago es de prueba o real. El modo de prueba usa solo la clave de prueba, y el modo real, solo la clave real.

Test mode: Use the test secret key (no real payments). No se cobra dinero real; paga con tarjetas de prueba de Yoco. Por defecto: on. Desmárcalo para aceptar pagos reales.

Test secret key: la clave secreta del modo de prueba. Empieza por sk_test_.

Live secret key: la clave secreta del modo real. Empieza por sk_live_.

Una clave que no empieza por el prefijo esperado no se guarda: la página muestra un error y conserva el valor anterior. Si Yoco informa durante el registro del webhook de que una clave pertenece al otro modo, la página te lo indica.

Webhooks

Yoco confirma los pagos y los reembolsos a la URL del webhook que se muestra en esta sección. Tiene este aspecto: https://your-site/wc-api/yoco_pay_webhook/. No necesitas crear el webhook en el portal de Yoco. Al guardar los ajustes, el plugin registra la URL en Yoco para cada modo que tenga una clave secreta pero no un secreto de webhook, y guarda el secreto de firma en el campo de ese modo. Vuelve a registrar la URL cuando cambia la clave secreta de ese modo o la URL del webhook. Cuando cambia la URL, el registro anterior se elimina.

Para cada modo, la sección muestra el estado del webhook:

El plugin gestiona estos eventos:

Los webhooks sin una firma válida se rechazan. Si tu sitio usa un prefijo de idioma en las URL, mantén la URL exactamente como la muestra la configuración, porque el webhook debe llegar a tu tienda sin redirección.

Test webhook secret: se rellena automáticamente al registrar el webhook. Pega un secreto (whsec_...) solo si registraste tú mismo la URL del webhook.

Live webhook secret: se rellena automáticamente al registrar el webhook. Borra el campo y guarda para registrar el webhook de nuevo.

Un secreto de webhook debe tener la forma whsec_ seguido de texto en base64. Cualquier otro valor no se guarda y se conserva el anterior.

Avanzado

Debug log: Log Yoco requests and webhooks escribe las peticiones y los webhooks en WooCommerce > Status > Logs, origen wcp_yoco_pay. Los errores y las advertencias, como las peticiones fallidas a Yoco y los webhooks rechazados, siempre se registran. Las claves, los secretos de webhook y las direcciones de correo se enmascaran. Por defecto: off.

Delete data: Delete the settings and logs of this plugin when it is deleted. Desactivar el plugin nunca borra nada. Los datos de pedidos (los ID del checkout y del pago de Yoco) siempre se conservan, porque son necesarios para los reembolsos. Por defecto: off.

Finalización de compra

El cliente elige el método de pago (por defecto Card or Instant EFT (Yoco)) y realiza el pedido. En el modo de prueba, la finalización de compra muestra Test mode — use a Yoco test card; no real money is charged. El plugin crea un checkout de Yoco por el importe total del pedido en céntimos y envía al cliente a la página de pago de Yoco, donde paga con tarjeta o Instant EFT.

Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Yoco lo confirma: el plugin pide a Yoco el checkout cuando el cliente regresa y de nuevo cuando llega el webhook firmado. Si Yoco todavía no ha confirmado el pago, la página de pedido recibido muestra We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

Si el cliente cancela en la página de Yoco, el pedido queda sin pagar y el cliente llega a la página Pay for order con el mensaje The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. Si el pago falla, el mensaje es The Yoco payment was not successful. Please try again or choose another payment method. y se añade una nota al pedido.

El cliente puede pagar de nuevo un pedido sin pagar desde la página Pay for order. Antes de un nuevo intento, el plugin comprueba el anterior con Yoco. Si ya estaba pagado, el pedido se completa sin mostrar una nueva página de pago. Si sigue abierto por el mismo importe y se creó hace menos de 30 minutos, el cliente recibe de nuevo la misma página de Yoco.

Si Yoco no puede iniciar el pago, el cliente ve Yoco could not start the payment. Please try again in a moment or choose another payment method. y el motivo se añade a las notas del pedido. Un pedido por debajo de R2,00 muestra Yoco requires an order total of at least R2.00.

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. Es compatible con WooCommerce High-Performance Order Storage (HPOS).

Los pagos se cobran de inmediato en la página de Yoco. El plugin no tiene tarjetas guardadas, suscripciones ni pagos recurrentes, ni formulario de tarjeta en el sitio, ni autorización y captura por separado, y no funciona en monedas distintas de ZAR.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente fue enviado a Yoco y todavía no ha pagado, canceló en la página de Yoco o Yoco aún no ha confirmado el pago.

Processing or Completed: el pago fue confirmado. WooCommerce pone Procesando, o Completado para los pedidos con solo productos virtuales descargables. La nota del pedido muestra el importe, los ID del pago y del checkout de Yoco, el modo y cómo se confirmó el pago (el regreso del cliente, el webhook o una comprobación antes de un nuevo intento de pago). El ID de la transacción es el ID del pago de Yoco.

On hold: Yoco informó de un importe o una moneda distintos del total del pedido, por ejemplo porque el pedido se editó después de iniciar el pago. La nota lo explica, y el cliente que regresa desde Yoco ve We received your payment and are reviewing it. We will contact you if anything else is needed. Revisa el pago antes de enviar el pedido.

Cancelled or Refunded: un pago que llega para un pedido así no lo modifica. Una nota te pide reembolsar el pago en el portal de Yoco o restaurar el pedido manualmente. El cliente que regresa desde Yoco ve Your payment was received after the order had been cancelled. Please contact us — do not pay again.

Si llega un segundo pago para un pedido que ya está pagado, el pedido no se vuelve a modificar. Una nota te pide reembolsarlo en el portal de Yoco.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en el botón Refund via con el nombre de tu método de pago (por defecto Card or Instant EFT (Yoco)). Se admiten reembolsos totales y parciales. El reembolso se envía en el modo en que se hizo el pago (prueba o real), así que la clave secreta de ese modo debe estar configurada. Un reembolso repetido tras una respuesta perdida no se paga dos veces.

Un reembolso correcto se añade a las notas del pedido con el ID del reembolso de Yoco. Si Yoco rechaza el reembolso, WooCommerce muestra Yoco refused the refund: con el motivo, y no se registra ningún reembolso. Si Yoco informa de que el reembolso está pendiente, WooCommerce muestra que sigue pendiente y no registra nada. No lo repitas: se añade al pedido cuando Yoco lo confirme por webhook.

Los reembolsos hechos en el portal de Yoco llegan mediante el webhook refund.succeeded y se registran automáticamente como reembolsos de WooCommerce, sin reponer existencias. Un reembolso mayor que el importe que queda por reembolsar no se registra, y una nota te pide revisar el pedido. Un reembolso fallido añade una nota que indica que el dinero no se devolvió al cliente.

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 > Yoco. 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 volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla 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. Quitar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Yoco 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. Los gestores de la tienda que han iniciado sesión 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 aviso 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 una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

Yoco no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el modo actual tiene una clave secreta: Test secret key en el modo de prueba, Live secret key en el modo real. La moneda de la tienda o del pedido debe ser ZAR, y el importe total del pedido, de al menos R2,00. La página de ajustes muestra un aviso cuando falta la clave o la moneda no es ZAR.

El pago se realizó, pero el pedido sigue en Pending payment: el webhook no funciona. Abre la sección Webhooks de los ajustes y revisa el estado del modo que usas. Si no está registrado, o está registrado para otra URL, guarda los ajustes. Si el registro falla, la página muestra el motivo. Si introdujiste el secreto tú mismo, comprueba que pertenece al webhook de esta URL y de este modo. El pedido también se confirma cuando el cliente vuelve a la tienda después de pagar y cuando intenta pagar de nuevo.

No se pudo registrar el webhook: los pagos siguen confirmándose cuando los clientes vuelven a la tienda. Corrige el motivo que muestra el mensaje, por ejemplo que el sitio debe ser accesible desde internet por HTTPS, y guarda de nuevo. También puedes registrar la URL tú mismo y pegar el secreto de firma.

Los webhooks se rechazan: los webhooks rechazados se escriben en el registro, origen wcp_yoco_pay. webhook secret not configured significa que no hay ningún secreto de webhook configurado. invalid signature significa que el secreto pertenece a otro registro o modo. timestamp outside the tolerance significa que el reloj del servidor está mal: las firmas se aceptan dentro de 5 minutos de la hora del servidor. checkout not completed yet — retry y could not confirm the checkout with Yoco — retry son temporales; Yoco vuelve a enviar el webhook.

The secret key must start with sk_test_ / sk_live_ error on save: se pegó una clave en el campo equivocado. La clave de prueba empieza por sk_test_, y la real, por sk_live_. Se conservó el valor anterior.

El cliente ve un error al realizar el pedido: lee las notas del pedido o WooCommerce > Status > Logs, origen wcp_yoco_pay. Yoco is not available at the moment. Please choose another payment method. significa que el modo actual no tiene clave secreta.

Al cliente se le indica que un pago debe revisarse: un intento anterior se pagó con un importe distinto, o después de cancelar el pedido. Lee la nota del pedido y completa el pedido o reembolsa el pago en el portal de Yoco.

El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o real, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo.

El reembolso falla con el mensaje No answer from Yoco: no se registró nada en WooCommerce. Si Yoco sí procesó el reembolso, repite el mismo reembolso: no se reembolsará dos veces.

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 cambió la dirección del sitio, 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.

Desinstalación

Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, los registros de webhooks en Yoco y los registros, incluidos los archivos de registro rotados, se eliminan solo si Delete data 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.

Yoco es una marca comercial de su respectivo titular. Este plugin no está afiliado a Yoco ni cuenta con su aprobación.