VibeFox MercadoPago for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. Sem o WooCommerce o plugin não ativa.

PHP: 8.0 ou superior.

Moeda da loja: a moeda do país da sua conta do MercadoPago: ARS (Argentina), BRL (Brasil), CLP (Chile), COP (Colômbia), MXN (México), PEN (Peru) ou UYU (Uruguai). O MercadoPago cobra na moeda da conta e não converte, por isso o método de pagamento fica oculto quando as moedas não coincidem.

Conta do MercadoPago: você precisa de um aplicativo no painel de desenvolvedores do MercadoPago (Your integrations > your application > Credentials) com as credenciais de teste (começam com TEST-) e de produção (começam com APP_USR-): uma Public Key e um Access Token para cada uma. Para a verificação opcional da assinatura das notificações, também é preciso o segredo de assinatura em your application > Webhooks.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_mercadopago_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > MercadoPago > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Escolha o Account country, insira as credenciais de teste e de produção e, se quiser, configure as notificações no seu aplicativo do MercadoPago (veja Configuração).

6. Ative Enable / Disable e salve. Teste com os cartões de teste do MercadoPago (nome do titular APRO = aprovado, CONT = pendente, OTHE = recusado) e depois desmarque Test mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > MercadoPago. Acima dos campos, a página mostra Test mode is on: the TEST- credentials are used and no real money is charged. enquanto o modo de teste estiver ativo. Ela avisa quando faltam as credenciais do modo atual ou quando a moeda da loja não é a moeda da sua conta do MercadoPago (nesse caso o método de pagamento fica oculto no checkout), e quando as credenciais pertencem a uma conta de outro país que não o de Account country. Na lista de métodos de pagamento, o MercadoPago aparece como precisando de configuração até que o modo atual tenha as suas credenciais.

Ao salvar, uma credencial que não começa com o prefixo esperado (TEST- nos campos de teste, APP_USR- nos campos de produção) não é salva: aparece um erro e o valor anterior é mantido. O plugin também pergunta ao MercadoPago a qual país pertence o Access Token. Se não conseguir verificar o token, se a conta não estiver em um país suportado ou se o país for diferente de Account country, aparece um erro. O plugin então usa o país da conta.

Geral

Enable / Disable: Enable MercadoPago card payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento exibido ao cliente no checkout. Padrão: Credit or debit card (MercadoPago).

Description: o texto exibido acima dos campos do cartão no checkout. Padrão: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

Conta do MercadoPago

Obtenha as credenciais do seu aplicativo no painel de desenvolvedores do MercadoPago: Your integrations > your application > Credentials. As credenciais de teste começam com TEST-, as de produção com APP_USR-.

Account country: o país da sua conta do MercadoPago. Ele define a moeda cobrada, o idioma dos campos do cartão e se o documento do titular é solicitado. A moeda da loja deve ser a mesma, por exemplo ARS para a Argentina. Padrão: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): os países suportados. O campo de documento é exibido para todos, exceto o México.

Test mode: Use the test credentials (no real charges). No modo de teste são usadas as credenciais TEST- e você paga com os cartões de teste do MercadoPago; no checkout aparece o selo TEST MODE. Desmarque para cobrar cartões reais com as credenciais de produção. Padrão: ativado. Para testar com uma conta de usuário de teste do MercadoPago (credenciais APP_USR-), insira as credenciais dessa conta nos campos de produção e desative o modo de teste.

Test Public Key: começa com TEST-. Usada no navegador para tokenizar o cartão.

Test Access Token: começa com TEST-. Usado apenas no servidor. Mantenha em segredo.

Production Public Key: começa com APP_USR-.

Production Access Token: começa com APP_USR-. Usado apenas no servidor. Mantenha em segredo.

Opções de pagamento

Maximum installments: o maior número de parcelas que o cliente pode escolher, de 1 a 24. 1 = apenas pagamento à vista, e o campo de parcelas não é exibido. O limite também é aplicado no servidor. Padrão: 1.

Notificações de pagamento (webhooks)

Pagamentos com cartão geralmente recebem uma resposta final na hora. Pagamentos que o MercadoPago mantém em análise (em processamento ou pendentes) são concluídos por notificações do MercadoPago. O plugin envia a URL de notificação com cada pagamento quando o seu site tem um endereço público. Você também pode adicioná-la em your application > Webhooks, evento Payments. A URL aparece nesta seção das configurações e tem este formato: https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

Uma notificação nunca é considerada confiável por si só. O plugin consulta o pagamento novamente na API do MercadoPago com o Access Token do ambiente em que o pagamento foi feito e o vincula ao pedido pelo ID do pedido e pela chave do pedido. Sem notificações, os pedidos em análise permanecem em Em espera até que você os atualize manualmente.

O plugin trata estes status de pagamento do MercadoPago:

approved: o pagamento foi aprovado. O pedido é marcado como pago quando o valor e a moeda coincidem.

in_process, pending, authorized: o pagamento está em análise. O pedido é colocado em espera e concluído por uma notificação posterior.

rejected, cancelled: o pagamento foi recusado ou cancelado. Um pedido não pago é marcado como Falhou.

refunded, charged_back, in_mediation: uma nota é adicionada; o status do pedido não muda.

Webhook secret signature: opcional. O segredo de assinatura exibido em your application > Webhooks. Quando definido, notificações sem uma x-signature válida são rejeitadas (HTTP 401).

Avançado

Debug log: Log API requests and notifications grava em WooCommerce > Status > Logs, origem wcp_mercadopago_gateway. Access Tokens, tokens de cartão e dados do pagador não são registrados. Padrão: desativado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Os IDs de pagamento do MercadoPago salvos nos pedidos fazem parte do histórico de pagamentos e são sempre mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Credit or debit card (MercadoPago)) e preenche os campos do cartão: Card number, Expiry (MM/YY), Security code e Cardholder name. Dependendo do país e do cartão, o cliente também escolhe Document type e digita Document number, seleciona o Card issuer e o número de Installments. As opções de parcelamento e os juros vêm do MercadoPago para o total do pedido.

Ao fazer o pedido, o MercadoPago transforma o cartão em um token de uso único e a sua loja cria o pagamento no servidor pelo total do pedido. O e-mail e o nome de cobrança, o documento e o número do pedido são enviados ao MercadoPago. Valores em CLP e COP são cobrados sem casas decimais e arredondados para um número inteiro; por isso, defina como 0 o número de casas decimais do WooCommerce para essas moedas.

Um pagamento aprovado é marcado como pago na hora, e o cliente vai para a página de pedido recebido. Um pagamento em análise coloca o pedido em espera; o cliente também vai para a página de pedido recebido, e o pedido é concluído pela notificação. Um cartão recusado mostra no checkout um motivo curto, por exemplo Your card has insufficient funds. Please use another card or payment method. ou Please check the security code of your card. O cliente pode corrigir os dados ou usar outro cartão; um novo token de cartão é criado em cada tentativa.

Se o MercadoPago não responder, o cliente vê 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. A próxima tentativa consulta primeiro o pagamento, para que o cartão não seja cobrado duas vezes. Um segundo clique enquanto o pedido está sendo pago mostra This order is already being paid. Please wait a moment and check your e-mail before trying again.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita apenas cartões de crédito e débito. Não tem redirecionamento para o Checkout Pro, carteira ou saldo do MercadoPago, nem pagamentos em dinheiro (Rapipago, OXXO, boleto e outros), nem Pix, PSE ou Yape, nem cartões salvos ou assinaturas, nem autorização e captura separadas, nem desafio 3-D Secure e nem conversão de moeda.

Pedidos e reembolsos

Status do pedido

Pending payment: o pedido foi criado e ainda não chegou nenhum resultado de pagamento, por exemplo após um tempo limite.

Processing: o MercadoPago aprovou o pagamento e o valor e a moeda coincidem. Pedidos com apenas produtos virtuais para download passam para Concluído, o comportamento padrão do WooCommerce. A nota do pedido mostra o ID do pagamento do MercadoPago e o número de parcelas. O ID da transação é o ID do pagamento do MercadoPago.

On hold: o pagamento está em análise (em processamento ou pendente) e aguarda a notificação do MercadoPago. O pedido também fica Em espera quando o valor ou a moeda aprovados não coincidem com o pedido, ou quando o MercadoPago retorna um status inesperado. A nota do pedido explica o motivo.

Failed: o pagamento foi recusado ou cancelado. A nota do pedido mostra o status e o seu detalhe. O cliente pode pagar novamente.

Se o MercadoPago aprovar um pagamento para um pedido cancelado ou reembolsado, o status não muda e uma nota pede que você conclua o pedido ou reembolse o pagamento. Se chegar outro pagamento para um pedido já pago, uma nota pede que você reembolse o pagamento extra no painel do MercadoPago.

Reembolsos

Abra o pedido, clique em Refund, insira o valor e clique em Refund via Credit or debit card (MercadoPago) (o botão mostra o seu Title). São aceitos reembolsos totais e parciais. O reembolso é enviado com as credenciais do ambiente em que o pagamento foi feito (teste ou produção), por isso o Access Token desse ambiente precisa estar definido. Se o MercadoPago recusar o reembolso, o WooCommerce mostra MercadoPago refused the refund com o motivo e nenhum reembolso é registrado. Um reembolso aprovado ou em processamento é adicionado às notas do pedido com o ID do reembolso.

Reembolsos e contestações feitos no painel do MercadoPago chegam pela notificação e são adicionados às notas do pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > MercadoPago. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.

Sem uma chave ativa, o MercadoPago não é exibido aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Os gerentes da loja que estiverem conectados continuam vendo o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

MercadoPago does not appear at checkout: verifique se a licença está ativa, se Enable / Disable está ativado e se o modo atual tem as duas credenciais com o prefixo correto: as chaves TEST- no modo de teste, as chaves APP_USR- na produção. Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é a moeda da sua conta do MercadoPago. A página de configurações indica qual está faltando.

The payment went through, but the order stays On hold or Pending payment: o pagamento foi concluído, mas o pedido continua Em espera ou Pagamento pendente: a notificação não chegou. O plugin só envia a URL de notificação quando o seu site tem um endereço público (não localhost nem um domínio .local ou .test). Adicione a URL das configurações em your application > Webhooks com o evento Payments. Se a Webhook secret signature estiver definida, verifique se é o segredo do mesmo aplicativo. O painel do MercadoPago mostra a resposta da sua loja para cada notificação.

Notification answers invalid signature: o segredo de assinatura pertence a outro aplicativo, ou a notificação não tem uma x-signature válida. Copie o segredo novamente ou deixe o campo vazio.

Notification answers not for this store: o pagamento não pertence a um pedido desta loja pago com o MercadoPago. O pedido não é alterado.

A credential is not saved: o erro must start with indica que o valor tem o prefixo errado para o campo. Os campos de teste aceitam credenciais TEST-, os campos de produção aceitam credenciais APP_USR-.

The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.: as credenciais do modo atual estão faltando, têm o prefixo errado ou foram rejeitadas pelo MercadoPago. Verifique-as na página de configurações.

The customer sees MercadoPago cannot process payments in: a moeda do pedido não é a moeda da sua conta do MercadoPago. O MercadoPago não converte moedas.

The secure card form does not load: o cliente vê The secure card form could not be loaded. Please reload the page or choose another payment method. Verifique a Public Key do modo atual. Para mais detalhes, ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_mercadopago_gateway.

Refund fails with a message about the mode: o pagamento foi feito no modo de teste ou de produção, e o Access Token desse modo não está definido. Insira-o e tente novamente.

Refund fails with MercadoPago did not answer the refund request: verifique o pagamento no painel do MercadoPago antes de tentar de novo.

The license block shows an error: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta da vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway, a verificação de conta salva e os logs são removidos somente se Delete data on uninstall estiver ativado. Caso contrário, ficam guardados para uma reinstalação futura. Os pedidos existentes mantêm as suas notas de pagamento, os IDs de pagamento do MercadoPago e os IDs de transação.

MercadoPago é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo MercadoPago.