VibeFox Braintree 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 anteriores do PHP.
Conta Braintree: você precisa do Merchant ID, da Public Key e da Private Key da sua conta Braintree. Eles ficam no Painel de Controle da Braintree (sandbox: sandbox.braintreegateway.com, live: www.braintreegateway.com), no ícone de engrenagem, API, API Keys. Contas sandbox e live têm chaves diferentes. O 3-D Secure precisa estar ativado para a sua conta de comerciante na Braintree, a menos que você defina 3-D Secure como Disabled. Não é necessário webhook: os pagamentos com cartão são confirmados na hora.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, acesse 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, localize VibeFox Braintree 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. Copie o Merchant ID, a Public Key e a Private Key do Painel de Controle da Braintree para os campos sandbox ou live.
5. Ative Enable/Disable e clique em Save. Mantenha Sandbox mode ativado e faça um pedido de teste com um cartão de teste da Braintree sandbox. Depois, desative Sandbox mode para receber pagamentos reais com as credenciais live.
Ao ser instalado, o módulo cria dois status de pedido: Braintree payment authorized e Braintree 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á-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Braintree Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Quando o método de pagamento está ativado, mas o Merchant ID, a Public Key ou a Private Key do ambiente selecionado está faltando, a página avisa que o método de pagamento fica oculto na finalização de compra até que sejam preenchidos. Enquanto o modo sandbox estiver ativado, a página mostra Sandbox mode is on: test payments, no real money.
Braintree
Enable/Disable: Enable Braintree card payments liga ou desliga o método de pagamento. Padrão: off.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit / debit card. Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit or debit card via Braintree.
Credenciais de API
Entre no Painel de Controle da Braintree (sandbox ou live), clique no ícone de engrenagem e depois em API e API Keys. Ali estão listadas a Public Key e a Private Key, e o Merchant ID aparece na mesma página. A página mostra apenas os campos de credenciais do ambiente selecionado; os dois conjuntos continuam salvos.
Sandbox mode: usa o sandbox da Braintree (pagamentos de teste, sem dinheiro real). Padrão: on. Desative para receber pagamentos reais com as credenciais live. Reembolsos, capturas e anulações sempre usam o ambiente em que o pedido foi pago. Enquanto estiver ativado, os clientes veem SANDBOX / TEST MODE — no real money is charged. abaixo do método de pagamento.
Sandbox Merchant ID e Live Merchant ID: o Merchant ID da conta sandbox ou live.
Sandbox Public Key e Live Public Key: a Public Key dessa conta.
Sandbox Private Key e Live Private Key: a Private Key dessa conta. As Private Keys salvas nunca são mostradas de novo. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-la.
Sandbox merchant account ID(s) e Live merchant account ID(s): opcionais. A Braintree cobra na moeda da conta de comerciante. Deixe vazio para usar a sua conta de comerciante padrão, digite um ID (por exemplo mystore_EUR) ou um por moeda: EUR=mystore_EUR, USD=mystore_USD. Se a moeda cobrada não corresponder à moeda do pedido, a transação é anulada automaticamente e o cliente não é cobrado.
Clear saved private keys: marque Sandbox Private Key ou Live Private Key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Pagamento
Transaction type: como o cartão é cobrado.
3-D Secure: o 3-D Secure 2 (Strong Customer Authentication) é obrigatório para a maioria dos pagamentos com cartão no EEE e no Reino Unido. Ele também precisa estar ativado na sua conta Braintree (entre em contato com o suporte da Braintree se os pagamentos falharem com um erro de configuração do 3-D Secure).
O resultado do 3-D Secure é verificado no servidor, não apenas no navegador, antes de o cartão ser cobrado.
Avançado
Debug log: também registra chamadas à API e as etapas do pagamento em logs/wc_btg_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 a opção desativada. O log nunca contém chaves de API, dados de cartão ou de clientes. Padrão: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway e o log. As transações, os reembolsos e os status de pedido da Braintree sempre são mantidos, então pedidos pagos antes ainda podem ser reembolsados, capturados ou anulados depois de 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 / debit card) e digita o cartão no formulário da Braintree dentro da opção de pagamento. O formulário é carregado da Braintree somente na página de finalização de compra e usa o idioma da loja. Com o 3-D Secure ativado, o cliente conclui a verificação com o banco ao fazer o pedido; o total do carrinho, o e-mail e o endereço de cobrança são enviados a essa verificação.
Em seguida, o módulo cobra o token de uso único pela API da Braintree no valor total do carrinho, na moeda do carrinho, usando o número do carrinho como ID do pedido na Braintree. Não existe pedido antes desse ponto. O valor e a moeda cobrados são conferidos com o carrinho. O pedido só é criado depois que a Braintree aceita o pagamento, e o cliente vê a página padrão de confirmação de pedido do PrestaShop.
Se o pagamento falhar, nenhum pedido é criado, o motivo é registrado no log do módulo, e o cliente permanece na etapa de pagamento com uma mensagem, por exemplo Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. ou The card security code or billing address could not be verified. Please check your details and try again. O cliente pode tentar de novo imediatamente. Se a moeda ou o valor cobrado não corresponderem ao carrinho, a transação é anulada e o cliente vê This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.
Um carrinho nunca é cobrado duas vezes. Um segundo envio enquanto o pagamento está em andamento mostra This order is already being paid. Please wait a moment and check your e-mail before trying again. Se o cartão foi cobrado, mas o PrestaShop não conseguiu criar o pedido, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. A próxima tentativa para o mesmo carrinho cria o pedido a partir da transação salva, sem cobrar novamente.
O módulo aceita apenas pagamentos com cartão. Não há cartões salvos, assinaturas ou pagamentos recorrentes, nem PayPal, Venmo, Apple Pay, Google Pay ou métodos de pagamento locais, e não são usados webhooks da Braintree.
Pedidos e reembolsos
Status do pedido
Nenhum pedido ainda: o pagamento não foi feito ou foi recusado. Existe apenas o carrinho.
Payment accepted: o cartão foi cobrado (Sale), ou uma autorização foi capturada. O pagamento é registrado com o ID da transação Braintree, e uma nota privada nas mensagens do pedido mostra o valor, o ID da transação e o resultado do 3-D Secure.
Braintree payment authorized: os valores estão apenas autorizados (Authorize only). Nenhum pagamento é registrado até que você o capture.
Braintree payment on hold: a Braintree retornou um status de transação inesperado, ou uma cobrança na moeda ou com valor errados não pôde ser anulada automaticamente. A nota explica o que verificar no Painel de Controle da Braintree.
Canceled: uma autorização foi anulada.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se chegar outra transação para um pedido que já foi criado, o pedido não é alterado. Uma nota pede que você a verifique no Painel de Controle da Braintree e a anule ou reembolse.
Bloco Braintree payment
A página do pedido mostra um bloco Braintree payment com o ID da transação (com link para a transação no Painel de Controle da Braintree do respectivo ambiente), o status da transação, o valor e a conta de comerciante, o resultado do 3-D Secure, o valor cobrado e reembolsado, um selo Sandbox para pagamentos sandbox e o histórico de reembolsos. Os botões do bloco exigem a permissão para editar pedidos; o acesso às páginas Modules não é necessário.
Captura e anulação
Para um pedido com o status Braintree payment authorized, clique em Capture Braintree payment para cobrar o total do pedido, ou em Void Braintree authorization para liberar o valor retido. A captura define o pedido como Payment accepted e registra o pagamento; a anulação o define como Canceled. Se a ação falhar, o erro é mostrado no bloco e adicionado às notas do pedido.
Reembolsos
No bloco Braintree payment, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Braintree. Confirme a pergunta Refund this amount through Braintree? This cannot be undone. Reembolsos totais e parciais são suportados. Os reembolsos são feitos no valor e na moeda cobrados pela Braintree; assim, depois de uma divergência de valor ou de moeda, você pode reembolsar até o montante que o cliente realmente pagou. A Braintree reembolsa somente transações liquidadas, normalmente em até 24 horas. Antes da liquidação, um reembolso total é feito como anulação; um reembolso parcial falha, então, com uma mensagem pedindo que você aguarde a liquidação. O reembolso é enviado ao ambiente (sandbox ou live) do pagamento, por isso as credenciais desse ambiente precisam estar configuradas. Se a Braintree não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas. Um reembolso total define o pedido como Refunded; um reembolso parcial não altera o status.
O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Braintree. Contestações (chargebacks), recusas na liquidação e reembolsos feitos no Painel de Controle da Braintree não são sincronizados com o PrestaShop.
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 Braintree Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Braintree Gateway > Configure, acima das configurações. Cole 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-braintree e o link Manage licenses and domains in your account, que abre a sua conta na vibefox.net. Apenas funcionários com a permissão Configure para o 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 único domínio: o domínio da loja principal, inclusive em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.
Sem uma chave ativa, a Braintree não é exibida 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á conectado ao back office, então o método de pagamento também fica oculto 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. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e capturas, anulações e reembolsos continuam funcionando.
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. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Braintree não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o ambiente selecionado tem Merchant ID, Public Key e Private Key. A página de configurações mostra um aviso quando uma chave 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 cartão foi cobrado, mas nenhum pedido foi criado: os pagamentos com cartão são confirmados na hora, sem webhook. Veja o campo Log na página do módulo. Se o log disser que a resposta da Braintree foi perdida, verifique no Painel de Controle da Braintree se existe uma transação com o número do carrinho como ID do pedido antes de aceitar outro pagamento. Se o pedido não puder ser criado depois da cobrança, a próxima tentativa de pagamento para o mesmo carrinho o criará sem cobrar novamente.
O formulário do cartão mostra Could not initialize payment form: as chaves do ambiente selecionado estão incorretas, ou o ID da conta de comerciante não existe nessa conta. Verifique as chaves e os IDs das contas de comerciante e depois recarregue a página.
O 3-D Secure falha em todos os pagamentos: o 3-D Secure precisa estar ativado para a sua conta de comerciante na Braintree. Entre em contato com o suporte da Braintree ou defina 3-D Secure como Disabled (não recomendado no EEE e no Reino Unido, onde a SCA é obrigatória).
O cliente é informado de que o pagamento não pôde ser processado na moeda do pedido: a Braintree cobrou na moeda da conta de comerciante. Digite o ID da conta de comerciante para a moeda do carrinho no campo de conta de comerciante do ambiente atual.
O cliente vê a mensagem The order total must be greater than zero to pay by card: o total do carrinho é zero, por exemplo após um cupom. Esses pedidos não podem ser pagos com cartão.
Um reembolso parcial falha logo após o pagamento: a Braintree só pode reembolsar transações liquidadas, normalmente em até 24 horas. Reembolse o valor total para anular a transação agora, ou faça o reembolso parcial depois da liquidação.
Reembolso, captura ou anulação falha com uma mensagem sobre o ambiente: o pagamento foi feito no ambiente sandbox ou live, e as credenciais desse ambiente não estão configuradas. Digite-as e tente novamente.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Braintree 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 e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos da Braintree e os status de pedido Braintree payment authorized e Braintree payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados, capturados ou anulados depois de uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e os IDs das transações.
A Braintree é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado à Braintree nem endossado por ela.