VibeFox Braintree for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo.
PHP: 8.0 o posterior.
HTTPS: tu sitio debe usar HTTPS.
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 del engranaje, API, API Keys. Las cuentas de sandbox y de producción tienen claves distintas. 3-D Secure debe estar activado en tu cuenta de comerciante de Braintree, salvo que pongas 3-D Secure en Disabled. No se necesita webhook.
Clave de licencia de VibeFox: se compra 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_braintree_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > Braintree > Manage, o haz clic en Settings debajo del nombre del plugin en la página 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. 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.
6. Activa Enable/Disable. Mantén Sandbox mode activado y haz un pedido de prueba con una tarjeta de prueba de Braintree, por ejemplo 4111 1111 1111 1111 con cualquier fecha de caducidad futura. Para 3-D Secure usa las tarjetas de prueba de 3-D Secure de Braintree.
7. Desmarca Sandbox mode para aceptar pagos reales con las credenciales de producción.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Braintree. Si la pasarela está activada pero falta el ID de comerciante, la clave pública o la clave privada del modo seleccionado, la página te avisa de que el método de pago está oculto en la finalización de compra hasta que los completes. La página muestra solo los campos de credenciales del modo seleccionado; ambos conjuntos se mantienen guardados.
General
Enable/Disable: Enable Braintree card payments activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Por defecto: Credit / debit card.
Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Por defecto: Pay securely with your credit or debit card via Braintree.
Credenciales de API
Inicia sesión en el Panel de control de Braintree (sandbox o producción), haz clic en el icono del engranaje y después en API y API Keys. Ahí aparecen las claves pública y privada, y el ID de comerciante se muestra en la misma página.
Sandbox mode: Use the Braintree sandbox (test payments, no real money). Por defecto: activado. Desmárcalo para aceptar pagos reales con las credenciales de producción. Los reembolsos, las capturas y las anulaciones siempre usan el entorno en el que se pagó el pedido.
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.
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 por defecto, 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 no se cobra al cliente.
Pago
Transaction type: cómo se cobra la tarjeta.
3-D Secure: 3-D Secure 2 (autenticación reforzada del cliente, SCA) es obligatorio en 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.
Avanzado
Debug log: Also log API calls and payment steps (errors are always logged). Los registros están en WooCommerce > Status > Logs, origen wcp_braintree_gateway. Nunca contienen claves de API, datos de tarjeta ni datos de clientes. Por defecto: desactivado.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Por defecto: desactivado.
Finalizar compra
El cliente elige el método de pago (por defecto, Credit / debit card) e introduce la tarjeta en el formulario de Braintree de la página de finalización de compra. En modo sandbox, el formulario muestra SANDBOX / TEST MODE — no real money is charged. Con 3-D Secure activado, el cliente completa la verificación de su banco al realizar el pedido.
El plugin cobra el token de un solo uso a través de la API de Braintree por el total del pedido en la moneda del pedido, con el número de pedido como ID del pedido. El pedido solo se marca como pagado con la respuesta autenticada de Braintree, después de comprobar que el importe y la moneda cobrados coinciden con el pedido. Si el pago se aprueba, el cliente pasa a la página de pedido recibido. Los pagos con tarjeta no necesitan webhook: el resultado se conoce al instante.
Si el pago falla, el pedido sigue en Pendiente de pago, el motivo se añade a las notas del pedido y el cliente ve un mensaje claro, 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 cobrada no coincide con la del pedido, 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 pedido nunca se cobra dos veces: si el formulario se envía por segunda vez mientras el pago está en curso, aparece This order is already being paid. Please wait a moment and check your e-mail before trying again.
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 el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin solo acepta pagos con tarjeta. No tiene tarjetas guardadas (vaulting), ni WooCommerce Subscriptions ni pedidos anticipados, ni PayPal, Venmo, Apple Pay, Google Pay, ACH ni métodos de pago locales, no usa webhooks de Braintree y no incluye datos de nivel 2/3, líneas de pedido ni Fastlane.
Pedidos y reembolsos
Estados del pedido
Pending payment: el pago aún no se ha realizado o fue rechazado.
Processing or Completed: se cobró la tarjeta (Sale) o se capturó una autorización. WooCommerce asigna Procesando, o Completado en los pedidos que solo tienen productos virtuales descargables. La nota del pedido muestra el importe, el ID de la transacción y el resultado de 3-D Secure. El ID de la transacción es el ID de transacción de Braintree y, en la pantalla del pedido, enlaza con la transacción en el Panel de control de Braintree.
On hold: los fondos solo están autorizados (Authorize only). Un pedido también pasa a En espera cuando Braintree devuelve un estado de transacción inesperado, o cuando un cargo en una moneda incorrecta no pudo anularse automáticamente. La nota del pedido explica qué revisar en el Panel de control de Braintree.
Cancelled: una autorización se anuló con Void Braintree authorization.
Captura y anulación
En un pedido con autorización, abre el pedido y elige Capture Braintree payment o Void Braintree authorization en las acciones del pedido, y después haz clic en el botón de actualizar. La captura marca el pedido como pagado; la anulación cancela el pedido y libera el importe retenido para el cliente. Si la acción falla, el error se muestra en la pantalla del pedido y se añade a las notas del pedido.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Credit / debit card (el botón usa el título de tu método de pago). Se admiten reembolsos totales y parciales. Braintree solo puede reembolsar transacciones liquidadas, que normalmente se liquidan en 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) en el que se pagó el pedido. Si Braintree no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso o una anulación correctos se añaden a las notas del pedido.
Las disputas (contracargos) y los rechazos en la liquidación no se sincronizan con WooCommerce. Revísalos en el Panel de control de Braintree.
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 > Braintree. 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio 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. Los gestores de la tienda que hayan 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: las capturas, las anulaciones y los reembolsos siguen funcionando.
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
Braintree no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo seleccionado tenga ID de comerciante, clave pública y clave privada. La página de ajustes muestra un aviso cuando falta alguna clave.
El pago se realizó, pero el pedido sigue en Pendiente de pago: los pagos con tarjeta se confirman al instante, sin webhook. Si la nota del pedido indica que se perdió la respuesta de Braintree, revisa en el Panel de control de Braintree si hay una transacción con este número de pedido antes de aceptar otro pago. Activa el Debug log y mira en WooCommerce > Status > Logs, origen wcp_braintree_gateway.
El formulario de tarjeta muestra Could not initialize payment form: las claves del modo seleccionado son incorrectas, o el ID de la cuenta de comerciante no existe en esa cuenta. Comprueba las claves y los ID de cuenta de comerciante, y después recarga la página.
3-D Secure falla en todos los pagos: 3-D Secure debe estar activado en 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 la SCA es obligatoria).
Al cliente se le indica que el pago no se pudo procesar en la moneda del pedido: Braintree cobró en la moneda de la cuenta de comerciante. Introduce en el campo de cuenta de comerciante del modo actual el ID de la cuenta de comerciante para la moneda del pedido.
Un reembolso parcial falla justo después del pago: Braintree solo puede reembolsar transacciones liquidadas, normalmente en 24 horas. Reembolsa el importe total para anular la transacción ahora, o haz el reembolso parcial después de la liquidación.
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 para 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 y los registros se eliminan solo si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los datos de Braintree guardados en los pedidos siempre se conservan, porque hacen falta para los reembolsos tras una reinstalación. Los pedidos existentes conservan sus notas de pago e ID de transacción.
Braintree es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Braintree ni cuenta con su respaldo.