VibeFox Peach Payments for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior con la extensión OpenSSL (se usa para descifrar los webhooks). El módulo no se instala si faltan.
Moneda: la moneda del carrito debe ser ZAR, KES o MUR. En los carritos con otras monedas, el método de pago se oculta. La página de configuración avisa cuando la moneda predeterminada de la tienda no es una de ellas.
Cuenta de Peach Payments: necesitas las credenciales de Card API de tu cuenta de Peach Payments: el Entity ID y el Access Token. Las credenciales de prueba se obtienen 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 de webhooks, que Peach Payments te envía cuando activa los webhooks de Card para tu tienda (ver Configuración). Tu tienda debe ser accesible desde internet para recibir webhooks.
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 Peach Payments Pay Gateway en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. 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 del webhook que aparece en la página de configuración (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Mantén Test mode activado y haz un pago con una tarjeta de prueba del sandbox de Peach Payments. Después desactiva Test mode, introduce las credenciales de producción y la clave de webhook de producción, y haz clic en Save.
Al instalar, el módulo crea dos estados de pedido: Awaiting Peach Payments payment y Peach Payments payment on hold. PrestaShop ofrece un nuevo método de pago para las monedas, países y grupos de clientes activos en ese momento. Los países que añadas después deben habilitarse para el módulo en Payment > Preferences, donde también puedes limitarlos.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra avisos: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; un error cuando falta el Entity ID o el Access Token del modo actual (hasta entonces el método de pago no se muestra en la finalización de compra); una advertencia cuando 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 error cuando la moneda predeterminada de la tienda no es compatible. Al guardar, se eliminan los espacios de las credenciales, y una clave de webhook que no sea un valor hexadecimal de 64 caracteres se notifica con una advertencia.
Peach Payments
Enable/Disable: Enable Peach Payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que el cliente ve en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Credit / Debit Card (Peach Payments). Obligatorio.
Description: el texto que se muestra 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.
API credentials
El Access Token y el Entity ID de la Card API aparecen en el panel de Peach Payments (las credenciales de prueba, en el panel del sandbox). La sección enlaza a ambos paneles y a la documentación para desarrolladores de Peach Payments.
Test mode: envía los pagos nuevos al sandbox de Peach Payments con las credenciales de prueba, y no se cobra dinero real. Desactívalo para aceptar pagos reales con las credenciales de producción. Un pago iniciado en un modo siempre se comprueba en ese modo, incluso después de cambiarlo. Predeterminado: activado.
Test Entity ID: el Entity ID (canal de 3-D Secure) de tu cuenta sandbox.
Test Access Token: el token de acceso bearer de tu cuenta sandbox.
Test Webhook Decryption Key: la clave hexadecimal de 64 caracteres que se usa para descifrar los webhooks de Card del sandbox.
Live Entity ID: el Entity ID (canal de 3-D Secure) de tu cuenta de producción.
Live Access Token: el token de acceso bearer de tu cuenta de producción.
Live Webhook Decryption Key: la clave hexadecimal de 64 caracteres que se usa para descifrar los webhooks de Card de la cuenta de producción.
Los access tokens y las claves de webhook guardados no 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 access token o una clave de webhook y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Webhook
Los webhooks confirman los pagos aunque el cliente cierre el navegador antes de volver a la tienda. El campo Webhook URL muestra la URL del webhook de tu tienda. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_peach_pay/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en la configuración. 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 que recibas en el campo Webhook Decryption Key del mismo modo.
Peach Payments cifra cada webhook (AES-256-GCM). Un webhook que no se pueda descifrar con la clave de prueba o de producción se rechaza, de modo que solo Peach Payments puede cambiar tus pedidos. Un webhook descifrado con la clave de un modo se aplica solo a los pagos iniciados en ese modo. El módulo usa notificaciones de pago:
Otras notificaciones, por ejemplo la notificación de prueba que se envía al activar el webhook, reciben la respuesta ignored. Sin la clave de webhook, un pedido se crea solo cuando el cliente vuelve a la tienda después de pagar.
Payment form
Card brands: las marcas que se muestran en el formulario de Peach Payments: Visa, Mastercard, American Express, Diners Club. Selecciona solo las marcas habilitadas para tu Entity ID. Predeterminado: Visa y Mastercard. Si no se selecciona ninguna marca, al guardar aparece una advertencia y el formulario muestra Visa y Mastercard.
Advanced
Logging: registra las peticiones a la API y los resultados de pago en logs/peach_p_debug.log.php dentro de la carpeta del módulo. El archivo no se puede leer desde la web. Los errores y advertencias se registran siempre. Los registros no contienen datos de tarjeta, claves ni datos de clientes. Predeterminado: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan sus ajustes y registros. Los datos de Peach Payments de los pedidos (intentos de pago, ID de pago) y los estados de pedido se conservan, porque pertenecen a los pedidos. Predeterminado: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Credit / Debit Card (Peach Payments)) y confirma el pedido. En modo de prueba, el método de pago muestra Test mode: no real payment will be made. El módulo prepara una finalización de compra de Peach Payments por el total del carrito en la moneda del carrito y muestra la página Peach Payments payment de tu tienda con el formulario de tarjeta de Peach Payments y las marcas de tarjeta seleccionadas, en el idioma del cliente cuando 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 la tarjeta se introducen en el formulario de Peach Payments, y el script del formulario se carga con un hash de Subresource Integrity. El enlace Choose another payment method lleva de nuevo a la finalización de compra. Todavía no existe ningún pedido en este punto. Si se recarga la página, se reutiliza la misma finalización de compra durante hasta 25 minutos, salvo que el carrito haya cambiado.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Peach Payments lo confirma: la tienda lee el resultado de la finalización de compra de este carrito desde la API de Peach Payments, en el modo en que se creó la finalización, y comprueba que el pago pertenece a este carrito. El webhook hace lo mismo de forma independiente, así que llegue primero lo que llegue, crea el pedido y el otro no cambia nada. Después, el cliente ve la página estándar de confirmación del pedido.
Si el pago no se completa, el cliente vuelve a la finalización de compra con un mensaje y puede intentarlo de nuevo: Payment failed: seguido del motivo indicado por Peach Payments y Please try again or use another card., o The payment was not completed. Please try again. El carrito se conserva. Si el resultado todavía no se puede confirmar (por ejemplo, Peach Payments no respondió, o el webhook está procesando ese mismo carrito en ese momento), el mensaje es We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Si no hay ninguna clave de webhook configurada para el modo del pago, se pide al cliente que se ponga en contacto contigo.
Si no se puede preparar el formulario de pago, el cliente se queda en la finalización de compra con un mensaje breve: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (credenciales faltantes o incorrectas), un mensaje que indica que el proveedor de pagos no aceptó algunos datos de facturación, o The payment form could not be loaded. Please try again in a moment. El motivo técnico se escribe en el registro.
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 no tiene formulario de tarjeta en el propio paso de finalización de compra, ni tarjetas guardadas, ni suscripciones, ni preautorización y captura, ni EFT, BNPL, QR u otros métodos que no sean con tarjeta.
Pedidos
Estados del pedido
No order yet: el cliente no ha pagado, el pago fue rechazado o no se completó, o Peach Payments todavía no lo ha confirmado. Solo existe el carrito, y el cliente puede volver a pagar.
Payment accepted: el pago se confirmó y el importe y la moneda coinciden con el carrito. El pago se registra con el ID de pago de Peach Payments como ID de transacción, y una nota muestra el código de resultado, la descripción y el ID de pago de Peach Payments. Si Peach Payments marcó el pago para revisión manual, la nota te pide que lo compruebes en el panel de Peach Payments antes de enviar el pedido.
Awaiting Peach Payments payment: Peach Payments informó de un pago que espera una confirmación. Después, el webhook pasa el pedido a Payment accepted o lo marca como fallido.
Peach Payments payment on hold: el importe o la moneda pagados no coinciden con el carrito (nota amount/currency mismatch — manual review required), o el pago llegó después de que el pedido se hubiera cancelado. La nota explica qué comprobar. Revisa el pago en el panel de Peach Payments y luego procesa el pedido o reembolsa el pago.
Payment error: Peach Payments rechazó el pago que esperaba el pedido pendiente de Peach Payments. Un intento rechazado nunca cambia un pedido que está pagado, en espera o cancelado.
Si un segundo pago de un pedido ya pagado se completa, el pedido no cambia. Una nota indica que es un pago duplicado y pide que lo reembolses en el panel de Peach Payments. Un pago que llega para un pedido reembolsado solo se anota en el pedido.
Bloque de pago de Peach Payments
La página del pedido muestra un bloque Peach Payments payment con el ID del pago, el ID de la finalización de compra, el ID de transacción del comerciante, el importe enviado a Peach Payments, el resultado y el código de resultado, una insignia Test mode para los pagos de prueba y las Peach Payments notes del pedido.
Reembolsos
Los reembolsos desde la página del pedido de PrestaShop no están disponibles. Reembolsa el pago en el panel de Peach Payments y regístralo en PrestaShop (reembolso parcial o nota de crédito) si hace falta. Con el webhook configurado, los reembolsos, anulaciones y contracargos hechos en Peach Payments se añaden a las notas del pedido con el importe y el ID; el estado del pedido no cambia.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Peach Payments Pay Gateway es el primer bloque de Modules > Module Manager > VibeFox Peach Payments 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-peach 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 el inglés y el 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, Peach Payments 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. 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 la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando con el regreso del cliente y con el webhook.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren 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 tras introducir la clave y después una vez a la semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Peach Payments no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el Entity ID y el Access Token del modo actual están introducidos (Test Entity ID y Test Access Token en modo de prueba, Live Entity ID y Live Access Token en modo de producción) y que la moneda del carrito es ZAR, KES o MUR. Los avisos de la parte superior de la configuración indican el problema. En Payment > Preferences comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo de clientes.
El pago se realizó, pero no se creó ningún pedido: el cliente no volvió a la tienda y el webhook no llegó. Comprueba que Peach Payments activó los webhooks de Card exactamente para la URL que aparece en la configuración, que está introducida la Webhook Decryption Key del modo en que se hizo el pago, y que ningún cortafuegos ni protección por contraseña bloquea la URL. Activa Logging y revisa el campo Log para ver los webhooks rechazados.
El webhook responde Decryption failed: el webhook no pudo descifrarse ni con la clave de prueba ni con la 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: no hay ninguna clave de webhook configurada o válida. Introduce la clave de 64 caracteres. Peach Payments volverá a enviar el webhook más tarde.
El webhook responde Busy, retry later: el carrito estaba siendo procesado por el regreso del cliente en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). No se cambió nada, y Peach Payments vuelve a enviar el webhook. El registro muestra el motivo.
El webhook responde Missing or malformed data: la petición no tenía cuerpo cifrado ni 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 carrito eliminado) o procede de un modo distinto al del pago. No se cambió nada.
La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta peticiones de Peach Payments.
El cliente ve The payment form is not available right now: el Access Token o el Entity ID del modo actual son incorrectos. Revisa las credenciales y el modo, y consulta el registro para ver el código de Peach Payments.
El pedido está en Peach Payments payment on hold después del pago: lee las notas del bloque Peach Payments payment. El importe o la moneda pagados eran distintos del carrito, o el pago llegó después de que el pedido se cancelara. Comprueba el pago en el panel de Peach Payments y luego procesa el pedido o reembolsa el pago.
Al guardar se muestra que la clave del webhook debe ser la clave hexadecimal de 64 caracteres: el valor no es la clave de Peach Payments. Los webhooks no se pueden descifrar hasta que se corrija.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Peach Payments Pay Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes y registros del módulo. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de pago, los ID de pago y los estados de pedido Awaiting Peach Payments payment y Peach Payments payment on hold siempre se conservan. Los pedidos existentes mantienen sus notas de pago, ID de transacción y datos de la finalización de compra de Peach Payments.
Peach Payments es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por Peach Payments.