VibeFox Authorize.Net for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin mostra um aviso na área administrativa e o método de pagamento não é carregado.
PHP: 8.0 ou superior.
HTTPS: a sua finalização de compra precisa usar HTTPS. O Accept.js não funciona em HTTP simples.
Conta Authorize.Net: você precisa do API Login ID, da chave de transação (Transaction Key) e da chave pública do cliente (Public Client Key) da sua conta Authorize.Net, e de uma chave de assinatura (Signature Key) se usar webhooks. As contas de produção (account.authorize.net) e de sandbox (sandbox.authorize.net) têm credenciais diferentes. As contas Authorize.Net estão disponíveis para comerciantes dos Estados Unidos, Canadá, Reino Unido, Europa, Austrália e Nova Zelândia.
Moeda: a moeda da loja precisa ser USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD ou NZD, e a sua conta Authorize.Net precisa liquidar nela. Para outras moedas, o método de pagamento fica oculto na finalização de compra.
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_authorizenet_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Authorize.Net > 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 as credenciais das contas de sandbox e de produção (veja Configuração). Opcionalmente, configure o webhook.
6. Ative Enable/Disable, escolha o Transaction type e salve. Teste um pagamento no modo sandbox com o cartão 4111 1111 1111 1111, qualquer data de validade futura e qualquer CVV, e depois desmarque Sandbox mode.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Authorize.Net. Acima dos campos, a página avisa quando o site não usa HTTPS (o Accept.js funciona somente em páginas HTTPS) e quando a moeda da loja não é compatível (nesse caso, o método de pagamento fica oculto na finalização de compra). A página mostra apenas os campos de credenciais do modo selecionado.
Geral
Enable/Disable: Enable Authorize.Net 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 Card.
Description: o texto exibido acima do formulário de cartão na finalização de compra. Padrão: Pay securely with your credit card via Authorize.Net.
Credenciais de API
No Merchant Interface da Authorize.Net, abra Account > Settings > Security Settings. Em API Credentials & Keys, copie o API Login ID e crie uma chave de transação e uma chave de assinatura. Em Manage Public Client Key, copie a chave pública do cliente. Sandbox e produção usam credenciais diferentes.
Sandbox mode: Use the Authorize.Net sandbox (test transactions, no real charges). Alterna o endpoint da API, o Accept.js e o conjunto de credenciais abaixo. Padrão: ativado. Desmarque para receber pagamentos reais.
Live API Login ID e Sandbox API Login ID: o API Login ID da conta de produção ou de sandbox.
Live Transaction Key e Sandbox Transaction Key: a chave de transação dessa conta.
Live Public Client Key e Sandbox Public Client Key: a chave pública usada pelo Accept.js no navegador.
Live Signature Key e Sandbox Signature Key: necessárias apenas para webhooks. Ela verifica o cabeçalho X-ANET-Signature de cada notificação.
Pagamento
Transaction type: como o cartão é cobrado. Uma autorização expira após 30 dias.
Webhooks (recomendado)
Sem webhooks, os pedidos retidos pelo Fraud Detection Suite, ou capturados ou anulados no painel da Authorize.Net, precisam ser atualizados manualmente. No Merchant Interface, acesse Account > Settings > Business Settings > Webhooks e clique em Add Endpoint. Use a URL exibida nesta seção das configurações. Ela tem a forma https://your-site/wc-api/wc_authorizenet/. Selecione estes eventos:
Insira a chave de assinatura da conta em Live Signature Key ou Sandbox Signature Key. Webhooks sem assinatura válida são rejeitados. Para cada notificação, o plugin também consulta a Authorize.Net sobre o status e o valor atuais da transação antes de alterar o pedido, então notificações repetidas não alteram nada.
Avançado
Debug log: Log API requests and responses em WooCommerce > Status > Logs, origem wcp_authorizenet_gateway. Chaves, tokens de cartão e dados pessoais são mascarados. Padrão: desativado.
Delete data on uninstall: Remove the settings and the Authorize.Net order meta when the plugin is deleted. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Credit Card) e informa o número do cartão, a data de validade (MM/AA) e o código de segurança (CVV) na página de finalização de compra. No modo sandbox, o formulário mostra uma dica com o cartão de teste 4111 1111 1111 1111. Ao fazer o pedido, o Accept.js troca os dados do cartão por um token de uso único no navegador. Os campos do cartão não têm nomes de formulário, então o número do cartão e o CVV nunca são enviados ao seu servidor.
O plugin cobra o token pela API da Authorize.Net, pelo total do pedido na moeda do pedido. O endereço de faturamento, o e-mail e o endereço IP são enviados com a transação para verificação de endereço e filtros de fraude. Se o pagamento for aprovado, o cliente vai para a página de pedido recebido e o carrinho é esvaziado.
Se o cartão for recusado, o cliente permanece na finalização de compra e vê Payment failed: seguido do motivo, por exemplo cartão recusado, código de segurança incorreto ou cartão vencido. Erros de configuração e de API não são mostrados aos clientes: eles veem uma mensagem geral, e os detalhes vão para a nota do pedido e para o log. Se a loja não conseguir acessar a Authorize.Net, o cliente vê Payment error: unable to connect to the payment gateway. Please try again.
Envios repetidos e pagamentos repetidos do mesmo pedido nunca o cobram uma segunda vez. 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 não salva cartões nem perfis de cliente, não tem WooCommerce Subscriptions ou Pre-Orders, não tem eCheck/ACH, Apple Pay, Google Pay, PayPal ou 3-D Secure, não tem captura parcial de uma autorização e não faz conversão automática de moeda.
Pedidos e reembolsos
Status do pedido
Processing or Completed: o cartão foi cobrado (Authorize and capture), ou uma autorização foi capturada. O WooCommerce define o status Processando ou, para pedidos com apenas produtos digitais para download, Concluído. A nota do pedido mostra o valor, o ID da transação, o código de autorização, a bandeira do cartão e os últimos quatro dígitos. O ID da transação é o Trans ID da Authorize.Net.
On hold: o valor apenas foi autorizado (Authorize only), ou o Fraud Detection Suite reteve a transação para revisão. Aprove ou recuse uma transação retida no painel da Authorize.Net; com webhooks, o pedido é atualizado automaticamente. Um pedido também é colocado em espera quando uma captura informada por webhook não corresponde ao valor do pedido.
Cancelled: um webhook informou que a transação foi recusada, anulada ou expirou antes de o pedido ser pago. Se isso acontecer com um pedido pago, o status não é alterado e uma nota de aviso é adicionada.
Captura
Para um pedido com autorização, abra o pedido, escolha Capture payment (Authorize.Net) nas ações do pedido e clique no botão de atualizar. O valor total do pedido menos os reembolsos é capturado, e o pedido é marcado como pago. Se a captura falhar, o erro é mostrado e adicionado às notas do pedido. Você também pode capturar no painel da Authorize.Net; com webhooks, o pedido é atualizado automaticamente.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit Card (o botão usa o título do seu método de pagamento). Um reembolso do valor total do pedido primeiro anula a transação, se ela ainda não tiver sido liquidada, ou uma autorização que não foi capturada. Transações liquidadas, geralmente após 24 horas, podem ser reembolsadas total ou parcialmente. Antes da liquidação, um reembolso parcial não é possível: reembolse o valor total para anular a transação, ou tente novamente após a liquidação. Se a Authorize.Net 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.
Reembolsos, capturas e verificações por webhook de um pedido usam as credenciais do modo em que o pedido foi pago; assim, pedidos do outro modo ainda podem ser capturados e reembolsados depois que você alternar o Sandbox mode. Mantenha as credenciais desse modo nos seus campos até que esses pedidos sejam concluídos.
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 > Authorize.Net. 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 Authorize.Net 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: os webhooks continuam sendo processados, e as capturas e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente em segundo plano, automaticamente.
Solução de problemas
A Authorize.Net não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem API Login ID, chave de transação e chave pública do cliente. Verifique se a moeda da loja é compatível; a página de configurações mostra um aviso quando não é.
O pagamento foi feito, mas o pedido continua On hold: o tipo de transação é Authorize only (capture o valor com a ação do pedido), ou a Authorize.Net reteve a transação para revisão. Aprove ou recuse no painel da Authorize.Net. Para que esses pedidos sejam atualizados automaticamente, configure o webhook: verifique se a URL do endpoint é exatamente a exibida nas configurações, se os quatro eventos estão selecionados e se a chave de assinatura do modo atual foi inserida.
Webhook answers webhooks are not configured: nenhuma chave de assinatura foi inserida para nenhum dos modos.
Webhook answers invalid signature: a chave de assinatura pertence a outra conta ou modo. Crie ou copie a chave de assinatura novamente e cole-a no campo do seu modo.
Webhook answers verification failed, retry later: a loja não conseguiu ler a transação pela API da Authorize.Net. A Authorize.Net reenvia a entrega.
O formulário de cartão não carrega ou mostra The secure card form (Accept.js) could not be loaded: a finalização de compra precisa usar HTTPS, e a chave pública do cliente e o API Login ID do modo atual precisam estar corretos.
Payment error: the card could not be tokenized: o Accept.js não retornou um token. O cliente deve informar os dados do cartão novamente e tentar de novo.
O cliente vê um erro geral: abra as notas do pedido ou ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_authorizenet_gateway. Uma moeda que a conta não suporta é recusada pela Authorize.Net.
Um reembolso parcial falha porque a transação ainda não foi liquidada: reembolse o valor total do pedido para anular a transação, ou tente novamente após a liquidação, geralmente em até 24 horas.
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, os dados da Authorize.Net armazenados nos pedidos e os logs são removidos somente se Delete data on uninstall estava ativado. Caso contrário, permanecem para uma eventual reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Authorize.Net é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Authorize.Net.