VibeFox Authorize.Net for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões antigas do PHP.
HTTPS: a finalização de compra deve usar HTTPS. O Accept.js não funciona em páginas HTTP comuns.
Conta Authorize.Net: você precisa do API Login ID, da chave de transação e da chave pública do cliente da sua conta Authorize.Net, e de uma chave de assinatura se usar webhooks. 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 do carrinho deve ser USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD ou NZD, e sua conta Authorize.Net precisa liquidar nessa moeda. 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 único 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 encontre depois VibeFox Authorize.Net Gateway na lista de módulos e clique em Configure.
3. Informe 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 as credenciais das contas de sandbox e de produção (veja Configuração). Opcionalmente, configure o webhook.
5. Ative Enable/Disable, escolha o Transaction type e clique em Save. Teste um pagamento no modo sandbox com o cartão 4111 1111 1111 1111, qualquer data de validade futura e qualquer CVV, depois desative Sandbox mode.
Ao ser instalado, o módulo cria dois status de pedido: Authorize.Net payment authorized e Authorize.Net 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 ficam na página do módulo: Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando o SSL não está ativado para a loja (o Accept.js funciona apenas em páginas HTTPS), quando a moeda padrão da loja não é suportada pela Authorize.Net, quando o modo atual não tem API Login ID, Transaction Key ou Public Client Key (nesse caso o método de pagamento fica oculto na finalização de compra) e quando o modo atual não tem Signature Key (nesse caso os webhooks ficam desativados). Enquanto o modo sandbox estiver ativo, a página mostra Sandbox mode is on: test transactions, no real charges.
Authorize.Net
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 os clientes veem na finalização de compra. É também o nome do método de pagamento salvo no pedido. Padrão: Credit 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 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 Transaction Key e uma Signature Key. Em Manage Public Client Key, copie a Public Client Key. Sandbox e produção usam credenciais diferentes. A página mostra os campos dos dois modos, então você pode manter os dois conjuntos.
Sandbox mode: usa o sandbox da Authorize.Net (transações de teste, sem cobranças reais). Ele troca o endpoint da API, o Accept.js e o conjunto de credenciais usado nos novos pagamentos. Padrão: ativado. Desative para receber pagamentos reais. Enquanto estiver ativo, os clientes veem uma dica com o cartão de teste 4111 1111 1111 1111 abaixo do método de pagamento.
Sandbox API Login ID e Live API Login ID: o API Login ID da conta de sandbox ou de produção.
Sandbox Transaction Key e Live Transaction Key: a chave de transação dessa conta.
Sandbox Public Client Key e Live Public Client Key: a chave pública que o Accept.js usa no navegador.
Sandbox Signature Key e Live Signature Key: necessárias apenas para webhooks. Ela verifica o cabeçalho X-ANET-Signature de cada notificação.
As chaves de transação e de assinatura salvas nunca são mostradas de novo. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um valor novo somente para alterá-lo.
Clear saved secrets: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
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, vá em Account > Settings > Business Settings > Webhooks e clique em Add Endpoint, tanto na conta de sandbox quanto na de produção. Use a URL mostrada em Endpoint URL nesta seção. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_authorizenet_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram. Selecione estes eventos (eles também estão listados nesta seção):
Informe a Signature Key de cada conta em Sandbox Signature Key ou Live Signature Key. Webhooks sem uma assinatura válida são rejeitados. Uma notificação deve ser assinada com a chave do modo em que o pagamento foi feito; uma notificação do outro modo não altera nada. Para cada notificação, o módulo também consulta a Authorize.Net o status e o valor atuais da transação antes de alterar o pedido, então notificações repetidas não mudam nada.
Avançado
Debug log: grava as requisições e respostas da API em logs/wc_ang_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves, tokens de cartão e dados pessoais são mascarados. Padrão: desativado. Erros, como pagamentos recusados ou falhos, erros da API e reembolsos falhos, são sempre registrados, mesmo quando essa opção está desativada.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações e o log. As transações e os reembolsos da Authorize.Net e os status de pedido do módulo são sempre mantidos, então pedidos pagos antes ainda podem ser capturados e reembolsados após uma reinstalação. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, 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/YY) e o código de segurança (CVV) no formulário abaixo dele. O Accept.js é carregado somente na página de finalização de compra. Quando o cliente faz 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 módulo cobra o token pela API da Authorize.Net, pelo total do carrinho na moeda do carrinho. O endereço de cobrança, o e-mail e o endereço IP são enviados com a transação para verificação de endereço e filtros antifraude. O número do carrinho é enviado como número da fatura, porque nenhum pedido existe antes do pagamento. O pedido só é marcado como pago depois que a Authorize.Net confirma: se a transação for aprovada, o pedido é criado na hora e o cliente vê a página padrão de confirmação do pedido com Your card payment has been received. Com Authorize only, a página mostra Your card payment has been authorized. The amount will be charged when your order is processed. Se o Fraud Detection Suite retiver a transação, a página mostra Your payment is being reviewed. We will update your order as soon as the review is complete.
Se o cartão for recusado, o cliente permanece na etapa de pagamento e vê Payment failed: seguido do motivo, por exemplo cartão recusado, código de segurança incorreto ou cartão vencido. Nenhum pedido é criado e o carrinho é mantido. Erros de configuração e da API não são mostrados aos clientes: eles veem uma mensagem genérica, e os detalhes vão 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. Se os campos do cartão estiverem vazios, o formulário pede Please enter the card number, expiry date and card code.
Um clique duplo, uma segunda aba ou um envio repetido nunca cobram um carrinho duas vezes. Uma segunda tentativa enquanto a primeira ainda está em andamento mostra Your payment is already being processed. Please wait a moment and check your order history before trying again. Se um pagamento foi aprovado, mas o pedido não pôde ser criado, o cliente vê Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. O pedido é então criado a partir do pagamento aprovado na próxima tentativa ou pelo webhook, sem cobrar o cartão novamente.
Se o carrinho mudar enquanto o pagamento está em andamento, o valor cobrado não corresponde mais ao carrinho. Então o pedido vai para Authorize.Net payment on hold com uma nota, e o pagamento é registrado pelo valor realmente cobrado.
O webhook funciona mesmo quando 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 cartões salvos nem perfis de cliente, assinaturas ou pagamentos recorrentes, eCheck/ACH, Apple Pay, Google Pay, PayPal ou 3-D Secure, captura parcial de uma autorização nem conversão automática de moeda.
Pedidos e reembolsos
Status do pedido
No order: o cartão foi recusado ou o pagamento falhou. Existe apenas o carrinho.
Payment accepted: o cartão foi cobrado (Authorize and capture), ou uma autorização foi capturada. O pagamento é registrado com o Trans ID da Authorize.Net como ID da transação, e uma nota mostra o valor, o Trans ID, o código de autorização, o tipo de cartão e os últimos quatro dígitos.
Authorize.Net payment authorized: os valores estão apenas autorizados (Authorize only). Capture-os antes do envio.
Authorize.Net payment on hold: o Fraud Detection Suite reteve a transação para revisão, o valor cobrado não corresponde ao total do pedido, ou uma captura informada pelo webhook não corresponde ao valor do pedido. A nota explica o motivo. Aprove ou recuse uma transação retida no painel da Authorize.Net; com webhooks, o pedido é atualizado automaticamente.
Canceled: um webhook informou que a transação foi recusada, anulada ou expirou antes de o pedido ser pago, ou você anulou uma autorização que não foi capturada. Se a transação de um pedido pago for anulada no painel da Authorize.Net, o status dele não muda e é acrescentada uma nota de aviso.
Refunded: o pagamento foi totalmente reembolsado ou anulado pelo módulo.
Se uma segunda transação for aprovada para um carrinho que já tem pedido, o pedido não muda. Uma nota pede que você verifique e anule ou reembolse a duplicata no painel da Authorize.Net.
Bloco de pagamento da Authorize.Net
A página do pedido mostra um bloco Authorize.Net payment com o Trans ID, o tipo de transação, o status da transação, o cartão e o código de autorização, o valor cobrado, o total do pedido e o valor reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as Authorize.Net notes do pedido. Captura e reembolsos precisam apenas da permissão para editar pedidos, não do acesso às páginas de módulos.
Captura
Para um pedido em Authorize.Net payment authorized, clique em Capture payment no bloco e confirme Capture the authorized amount through Authorize.Net? O valor autorizado é capturado, o pagamento é registrado com o Trans ID e o pedido passa para Payment accepted. Se a captura falhar, o erro é exibido e adicionado às notas. Você também pode capturar no painel da Authorize.Net; com webhooks, o pedido é atualizado automaticamente.
Reembolsos
No bloco, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, clique em Refund via Authorize.Net e confirme Refund this amount through Authorize.Net? This cannot be undone. Um reembolso do valor total primeiro anula a transação, se ela ainda não tiver sido liquidada, ou uma autorização não capturada. Transações liquidadas, normalmente após 24 horas, podem ser reembolsadas total ou parcialmente. Antes da liquidação, não é possível um reembolso parcial: reembolse o valor total para anular a transação, ou tente novamente após a liquidação. Os reembolsos são feitos no valor e na moeda que a Authorize.Net cobrou; assim, depois de uma divergência de valor, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. Se a Authorize.Net não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso ou uma anulação bem-sucedidos são adicionados ao histórico de reembolsos e às notas. Um reembolso total muda o pedido para Refunded (Canceled quando apenas uma autorização foi anulada). Um reembolso parcial não altera o status. Enquanto uma transação estiver retida para revisão, os reembolsos não são oferecidos.
As capturas, os reembolsos e as verificações de webhook de um pedido usam as credenciais do modo em que o pedido foi pago, então pedidos do outro modo ainda podem ser capturados e reembolsados depois que você alternar Sandbox mode. Mantenha as credenciais desse modo nos respectivos campos até que esses pedidos estejam concluídos.
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 Authorize.Net. Reembolsos feitos no painel da Authorize.Net não são informados à loja: atualize o pedido manualmente.
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 Authorize.Net Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Authorize.Net 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 estão a linha Product: presta-payment-authorizenet e o link Manage licenses and domains in your account, que abre sua conta em 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 com uma data. Depois que o endereço da loja mudar, ou depois 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, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, também em configurações com várias lojas. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave de licença ativa, o pagamento com cartão da Authorize.Net não é exibido 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 loja 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 as capturas 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. Não é necessária nenhuma tarefa cron. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status de licença.
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, Transaction Key e Public Client Key. A página de configurações mostra um aviso quando alguma está faltando. Verifique se a moeda do carrinho é suportada e, em Payment > Preferences, se o módulo está liberado para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas o pedido continua em Authorize.Net payment on hold ou authorized: o tipo de transação é Authorize only (capture-a no bloco 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 o endpoint existe na conta do modo que você usa, se a URL é exatamente a mostrada em Endpoint URL, se os quatro eventos estão selecionados e se a Signature Key dessa conta foi informada.
Webhook answers webhooks are not configured: nenhuma Signature Key foi informada para nenhum dos dois modos.
Webhook answers invalid signature: a Signature Key pertence a outra conta, ou uma chave foi alterada na Authorize.Net. Crie ou copie a Signature Key novamente e cole-a no campo do seu modo.
Webhook answers mode mismatch: a notificação foi assinada com a chave de um modo, mas o pagamento foi feito no outro modo. Verifique se as Signature Keys de sandbox e live não foram trocadas.
Webhook answers verification failed, retry later: a loja não conseguiu ler a transação pela API da Authorize.Net, ou as credenciais do modo do pagamento estão ausentes. A Authorize.Net tenta a entrega novamente.
Webhook answers busy, retry later: o pedido estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado. A Authorize.Net tenta a entrega novamente. Veja o campo Log para o motivo.
A URL do webhook mostra method not allowed no navegador: isso é normal. A URL aceita apenas requisições da Authorize.Net.
O formulário do cartão mostra The secure card form (Accept.js) could not be loaded: a finalização de compra deve usar HTTPS, e a Public Client Key e o API Login ID do modo atual devem estar corretos.
Payment error: the card could not be tokenized: o Accept.js não retornou um token. O cliente deve informar novamente os dados do cartão e tentar de novo.
O cliente vê um erro genérico: veja o campo Log na página do módulo; os erros são sempre gravados ali. 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 para anular a transação, ou tente novamente após a liquidação, normalmente em até 24 horas.
Reembolso ou captura falha com uma mensagem sobre o modo: o pagamento foi feito no modo sandbox ou de produção, e o API Login ID e a Transaction Key desse modo não estão configurados. Informe-os e tente novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Authorize.Net Gateway e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações 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 Authorize.Net e os status de pedido Authorize.Net payment authorized e Authorize.Net payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser capturados e reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Authorize.Net é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Authorize.Net.