VibeFox Braintree 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.
Cuenta de Braintree: necesitas el ID de comerciante, la clave pública y la clave privada de tu cuenta de Braintree. Están en el Panel de control de Braintree (sandbox: sandbox.braintreegateway.com, producción: www.braintreegateway.com), en el icono de engranaje, API, API Keys. Las cuentas de sandbox y de producción tienen claves distintas. 3-D Secure debe estar activado para tu cuenta de comerciante de Braintree, a menos que pongas 3-D Secure en Disabled. No se necesita webhook: los pagos con tarjeta se confirman al momento.
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 VibeFox Braintree Gateway en la lista de módulos más tarde 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. Copia el ID de comerciante, la clave pública y la clave privada del Panel de control de Braintree en los campos de sandbox o de producción.
5. Activa Enable/Disable y haz clic en Save. Deja Sandbox mode activado y haz un pedido de prueba con una tarjeta de prueba de Braintree sandbox. Después, desactiva Sandbox mode para aceptar pagos reales con las credenciales de producción.
Al instalarse, el módulo crea dos estados de pedido: Braintree payment authorized y Braintree payment on hold. PrestaShop ofrece 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 Braintree Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Cuando el método de pago está activado pero falta el ID de comerciante, la clave pública o la clave privada del entorno seleccionado, la página te avisa de que el método de pago se oculta en la finalización de compra hasta que se completen. Mientras el modo sandbox está activado, la página muestra Sandbox mode is on: test payments, no real money.
Braintree
Enable/Disable: Enable Braintree card payments activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago que se guarda en el pedido. Por defecto: Credit / debit card. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely with your credit or debit card via Braintree.
API credentials
Inicia sesión en el Panel de control de Braintree (sandbox o producción), haz clic en el icono de engranaje y después en API y API Keys. Las claves pública y privada aparecen allí, y el ID de comerciante se muestra en la misma página. La página muestra solo los campos de credenciales del entorno seleccionado; ambos conjuntos siguen guardados.
Sandbox mode: usa el sandbox de Braintree (pagos de prueba, sin dinero real). Por defecto: on. Desactívalo para aceptar pagos reales con las credenciales de producción. Los reembolsos, las capturas y las anulaciones usan siempre el entorno en el que se pagó el pedido. Mientras esté activado, los clientes ven SANDBOX / TEST MODE — no real money is charged. debajo del método de pago.
Sandbox Merchant ID y Live Merchant ID: el ID de comerciante de la cuenta de sandbox o de producción.
Sandbox Public Key y Live Public Key: la clave pública de esa cuenta.
Sandbox Private Key y Live Private Key: la clave privada de esa cuenta. Las claves privadas guardadas 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 cambiarla.
Sandbox merchant account ID(s) y Live merchant account ID(s): opcional. Braintree cobra en la moneda de la cuenta de comerciante. Déjalo vacío para usar tu cuenta de comerciante predeterminada, o introduce un ID (por ejemplo mystore_EUR) o uno por moneda: EUR=mystore_EUR, USD=mystore_USD. Si la moneda cobrada no coincide con la moneda del pedido, la transacción se anula automáticamente y el cliente no paga.
Clear saved private keys: marca Sandbox Private Key o Live Private Key y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Payment
Transaction type: cómo se cobra la tarjeta.
3-D Secure: 3-D Secure 2 (Strong Customer Authentication) es obligatorio para la mayoría de los pagos con tarjeta en el EEE y el Reino Unido. También debe estar activado en tu cuenta de Braintree (contacta con el soporte de Braintree si los pagos fallan con un error de configuración de 3-D Secure).
El resultado de 3-D Secure se comprueba en el servidor, no solo en el navegador, antes de cobrar la tarjeta.
Advanced
Debug log: también registra las llamadas a la API y los pasos del pago en logs/wc_btg_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, aunque esté desactivado. El registro nunca contiene claves de API, datos de tarjeta ni datos de clientes. Por defecto: off.
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 los ajustes de la pasarela y el registro. Las transacciones, los reembolsos y los estados de pedido de Braintree se conservan siempre, así que los pedidos pagados antes se pueden reembolsar, capturar o anular después de volver a instalar. Por defecto: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto, Credit / debit card) e introduce la tarjeta en el formulario de Braintree dentro de la opción de pago. El formulario se carga desde Braintree solo en la página de finalización de compra y usa el idioma de la tienda. Con 3-D Secure activado, el cliente completa la verificación de su banco al realizar el pedido; el total del carrito, el correo electrónico y la dirección de facturación se pasan a esa verificación.
Después, el módulo cobra el token de un solo uso a través de la API de Braintree por el total del carrito en la moneda del carrito, con el número de carrito como ID de pedido en Braintree. Ningún pedido existe antes de este punto. El importe y la moneda cobrados se comprueban con el carrito. El pedido se crea solo después de que Braintree acepte el pago, y el cliente ve la página estándar de confirmación de pedido de PrestaShop.
Si el pago falla, no se crea ningún pedido, el motivo se escribe en el registro del módulo y el cliente permanece en el paso de pago con un mensaje, por ejemplo Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. o The card security code or billing address could not be verified. Please check your details and try again. El cliente puede volver a intentarlo de inmediato. Si la moneda o el importe cobrados no coinciden con el carrito, la transacción se anula y el cliente ve This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.
Un carrito nunca se cobra dos veces. Un segundo envío mientras el pago está en curso muestra This order is already being paid. Please wait a moment and check your e-mail before trying again. Si la tarjeta se cobró pero PrestaShop no pudo crear el pedido, el cliente ve Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. El siguiente intento para el mismo carrito crea el pedido a partir de la transacción guardada, sin cobrar de nuevo.
El módulo solo acepta pagos con tarjeta. No tiene tarjetas guardadas, ni suscripciones ni pagos recurrentes, ni PayPal, Venmo, Apple Pay, Google Pay ni métodos de pago locales, y no usa webhooks de Braintree.
Pedidos y reembolsos
Estados del pedido
Sin pedido todavía: el pago no se ha realizado o fue rechazado. Solo existe el carrito.
Payment accepted: se cobró la tarjeta (Sale) o se capturó una autorización. El pago se registra con el ID de transacción de Braintree, y una nota privada en los mensajes del pedido muestra el importe, el ID de transacción y el resultado de 3-D Secure.
Braintree payment authorized: los fondos solo están autorizados (Authorize only). No se registra ningún pago hasta que lo captures.
Braintree payment on hold: Braintree devolvió un estado de transacción inesperado, o no se pudo anular automáticamente un cobro en una moneda o por un importe incorrectos. La nota explica qué revisar en el Panel de control de Braintree.
Canceled: se anuló una autorización.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega otra transacción para un pedido que ya está registrado, el pedido no cambia. Una nota te pide que la revises en el Panel de control de Braintree y que la anules o reembolses.
Bloque de pago de Braintree
La página del pedido muestra un bloque Braintree payment con el ID de transacción (enlazado a la transacción en el Panel de control de Braintree de su entorno), el estado de la transacción, el importe y la cuenta de comerciante, el resultado de 3-D Secure, el importe cobrado y reembolsado, una insignia Sandbox para los pagos de sandbox y el historial de reembolsos. Los botones del bloque requieren el permiso para editar pedidos; no hace falta acceso a las páginas de Modules.
Captura y anulación
Para un pedido con el estado Braintree payment authorized, haz clic en Capture Braintree payment para cobrar el total del pedido, o en Void Braintree authorization para liberar el importe retenido. La captura pone el pedido en Payment accepted y registra el pago; la anulación lo pone en Canceled. Si la acción falla, el error se muestra en el bloque y se añade a las notas del pedido.
Reembolsos
En el bloque Braintree payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Braintree. Confirma la pregunta Refund this amount through Braintree? This cannot be undone. Se admiten reembolsos totales y parciales. Los reembolsos se hacen por el importe y la moneda que cobró Braintree, así que tras una diferencia de importe o de moneda puedes reembolsar hasta lo que el cliente pagó realmente. Braintree solo reembolsa transacciones liquidadas, normalmente en un plazo de 24 horas. Antes de la liquidación, un reembolso total se hace como anulación; un reembolso parcial falla entonces con un mensaje que indica que hay que esperar a la liquidación. El reembolso se envía al entorno (sandbox o producción) del pago, así que deben estar configuradas las credenciales de ese entorno. Si Braintree no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado.
El módulo no crea abonos. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de Braintree. Las disputas (contracargos), los rechazos en la liquidación y los reembolsos hechos en el Panel de control de Braintree no se sincronizan con PrestaShop.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Braintree Gateway es el primer bloque de Modules > Module Manager > VibeFox Braintree 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-braintree 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 con 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, Braintree 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. 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 y las capturas, las anulaciones y los reembolsos siguen funcionando.
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
Braintree no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el entorno seleccionado tenga ID de comerciante, clave pública y clave privada. La página de ajustes muestra un aviso cuando falta una clave. En Payment > Preferences, comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
La tarjeta se cobró, pero no se creó ningún pedido: los pagos con tarjeta se confirman al momento, sin webhook. Revisa el campo Log de la página del módulo. Si el registro indica que se perdió la respuesta de Braintree, busca en el Panel de control de Braintree una transacción con el número de carrito como ID de pedido antes de aceptar otro pago. Si el pedido no pudo crearse tras el cobro, el siguiente intento de pago para el mismo carrito lo crea sin volver a cobrar.
El formulario de tarjeta muestra Could not initialize payment form: las claves del entorno seleccionado son incorrectas, o el ID de la cuenta de comerciante no existe en esa cuenta. Revisa las claves y los ID de cuentas de comerciante, y luego recarga la página.
3-D Secure falla en todos los pagos: 3-D Secure debe estar activado para tu cuenta de comerciante de Braintree. Contacta con el soporte de Braintree, o pon 3-D Secure en Disabled (no recomendado en el EEE y el Reino Unido, donde SCA es obligatorio).
Se informa al cliente de que el pago no se pudo procesar en la moneda del pedido: Braintree cobró en la moneda de la cuenta de comerciante. Introduce el ID de cuenta de comerciante para la moneda del carrito en el campo de cuenta de comerciante del entorno actual.
El cliente ve el mensaje The order total must be greater than zero to pay by card: el total del carrito es cero, por ejemplo tras un cupón. Estos pedidos no se pueden pagar con tarjeta.
Un reembolso parcial falla justo después del pago: Braintree solo puede reembolsar transacciones liquidadas, normalmente en un plazo de 24 horas. Reembolsa el importe total para anular la transacción ahora, o haz el reembolso parcial después de la liquidación.
El reembolso, la captura o la anulación falla con un mensaje sobre el entorno: el pago se hizo en el entorno sandbox o de producción, y las credenciales de ese entorno no están configuradas. Introdúcelas y vuelve a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Braintree Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Braintree y los estados de pedido Braintree payment authorized y Braintree payment on hold se conservan siempre, así que los pedidos pagados antes se pueden reembolsar, capturar o anular tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Braintree es una marca comercial de su respectivo titular. Este módulo no está afiliado a Braintree ni cuenta con su aprobación.