VibeFox Yoco 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.

Moneda de la tienda: rand sudafricano (ZAR). Yoco solo acepta ZAR. En cualquier otra moneda, el método de pago no se muestra en el checkout. El 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 módulo, y su secreto de firma se rellena por ti.

Sitio público: Yoco envía webhooks a tu tienda, por lo 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 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 carga, haz clic en Configure, o busca más tarde VibeFox Yoco Pay Gateway en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).

4. Pega la clave secreta de prueba (sk_test_...) y, cuando estés listo, la clave secreta real (sk_live_...). Haz clic en Save. El webhook se registra para cada modo que tenga una clave.

5. Activa Enable/Disable y haz clic en Save. Haz un pago de prueba con una tarjeta de prueba de Yoco mientras Test mode esté activado; después desactiva Test mode para cobrar pagos reales.

Al instalarse, el módulo crea el estado de pedido Yoco payment on hold. PrestaShop activa el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Sobre los campos, la página avisa cuando la moneda de la tienda no es ZAR (en ese caso Yoco no se ofrece en el checkout) y cuando el modo actual no tiene clave secreta, por ejemplo Enter the test secret key to offer Yoco at checkout (test mode). Al guardar, el módulo comprueba las claves y los secretos de webhook, y registra los webhooks. Los mensajes al respecto aparecen en la parte superior de la página.

Yoco

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

Title: el nombre del método de pago que ven los clientes en el checkout. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Card or Instant EFT (Yoco).

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

API keys

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; el modo real, solo la clave real.

Test mode: usa la clave secreta de prueba. No se cobra dinero real; paga con tarjetas de prueba de Yoco. Por defecto: activado. Desactívalo para cobrar pagos reales. Mientras esté activado, los clientes ven Test mode — use a Yoco test card; no real money is charged. debajo del método de pago.

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, por ejemplo Yoco: the test secret key must start with sk_test_ — the previous value was kept. Si Yoco informa durante el registro del webhook de que una clave pertenece al otro modo, la página te lo indica.

Las claves y los secretos 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.

Webhooks

Yoco confirma los pagos y los reembolsos a la URL que aparece en Webhook URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_yoco_pay/webhook, posiblemente con un código de idioma como /en/. No necesitas crear el webhook en el portal de Yoco. Al guardar los ajustes, el módulo 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 cuando cambia la URL del webhook. Si la URL cambia, el registro anterior se elimina.

Para cada modo (Test y Live) la sección muestra el estado del webhook:

El módulo gestiona estos eventos (también aparecen en esta sección):

Los webhooks sin una firma válida se rechazan. Un evento debe estar firmado con el secreto del modo en el que se hizo el pago, de modo que una clave secreta de prueba nunca confirma un pago real. Copia la URL exactamente como la muestran los ajustes, 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. Bórralo y guarda para registrar el webhook de nuevo.

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

Clear saved secrets: marca una clave o un secreto y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado. Borrar un secreto de webhook y guardar vuelve a registrar el webhook.

Advanced

Debug log: escribe las peticiones y los webhooks de Yoco en logs/yoco_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y avisos, como las peticiones fallidas a Yoco y los webhooks rechazados, siempre se registran. Las claves, los secretos de webhook y las direcciones de correo electrónico se enmascaran. Por defecto: desactivado.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete data: cuando está activado, al desinstalar el módulo se eliminan los ajustes, el registro y los webhooks que el módulo registró en Yoco. Los datos de pedido (IDs de checkout y de pago de Yoco, reembolsos) y el estado de pedido Yoco payment on hold siempre se conservan, porque son necesarios para los reembolsos. Por defecto: desactivado.

Checkout

En el paso de pago, el cliente elige el método de pago (por defecto Card or Instant EFT (Yoco)) y confirma. El módulo crea un checkout de Yoco por el total del carrito en céntimos y envía al cliente a la página de pago de Yoco, donde paga con tarjeta o Instant EFT. En este momento 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 Yoco lo confirma: el módulo pide a Yoco el checkout cuando el cliente regresa y de nuevo cuando llega el webhook firmado. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with Yoco has been received. Si Yoco todavía no ha confirmado el pago cuando el cliente vuelve, se muestra una página Payment confirmation con We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. y un botón Check again; el webhook crea el pedido en cuanto llega.

Si el cliente cancela en la página de Yoco, vuelve al checkout con The Yoco payment was cancelled. Your cart is saved — you can pay again 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. El carrito se conserva.

Antes de un nuevo intento de pago para el mismo carrito, el módulo comprueba el anterior con Yoco. Si ya estaba pagado, el pedido se crea 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. En caso contrario, se crea un nuevo checkout de Yoco.

Si Yoco no puede iniciar el pago, el cliente se queda en el checkout con Yoco could not start the payment. Please try again in a moment or choose another payment method. y el motivo se escribe en el registro. A un pedido por debajo de R2,00 se le muestra Yoco requires an order total of at least R2.00.

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.

Los pagos se cobran de inmediato en la página de Yoco. El módulo 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

No order yet: el cliente fue enviado a Yoco y no ha pagado, canceló en la página de Yoco, o Yoco todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: el pago fue confirmado. El pago se registra con el ID de pago de Yoco como ID de transacción, y una nota muestra el importe, los IDs de pago y de checkout de Yoco, el modo y la forma en que se confirmó el pago (el regreso del cliente, el webhook o una comprobación antes de un nuevo intento de pago).

Yoco payment on hold: Yoco informó de un importe o una moneda distintos al total del carrito, por ejemplo porque el carrito se cambió en otra pestaña después de iniciar el pago. No se registra ningún pago, la nota lo explica y el cliente 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. Si el cliente paga el importe correcto con otro intento, el pedido pasa a Payment accepted.

Cancelled or Refunded: un pago que llega para un pedido así no lo modifica. Una nota te pide que reembolses el pago en el portal de Yoco o que restaures el pedido manualmente. El cliente 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 cambia. Una nota te pide que lo reembolses en el portal de Yoco.

Bloque de pago de Yoco

La página del pedido muestra un bloque Yoco payment con los IDs de pago y de checkout de Yoco, el estado, el importe pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos, los intentos de pago del carrito (cuando hubo más de uno) y las Yoco notes del pedido.

Reembolsos

En el bloque Yoco payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Yoco. Confirma la pregunta Refund this amount through Yoco? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas permiso para editar pedidos. Los reembolsos se calculan sobre el importe que cobró Yoco, así que solo puedes reembolsar como máximo lo que el cliente pagó realmente, aunque el pedido se haya editado después. 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 al historial de reembolsos y a las notas, con el ID de reembolso de Yoco. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Si Yoco rechaza el reembolso, el bloque muestra Yoco refused the refund: con el motivo, y no se registra ningún reembolso. Si Yoco informa de que el reembolso está pendiente, el bloque indica que sigue pendiente. No lo repitas: se registrará cuando Yoco lo confirme mediante webhook. Los reembolsos están disponibles para pedidos pagados con un checkout de Yoco. Un pedido en Yoco payment on hold no tiene un checkout pagado que reembolsar; reembólsalo en el portal de Yoco.

El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Yoco.

Los reembolsos hechos en el portal de Yoco llegan mediante el webhook refund.succeeded y se registran en el historial de reembolsos y en las notas. Cuando alcanzan el importe pagado, el pedido pasa a Refunded. Un reembolso mayor que el importe que queda por reembolsar no se registra, y una nota te pide que revises el pedido. Un reembolso fallido añade una nota que indica que el dinero no se devolvió al cliente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Yoco Pay Gateway es el primer bloque de Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure, por 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 aparecen la línea Product: presta-payment-yoco 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. Tras 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 el servidor de licencias no responde, 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, Yoco no se muestra a los clientes en el checkout. Si se inicia un pago de todos modos, 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 se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en el checkout. Un recordatorio aparece en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

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 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

Yoco no aparece en el checkout: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga una clave secreta: Test secret key en modo de prueba, Live secret key en modo real. La moneda del carrito debe ser ZAR y el total del pedido, de al menos R2,00. La página de ajustes muestra una advertencia cuando falta la clave o la moneda de la tienda no es ZAR. En Payment > Preferences comprueba que el módulo esté permitido para ZAR, el país del cliente y el grupo del cliente.

El pago se completó, pero no se creó ningún pedido: el webhook no funciona. Abre la sección Webhooks de los ajustes y comprueba 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 pertenezca al webhook de esta URL y de este modo. El pedido también se crea 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 se siguen confirmando cuando los clientes vuelven a la tienda. Corrige el motivo que muestra el mensaje, por ejemplo que la tienda 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. 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 a otro modo. timestamp outside the tolerance significa que el reloj del servidor está mal: las firmas se aceptan dentro de los 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.

La URL del webhook muestra solo POST en el navegador: es normal. La URL acepta únicamente peticiones de Yoco.

Error al guardar la clave secreta («The secret key must start with sk_test_ / sk_live_»): una clave se pegó en el campo equivocado. La clave de prueba empieza por sk_test_ y la real por sk_live_. Se mantuvo el valor anterior.

El cliente ve un error al elegir Yoco: mira el campo Log de la página del módulo. Yoco is not available at the moment. Please choose another payment method. significa que el modo actual no tiene clave secreta.

Se avisa al cliente de que su pago debe revisarse: un intento se pagó con un importe distinto, o después de que el pedido se cancelara. Lee las notas del bloque Yoco payment 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 «No answer from Yoco»: no se registró nada en PrestaShop. Si Yoco sí procesó el reembolso, repite el mismo reembolso: no se reembolsará dos veces.

Desarrolladores: el hook actionYocoPCheckoutPayload permite que otro módulo modifique la petición que crea el checkout de Yoco.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Yoco Pay Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete data está activado, se eliminan los ajustes, el registro y los webhooks que el módulo registró en Yoco. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los checkouts y reembolsos de Yoco y el estado de pedido Yoco payment on hold siempre se conservan, de modo que los pedidos pagados antes pueden seguir reembolsándose tras reinstalar. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.

Yoco es una marca comercial de su titular. Este módulo no está afiliado a Yoco ni cuenta con su respaldo.