VibeFox MercadoPago for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

WooCommerce: 8.0 o posterior, instalado y activo. Sin WooCommerce, el plugin no se activa.

PHP: 8.0 o posterior.

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 divisas, por eso el método de pago se oculta cuando las monedas no coinciden.

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 solo 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_mercadopago_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > MercadoPago > Manage, o haz clic en Settings debajo del nombre del plugin en la página de 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. Elige el Account country, introduce las credenciales de prueba y de producción y, opcionalmente, configura las notificaciones en tu aplicación de MercadoPago (véase Configuración).

6. Activa Enable / Disable y guarda. Haz pruebas con las tarjetas de prueba de MercadoPago (nombre del titular APRO = aprobada, CONT = pendiente, OTHE = rechazada) y después desmarca Test mode.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > MercadoPago. 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 prueba está activado. Avisa cuando faltan las credenciales del modo actual o cuando la moneda de la tienda no es la moneda de tu cuenta de MercadoPago (entonces el método de pago se oculta en la finalización de compra), y cuando las credenciales pertenecen a una cuenta de otro país distinto de Account country. En la lista de métodos de pago, MercadoPago aparece como que necesita configuración hasta que el modo actual tenga sus credenciales.

Al guardar, una credencial que no empieza por el prefijo esperado (TEST- en los campos de prueba, APP_USR- en los de producción) no se guarda: aparece un error y se mantiene el valor anterior. El plugin también consulta a MercadoPago a qué país pertenece el Access Token. Si no puede comprobar el token, si la cuenta no está en un país compatible o si el país no coincide con Account country, aparece un error. El plugin entonces usa el país de la cuenta.

General

Enable / Disable: Enable MercadoPago card payments activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. Predeterminado: Credit or debit card (MercadoPago).

Description: el texto que aparece encima de los campos de tarjeta en la finalización de compra. Predeterminado: 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. Determina la moneda de cobro, el idioma de los campos de tarjeta y si se pide el documento del titular. La moneda de la tienda debe ser la misma, por ejemplo ARS para Argentina. Predeterminado: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): los países compatibles. El campo de documento se muestra en todos ellos excepto en México.

Test mode: Use the test credentials (no real charges). En modo prueba se usan las credenciales TEST- y pagas con tarjetas de prueba de MercadoPago; en la finalización de compra aparece una insignia TEST MODE. Desmárcalo para cobrar tarjetas reales con las credenciales de producción. Predeterminado: activado. Para probar con una cuenta de usuario de prueba de MercadoPago (credenciales APP_USR-), introduce las credenciales de esa cuenta en los campos de producción y desactiva el modo prueba.

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.

Opciones de pago

Maximum installments: el número máximo 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. Predeterminado: 1.

Notificaciones de pago (webhooks)

Los pagos con tarjeta suelen tener una respuesta final al momento. Los pagos que MercadoPago mantiene en revisión (en proceso o pendientes) se completan con notificaciones de MercadoPago. El plugin envía la URL de notificación con cada pago cuando tu sitio tiene una dirección pública. También puedes añadirla en your application > Webhooks, evento Payments. La URL se muestra en esta sección de la configuración y tiene este aspecto: https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

Una notificación nunca se da por válida sin más. El plugin 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 al pedido mediante el ID y la clave del pedido. Sin notificaciones, los pedidos en revisión permanecen En espera hasta que los actualices a mano.

El plugin gestiona estos estados de pago de MercadoPago:

approved: el pago fue aprobado. El pedido se marca como pagado cuando el importe y la moneda coinciden.

in_process, pending, authorized: el pago está en revisión. El pedido pasa a En espera y lo completa una notificación posterior.

rejected, cancelled: el pago fue rechazado o cancelado. Un pedido sin pagar se marca como Fallido.

refunded, charged_back, in_mediation: se añade una nota; el estado del pedido no cambia.

Webhook secret signature: opcional. La clave secreta de firma que se muestra en your application > Webhooks. Si está configurada, las notificaciones sin una x-signature válida se rechazan (HTTP 401).

Avanzado

Debug log: Log API requests and notifications escribe en WooCommerce > Status > Logs, origen wcp_mercadopago_gateway. Los Access Token, los tokens de tarjeta y los datos del pagador no se registran. Predeterminado: desactivado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Los ID de pago de MercadoPago guardados en los pedidos son historial de pagos y siempre se conservan. Predeterminado: desactivado.

Finalización de compra

El cliente elige el método de pago (de forma predeterminada Credit or debit card (MercadoPago)) y completa los campos de 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 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 pedido.

Al realizar el pedido, MercadoPago convierte la tarjeta en un token de un solo uso y tu tienda crea el pago en el servidor por el total del pedido. El correo electrónico y el nombre de facturación, el documento y el número de pedido se envían a MercadoPago. Los importes en CLP y COP se cobran sin decimales y se redondean a un número entero, así que pon el número de decimales de WooCommerce en 0 para estas monedas.

Un pago aprobado se marca como pagado de inmediato y el cliente va a la página de pedido recibido. Un pago en revisión pone el pedido En espera; el cliente también va a la página de pedido recibido, y la notificación completa el pedido. Una tarjeta rechazada muestra en la finalización de compra 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 pedido muestra 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 WooCommerce High-Performance Order Storage (HPOS).

El plugin solo acepta tarjetas de crédito y débito. No tiene redirección a Checkout Pro, billetera de MercadoPago ni dinero en cuenta, ni pagos en 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

Pending payment: el pedido se creó y todavía no ha llegado ningún resultado de pago, por ejemplo tras un tiempo de espera.

Processing: MercadoPago aprobó el pago y el importe y la moneda coinciden. Los pedidos con solo productos virtuales descargables pasan a Completado, el comportamiento predeterminado de WooCommerce. La nota del pedido muestra el ID del pago de MercadoPago y el número de cuotas. El ID de transacción es el ID del pago de MercadoPago.

On hold: el pago está en revisión (en proceso o pendiente) y espera la notificación de MercadoPago. También se pone En espera cuando el importe o la moneda aprobados no coinciden con el pedido, o cuando MercadoPago devuelve un estado inesperado. La nota del pedido lo explica.

Failed: el pago fue rechazado o cancelado. La nota del pedido muestra el estado y su detalle. El cliente puede volver a pagar.

Si MercadoPago aprueba un pago para un pedido 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.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Credit or debit card (MercadoPago) (el botón muestra tu Title). Se admiten reembolsos totales y parciales. 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, WooCommerce muestra MercadoPago refused the refund con el motivo y no se registra ningún reembolso. Un reembolso aprobado o en proceso se añade a las notas del pedido con el ID del reembolso.

Los reembolsos y contracargos hechos en el panel de MercadoPago llegan por notificación y se añaden a las notas del pedido. No se registran automáticamente como reembolsos de WooCommerce.

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 > MercadoPago. 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 volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un solo dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, MercadoPago 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. Los gestores de la tienda que han 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 recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

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

MercadoPago does not appear at checkout: comprueba que la licencia esté activa, que Enable / Disable esté activado y que el modo actual tenga ambas credenciales con el prefijo correcto: las claves TEST- en modo prueba, las claves APP_USR- en producción. Comprueba que la moneda de la tienda (o la moneda del pedido en la página Pay for order) sea la moneda de tu cuenta de MercadoPago. La página de configuración indica cuál falta.

The payment went through, but the order stays On hold or Pending payment: la notificación no llegó. El plugin solo envía la URL de notificación cuando tu sitio tiene una dirección pública (no localhost ni un dominio .local o .test). Añade la URL de la configuración en your application > Webhooks con el evento Payments. Si está configurada la Webhook secret signature, comprueba que sea el secreto de la misma aplicación. El panel de MercadoPago muestra la respuesta de tu tienda para cada notificación.

Notification answers invalid signature: el secreto de firma pertenece a otra aplicación, o la notificación no tiene una x-signature válida. Vuelve a copiar el secreto o deja el campo vacío.

Notification answers not for this store: el pago no pertenece a un pedido de esta tienda pagado con MercadoPago. El pedido no se modifica.

A credential is not saved: 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-.

The customer sees 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 configuración.

The customer sees MercadoPago cannot process payments in: la moneda del pedido no es la moneda de tu cuenta de MercadoPago. MercadoPago no convierte monedas.

The secure card form does not load: el cliente ve The secure card form could not be loaded. Please reload the page or choose another payment method. Revisa la Public Key del modo actual. Para más detalles, activa el Debug log y mira en WooCommerce > Status > Logs, origen wcp_mercadopago_gateway.

Refund fails with a message about the mode: el pago se hizo en modo prueba o de producción, y el Access Token de ese modo no está configurado. Introdúcelo y vuelve a intentarlo.

Refund fails with MercadoPago did not answer the refund request: revisa el pago en el panel de MercadoPago antes de volver a intentarlo.

The license block shows an 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 en 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. La configuración de la pasarela, la comprobación guardada de la cuenta y los registros se eliminan solo si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, los ID de pago de MercadoPago y los ID de transacción.

MercadoPago es una marca comercial de su respectivo titular. Este plugin no está afiliado ni respaldado por MercadoPago.