VibeFox Peach Payments for WooCommerce — Ayuda
Requisitos
WordPress: 6.2 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. El plugin no permite activarse sin él.
PHP: 8.0 o posterior.
Currency: la moneda de la tienda debe ser ZAR, KES o MUR. Con otras monedas se oculta el método de pago y se indica en la página de ajustes.
Peach Payments account: necesitas las credenciales de Card API de tu cuenta de Peach Payments: Entity ID y Access Token. Las credenciales de prueba proceden del panel del sandbox de Peach Payments, y las de producción, del panel de Peach Payments; son distintas. Para los webhooks también necesitas una clave de descifrado que Peach Payments te envía al activar los webhooks de Card para tu tienda (consulta Configuración). Tu sitio debe ser accesible desde Internet para recibir webhooks.
VibeFox license key: comprada en vibefox.net. Una clave funciona en un 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_peach_pay a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Peach Payments > Manage, o haz clic en Settings debajo del nombre del plugin en la página de 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 el Entity ID y el Access Token de prueba del panel del sandbox de Peach Payments y pide a Peach Payments que active los webhooks de Card para la URL de webhook que aparece en los ajustes (consulta Configuración).
6. Activa Enable/Disable y guarda. Mantén Test mode activado y realiza un pago con una tarjeta de prueba del sandbox de Peach Payments. Después desmarca Test mode, introduce las credenciales de producción y la clave de webhook de producción, y guarda.
Los ajustes de la versión 1.0 se trasladan automáticamente a los nuevos campos tras la actualización.
Configuración
Todos los ajustes están en una página: WooCommerce > Settings > Payments > Peach Payments. Encima de los campos aparecen avisos: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; un aviso si falta el Entity ID o el Access Token del modo actual (hasta entonces el método no aparece en la finalización de compra); un aviso si falta la clave de descifrado de webhooks del modo actual (entonces los pagos solo se confirman cuando el cliente vuelve a la tienda); y un aviso si la moneda de la tienda no es compatible. En la lista de métodos de pago, Peach Payments figura como pendiente de configuración hasta que el modo actual tenga Entity ID y Access Token. Al guardar se eliminan los espacios de las credenciales y se muestra un error si la clave de webhook no es un valor hexadecimal de 64 caracteres.
Enable/Disable: Enable Peach Payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ve el cliente en la finalización de compra. Predeterminado: Credit / Debit Card (Peach Payments).
Description: el texto que aparece debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
Credenciales de API
El Access Token y el Entity ID de Card API aparecen en el panel de Peach Payments (las credenciales de prueba, en el panel del sandbox). La sección enlaza con ambos paneles y con la documentación para desarrolladores de Peach Payments.
Test mode: Enable test mode envía los nuevos pagos al sandbox de Peach Payments con las credenciales de prueba, sin cobrar dinero real. Desmárcalo para aceptar pagos reales con las credenciales de producción. Un pago iniciado en un modo siempre se comprueba en ese modo, incluso si lo cambias después. Predeterminado: activado.
Test Entity ID: el Entity ID (canal 3-D Secure) de tu cuenta de sandbox.
Test Access Token: el token de acceso de tipo bearer de tu cuenta de sandbox.
Test Webhook Decryption Key: la clave hexadecimal de 64 caracteres para descifrar los webhooks de Card del sandbox.
Live Entity ID: el Entity ID (canal 3-D Secure) de tu cuenta de producción.
Live Access Token: el token de acceso de tipo bearer de tu cuenta de producción.
Live Webhook Decryption Key: la clave hexadecimal de 64 caracteres para descifrar los webhooks de Card de la cuenta de producción.
Webhook
Los webhooks confirman los pagos aunque el cliente cierre el navegador antes de volver a la tienda. La sección muestra la URL de webhook de tu tienda. Tiene el formato https://your-site/wp-json/peach-pay/v1/webhook. Copia la URL exactamente como aparece en los ajustes. Pide a Peach Payments (support@peachpayments.com) que active los webhooks de Card para tu cuenta con esta URL y después introduce la clave de descifrado recibida en el campo Webhook Decryption Key del mismo modo.
Peach Payments cifra cada webhook (AES-256-GCM). Los webhooks que no puedan descifrarse con la clave de prueba o de producción se rechazan, de modo que solo Peach Payments puede modificar tus pedidos. Un webhook descifrado con la clave de un modo solo se aplica a pagos iniciados en ese modo. El plugin usa notificaciones de pago:
Las demás notificaciones, como la notificación de prueba al activar el webhook, reciben una respuesta OK y se ignoran. Sin la clave de webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda después de pagar.
Formulario de pago
Card brands: las marcas que aparecen en el formulario de Peach Payments: Visa, Mastercard, American Express, Diners Club. Selecciona solo las activadas para tu Entity ID. Predeterminado: Visa y Mastercard.
Avanzado
Logging: Log API requests and payment results escribe información de depuración en WooCommerce > Status > Logs, origen wcp_peach_pay. Los errores y las advertencias siempre se registran. Los registros no contienen datos de tarjeta, claves ni datos de clientes. Predeterminado: desactivado.
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Desactivar el plugin nunca elimina nada. Se conservan los datos de Peach Payments guardados en los pedidos. Predeterminado: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Credit / Debit Card (Peach Payments)) y hace clic en Continue to payment. Se le dirige a la página Pay for order de tu tienda. Allí el plugin prepara una finalización de compra de Peach Payments por el total y en la moneda del pedido, y muestra el formulario de tarjeta de Peach Payments con las marcas seleccionadas, en el idioma del sitio si Peach Payments lo admite. En modo de prueba la página muestra Test mode: use a Peach Payments test card, no real payment will be made.. Los datos de tarjeta se introducen en el formulario de Peach Payments y su script se carga con un hash de Subresource Integrity.
Después de pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando Peach Payments lo confirma: la tienda consulta el resultado de la finalización de compra de este pedido en la API de Peach Payments, en el modo en que se creó, y comprueba que el pago pertenece al pedido. El webhook hace lo mismo de forma independiente; el primero en llegar aplica el resultado y el otro no cambia nada. El cliente que ha pagado ve la página Order received.
Si el pago no se completa, el cliente vuelve a la página Pay for order con un mensaje y puede reintentarlo: Payment failed: seguido del motivo de Peach Payments y Please try again or use another card., o The payment was not completed. Please try again.. Si aún no puede confirmarse el resultado (por ejemplo, Peach Payments no respondió o el webhook está procesando el mismo pedido), aparece We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.. Si no hay una clave de webhook configurada para ese modo, se pide al cliente que se ponga en contacto contigo indicando el número del pedido.
Si no se puede preparar el formulario de pago, el cliente ve un mensaje breve y un botón Try again: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (credenciales incorrectas), un mensaje indicando que el proveedor de pago no aceptó algunos datos de facturación, o The payment form could not be loaded. Please try again in a moment.. Se añade al pedido una nota con el código y la descripción de Peach Payments.
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).
El plugin no tiene formulario de tarjeta en la propia página de finalización de compra, tarjetas guardadas, suscripciones, preautorización y captura, ni EFT, BNPL, QR u otros métodos que no sean con tarjeta.
Pedidos
Estados del pedido
Pending payment: el cliente aún no ha pagado o el pago no se completó. Puede volver a pagar el mismo pedido.
Processing: el pago se confirmó y el importe y la moneda coinciden con el pedido. La nota muestra el código de resultado, la descripción y el ID de pago de Peach Payments; este ID es el ID de transacción del pedido. Si Peach Payments señaló el pago para revisión manual, la nota te pide que lo compruebes en el panel de Peach Payments antes del envío.
On hold: el pago espera confirmación de Peach Payments (el webhook lo completa más tarde o lo marca como fallido); el importe o la moneda pagados difieren del pedido (nota amount/currency mismatch — manual review required); o el pago llegó después de que se cancelara el pedido. La nota explica qué comprobar.
Failed: Peach Payments rechazó el pago de un pedido Pendiente de pago o el pago que esperaba un pedido En espera. Un intento rechazado nunca modifica un pedido pagado, en espera por otro motivo o cancelado. El cliente puede volver a pagar.
Si se realiza correctamente un segundo pago de un pedido ya pagado, el pedido no cambia. Una nota indica que el pago está duplicado y te pide que lo reembolses en el panel de Peach Payments. Si llega un pago para un pedido reembolsado, solo se añade una nota al pedido.
Reembolsos
No se pueden hacer reembolsos desde la pantalla del pedido de WooCommerce. Reembolsa el pago en el panel de Peach Payments y registra un reembolso manual en WooCommerce. Con el webhook configurado, los reembolsos, anulaciones y contracargos realizados en Peach Payments se añaden como notas con el importe y el ID; el estado del pedido no cambia.
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 > Peach Payments. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que está activa la licencia y tu dominio. Usa Check now para volver a comprobarlo, 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 dominio. Quitarla de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Peach Payments no aparece a los clientes en la finalización de compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one.. Los gestores de tienda que han iniciado sesión siguen viendo el método, marcado con (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 de plugins y en las de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose cuando vuelve el cliente y mediante el webhook.
Cuando caduca una licencia, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Peach Payments no aparece en la finalización de compra: comprueba que la licencia está activa, Enable/Disable está activado, has introducido el Entity ID y el Access Token del modo actual (Test Entity ID y Test Access Token en modo de prueba, Live Entity ID y Live Access Token en producción) y la moneda de la tienda es ZAR, KES o MUR. Los avisos de la parte superior de los ajustes indican el problema. Los desarrolladores pueden cambiar las monedas mediante el filtro peach_p_supported_currencies; añade solo monedas que procese tu cuenta de Peach Payments.
El pago se realizó, pero el pedido sigue en Pending payment: el cliente no volvió a la tienda y el webhook no llegó. Comprueba que Peach Payments activó los webhooks de Card para la URL exacta de los ajustes, que has introducido la Webhook Decryption Key del modo en que se pagó y que ningún modo de mantenimiento, cortafuegos o protección por contraseña bloquea la URL. Busca webhooks rechazados en WooCommerce > Status > Logs, origen wcp_peach_pay.
El webhook responde Decryption failed: no se pudo descifrar con la clave de prueba ni de producción. La clave es incorrecta o pertenece a otra cuenta o modo. Introduce la clave que Peach Payments envió para esta URL de webhook.
El webhook responde Webhook key not configured: ninguna de las claves está configurada o es válida. Introduce la clave de 64 caracteres. Peach Payments volverá a enviar el webhook más tarde.
El webhook responde Order busy, retry later: el pedido se estaba actualizando al volver el cliente en ese mismo momento. No se cambió nada y Peach Payments volverá a enviar el webhook.
El webhook responde Missing or malformed data: la solicitud no tenía cuerpo cifrado o faltaban las cabeceras X-Initialization-Vector / X-Authentication-Tag, por ejemplo porque un proxy la modificó. No se cambió nada.
El webhook responde ignored: la notificación es auténtica, pero no pertenece a una finalización de compra de esta tienda (otra tienda con el mismo Entity ID, un pedido eliminado), o procede de un modo distinto al del pago. No se cambió nada.
El cliente ve The payment form is not available right now: el Access Token o el Entity ID del modo actual es incorrecto. Comprueba las credenciales y el modo, y consulta el código de Peach Payments en la nota del pedido.
El pedido está en On hold después de pagar: lee la nota del pedido. El importe o la moneda pagados eran distintos, el pago llegó tras la cancelación del pedido o Peach Payments aún espera confirmación del pago. Comprueba el pago en el panel de Peach Payments y después procesa el pedido o reembolsa el pago.
Al guardar se indica que la clave de webhook debe ser hexadecimal de 64 caracteres: el valor no es la clave de Peach Payments. Los webhooks no se pueden descifrar hasta corregirlo.
El bloque de licencia muestra un error: sigue el mensaje del bloque. 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 contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para quitarlo, desactívalo y elimínalo en la página Plugins. La clave y el estado de licencia de este plugin siempre se eliminan. Sus ajustes y registros (archivos de registro y entradas en la base de datos del origen wcp_peach_pay) solo se eliminan si Delete data on uninstall estaba activado. En caso contrario, se conservan para una futura reinstalación. Los pedidos existentes conservan sus notas de pago, ID de transacción y datos de finalización de compra de Peach Payments.
Peach Payments es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Peach Payments ni cuenta con su respaldo.