VibeFox MercadoPago 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.
Moneda de la tienda: la moneda del país de tu cuenta de MercadoPago: ARS (Argentina), BRL (Brasil), CLP (Chile), COP (Colombia), MXN (México), PEN (Perú) o UYU (Uruguay). MercadoPago cobra en la moneda de la cuenta y no convierte, así que el método de pago se oculta para un carrito en otra moneda.
Cuenta de MercadoPago: necesitas una aplicación en el panel de desarrolladores de MercadoPago (Your integrations > your application > Credentials) con sus credenciales de prueba (empiezan por TEST-) y de producción (empiezan por APP_USR-): una clave pública y un Access Token para cada una. Para la comprobación opcional de la firma de las notificaciones también necesitas la clave secreta de firma de your application > Webhooks.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 carga, haz clic en Configure, o busca VibeFox MercadoPago 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, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).
4. Elige el Account country, introduce las credenciales de prueba y de producción y, si quieres, configura las notificaciones en tu aplicación de MercadoPago (ver Configuración).
5. Activa Enable / Disable y haz clic en Save. Prueba un pago en modo de prueba con tarjetas de prueba de MercadoPago y, después, desactiva Test mode.
Al instalarse, el módulo crea dos estados de pedido: Awaiting MercadoPago payment y MercadoPago payment on hold. PrestaShop asigna un módulo de pago nuevo a los países que están activos en el momento de la instalación. Revisa las monedas, los países y los grupos de clientes del módulo en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox MercadoPago 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 Test mode is on: the TEST- credentials are used and no real money is charged. mientras el modo de prueba está activado. También avisa cuando falta la clave pública o el Access Token del modo actual, cuando la moneda de la tienda no es la moneda de tu cuenta de MercadoPago (en ese caso el método de pago se oculta en el pago) y cuando las credenciales pertenecen a una cuenta de un país distinto de Account country.
Al guardar, una credencial que no empieza por el prefijo esperado (TEST- para los campos de prueba, APP_USR- para los de producción) no se guarda, y se muestra el error must start with … — the previous value was kept.. El módulo también pregunta a MercadoPago a qué país pertenece cada Access Token. Si no se puede comprobar el token del modo actual, si la cuenta no está en un país admitido o si el país no coincide con Account country, se muestra un error. El módulo usa entonces el país de la cuenta.
MercadoPago
Enable / Disable: Enable MercadoPago card payments activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Credit or debit card (MercadoPago). Obligatorio.
Description: el texto que se muestra encima de los campos de tarjeta en la finalización de compra. Por defecto: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.
Cuenta de MercadoPago
Obtén las credenciales de tu aplicación en el panel de desarrolladores de MercadoPago: Your integrations > your application > Credentials. Las credenciales de prueba empiezan por TEST-, las de producción por APP_USR-.
Account country: el país de tu cuenta de MercadoPago. Decide la moneda de cobro, el idioma de los campos de la tarjeta y si se pide el documento del titular. La moneda de la tienda debe ser la misma, por ejemplo ARS para Argentina. Al guardar las credenciales, el país se comprueba con la cuenta. Por defecto: Argentina (ARS).
Test mode: en modo de prueba se usan las credenciales TEST- y pagas con tarjetas de prueba de MercadoPago; en la finalización de compra se muestra una insignia TEST MODE. Desactívalo para cobrar tarjetas reales con las credenciales de producción. Por defecto: on.
Test Public Key: empieza por TEST-. Se usa en el navegador para tokenizar la tarjeta.
Test Access Token: empieza por TEST-. Se usa solo en el servidor. Mantenlo en secreto.
Production Public Key: empieza por APP_USR-.
Production Access Token: empieza por APP_USR-. Se usa solo en el servidor. Mantenlo en secreto.
Los Access Token guardados y el secreto del webhook 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.
Opciones de pago
Maximum installments: el mayor número de cuotas que puede elegir el cliente, de 1 a 24. 1 = solo pago único, y no se muestra el campo de cuotas. El límite también se aplica en el servidor. Por defecto: 1.
Notificaciones de pago (webhooks)
Los pagos con tarjeta normalmente reciben una respuesta final al momento. Los pagos que MercadoPago mantiene en revisión (en proceso o pendientes) se completan con las notificaciones de MercadoPago. El módulo envía la URL de notificación con cada pago cuando tu tienda tiene una dirección pública (no localhost ni un dominio .local o .test). También puedes añadirla en your application > Webhooks, evento Payments. La URL aparece en Notification URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Copia la URL tal como la muestra la configuración.
Una notificación nunca se considera válida por sí misma. El módulo vuelve a leer el pago desde la API de MercadoPago con el Access Token del entorno en el que se hizo el pago y lo vincula a un intento de pago de tu tienda. Sin notificaciones, los pedidos en revisión se quedan en Awaiting MercadoPago payment hasta que los actualices a mano.
El módulo gestiona estos estados de pago de MercadoPago:
Webhook secret signature: opcional. La clave secreta de firma que aparece en your application > Webhooks. Si está configurada, las notificaciones sin un x-signature válido se rechazan (HTTP 401).
Clear saved secrets: marca Test Access Token, Production Access Token o Webhook secret signature y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Avanzado
Debug log: escribe las peticiones y las notificaciones de MercadoPago en logs/wc_mpg_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 este ajuste esté desactivado. No se registran los Access Token, los tokens de tarjeta ni los datos del pagador. 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 los registros. Los registros de pagos de MercadoPago, los reembolsos y los estados de pedido del módulo siempre se conservan, así que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Por defecto: off.
Finalización de compra
En el paso de pago el cliente elige el método de pago (por defecto Credit or debit card (MercadoPago)) y rellena los campos de la tarjeta: Card number, Expiry (MM/YY), Security code y Cardholder name. Según el país y la tarjeta, el cliente también elige Document type e introduce el Document number, selecciona el Card issuer y el número de Installments. Las opciones de cuotas y los intereses los devuelve MercadoPago para el total del carrito. El formulario de tarjeta funciona con los temas Classic y Hummingbird.
Cuando el cliente confirma, MercadoPago convierte la tarjeta en un token de un solo uso y tu tienda crea el pago en el servidor por el total del carrito. El correo electrónico y el nombre del cliente, el documento y el número de carrito se envían a MercadoPago; el pago aparece como Cart #, con el número de carrito y el nombre de tu tienda. Los importes en CLP y COP se cobran sin decimales. No existe ningún pedido hasta que MercadoPago responde.
Un pago aprobado crea un pedido pagado, y el cliente ve la página de confirmación del pedido con Your card payment has been received. Un pago en revisión crea un pedido en Awaiting MercadoPago payment, y la página muestra MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. Si después se rechaza un pago en revisión, la página muestra Your MercadoPago payment was not completed. Please contact us about this order. Un pedido retenido muestra Your payment is being reviewed. We will update your order as soon as the review is complete.
Una tarjeta rechazada no crea ningún pedido. El cliente se queda en el paso de pago con un motivo breve, por ejemplo Your card has insufficient funds. Please use another card or payment method. o Please check the security code of your card. El cliente puede corregir los datos o usar otra tarjeta; se crea un nuevo token de tarjeta en cada intento.
Si MercadoPago no responde, el cliente ve We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. El siguiente intento busca primero el pago, así que la tarjeta no se cobra dos veces. Un segundo clic mientras se paga el carrito muestra This order is already being paid. Please wait a moment and check your e-mail before trying again. Un carrito que ya tiene un pedido nunca se vuelve a cobrar; el cliente pasa a la página de confirmación de ese pedido.
La URL de notificación funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción de países de tu tienda.
El módulo acepta solo tarjetas de crédito y débito. No tiene redirección a Checkout Pro, billetera ni saldo de MercadoPago, ni efectivo (Rapipago, OXXO, boleto y otros), ni Pix, PSE ni Yape, ni tarjetas guardadas o suscripciones, ni autorización y captura por separado, ni desafío 3-D Secure, ni conversión de moneda.
Pedidos y reembolsos
Estados del pedido
No order: la tarjeta fue rechazada, o MercadoPago todavía no ha respondido. Solo existe el carrito.
Payment accepted: MercadoPago aprobó el pago y el importe y la moneda coinciden con el carrito. El pago se registra con el ID de pago de MercadoPago como ID de transacción, y una nota muestra el ID de pago, el entorno y el número de cuotas.
Awaiting MercadoPago payment: el pago está en revisión (en proceso o pendiente) y espera la notificación de MercadoPago. El pedido pasa a Payment accepted cuando MercadoPago lo aprueba.
MercadoPago payment on hold: el importe o la moneda aprobados no coinciden con el carrito, o MercadoPago devolvió un estado inesperado. La nota lo explica. Revisa el pedido y complétalo o reembolsa el pago.
Payment error: un pago en revisión fue rechazado o cancelado. La nota muestra el estado y su detalle.
Refunded: el pago fue reembolsado por completo a través del módulo.
Si MercadoPago aprueba un pago para un pedido que ya está cancelado o reembolsado, el estado no cambia y una nota te pide completar el pedido o reembolsar el pago. Si llega otro pago para un pedido que ya está pagado, una nota te pide reembolsar el pago extra en el panel de MercadoPago.
Bloque de pago de MercadoPago
La página del pedido muestra un bloque MercadoPago payment con el ID de pago, el estado del pago, el entorno (una insignia Test en los pagos de prueba), las cuotas, el importe cobrado por MercadoPago y el total del pedido, el importe reembolsado, el historial de reembolsos y las MercadoPago notes del pedido.
Reembolsos
En el bloque MercadoPago payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via MercadoPago. Confirma la pregunta Refund this amount through MercadoPago? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos se limitan al importe cobrado por MercadoPago, así que tras una diferencia de importe puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía con las credenciales del entorno en el que se hizo el pago (prueba o producción), así que el Access Token de ese entorno debe estar configurado. Si MercadoPago rechaza el reembolso, el bloque muestra MercadoPago refused the refund con el motivo, y no se registra ningún reembolso. Un reembolso aprobado o en proceso se añade al historial de reembolsos y a las notas con el ID del reembolso. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea facturas de abono. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de MercadoPago.
Los reembolsos, contracargos y mediaciones hechos en el panel de MercadoPago llegan con la notificación y se añaden a las notas. El estado del pedido y las facturas de abono no cambian automáticamente. Actualízalos a mano si hace falta.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox MercadoPago Gateway es el primer bloque de Modules > Module Manager > VibeFox MercadoPago 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-mercadopago 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 que cambie 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 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 activa, MercadoPago 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 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 tras introducir la clave, y después una vez a la semana. No hace falta 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
MercadoPago 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 las dos credenciales con el prefijo correcto: las TEST- en modo de prueba, las APP_USR- en producción. Comprueba que la moneda del carrito sea la moneda de tu cuenta de MercadoPago. La página de ajustes indica cuál falta. 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.
El pago se realizó, pero el pedido sigue en Awaiting MercadoPago payment: la notificación no llegó. El módulo envía la URL de notificación solo cuando tu tienda tiene una dirección pública (no localhost ni un dominio .local o .test). Añade la URL de Notification URL en your application > Webhooks con el evento Payments. Si Webhook secret signature está configurado, comprueba que sea el secreto de la misma aplicación. El panel de MercadoPago muestra la respuesta de tu tienda para cada notificación.
La notificación responde invalid signature: el secreto de firma pertenece a otra aplicación, o la notificación no tiene un x-signature válido. Copia de nuevo el secreto o deja el campo vacío.
La notificación responde no credentials for test or no credentials for live: el Access Token del entorno en el que se hizo el pago no está configurado. Introdúcelo; MercadoPago reintenta la notificación.
La notificación responde not for this store: el pago no pertenece a un intento de pago de esta tienda. No se modifica ningún pedido.
La notificación responde order busy or payment could not be read: otra petición estaba actualizando el pedido en ese mismo momento, o no se pudo contactar con MercadoPago. MercadoPago reintenta la notificación automáticamente.
Una credencial no se guarda: el error must start with indica que el valor tiene un prefijo incorrecto para el campo. Los campos de prueba aceptan credenciales TEST- y los de producción, credenciales APP_USR-.
El cliente ve This payment method is not configured correctly. Please choose another payment method or contact the store.: faltan las credenciales del modo actual, tienen un prefijo incorrecto o MercadoPago las rechazó. Revísalas en la página de ajustes.
El cliente ve MercadoPago cannot process payments in: la moneda del carrito no es la moneda de tu cuenta de MercadoPago. MercadoPago no convierte monedas.
El formulario seguro de tarjeta no se carga: el cliente ve The secure card form could not be loaded. Please reload the page or choose another payment method. Comprueba la clave pública del modo actual.
El cliente ve Your payment was received, but the order could not be completed automatically: MercadoPago cobró el pago, pero PrestaShop no pudo crear el pedido (por ejemplo, porque el módulo estaba desactivado en ese momento). Revisa el campo Log de la página del módulo: los errores siempre se registran. Se pide al cliente que no pague otra vez; el siguiente intento de pago o la siguiente notificación del carrito crea el pedido sin un nuevo cobro.
El pedido queda en MercadoPago payment on hold tras el pago: lee las MercadoPago notes en el bloque del pedido (ver Estados del pedido) y después completa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o de producción, y el Access Token de ese modo no está configurado. Introdúcelo y vuelve a intentarlo.
El reembolso falla con MercadoPago did not answer the refund request: comprueba el pago en el panel de MercadoPago antes de volver a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox MercadoPago 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, la comprobación guardada de la cuenta y los registros. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de MercadoPago y los estados de pedido Awaiting MercadoPago payment y MercadoPago payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
MercadoPago es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por MercadoPago.