VibeFox Braintree for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e posterior (testado na 4.1.0.3).

PHP: 8.0 ou posterior.

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

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

Instalação

O download é um único arquivo zip com os pacotes das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3, wcp_braintree_gateway-oc3-(version).ocmod.zip, e o pacote do OpenCart 4, wcp_braintree_gateway.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel de administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_braintree_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions, escolha o tipo Payments, encontre VibeFox Braintree Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão de lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja a seção Chave de licença).

4. Copie o Merchant ID, a Public Key e a Private Key do Braintree Control Panel para os campos de sandbox ou de produção.

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 do sandbox da Braintree, como 4111 1111 1111 1111. Depois, informe as credenciais de produção e desative Sandbox mode para receber pagamentos reais.

OpenCart 4

1. No painel de administração, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_braintree_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Braintree Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as credenciais da Braintree e teste o pagamento como nas etapas 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Uma instalação nova começa com o método de pagamento desativado e o modo sandbox ativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Quando o método de pagamento está ativado, mas falta o Merchant ID, a Public Key ou a Private Key do ambiente selecionado, 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. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter de 1 a 128 caracteres, Sort Order deve ser um número inteiro e Total um número igual ou maior que 0. Se algum campo tiver erro, nada é salvo e a página indica o campo.

Braintree

Enable/Disable: liga ou desliga os pagamentos com cartão Braintree. O método de pagamento fica oculto na finalização de compra até que o Merchant ID, a Public Key e a Private Key do ambiente selecionado estejam preenchidos. Padrão: desligado.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. É também o nome do método de pagamento salvo no pedido. Padrão: Credit / debit card. Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do formulário do cartão. Padrão: Pay securely with your credit or debit card via Braintree.

Sort Order: a posição da Braintree entre os métodos de pagamento na finalização de compra. Deixe vazio ou informe um número inteiro.

Geo Zone: ofereça a Braintree somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido deve atingir para que a Braintree seja oferecida. Deixe vazio para oferecer a Braintree para qualquer total.

Credenciais da API

Entre no Braintree Control Panel (sandbox ou produção, vinculados nesta seçã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 é exibido 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: ativado. Desative 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. Enquanto estiver ativado, os clientes veem SANDBOX / TEST MODE — no real money is charged. na etapa Confirm Order.

Sandbox Merchant ID e Live Merchant ID: o Merchant ID da conta de sandbox 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, salva exatamente como foi informada. As chaves privadas salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

Sandbox merchant account ID(s) e Live merchant account ID(s): opcional. A Braintree cobra na moeda da conta de comerciante. Deixe vazio para usar a sua conta de comerciante padrão, informe um ID (por exemplo, mystore_EUR) ou um ID 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: a forma 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 (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, e não apenas no navegador, antes de o cartão ser cobrado.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele recebe um status somente depois que a Braintree aceita o pagamento com cartão. Um cartão recusado deixa o pedido sem status, e o cliente permanece na etapa de confirmação. Cada campo abaixo lista os status de pedido do seu OpenCart.

Order Status After Payment: uma venda foi capturada, ou uma autorização foi capturada na aba do pedido. Padrão: Processando.

Authorized Status: somente autorização: o valor fica reservado, ainda não pago. Padrão: Pendente, porque o OpenCart não tem o status Em espera; a nota do pedido e a aba do pedido explicam isso. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

On Hold (Review) Status: a Braintree retornou um status de transação inesperado, ou o valor ou a moeda cobrados não coincidiam e a anulação automática falhou. Uma nota explica o que verificar. Padrão: Pendente.

Voided Status: a autorização foi anulada na aba do pedido e o valor retido é liberado. Padrão: Cancelado.

Refunded Status: o pagamento foi totalmente reembolsado, ou anulado como reembolso total antes da liquidação. Reembolsos parciais apenas adicionam uma nota. Padrão: Reembolsado.

Avançado

Debug log: também registra as chamadas à API e as etapas do pagamento em wc_btg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros são sempre registrados, mesmo com esta opção desligada. O log nunca contém chaves de API nem dados de cartão ou do cliente. Padrão: desligado.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. As transações e os reembolsos da Braintree são sempre mantidos, portanto pedidos pagos antes ainda podem ser reembolsados, capturados ou anulados após uma reinstalação. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves privadas não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves privadas salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Credit / debit card). Na etapa Confirm Order, o cliente vê a sua descrição e o formulário de cartão da Braintree, carregado pela Braintree no idioma da loja. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, o formulário verifica o cartão e, com o 3-D Secure ativado, o cliente conclui a verificação do banco; o total do pedido, o e-mail e o endereço de cobrança são passados ao formulário. Somente um token de uso único chega à sua loja. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options. O formulário do cartão então aparece no bloco de confirmação, na parte inferior da página de finalização de compra, acima do botão Confirm Order. Se a loja não pedir um endereço de pagamento (padrão do OpenCart 4), a verificação 3-D Secure usa o endereço de entrega.

Em seguida, a extensão cobra o token pela API da Braintree pelo total do pedido na moeda do pedido, usando o número do pedido do OpenCart como ID do pedido na Braintree. O valor e a moeda cobrados são conferidos com o pedido. O pedido recebe o seu status somente quando a Braintree aceita o pagamento, da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização de estoque. O carrinho é esvaziado e o cliente vê a página de sucesso do pedido do OpenCart.

Se o pagamento falhar, o pedido fica sem status, uma nota com o motivo é adicionada ao pedido e o cliente permanece na etapa Confirm Order 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 informar o cartão novamente e tentar de imediato. Se a moeda ou o valor cobrado não corresponderem ao 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. Uma nova confirmação de um pedido pago leva diretamente à página de sucesso; para um pagamento autorizado, mostra A payment for this order has already been received and is awaiting review. Se o cartão foi cobrado, mas o OpenCart não conseguiu definir o status do pedido, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. A tentativa seguinte com o mesmo carrinho define o status desse pedido a partir da transação salva, sem cobrar de novo. O OpenCart 3 cria um novo pedido toda vez que a etapa Confirm Order é exibida, então um mesmo carrinho pode ter vários pedidos (no OpenCart 4, o pedido da finalização de compra é um só e é atualizado, então depois de um cartão recusado o cliente paga o mesmo pedido):assim que um deles for pago, outro pedido do mesmo carrinho não é cobrado, e o cliente vê This cart has already been paid with order #…. Please check your order history — do not pay again.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado pela loja nesse meio-tempo (por exemplo, cancelado, anulado ou reembolsado), ou se já estiver pago e o carrinho tiver mudado desde então (outros produtos ou quantidades), clicar em Confirm Order envia o cliente de volta à finalização de compra, o que cria um novo pedido do carrinho com o seu próprio pagamento. O mesmo carrinho enviado duas vezes ainda leva à página de sucesso, sem uma segunda cobrança.

A extensão aceita somente 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 há webhooks da Braintree.

Pedidos e reembolsos

Status dos pedidos

Sem status (pedido ausente): o pagamento não foi feito ou foi recusado. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processing): o cartão foi cobrado (Sale), ou uma autorização foi capturada. Uma nota mostra o valor, o ID da transação da Braintree e o resultado do 3-D Secure.

Authorized Status (padrão Pending): os valores estão apenas autorizados (Authorize only). Uma nota pede que você capture o pagamento na página do pedido antes do envio.

On Hold (Review) Status (padrão Pending): a Braintree retornou um status de transação inesperado, ou uma cobrança com moeda ou valor errados não pôde ser anulada automaticamente. A nota explica o que verificar no Braintree Control Panel.

Voided Status (padrão Canceled): uma autorização foi anulada.

Refunded Status (padrão Refunded): o pagamento foi totalmente reembolsado pela extensão.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Braintree Gateway

Em Sales > Orders, abra um pedido pago com a Braintree. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Braintree Gateway mostra o Transaction ID (vinculado à transação no Braintree Control Panel do seu ambiente), com o rótulo Sandbox em pagamentos de sandbox, o Status da transação, o Amount e a conta de comerciante, o resultado do 3-D Secure, os valores Charged / refunded, os botões de captura, anulação e reembolso, o histórico de reembolsos e as Braintree notes do pedido. A aba é mostrada aos usuários que têm acesso à extensão; os botões exigem o direito de modificá-la (definido em System > Users > User Groups).

Captura e anulação

Para um pagamento autorizado, clique em Capture Braintree payment para cobrar o total do pedido, ou em Void Braintree authorization para liberar o valor retido e cancelar o pedido. A captura define o pedido como Order Status After Payment; a anulação o define como Voided Status. Se a ação falhar, o erro é mostrado na aba e adicionado às notas do pedido.

Reembolsos

Na aba VibeFox Braintree Gateway, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Braintree. Confirme a pergunta Reembolsar este valor pela Braintree? Isso não pode ser desfeito. Reembolsos totais e parciais são suportados, tanto para um pagamento capturado quanto para um pagamento em análise. Os reembolsos são feitos no valor e na moeda cobrados pela Braintree. A Braintree só reembolsa transações liquidadas, normalmente em até 24 horas. Antes da liquidação, um reembolso total é feito como anulação; um reembolso parcial nesse caso falha com uma mensagem para aguardar a liquidação. O reembolso é enviado ao ambiente (sandbox ou produção) do pagamento, por isso as credenciais desse ambiente precisam estar definidas. Se a Braintree não aceitar o reembolso, a aba 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 Status; um reembolso parcial não altera o status. Mudanças de status feitas pela aba não notificam o cliente nem devolvem produtos ao estoque, como uma mudança manual de status.

Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Braintree. Contestações (chargebacks), recusas na liquidação e reembolsos feitos no Braintree Control Panel não são sincronizados com o OpenCart.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Braintree Gateway é o primeiro bloco de Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit, 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: opencart-payment-braintree e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify sobre a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel de administração (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 de alterar o endereço da loja ou de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a vaga de 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. Um usuário administrador conectado ao painel de administração no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa pré-visualização não está disponível: a loja não vê o login do administrador, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel de administração. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, e capturas, anulações e reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente automaticamente quando você abre o Dashboard do painel de administração ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário cron job. Desinstalar a extensão 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. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O cartão foi cobrado, mas o pedido continua sem status: os pagamentos com cartão são confirmados imediatamente, sem webhook. Veja as notas do pedido e o campo Log na página da extensão. Se uma nota disser que a resposta da Braintree foi perdida, procure no Braintree Control Panel uma transação com este número de pedido antes de aceitar outro pagamento. Se o status não puder ser definido após a cobrança, a próxima tentativa de pagamento com o mesmo carrinho o define sem cobrar novamente.

O formulário do cartão mostra Could not initialize payment form: as chaves do ambiente selecionado estão erradas, 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 cliente vê Your session has expired. Please refresh the page and try again.: a sessão da finalização de compra mudou enquanto o formulário estava aberto. O cliente deve recarregar a página de finalização de compra.

O 3-D Secure falha em todos os pagamentos: o 3-D Secure precisa estar ativado para a sua conta de comerciante 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).

Ao cliente é informado que o pagamento não pôde ser processado na moeda do pedido: a Braintree cobrou na moeda da conta de comerciante. Informe o ID da conta de comerciante da moeda do pedido no campo de conta de comerciante do ambiente atual.

O cliente vê The order total must be greater than zero to pay by card.: o total do pedido é 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.

Não há botões na aba, ou aparece uma mensagem sobre o ambiente: o seu grupo de usuários não tem o direito de modificar a extensão, ou o pagamento foi feito no ambiente sandbox ou de produção e as credenciais desse ambiente não estão definidas. Informe-as e tente novamente.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Braintree Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma reinstalação. Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo sandbox, credenciais, contas de comerciante, tipo de transação, 3-D Secure, log de depuração) e o log são removidos. Se estiver desativado, eles são mantidos para uma reinstalação posterior. As transações e os reembolsos da Braintree são sempre mantidos, portanto pedidos pagos antes ainda podem ser reembolsados, capturados ou anulados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Braintree Gateway na lista de extensões instaladas. Depois, clique em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

A Braintree é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada à Braintree nem endossada por ela.