VibeFox Authorize.Net for PrestaShop — Ayuda
Requisitos
PrestaShop: de 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
HTTPS: tu finalización de compra debe usar HTTPS. Accept.js no se ejecuta en páginas HTTP sin cifrar.
Cuenta de Authorize.Net: necesitas el API Login ID, la Transaction Key y la Public Client Key de tu cuenta de Authorize.Net, y una Signature Key si usas webhooks. Las cuentas de producción (account.authorize.net) y de sandbox (sandbox.authorize.net) tienen credenciales diferentes. Las cuentas de Authorize.Net están disponibles para comerciantes de Estados Unidos, Canadá, Reino Unido, Europa, Australia y Nueva Zelanda.
Moneda: la moneda del carrito debe ser USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD o NZD, y tu cuenta de Authorize.Net debe liquidar en esa moneda. Para otras monedas, el método de pago se oculta en la finalización de compra.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave sirve para 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 Authorize.Net Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, dentro del bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).
4. Introduce las credenciales de las cuentas de sandbox y de producción (consulta Configuración). Opcionalmente, configura el webhook.
5. Activa Enable/Disable, elige el Transaction type y haz clic en Save. Haz una prueba de pago en modo sandbox con la tarjeta 4111 1111 1111 1111, cualquier fecha de caducidad futura y cualquier CVV, y después desactiva Sandbox mode.
Al instalarse, el módulo crea dos estados de pedido: Authorize.Net payment authorized y Authorize.Net payment on hold. PrestaShop activa el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa si SSL no está activado en la tienda (Accept.js solo funciona en páginas HTTPS), si la moneda predeterminada de la tienda no es compatible con Authorize.Net, si el modo actual no tiene API Login ID, Transaction Key o Public Client Key (en ese caso el método de pago se oculta en la finalización de compra) y si el modo actual no tiene Signature Key (en ese caso los webhooks se desactivan). Mientras el modo sandbox está activado, muestra Sandbox mode is on: test transactions, no real charges.
Authorize.Net
Enable/Disable: Enable Authorize.Net activa o desactiva el método de pago. 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 que se guarda en el pedido. Predeterminado: Credit Card. Obligatorio.
Description: el texto que aparece debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with your credit card via Authorize.Net.
Credenciales de API
En Authorize.Net Merchant Interface, abre Account > Settings > Security Settings. En API Credentials & Keys copia el API Login ID y crea una Transaction Key y una Signature Key. En Manage Public Client Key copia la Public Client Key. El sandbox y la producción usan credenciales distintas. La página muestra los campos de ambos modos, así que puedes guardar los dos juegos.
Sandbox mode: usa el sandbox de Authorize.Net (transacciones de prueba, sin cobros reales). Cambia el endpoint de la API, Accept.js y el conjunto de credenciales que se usan para los pagos nuevos. Predeterminado: activado. Desactívalo para aceptar pagos reales. Mientras está activado, los clientes ven una indicación con la tarjeta de prueba 4111 1111 1111 1111 debajo del método de pago.
Sandbox API Login ID y Live API Login ID: el API Login ID de la cuenta de sandbox o de producción.
Sandbox Transaction Key y Live Transaction Key: la Transaction Key de esa cuenta.
Sandbox Public Client Key y Live Public Client Key: la clave pública que usa Accept.js en el navegador.
Sandbox Signature Key y Live Signature Key: solo se necesitan para los webhooks. Verifica la cabecera X-ANET-Signature de cada notificación.
Las Transaction Keys y las Signature Keys 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.
Clear saved secrets: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Pago
Transaction type: cómo se cobra la tarjeta. Una autorización caduca a los 30 días.
Webhooks (recomendado)
Sin webhooks, los pedidos retenidos por Fraud Detection Suite o capturados o anulados en el panel de Authorize.Net deben actualizarse a mano. En Merchant Interface ve a Account > Settings > Business Settings > Webhooks y haz clic en Add Endpoint, tanto en la cuenta de sandbox como en la de producción. Usa la URL que aparece en Endpoint URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_authorizenet_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en los ajustes. Selecciona estos eventos (también aparecen listados en esta sección):
Introduce la Signature Key de cada cuenta en Sandbox Signature Key o Live Signature Key. Los webhooks sin una firma válida se rechazan. Una notificación debe estar firmada con la clave del modo en el que se hizo el pago; una notificación del otro modo no cambia nada. Para cada notificación, el módulo también consulta a Authorize.Net el estado y el importe actuales de la transacción antes de cambiar el pedido, así que las notificaciones repetidas no cambian nada.
Avanzado
Debug log: escribe las solicitudes y respuestas de la API en logs/wc_ang_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves, los tokens de tarjeta y los datos personales se enmascaran. Predeterminado: desactivado. Los errores, como pagos rechazados o fallidos, errores de la API y reembolsos fallidos, siempre se registran, incluso si esta opción está desactivada.
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 y el registro. Las transacciones y los reembolsos de Authorize.Net y los estados de pedido del módulo siempre se conservan, así que los pedidos pagados antes se pueden capturar y reembolsar tras una reinstalación. Predeterminado: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (de forma predeterminada Credit Card) e introduce el número de tarjeta, la fecha de caducidad (MM/YY) y el código de seguridad (CVV) en el formulario que aparece debajo. Accept.js se carga solo en la página de finalización de compra. Cuando el cliente realiza el pedido, Accept.js cambia los datos de la tarjeta por un token de un solo uso en el navegador. Los campos de la tarjeta no tienen nombres de formulario, así que el número de tarjeta y el CVV nunca llegan a tu servidor.
El módulo cobra el token a través de la API de Authorize.Net por el total del carrito en la moneda del carrito. La dirección de facturación, el correo electrónico y la dirección IP se envían con la transacción para la verificación de dirección y los filtros antifraude. El número de carrito se envía como número de factura, porque antes del pago no existe ningún pedido. El pedido se marca como pagado solo cuando Authorize.Net lo confirma: si la transacción se aprueba, el pedido se crea de inmediato y el cliente ve la página estándar de confirmación del pedido con Your card payment has been received. Con Authorize only, la página muestra Your card payment has been authorized. The amount will be charged when your order is processed. Si Fraud Detection Suite retiene la transacción, la página muestra Your payment is being reviewed. We will update your order as soon as the review is complete.
Si la tarjeta se rechaza, el cliente se queda en el paso de pago y ve Payment failed: seguido del motivo, por ejemplo una tarjeta rechazada, un código de seguridad incorrecto o una tarjeta caducada. No se crea ningún pedido y el carrito se conserva. Los errores de configuración y de la API no se muestran a los clientes: ven un mensaje general, y los detalles van al registro. Si la tienda no puede conectarse con Authorize.Net, el cliente ve Payment error: unable to connect to the payment gateway. Please try again. Si los campos de la tarjeta están vacíos, el formulario pide Please enter the card number, expiry date and card code.
Un doble clic, una segunda pestaña o un envío repetido nunca cobran dos veces el mismo carrito. Un segundo intento mientras el primero sigue en curso muestra Your payment is already being processed. Please wait a moment and check your order history before trying again. Si un pago fue aprobado pero no se 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. Después, el pedido se crea a partir del pago aprobado en el siguiente intento o mediante el webhook, sin volver a cobrar la tarjeta.
Si el carrito cambia mientras se procesa el pago, el importe cobrado ya no coincide con el carrito. Entonces el pedido pasa a Authorize.Net payment on hold con una nota, y el pago se registra por el importe realmente cobrado.
El webhook funciona aunque la tienda esté en modo de mantenimiento, y no lo bloquea la restricción por países de tu tienda.
El módulo no tiene tarjetas guardadas ni perfiles de cliente, suscripciones ni pagos recurrentes, eCheck/ACH, Apple Pay, Google Pay, PayPal ni 3-D Secure, tampoco captura parcial de una autorización ni conversión automática de moneda.
Pedidos y reembolsos
Estados del pedido
No order: la tarjeta fue rechazada o el pago falló. Solo existe el carrito.
Payment accepted: la tarjeta fue cobrada (Authorize and capture), o se capturó una autorización. El pago se registra con el Trans ID de Authorize.Net como ID de transacción, y una nota muestra el importe, el Trans ID, el código de autorización, el tipo de tarjeta y las últimas cuatro cifras.
Authorize.Net payment authorized: los fondos solo están autorizados (Authorize only). Captúralos antes de preparar el pedido.
Authorize.Net payment on hold: Fraud Detection Suite retuvo la transacción para revisión, el importe cobrado no coincide con el total del pedido, o una captura notificada por webhook no coincide con el importe del pedido. La nota lo explica. Aprueba o rechaza una transacción retenida en el panel de Authorize.Net; con webhooks, el pedido se actualiza automáticamente.
Canceled: un webhook informó de que la transacción fue rechazada, anulada o caducó antes de que se pagara el pedido, o anulaste una autorización que no se había capturado. Si la transacción de un pedido pagado se anula en el panel de Authorize.Net, su estado no cambia y se añade una nota de advertencia.
Refunded: el pago se reembolsó o se anuló por completo a través del módulo.
Si se aprueba una segunda transacción para un carrito que ya tiene pedido, el pedido no cambia. Una nota te pide que la revises y que anules o reembolses el duplicado en el panel de Authorize.Net.
Bloque de pago de Authorize.Net
La página del pedido muestra un bloque Authorize.Net payment con el Trans ID, el tipo de transacción, el estado de la transacción, la tarjeta y el código de autorización, el importe cobrado, el total del pedido y el importe reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las Authorize.Net notes del pedido. Para capturar y reembolsar basta el permiso de editar pedidos, no el acceso a las páginas de módulos.
Captura
En un pedido en Authorize.Net payment authorized, haz clic en Capture payment en el bloque y confirma Capture the authorized amount through Authorize.Net? Se captura el importe autorizado, el pago se registra con el Trans ID y el pedido pasa a Payment accepted. Si la captura falla, se muestra el error y se añade a las notas. También puedes capturar en el panel de Authorize.Net; con webhooks, el pedido se actualiza automáticamente.
Reembolsos
En el bloque, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, haz clic en Refund via Authorize.Net y confirma Refund this amount through Authorize.Net? This cannot be undone. Un reembolso del importe total anula primero la transacción si todavía no está liquidada, o una autorización que no se capturó. Las transacciones liquidadas, normalmente después de 24 horas, se pueden reembolsar total o parcialmente. Antes de la liquidación no es posible un reembolso parcial: reembolsa el importe total para anular la transacción, o inténtalo de nuevo después de la liquidación. Los reembolsos se hacen en el importe y la moneda que cobró Authorize.Net, así que tras una diferencia de importe puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. Si Authorize.Net no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso o una anulación correctos se añaden al historial de reembolsos y a las notas. Un reembolso total cambia el pedido a Refunded (Canceled cuando solo se anuló una autorización). Un reembolso parcial no cambia el estado. Mientras una transacción esté retenida para revisión, no se ofrecen reembolsos.
Las capturas, los reembolsos y las comprobaciones de webhooks de un pedido usan las credenciales del modo en el que se pagó, así que los pedidos del otro modo se pueden seguir capturando y reembolsando después de cambiar Sandbox mode. Conserva las credenciales de ese modo en sus campos hasta que esos pedidos estén terminados.
El módulo no crea abonos. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Authorize.Net. Los reembolsos hechos en el panel de Authorize.Net no se notifican a la tienda: actualiza el pedido a mano.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Authorize.Net Gateway es el primer bloque de Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure, encima de los ajustes. Introduce 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-authorizenet y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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. Tras 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 acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un 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. Libérala en tu cuenta de vibefox.net.
Sin una clave de licencia activa, el pago con tarjeta de Authorize.Net 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 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 y los reembolsos funcionan.
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 después de introducir la clave, y después una vez a la semana. No se necesita 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
Authorize.Net no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga API Login ID, Transaction Key y Public Client Key. La página de ajustes muestra un aviso si falta alguna. Comprueba que la moneda del carrito sea compatible y, en Payment > Preferences, que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero el pedido sigue en Authorize.Net payment on hold o authorized: el tipo de transacción es Authorize only (captúrala en el bloque del pedido), o Authorize.Net retuvo la transacción para revisión. Apruébala o recházala en el panel de Authorize.Net. Para que estos pedidos se actualicen automáticamente, configura el webhook: comprueba que el endpoint existe en la cuenta del modo que usas, que su URL es exactamente la que aparece en Endpoint URL, que están seleccionados los cuatro eventos y que la Signature Key de esa cuenta está introducida.
Webhook answers webhooks are not configured: no se ha introducido ninguna Signature Key para ninguno de los dos modos.
Webhook answers invalid signature: la Signature Key pertenece a otra cuenta, o se cambió una clave en Authorize.Net. Crea o copia de nuevo la Signature Key y pégala en el campo de su modo.
Webhook answers mode mismatch: la notificación se firmó con la clave de un modo, pero el pago se hizo en el otro modo. Comprueba que las Signature Keys de sandbox y de producción no estén intercambiadas.
Webhook answers verification failed, retry later: la tienda no pudo leer la transacción desde la API de Authorize.Net, o faltan las credenciales del modo del pago. Authorize.Net reintenta el envío.
Webhook answers busy, retry later: otra solicitud estaba actualizando el pedido en ese mismo momento, o no se pudo crear el pedido. Authorize.Net reintenta el envío. Consulta el campo Log para ver el motivo.
La URL del webhook muestra method not allowed en el navegador: es normal. La URL acepta solo solicitudes de Authorize.Net.
El formulario de tarjeta muestra The secure card form (Accept.js) could not be loaded: la finalización de compra debe usar HTTPS, y la Public Client Key y el API Login ID del modo actual deben ser correctos.
Payment error: the card could not be tokenized: Accept.js no devolvió ningún token. El cliente debe volver a introducir los datos de la tarjeta e intentarlo de nuevo.
El cliente ve un error general: revisa el campo Log de la página del módulo; los errores siempre se escriben allí. Authorize.Net rechaza una moneda que la cuenta no admite.
Un reembolso parcial falla porque la transacción aún no está liquidada: reembolsa el importe total para anular la transacción, o inténtalo de nuevo después de la liquidación, normalmente en un plazo de 24 horas.
El reembolso o la captura fallan con un mensaje sobre el modo: el pago se hizo en modo sandbox o de producción, y el API Login ID y la Transaction Key de ese modo no están configurados. Introdúcelos y vuelve a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Authorize.Net 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 el registro. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Las transacciones y los reembolsos de Authorize.Net y los estados de pedido Authorize.Net payment authorized y Authorize.Net payment on hold siempre se conservan, así que los pedidos pagados antes se pueden capturar y reembolsar después de una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Authorize.Net es una marca comercial de su titular. Este módulo no está afiliado ni respaldado por Authorize.Net.