VibeFox Braintree for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Cuenta de Braintree: necesitas el Merchant ID, la Public Key y la Private Key de tu cuenta de Braintree. Están en el Braintree Control Panel (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. El 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 ningún webhook: los pagos con tarjeta se confirman al instante.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_braintree_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_braintree_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_braintree_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que no hace falta actualizar Extensions > Modifications. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions, elige el tipo Payments, busca VibeFox Braintree Gateway y haz clic en Install (el botón verde +). Tu usuario administrador necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (consulta la sección Clave de licencia).

4. Copia el Merchant ID, la Public Key y la Private Key del Braintree Control Panel en los campos de sandbox o de producción.

5. Activa Enable/Disable y haz clic en Save. Mantén Sandbox mode activado y realiza un pedido de prueba con una tarjeta de prueba del sandbox de Braintree, como 4111 1111 1111 1111. Después, introduce las credenciales de producción y desactiva Sandbox mode para aceptar pagos reales.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_braintree_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions, elige el tipo Payments. Busca VibeFox Braintree Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las credenciales de Braintree y prueba el pago como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones.

Una instalación nueva empieza con el método de pago desactivado y el modo sandbox activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Si el método de pago está activado pero falta el Merchant ID, la Public Key o la Private Key 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 los completes. Mientras el modo sandbox esté activado, la página muestra Sandbox mode is on: test payments, no real money. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title debe tener de 1 a 128 caracteres, Sort Order debe ser un número entero y Total un número igual o mayor que 0. Si algún campo tiene un error, no se guarda nada y la página indica el campo.

Braintree

Enable/Disable: activa o desactiva los pagos con tarjeta de Braintree. El método de pago se oculta en la finalización de compra hasta que se completen el Merchant ID, la Public Key y la Private Key del entorno seleccionado. Predeterminado: desactivado.

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 guardado en el pedido. Predeterminado: Credit / debit card. Obligatorio, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del formulario de tarjeta. Predeterminado: Pay securely with your credit or debit card via Braintree.

Sort Order: la posición de Braintree entre los métodos de pago de la finalización de compra. Déjalo vacío o escribe un número entero.

Geo Zone: ofrece Braintree solo para las direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el importe total de la compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca Braintree. Déjalo vacío para ofrecer Braintree con cualquier importe.

Credenciales de la API

Inicia sesión en el Braintree Control Panel (sandbox o producción, enlazados en esta sección), haz clic en el icono de engranaje y luego en API y API Keys. Ahí aparecen las claves pública y privada, y el Merchant ID se muestra en la misma página. La página solo muestra los campos de credenciales del entorno seleccionado; ambos conjuntos se mantienen guardados.

Sandbox mode: usa el sandbox de Braintree (pagos de prueba, sin dinero real). Predeterminado: activado. 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. en el paso Confirm Order.

Sandbox Merchant ID y Live Merchant ID: el Merchant ID 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, guardada exactamente como se introdujo. 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 cambiarlo. Para eliminar una clave guardada, marca Clear the saved key on save debajo del campo y haz clic en Save.

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, escribe un ID (por ejemplo, mystore_EUR) o uno por moneda: EUR=mystore_EUR, USD=mystore_USD. Si la moneda del cobro no coincide con la moneda del pedido, la transacción se anula automáticamente y no se cobra al cliente.

Payment

Transaction type: la forma en que se cobra la tarjeta.

3-D Secure: el 3-D Secure 2 (autenticación reforzada del cliente, SCA) 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 del 3-D Secure se comprueba en el servidor, no solo en el navegador, antes de cobrar la tarjeta.

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). Solo recibe un estado después de que Braintree acepte el pago con tarjeta. Si la tarjeta es rechazada, el pedido queda sin estado y el cliente permanece en el paso de confirmación. Cada campo siguiente muestra los estados de pedido de tu tienda OpenCart.

Order Status After Payment: se capturó una venta o una autorización en la pestaña del pedido. Predeterminado: Procesando.

Authorized Status: solo autorización: el importe queda reservado, todavía no pagado. Predeterminado: Pendiente de pago, porque OpenCart no tiene el estado En espera; la nota del pedido y la pestaña del pedido lo explican. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

On Hold (Review) Status: Braintree devolvió un estado de transacción inesperado, o el importe o la moneda cobrados no coincidían y la anulación automática falló. Una nota explica qué revisar. Predeterminado: Pendiente de pago.

Voided Status: la autorización se anuló en la pestaña del pedido y se libera el importe retenido. Predeterminado: Cancelado.

Refunded Status: el pago se reembolsa por completo, o se anula como reembolso total antes de la liquidación. Los reembolsos parciales solo añaden una nota. Predeterminado: Reembolsado.

Advanced

Debug log: registra también las llamadas a la API y los pasos del pago en wc_btg_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Los errores siempre se registran, aunque esta opción esté desactivada. El registro nunca contiene claves de API ni datos de tarjetas o 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 la extensión se eliminan los ajustes de la pasarela y el registro. Las transacciones y los reembolsos de Braintree siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose, capturándose o anulándose tras una reinstalación. Predeterminado: desactivado.

Import / Export

Export: Download JSON guarda los ajustes en un archivo JSON. Las claves privadas no se exportan.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Las claves privadas guardadas se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto, Credit / debit card). En el paso Confirm Order, el cliente ve tu descripción y el formulario de tarjeta de Braintree, cargado desde Braintree en el idioma de la tienda. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, el formulario comprueba la tarjeta y, con el 3-D Secure activado, el cliente completa la verificación de su banco; el total del pedido, el correo y la dirección de facturación se envían al formulario. Solo llega a tu tienda un token de un solo uso. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options. El formulario de la tarjeta aparece entonces en el bloque de confirmación, al final de la página de compra, encima del botón Confirm Order. Si la tienda no pide una dirección de pago (el valor predeterminado de OpenCart 4), la comprobación de 3-D Secure usa la dirección de envío.

Después, la extensión cobra el token mediante la API de Braintree por el total del pedido en la moneda del pedido, usando el número de pedido de OpenCart como ID del pedido en Braintree. El importe y la moneda cobrados se comprueban frente al pedido. El pedido recibe su estado solo cuando Braintree acepta el pago, de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización de existencias. El carrito se vacía y el cliente ve la página de pedido completado de OpenCart.

Si el pago falla, el pedido queda sin estado, se añade al pedido una nota con el motivo y el cliente permanece en el paso Confirm Order 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 introducir la tarjeta y reintentar de inmediato. Si la moneda o el importe cobrados no coinciden con el 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. 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 se vuelve a confirmar un pedido pagado, el cliente va directamente a la página de éxito; en el caso de un pago autorizado, aparece A payment for this order has already been received and is awaiting review. Si la tarjeta se cobró pero OpenCart no pudo asignar el estado del 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 con el mismo carrito asigna el estado de ese pedido a partir de la transacción guardada, sin volver a cobrar. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, así que un mismo carrito puede tener varios pedidos (OpenCart 4 mantiene un solo pedido para la compra y lo actualiza, de modo que tras una tarjeta rechazada el cliente paga el mismo pedido): en cuanto uno de ellos está pagado, otro pedido del mismo carrito no se cobra, y el cliente ve This cart has already been paid with order #…. Please check your order history — do not pay again.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si la tienda cerró ese pedido entretanto (por ejemplo, cancelado, anulado o reembolsado), o si ya está pagado y el carrito ha cambiado desde entonces (otros productos o cantidades), Confirm Order devuelve al cliente a la finalización de compra, lo que crea un pedido nuevo del carrito con su propio pago. El mismo carrito enviado dos veces sigue llevando a la página de éxito sin un segundo cobro.

La extensión solo acepta pagos con tarjeta. No tiene tarjetas guardadas, ni suscripciones o pagos recurrentes, ni PayPal, Venmo, Apple Pay, Google Pay ni métodos de pago locales, y no usa webhooks de Braintree.

Pedidos y reembolsos

Order statuses

No status (missing order): el pago no se ha realizado o ha sido rechazado. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status ajustado a Missing Orders.

Order Status After Payment (default Processing): se cobró la tarjeta (Sale) o se capturó una autorización. Una nota muestra el importe, el ID de la transacción de Braintree y el resultado de 3-D Secure.

Authorized Status (default Pending): los fondos solo están autorizados (Authorize only). Una nota te pide que captures el pago en la página del pedido antes del envío.

On Hold (Review) Status (default Pending): Braintree devolvió un estado de transacción inesperado, o no se pudo anular automáticamente un cobro con una moneda o un importe incorrectos. La nota explica qué revisar en el Braintree Control Panel.

Voided Status (default Canceled): se anuló una autorización.

Refunded Status (default Refunded): el pago se reembolsó por completo a través de la extensión.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Braintree Gateway

En Sales > Orders abre un pedido pagado con Braintree. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Braintree Gateway muestra el Transaction ID (enlazado con la transacción en el Braintree Control Panel de su entorno), con la etiqueta Sandbox en los pagos de sandbox, el Status de la transacción, el Amount y la cuenta de comerciante, el resultado de 3-D Secure, los importes Charged / refunded, los botones de captura, anulación y reembolso, el historial de reembolsos y las Braintree notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión; los botones requieren el permiso para modificarla (se configura en System > Users > User Groups).

Captura y anulación

En un pago autorizado, haz clic en Capture Braintree payment para cobrar el total del pedido, o en Void Braintree authorization para liberar el importe retenido y cancelar el pedido. La captura asigna al pedido el estado de Order Status After Payment; la anulación lo asigna a Voided Status. Si la acción falla, el error se muestra en la pestaña y se añade a las notas del pedido.

Reembolsos

En la pestaña VibeFox Braintree Gateway introduce el Amount (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via Braintree. Confirma la pregunta ¿Reembolsar este importe a través de Braintree? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales, tanto para un pago capturado como para uno en revisión. Los reembolsos se hacen por el importe y en la moneda que cobró Braintree. 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 para 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, la pestaña 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 asigna al pedido el Refunded Status; un reembolso parcial no cambia el estado. Los cambios de estado desde la pestaña no notifican al cliente ni devuelven productos al stock, igual que un cambio manual de estado.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Braintree. Los contracargos, los rechazos en la liquidación y los reembolsos hechos en el Braintree Control Panel no se sincronizan con OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox Braintree Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, 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 eliminarla de esta tienda. Debajo aparecen la línea Product: opencart-payment-braintree y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen el inglés y el ruso).

Si la clave no se acepta, el bloque indica el motivo, por ejemplo Clave no encontrada, Esta clave pertenece a otro producto, Límite de dominios alcanzado o La licencia caducó el una fecha. Después de cambiar la dirección de la tienda, o de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda definida en la configuración de OpenCart. Eliminar 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 se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (sin licencia: visible solo para administradores), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando, y las capturas, las anulaciones y los reembolsos funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard del panel de administración o la página Edit: 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 se necesita ninguna tarea cron. Al desinstalar la extensión se eliminan 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 Merchant ID, Public Key y Private Key. La página de ajustes muestra un aviso cuando falta una clave. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

La tarjeta se cobró, pero el pedido se queda sin estado: los pagos con tarjeta se confirman al instante, sin webhook. Revisa las notas del pedido y el campo Log de la página de la extensión. Si una nota indica que se perdió la respuesta de Braintree, busca en el Braintree Control Panel una transacción con este número de pedido antes de aceptar otro pago. Si el estado no pudo asignarse después del cobro, el siguiente intento de pago con el mismo carrito lo asigna 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 IDs de cuentas de comerciante, y luego recarga la página.

El cliente ve Your session has expired. Please refresh the page and try again.: la sesión de compra cambió mientras el formulario estaba abierto. El cliente debe recargar la página de finalización de compra.

El 3-D Secure falla en todos los pagos: el 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).

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 la cuenta de comerciante de la moneda del pedido en el campo de cuenta de comerciante del entorno actual.

El cliente ve The order total must be greater than zero to pay by card.: el total del pedido es cero, por ejemplo tras aplicar 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.

No hay botones en la pestaña, o aparece un mensaje sobre el entorno: tu grupo de usuarios no tiene permiso para modificar la extensión, o el pago se realizó 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 Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Braintree Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart elimina siempre sus propios ajustes de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. Si Delete data on uninstall está activado, se eliminan el resto de ajustes de la pasarela (título, descripción, modo sandbox, credenciales, cuentas de comerciante, tipo de transacción, 3-D Secure, registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Braintree siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose, capturándose o anulándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox Braintree Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Braintree es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Braintree ni respaldada por esta empresa.