VibeFox Pagar.me for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda: real brasileiro (BRL). O método de pagamento fica oculto quando a moeda da loja (ou, na página Pay for order, a moeda do pedido) não é BRL.
Conta na Pagar.me: você precisa das chaves secretas da sua conta na Pagar.me: a chave de teste (sk_test_...) e, para ir para produção, a chave de produção (sk_...). Elas ficam no painel da Pagar.me, em Development > Keys. Somente as chaves secretas são usadas; a chave pública (pk_...) não é necessária. Só podem ser oferecidos os métodos de pagamento habilitados na sua conta da Pagar.me.
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_pagarme_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Pagar.me > 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. Insira a chave secreta de teste e, quando for para produção, a chave secreta de produção.
6. Crie o webhook no painel da Pagar.me com a URL mostrada nas configurações (veja Configuração).
7. Ative o Enable / Disable e salve. Faça pagamentos de teste com o Test mode ativado; depois desative-o para receber pagamentos reais.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Pagar.me. Abaixo do título, a página mostra o modo atual: TEST MODE (os pagamentos são criados com a chave secreta de teste, sem cobranças reais) ou LIVE. Ela avisa quando a chave secreta do modo atual está ausente (o método de pagamento fica então oculto no checkout), quando a chave de teste não começa com sk_test_, quando a chave de produção não começa com sk_ ou é uma chave de teste, e quando a moeda da loja não é BRL. Na lista de métodos de pagamento, a Pagar.me aparece como precisando de configuração até que a chave do modo atual seja informada, e um selo de modo de teste é exibido enquanto o modo de teste estiver ativo.
Geral
Enable / Disable: Enable Pagar.me payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê no checkout. Padrão: Pagar.me.
Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
Chaves de API
Copie as chaves secretas do painel da Pagar.me: Development > Keys. A Pagar.me usa um único endereço de API para pagamentos de teste e de produção; a chave é que define se um pagamento é de teste ou real.
Test mode: Use the test secret key (no real charges). Enquanto o modo de teste estiver ativo, uma nota TEST MODE é exibida no checkout. As consultas de status e os reembolsos de um pedido sempre usam a chave do modo em que o seu pagamento foi criado. Padrão: ativado.
Test secret key: a chave secreta de teste da Pagar.me (sk_test_...). Usada enquanto o modo de teste estiver ativo.
Live secret key: a chave secreta de produção da Pagar.me (sk_...). Usada quando o modo de teste está desativado. Mantenha-a em segredo.
A chave secreta única da versão 1.0 é transferida automaticamente: uma chave de teste vai para Test secret key e o modo de teste é ativado; caso contrário, ela permanece como chave de produção e o modo de teste é desativado.
Página de pagamento
Payment methods: os métodos oferecidos na página de pagamento da Pagar.me. Escolha somente métodos habilitados na sua conta da Pagar.me. Padrão: Credit card, PIX e Boleto.
Boleto due in (days): número de dias até o vencimento do boleto, de 1 a 30. O pedido permanece On hold até que a Pagar.me confirme o pagamento. Padrão: 3.
Notificações de pagamento (webhook)
No painel da Pagar.me, abra Settings > Webhooks e crie um webhook com a URL exibida nesta seção. Ela tem este formato: https://your-site/wc-api/webhook_wc_pagarme/. Copie-a exatamente como as configurações mostram.
Selecione estes eventos:
O webhook não precisa de senha nem de assinatura. O seu conteúdo nunca é considerado confiável: a loja usa dele apenas o ID do pedido da Pagar.me e lê esse pedido pela API da Pagar.me com a chave do modo em que foi criado. Notificações de pedidos de outras lojas da mesma conta da Pagar.me são ignoradas. Sem o webhook, pagamentos de PIX e boleto feitos depois só são confirmados quando o cliente volta para a loja.
Avançado
Debug log: Log API requests and notifications grava os detalhes em WooCommerce > Status > Logs, origem wcp_pagarme_gateway. Erros são sempre registrados. Os logs não contêm chaves nem dados de clientes. Padrão: desativado.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Padrão: desativado.
Checkout
O cliente escolhe o método de pagamento (por padrão Pagar.me) e faz o pedido. É necessário um e-mail de cobrança válido. O plugin cria um pedido na Pagar.me pelo total em BRL, com os itens do pedido, o frete e as taxas (ou uma única linha Order # com o número do pedido, quando os itens não puderem somar exatamente), e envia o cliente para a página de pagamento da Pagar.me. O nome, o e-mail e, para o Brasil, o telefone e o endereço de cobrança do cliente são repassados à Pagar.me. O CPF ou CNPJ é obtido dos campos do Brazilian Market on WooCommerce, quando existirem; caso contrário, o cliente o informa na página da Pagar.me.
Após o pagamento, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Pagar.me confirma: a loja lê o pedido da Pagar.me pela API, e o valor e a moeda pagos devem coincidir com o pedido. Um pagamento com cartão, PIX ou boleto efetuado marca o pedido como pago. Um PIX ou boleto emitido e ainda não pago coloca o pedido em On hold até que a Pagar.me confirme o pagamento pelo webhook.
Se o cliente voltar sem pagar, ou se o pagamento tiver sido recusado ou cancelado, ele vai para a página Pay for order com The Pagar.me payment was not completed. You can pay the order below. ou The Pagar.me payment was declined or canceled. You can try again below.
Quando o cliente paga novamente, a página de pagamento da Pagar.me ainda aberta é reaproveitada se o valor e o modo forem os mesmos; caso contrário, ela é fechada na Pagar.me antes que uma nova seja criada. Se a tentativa anterior tiver sido paga nesse meio-tempo, ou se o seu PIX ou boleto ainda estiver aguardando, o pedido é atualizado sem um novo pagamento. Se a página anterior não puder ser fechada, ela continua associada ao pedido, de modo que um pagamento feito nela ainda é registrado.
Se a Pagar.me não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo Could not connect to Pagar.me. Please try again in a moment., ou a mensagem da Pagar.me sobre dados de cobrança inválidos. O motivo técnico é adicionado às notas do pedido.
O método de pagamento funciona no checkout clássico, 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 não tem formulário de cartão no seu checkout, nem cartões salvos, assinaturas ou cobranças recorrentes, nem regras de parcelamento, nem pagamentos divididos (marketplace), nem pagamentos com cartão apenas de autorização e nenhuma integração com o Pagar.me Hub.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Pagar.me e ainda não pagou nem gerou um PIX ou boleto. Uma nota mostra o ID do pedido na Pagar.me e o modo.
Processing: o pagamento foi confirmado. Este é o status padrão do WooCommerce após o pagamento; pedidos com apenas produtos virtuais para download passam para Concluído. A nota do pedido mostra o ID do pedido na Pagar.me e o método de pagamento. O ID da transação é o ID do pedido na Pagar.me (or_...).
On hold: um PIX ou boleto foi gerado (ou um pagamento com cartão está em análise) e aguarda pagamento; ou o boleto foi pago apenas parcialmente; ou o valor ou a moeda pagos diferem do pedido; ou um pagamento chegou depois que o pedido foi cancelado; ou o pedido foi pago na Pagar.me depois que o cliente trocou de método de pagamento; ou uma contestação (chargeback) foi aberta em um pedido pago. A nota do pedido explica. Revise o pedido e defina-o como Processing, ou reembolse o pagamento na Pagar.me.
Failed: o pagamento falhou, ou o pedido da Pagar.me foi cancelado ou expirou (por exemplo, um boleto não pago). Somente a última tentativa de um pedido não pago pode levá-lo a Failed. O cliente pode pagar novamente.
Refunded: o pagamento foi reembolsado ou cancelado na Pagar.me.
Cada status da Pagar.me é aplicado uma única vez, por isso webhooks ou retornos repetidos não adicionam notas, e-mails ou baixas de estoque. Um pedido pago nunca volta a pendente ou falho, e um pedido cancelado ou reembolsado nunca é reaberto. Se um segundo pedido da Pagar.me do mesmo pedido do WooCommerce for pago, uma nota pede que você reembolse a duplicata no painel da Pagar.me.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Pagar.me (o botão exibe o título do seu método de pagamento). Reembolsos totais e parciais de pagamentos com cartão e PIX são suportados, até o valor ainda reembolsável na Pagar.me. O reembolso é enviado com a chave do modo em que o pagamento foi feito. Um reembolso só é registrado quando a Pagar.me o confirma; caso contrário, o WooCommerce exibe o erro, por exemplo Pagar.me refused the refund: ... ou Pagar.me did not confirm the refund, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID da cobrança.
Pagamentos com boleto só podem ser reembolsados para a conta bancária do cliente. Reembolse-os no painel da Pagar.me e depois registre o reembolso manualmente no WooCommerce, sem usar Refund via Pagar.me.
Um reembolso total ou um cancelamento feito no painel da Pagar.me chega por webhook e define o pedido como Refunded. Uma contestação adiciona uma nota e coloca um pedido Processing ou Completed em On hold.
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 > Pagar.me. 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 em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a Pagar.me não é exibida 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 conectados ainda veem o método de pagamento, marcado com (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 continuam funcionando.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente em segundo plano.
Solução de problemas
A Pagar.me não aparece no checkout: verifique se a licença está ativa, se o Enable / Disable está ativado, se a chave secreta do modo atual está informada (Test secret key no modo de teste, Live secret key no modo real) e se a moeda da loja é BRL. A página de configurações mostra um aviso em cada caso.
O pagamento foi feito, mas o pedido continua em Pending payment ou On hold: o webhook não está funcionando. No painel da Pagar.me, confira se o webhook existe para a conta e o modo que você usa, se a URL dele é exatamente a exibida nas configurações e se os eventos listados acima estão selecionados. O pedido também é verificado quando o cliente volta para a loja.
O webhook responde verification failed, retry later: a loja não conseguiu ler o pedido da Pagar.me pela API, por exemplo porque a chave desse modo está ausente ou a API não respondeu. A Pagar.me tenta o webhook novamente.
O webhook responde busy, retry later: o pedido estava sendo atualizado por outra requisição no mesmo momento. A Pagar.me tenta o webhook novamente.
O webhook responde unknown order: o pedido da Pagar.me não foi criado por esta loja, por exemplo um pedido de outra loja na mesma conta. Nada é alterado.
O cliente vê This order is already being processed: um webhook ou o retorno do cliente estava atualizando o pedido no mesmo momento. O cliente pode tentar novamente depois de instantes.
O cliente vê Pagar.me payments are not available right now: a chave secreta está errada ou ausente. Verifique a chave do modo atual.
O cliente vê Pagar.me could not start the payment: a Pagar.me recusou os dados de cobrança. A mensagem informa o problema; o motivo completo está nas notas do pedido.
O cliente vê Pagar.me only supports payments in Brazilian Real (BRL): o pedido está em outra moeda, por exemplo por causa de um plugin de troca de moeda.
Pedido On hold após o pagamento: leia a nota do pedido. Um PIX ou boleto está aguardando pagamento, o valor ou a moeda pagos eram diferentes, ou o pagamento chegou depois que o pedido foi cancelado.
O reembolso falha para um boleto: pagamentos com boleto não podem ser reembolsados pela API. Reembolse no painel da Pagar.me e registre o reembolso manualmente.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em 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 de licença deste plugin são sempre removidos. As configurações do gateway e os logs do plugin só são removidos se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm as suas notas de pagamento, IDs de transação e dados da Pagar.me.
Pagar.me é uma marca registrada de seu respectivo titular. Este plugin não é afiliado à Pagar.me nem endossado por ela.