VibeFox MercadoPago for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões anteriores do PHP.
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, então o método de pagamento fica oculto para um carrinho em outra moeda.
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 back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure, ou encontre depois VibeFox MercadoPago Gateway na lista de módulos e clique em Configure.
3. Digite a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).
4. Escolha o Account country, digite as credenciais de teste e de produção e, se quiser, configure as notificações no seu aplicativo do MercadoPago (veja Configuração).
5. Ative Enable / Disable e clique em Save. Teste um pagamento no modo de teste com os cartões de teste do MercadoPago e depois desative Test mode.
Na instalação, o módulo cria dois status de pedido: Awaiting MercadoPago payment e MercadoPago payment on hold. O PrestaShop atribui um novo módulo de pagamento aos países que estão ativos no momento da instalação. Confira as moedas, os países e os grupos de clientes do módulo em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. Cada seção tem o seu botão Save, que salva a página inteira. 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 falta a Public Key ou o Access Token do modo atual, quando a moeda da loja não é a moeda da sua conta do MercadoPago (o método de pagamento fica oculto na finalização de compra) e quando as credenciais pertencem a uma conta de um país diferente do indicado em Account country.
Ao salvar, uma credencial que não começa com o prefixo esperado (TEST- para campos de teste, APP_USR- para campos de produção) não é salva, e aparece o erro must start with … — the previous value was kept.. O módulo também consulta o MercadoPago para saber a que país pertence cada Access Token. Se o token do modo atual não puder ser verificado, se a conta não estiver em um país suportado ou se o país não corresponder a Account country, aparece um erro. O módulo então usa o país da conta.
MercadoPago
Enable / Disable: Enable MercadoPago card payments ativa ou desativa o método de pagamento. Padrão: off.
Title: o nome do método de pagamento mostrado ao cliente na finalização de compra. É também o nome do método salvo no pedido. Padrão: Credit or debit card (MercadoPago). Obrigatório.
Description: o texto mostrado acima dos campos do cartão na finalização de compra. 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 de cobrança, 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. Ao salvar as credenciais, o país é verificado com a conta. Padrão: Argentina (ARS).
Test mode: no modo de teste são usadas as credenciais TEST- e você paga com os cartões de teste do MercadoPago; na finalização de compra aparece o selo TEST MODE. Desative para cobrar cartões reais com as credenciais de produção. Padrão: on.
Test Public Key: começa com TEST-. Usada no navegador para tokenizar o cartão.
Test Access Token: começa com TEST-. Usado somente no servidor. Mantenha em segredo.
Production Public Key: começa com APP_USR-.
Production Access Token: começa com APP_USR-. Usado somente no servidor. Mantenha em segredo.
Os Access Tokens salvos e o segredo do webhook não são mais exibidos. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Opções de pagamento
Maximum installments: o maior número de parcelas que o cliente pode escolher, de 1 a 24. 1 = somente pagamento à vista, e o campo de parcelas não é mostrado. 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 processo ou pendentes) são concluídos por notificações do MercadoPago. O módulo envia a URL de notificação com cada pagamento quando a sua loja tem um endereço público (não localhost nem um domínio .local ou .test). Você também pode adicioná-la em your application > Webhooks, evento Payments. A URL aparece em Notification URL nesta seção. Com URLs amigáveis, ela tem esta aparência: https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Copie a URL exatamente como as configurações a mostram.
Uma notificação nunca é considerada confiável por si só. O módulo consulta o pagamento novamente na API do MercadoPago com o Access Token do ambiente em que o pagamento foi feito e o vincula a uma tentativa de pagamento da sua loja. Sem notificações, os pedidos em análise permanecem em Awaiting MercadoPago payment até você atualizá-los manualmente.
O módulo trata estes status de pagamento do MercadoPago:
Webhook secret signature: opcional. O segredo de assinatura mostrado em your application > Webhooks. Quando definido, notificações sem uma x-signature válida são rejeitadas (HTTP 401).
Clear saved secrets: marque Test Access Token, Production Access Token ou Webhook secret signature e clique em Save para remover. Um campo vazio mantém o valor salvo.
Avançado
Debug log: grava as requisições e notificações do MercadoPago no arquivo logs/wc_mpg_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com esta opção desativada. Access Tokens, tokens de cartão e dados do pagador não são registrados. Padrão: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.
Delete data on uninstall: quando ativada, a desinstalação do módulo remove as configurações do gateway e os logs. Os registros de pagamento do MercadoPago, os reembolsos e os status de pedido do módulo são sempre mantidos, assim pedidos pagos antes podem ser reembolsados mesmo após uma reinstalação. Padrão: off.
Finalização de compra
Na etapa de pagamento, 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 o Document number, seleciona o Card issuer e o número de Installments. As opções de parcelamento e os juros são fornecidos pelo MercadoPago para o total do carrinho. O formulário do cartão funciona com os temas Classic e Hummingbird.
Quando o cliente confirma, o MercadoPago transforma o cartão em um token de uso único e a sua loja cria o pagamento no servidor pelo total do carrinho. O e-mail e o nome do cliente, o documento e o número do carrinho são enviados ao MercadoPago; o pagamento aparece como Cart #, com o número do carrinho e o nome da sua loja. Valores em CLP e COP são cobrados sem casas decimais. Nenhum pedido existe antes da resposta do MercadoPago.
Um pagamento aprovado cria um pedido pago, e o cliente vê a página de confirmação do pedido com Your card payment has been received. Um pagamento em análise cria um pedido em Awaiting MercadoPago payment, e a página mostra MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. Se um pagamento em análise for recusado depois, a página mostra Your MercadoPago payment was not completed. Please contact us about this order. Um pedido retido mostra Your payment is being reviewed. We will update your order as soon as the review is complete.
Um cartão recusado não cria pedido. O cliente permanece na etapa de pagamento com 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 a 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 primeiro consulta o pagamento, então o cartão não é cobrado duas vezes. Um segundo clique enquanto o carrinho está sendo pago mostra This order is already being paid. Please wait a moment and check your e-mail before trying again. Um carrinho que já tem pedido nunca é cobrado de novo; o cliente é enviado para a página de confirmação desse pedido.
A URL de notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
O módulo 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), 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
No order: o cartão foi recusado, ou o MercadoPago ainda não respondeu. Só existe o carrinho.
Payment accepted: o MercadoPago aprovou o pagamento e o valor e a moeda coincidem com o carrinho. O pagamento é registrado com o ID do pagamento do MercadoPago como ID da transação, e uma nota mostra o ID do pagamento, o ambiente e o número de parcelas.
Awaiting MercadoPago payment: o pagamento está em análise (em processo ou pendente) e aguarda a notificação do MercadoPago. O pedido passa para Payment accepted quando o MercadoPago aprova.
MercadoPago payment on hold: o valor ou a moeda aprovados diferem do carrinho, ou o MercadoPago devolveu um status inesperado. A nota explica o motivo. Verifique o pedido e atenda-o ou reembolse o pagamento.
Payment error: um pagamento em análise foi recusado ou cancelado. A nota mostra o status e o seu detalhe.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se o MercadoPago aprovar um pagamento de um pedido que já está 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.
Bloco de pagamento do MercadoPago
A página do pedido mostra um bloco MercadoPago payment com o ID do pagamento, o status do pagamento, o ambiente (um selo Test para pagamentos de teste), as parcelas, o valor cobrado pelo MercadoPago e o total do pedido, o valor reembolsado, o histórico de reembolsos e as MercadoPago notes do pedido.
Reembolsos
No bloco MercadoPago payment, digite o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via MercadoPago. Confirme a pergunta Refund this amount through MercadoPago? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa do direito de editar pedidos. Os reembolsos são limitados ao valor cobrado pelo MercadoPago, então, após uma divergência de valor, você pode reembolsar até o que o cliente realmente pagou, e não até o total do pedido. 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 deve estar configurado. Se o MercadoPago recusar o reembolso, o bloco mostra MercadoPago refused the refund com o motivo e nenhum reembolso é registrado. Um reembolso aprovado ou em processo é adicionado ao histórico de reembolsos e às notas com o ID do reembolso. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pelo MercadoPago.
Reembolsos, chargebacks e mediações feitos no painel do MercadoPago chegam pela notificação e são adicionados às notas. O status do pedido e as notas de crédito não são alterados automaticamente. Atualize-os manualmente se necessário.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox MercadoPago Gateway é o primeiro bloco de Modules > Module Manager > VibeFox MercadoPago Gateway > Configure, acima das configurações. Digite a chave em License key e clique em Activate. Depois, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para remover a chave desta loja. Abaixo aparecem a linha Product: presta-payment-mercadopago e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o MercadoPago não é mostrado aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A vitrine do PrestaShop não sabe que você está logado no back office, então o método de pagamento fica oculto também para você: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem uma renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser digitada, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
MercadoPago não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ativado e se o modo atual tem as duas credenciais com o prefixo certo: as chaves TEST- no modo de teste, as APP_USR- em produção. Verifique se a moeda do carrinho é a moeda da sua conta do MercadoPago. A página de configurações indica qual está faltando. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas o pedido continua em Awaiting MercadoPago payment: a notificação não chegou. O módulo envia a URL de notificação somente quando a sua loja tem um endereço público (não localhost nem um domínio .local ou .test). Adicione a URL de Notification URL em your application > Webhooks com o evento Payments. Se Webhook secret signature estiver definido, confira se é o segredo do mesmo aplicativo. O painel do MercadoPago mostra a resposta da sua loja para cada notificação.
A notificação responde 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.
A notificação responde no credentials for test ou no credentials for live: o Access Token do ambiente em que o pagamento foi feito não está definido. Digite-o; o MercadoPago repete a notificação.
A notificação responde not for this store: o pagamento não pertence a uma tentativa de pagamento desta loja. Nenhum pedido é alterado.
A notificação responde order busy or payment could not be read: o pedido estava sendo atualizado por outra requisição no mesmo momento, ou o MercadoPago não pôde ser acessado. O MercadoPago repete a notificação automaticamente.
Uma credencial não é salva: o erro must start with mostra que o valor tem o prefixo errado para o campo. Os campos de teste aceitam credenciais TEST-, os de produção, credenciais APP_USR-.
O cliente vê 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. Confira-as na página de configurações.
O cliente vê MercadoPago cannot process payments in: a moeda do carrinho não é a moeda da sua conta do MercadoPago. O MercadoPago não converte moedas.
O formulário seguro do cartão não carrega: 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.
O cliente vê Your payment was received, but the order could not be completed automatically: o MercadoPago recebeu o pagamento, mas o PrestaShop não conseguiu criar o pedido (por exemplo, porque o módulo estava desativado naquele momento). Veja o campo Log na página do módulo: os erros são sempre registrados. O cliente é orientado a não pagar de novo; a próxima tentativa de pagamento ou a próxima notificação para o carrinho cria o pedido sem nova cobrança.
O pedido fica em MercadoPago payment on hold após o pagamento: leia as MercadoPago notes no bloco do pedido (veja Status do pedido) e depois atenda o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e o Access Token desse modo não está definido. Digite-o e tente novamente.
O reembolso falha com MercadoPago did not answer the refund request: verifique o pagamento no painel do MercadoPago antes de tentar novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox MercadoPago Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações do gateway, a verificação salva da conta e os logs são removidos. Se estiver desativado, todas as configurações são mantidas para uma futura reinstalação. Os registros de pagamento e reembolso do MercadoPago e os status de pedido Awaiting MercadoPago payment e MercadoPago payment on hold são sempre mantidos, assim pedidos pagos antes podem ser reembolsados mesmo após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
O MercadoPago é marca registrada do respectivo titular. Este módulo não é afiliado nem endossado pelo MercadoPago.