VibeFox Braintree for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo.

PHP: 8.0 ou superior.

HTTPS: o seu site deve usar HTTPS.

Conta Braintree: você precisa do Merchant ID, da Public Key e da Private Key da sua conta Braintree. Eles estão no Painel de Controle da Braintree (ambiente de teste: sandbox.braintreegateway.com; produção: www.braintreegateway.com), no ícone de engrenagem, em API, API Keys. As contas de teste e de produção têm chaves diferentes. O 3-D Secure precisa estar ativado na sua conta de comerciante da Braintree, a menos que você defina 3-D Secure como Disabled. Nenhum webhook é necessário.

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

Instalação

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Braintree > 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. Copie o Merchant ID, a Public Key e a Private Key do Painel de Controle da Braintree para os campos do ambiente de teste ou de produção.

6. Ative Enable/Disable. Mantenha Sandbox mode ativado e faça um pedido de teste com um cartão de teste da Braintree, por exemplo 4111 1111 1111 1111 com qualquer data de validade futura. Para o 3-D Secure, use os cartões de teste de 3-D Secure da Braintree.

7. Desmarque Sandbox mode para receber pagamentos reais com as credenciais de produção.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Braintree. Quando o gateway está ativado, mas falta o Merchant ID, a Public Key ou a Private Key do modo selecionado, a página avisa que o método de pagamento fica oculto na finalização de compra até que sejam preenchidos. A página mostra apenas os campos de credenciais do modo selecionado; os dois conjuntos continuam salvos.

Geral

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

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Credit / debit card.

Description: o texto exibido acima do formulário de cartão na finalização de compra. Padrão: Pay securely with your credit or debit card via Braintree.

Credenciais de API

Faça login no Painel de Controle da Braintree (teste ou produção), clique no ícone de engrenagem e, depois, em API e API Keys. As chaves pública e privada estão listadas ali, e o Merchant ID aparece na mesma página.

Sandbox mode: Use the Braintree sandbox (test payments, no real money). Padrão: ativado. Desmarque para receber pagamentos reais com as credenciais de produção. Reembolsos, capturas e anulações sempre usam o ambiente em que o pedido foi pago.

Sandbox Merchant ID e Live Merchant ID: o Merchant ID da conta de teste ou de produção.

Sandbox Public Key e Live Public Key: a chave pública dessa conta.

Sandbox Private Key e Live Private Key: a chave privada dessa conta.

Sandbox merchant account ID(s) e Live merchant account ID(s): opcional. A Braintree cobra na moeda da conta de comerciante. Deixe em branco para usar a sua conta de comerciante padrão, informe 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.

Pagamento

Transaction type: como o cartão é cobrado.

3-D Secure: o 3-D Secure 2 (Autenticação Forte do Cliente, SCA) é 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.

Avançado

Debug log: Also log API calls and payment steps (errors are always logged). Os logs ficam em WooCommerce > Status > Logs, origem wcp_braintree_gateway. Eles nunca contêm chaves de API, dados de cartão ou dados do cliente. Padrão: desativado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão, Credit / debit card) e insere os dados do cartão no formulário seguro da Braintree, na página de finalização de compra. No ambiente de teste, o formulário mostra SANDBOX / TEST MODE — no real money is charged. Com o 3-D Secure ativado, o cliente conclui a verificação do banco ao fazer o pedido.

O plugin cobra o token de uso único pela API da Braintree pelo total do pedido na moeda do pedido, com o número do pedido como ID do pedido. O pedido só é marcado como pago com a resposta autenticada da Braintree, depois que o valor cobrado e a moeda são conferidos com o pedido. Se o pagamento for aprovado, o cliente vai à página de pedido recebido. Pagamentos com cartão não precisam de webhook: o resultado é conhecido na hora.

Se o pagamento falhar, o pedido permanece com o status Pending payment, o motivo é adicionado às notas do pedido, e o cliente vê uma mensagem clara, 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 cobrada não corresponder à do pedido, 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 pedido 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.

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 armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).

O plugin aceita apenas pagamentos com cartão. Não há cartões salvos (vaulting), WooCommerce Subscriptions ou pré-vendas, nem PayPal, Venmo, Apple Pay, Google Pay, ACH ou métodos de pagamento locais, nem webhooks da Braintree, nem dados de Nível 2/3, itens do pedido ou Fastlane.

Pedidos e reembolsos

Status do pedido

Pending payment: o pagamento ainda não foi feito ou foi recusado.

Processing or Completed: o cartão foi cobrado (Sale), ou uma autorização foi capturada. O WooCommerce define Processando, ou Concluído para pedidos com apenas produtos virtuais para download. A nota do pedido mostra o valor, o ID da transação e o resultado do 3-D Secure. O ID da transação é o ID da transação da Braintree, e na tela do pedido ele leva à transação no Painel de Controle da Braintree.

On hold: os valores estão apenas autorizados (Authorize only). Um pedido também fica em espera quando a Braintree retorna um status de transação inesperado, ou quando uma cobrança na moeda errada não pôde ser anulada automaticamente. A nota do pedido explica o que verificar no Painel de Controle da Braintree.

Cancelled: uma autorização foi anulada com Void Braintree authorization.

Captura e anulação

Para um pedido com autorização, abra o pedido e escolha Capture Braintree payment ou Void Braintree authorization nas ações do pedido, depois clique no botão de atualização. A captura marca o pedido como pago; a anulação cancela o pedido e libera o valor retido ao cliente. Se a ação falhar, o erro é mostrado na tela do pedido e adicionado às notas do pedido.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit / debit card (o botão usa o título do seu método de pagamento). São compatíveis reembolsos totais e parciais. A Braintree só pode reembolsar transações liquidadas, geralmente em até 24 horas. Antes da liquidação, um reembolso total é feito como anulação; um reembolso parcial falha, com uma mensagem para aguardar a liquidação. O reembolso é enviado ao ambiente (teste ou produção) em que o pedido foi pago. Se a Braintree não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso ou uma anulação bem-sucedidos são adicionados às notas do pedido.

Contestações (chargebacks) e recusas na liquidação não são sincronizadas com o WooCommerce. Verifique-as no Painel de Controle da Braintree.

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 > Braintree. 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 Braintree não é mostrada 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. Gerentes da loja logados ainda veem 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. Pedidos existentes não são afetados: capturas, anulações e reembolsos continuam funcionando.

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

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á ativado e se o modo selecionado tem Merchant ID, Public Key e Private Key. A página de configurações mostra um aviso quando alguma chave está faltando.

O pagamento foi feito, mas o pedido continua com o status Pending payment: pagamentos com cartão são confirmados imediatamente, sem webhook. Se a nota do pedido disser que a resposta da Braintree se perdeu, verifique no Painel de Controle da Braintree se há uma transação com este número de pedido antes de aceitar outro pagamento. Ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_braintree_gateway.

O formulário de cartão mostra Could not initialize payment form: as chaves do modo 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 recarregue a página.

O 3-D Secure falha em todos os pagamentos: o 3-D Secure precisa estar ativado na sua conta de comerciante da 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 recebe a mensagem de que o pagamento não pôde ser processado na moeda do pedido: a Braintree cobrou na moeda da conta de comerciante. Informe, no campo de conta de comerciante do modo atual, o ID da conta para a moeda do pedido.

Um reembolso parcial falha logo após o pagamento: a Braintree só pode reembolsar transações liquidadas, geralmente em até 24 horas. Reembolse o valor total para anular a transação agora, ou faça o reembolso parcial depois da liquidação.

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 são removidos somente se Delete data on uninstall estava ativado. Caso contrário, permanecem para uma eventual reinstalação. Os dados da Braintree armazenados nos pedidos são sempre mantidos, porque são necessários para reembolsos após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

A Braintree é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Braintree.