VibeFox Pagar.me for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Moeda: real brasileiro (BRL). O meio de pagamento fica oculto para carrinhos em qualquer outra moeda.
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 meios 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 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, depois, encontre o VibeFox Pagar.me Gateway na lista de módulos e clique em Configure.
3. Informe 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. Informe a chave secreta de teste e, quando for para produção, a chave secreta de produção.
5. Crie o webhook no painel da Pagar.me com a URL mostrada nas configurações (veja Configuração).
6. Ative Enable / Disable e clique em Save. Faça pagamentos de teste com Test mode ligado e depois desligue-o para receber pagamentos reais.
Ao instalar, o módulo cria dois status de pedido: Awaiting Pagar.me payment e Pagar.me payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-lo em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Pagar.me Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, 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 falta a chave secreta do modo atual (nesse caso o meio de pagamento fica 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 padrão da loja não é BRL.
Pagar.me
Enable / Disable: Enable Pagar.me payments liga ou desliga o meio de pagamento. Padrão: desligado.
Title: o nome do meio de pagamento que o cliente vê no checkout. Também é o nome do meio de pagamento gravado no pedido. Padrão: Pagar.me. Obrigatório.
Description: o texto exibido abaixo do meio 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 reais; a chave define se um pagamento é de teste ou real.
Test mode: usa a chave secreta de teste, sem cobranças reais. Enquanto estiver ligado, os clientes veem TEST MODE — Use test credentials. No real charges. abaixo do meio de pagamento. As consultas de status e os reembolsos de um pedido sempre usam a chave do modo em que o pagamento dele foi criado. Padrão: ligado.
Test secret key: a chave secreta de teste da Pagar.me (sk_test_...). É usada enquanto o modo de teste estiver ligado.
Live secret key: a chave secreta de produção da Pagar.me (sk_...). É usada quando o modo de teste está desligado. Mantenha-a em sigilo.
As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-la.
Clear saved secret keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
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. Se nenhum estiver marcado, são usados os métodos padrão. Padrão: Credit card, PIX and Boleto.
Boleto due in (days): o número de dias até o vencimento do boleto, de 1 a 30. O pedido permanece em Awaiting Pagar.me payment até que a Pagar.me confirme o pagamento. Padrão: 3. Outro valor é recusado ao salvar, com a mensagem Boleto due in (days): enter a number from 1 to 30.
Notificações de pagamento (webhook)
No painel da Pagar.me, abra Settings > Webhooks e crie um webhook com a URL mostrada em Webhook URL nesta seção. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_pagarme_gateway/webhook, possivelmente com um código de idioma como /en/. Copie-a exatamente como as configurações a mostram.
Selecione estes eventos (eles também estão listados nesta seção):
O webhook não precisa de senha nem de assinatura. Seu conteúdo nunca é considerado confiável: a loja usa dele apenas o ID do pedido na Pagar.me e lê esse pedido pela API da Pagar.me com a chave do modo em que ele foi criado. Notificações de pedidos de outras lojas na 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 à loja.
Avançado
Debug log: registra as requisições à API e as notificações em logs/wc_pgm_debug.log.php, dentro da pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Chaves e dados de clientes não são registrados. Padrão: desligado.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ligado, desinstalar o módulo remove as configurações do gateway e o registro. Os pedidos, os seus dados de pagamento da Pagar.me (necessários para reembolsos) e os status de pedido são mantidos. Padrão: desligado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o meio de pagamento (por padrão, Pagar.me) e confirma. É necessário um e-mail válido. O módulo cria um pedido na Pagar.me pelo total do carrinho em BRL, com as linhas do carrinho, o frete e o embrulho para presente (ou uma única linha Order # com o número do carrinho quando o carrinho tem descontos), e envia o cliente à página de pagamento da Pagar.me. Nesse momento ainda não existe nenhum pedido na sua loja.
O nome e o e-mail do cliente são enviados à Pagar.me. O CPF ou CNPJ é obtido do campo Identification number do endereço ou de VAT number; também é enviado um celular brasileiro. O endereço de cobrança só é enviado para um endereço brasileiro com CEP de 8 dígitos e estado. O PrestaShop não traz os estados brasileiros por padrão, então o cliente normalmente informa o endereço na página da Pagar.me. Sem CPF ou CNPJ, o cliente também o informa lá.
Depois de pagar, o cliente volta à 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 pago e a moeda precisam corresponder ao carrinho. Um pagamento com cartão, PIX ou boleto aprovado cria o pedido em Payment accepted, e o cliente vê a página padrão de confirmação do pedido com Your payment with Pagar.me has been received. Um PIX ou boleto emitido e ainda não pago cria o pedido em Awaiting Pagar.me payment, e a página mostra Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Cada retorno posterior lê o pedido da Pagar.me novamente, então um PIX ou boleto pago nesse meio tempo é aplicado mesmo que o webhook não tenha chegado. Se o pagamento de um desses pedidos falhou ou expirou, a página mostra Your Pagar.me payment was not completed. Please contact us about this order.
Se o cliente voltar sem pagar, ele retorna ao checkout com a mensagem The Pagar.me payment was not completed. You can pay the order below. Se o pagamento foi recusado ou cancelado, a mensagem é The Pagar.me payment was declined or canceled. You can try again below. O carrinho é mantido. Se o pedido já existe e o pagamento dele falhou ou expirou, a mensagem é The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Se a Pagar.me não puder ser acessada, uma página Payment confirmation pede ao cliente que não pague de novo e oferece Check again e Back to checkout.
Quando o cliente paga novamente, a página de pagamento aberta da Pagar.me é reaproveitada se o valor e o modo forem os mesmos; caso contrário, ela é fechada na Pagar.me antes de uma nova ser criada. Se a tentativa anterior foi paga nesse meio tempo, ou se o PIX ou boleto dela ainda aguarda pagamento, o pedido é criado sem um novo pagamento. Se a página anterior não puder ser fechada, ela continua associada ao carrinho, então um pagamento feito nela ainda é registrado.
Se a Pagar.me não conseguir iniciar o pagamento, o cliente permanece no checkout com uma mensagem curta, por exemplo Could not connect to Pagar.me. Please try again in a moment., ou com a mensagem da Pagar.me sobre dados de cobrança inválidos. O motivo técnico é gravado no registro.
O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo 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
No order yet: o cliente foi enviado à Pagar.me e ainda não pagou nem gerou um PIX ou boleto. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o ID do pedido na Pagar.me (or_...) como ID da transação, e uma nota mostra o pedido da Pagar.me e o meio de pagamento.
Awaiting Pagar.me payment: um PIX ou boleto foi emitido (ou um pagamento com cartão está em análise) e aguarda pagamento. O pedido passa para Payment accepted quando a Pagar.me confirma o pagamento.
Pagar.me payment on hold: o boleto foi pago apenas parcialmente; ou o valor pago ou a moeda diferem do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou); ou o pagamento chegou depois que o pedido foi cancelado; ou uma contestação foi aberta em um pedido pago. A nota explica o motivo. Verifique o pedido e atenda-o ou reembolse o pagamento.
Payment error: o pagamento de um pedido aguardando ou retido falhou, ou o pedido na Pagar.me foi cancelado ou expirou (por exemplo, um boleto não pago). Se a Pagar.me informar um pagamento depois, o pedido ainda assim passa para Payment accepted.
Refunded: o pagamento foi totalmente reembolsado pelo módulo, ou reembolsado ou cancelado na Pagar.me.
Cada status da Pagar.me é aplicado uma única vez, então webhooks ou retornos repetidos não acrescentam notas nem pagamentos. Se um segundo pedido da Pagar.me do mesmo carrinho for pago, uma nota pede que você reembolse a duplicata no painel da Pagar.me.
Bloco de pagamento da Pagar.me
A página do pedido mostra um bloco Pagar.me payment com o ID do pedido na Pagar.me e os IDs das cobranças, o meio de pagamento, o status, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Pagar.me notes do pedido.
Reembolsos
No bloco Pagar.me payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Pagar.me. Confirme a pergunta Refund this amount through Pagar.me? This cannot be undone. São aceitos reembolsos totais e parciais de pagamentos com cartão e PIX. É preciso ter permissão para editar pedidos. Você pode reembolsar até o valor que a Pagar.me efetivamente cobrou, então, depois de uma divergência de valor, o limite é o que o cliente pagou, e não o total do pedido. O reembolso é enviado com a chave do modo em que o pagamento foi feito, então a chave secreta desse modo precisa estar configurada. Um reembolso só é registrado quando a Pagar.me o confirma; caso contrário, o bloco mostra 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 é acrescentado ao histórico de reembolsos e às notas, com o ID da cobrança. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a Pagar.me informa o pagamento.
Pagamentos por 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 PrestaShop.
O módulo não gera notas de crédito (credit slips). Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Pagar.me.
Um reembolso total ou um cancelamento feito no painel da Pagar.me chega por webhook, coloca o pedido em Refunded e acrescenta uma nota. Uma contestação acrescenta uma nota e coloca um pedido pago em Pagar.me payment on hold.
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 Pagar.me Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Pagar.me Gateway > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-pagarme e o link Manage licenses and domains in your account, que abre a sua conta do 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 do 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. A vitrine do PrestaShop não sabe que você está logado no back office, então o meio de pagamento fica oculto para você também: você pode configurar o módulo antes de comprar uma chave, mas não testá-lo no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os 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 precisam de 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 informada, 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
A Pagar.me não aparece no checkout: verifique se a licença está ativa, se Enable / Disable está ligado, se a chave secreta do modo atual está informada (Test secret key no modo de teste, Live secret key no modo de produção) e se a moeda do carrinho é BRL. A página de configurações mostra um aviso quando a chave está ausente. 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 nenhum pedido foi criado ou o pedido continua em Awaiting Pagar.me payment: o webhook não está funcionando. No painel da Pagar.me, verifique se o webhook existe para a conta e o modo que você usa, se a URL dele é exatamente a mostrada em Webhook URL e se os eventos listados acima estão selecionados. O pedido também é verificado sempre que o cliente volta à 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: o carrinho estava sendo atualizado por outra requisição no mesmo instante, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Pagar.me tenta o webhook novamente. Ligue o Debug log para ver o motivo.
O webhook responde unknown order: o pedido na Pagar.me não foi criado por esta loja, por exemplo um pedido de outra loja na mesma conta. Nada é alterado.
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, por exemplo o CPF no campo Identification number do endereço. A mensagem informa o problema; o motivo completo está no registro.
O cliente vê Pagar.me only supports payments in Brazilian Real (BRL): o carrinho está em outra moeda.
O cliente vê This order already has a Pagar.me payment that the store has to review: um pagamento anterior do carrinho precisa da sua revisão. Verifique o painel da Pagar.me e o registro.
O pedido está em Pagar.me payment on hold após o pagamento: leia as notas no bloco Pagar.me payment (veja Status do pedido) e depois atenda o pedido ou reembolse o pagamento.
O reembolso falha em um boleto: pagamentos por boleto não podem ser reembolsados pela API. Reembolse no painel da Pagar.me e registre o reembolso manualmente.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está informada. Informe-a e tente novamente.
Desenvolvedores podem alterar os dados do pedido na Pagar.me antes do envio com o hook actionWcpPagarmeOrderData.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Pagar.me 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 ligado, as configurações do gateway e o registro são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. Os dados de pagamento da Pagar.me dos pedidos e os status de pedido Awaiting Pagar.me payment e Pagar.me payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.
Pagar.me é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Pagar.me.