VibeFox Adyen for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Conta Adyen: você precisa do nome da sua conta de comerciante Adyen, de uma chave de API e de uma chave HMAC para cada ambiente que usar (teste e produção) e, para pagamentos em produção, do prefixo de URL de produção. A chave de API pertence a uma credencial de API com as funções Checkout webservice e Merchant PAL webservice. A chave HMAC é gerada para o webhook Standard (veja Configuração). A Área do Cliente de teste é ca-test.adyen.com, a de produção é ca-live.adyen.com. As chaves de teste e de produção são separadas. Não é necessária chave de cliente, porque a página de pagamento é hospedada pela Adyen.
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 Adyen 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 de configuração do módulo, e clique em Activate (veja Chave de licença).
4. Informe sua conta de comerciante, a chave de API de teste e a chave HMAC de teste e, depois, a chave de API de produção, a chave HMAC de produção e o prefixo de URL de produção.
5. Na Área do Cliente da Adyen (teste e produção), adicione um webhook Standard com a URL exibida na seção Webhook do módulo (veja Configuração).
6. Ative Enable/Disable e clique em Save. Teste um pagamento com Test mode ativado e depois desative-o.
Ao instalar, o módulo cria o status de pedido Adyen payment on hold. O PrestaShop oferece um novo módulo de pagamento para as moedas, países e grupos de clientes ativos naquele momento. Verifique e altere-os em Payment > Preferences; os países que você adicionar depois precisam ser marcados ali.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Adyen Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Enquanto as configurações do modo atual estiverem incompletas, a página mostra Adyen is hidden at checkout until the test settings are complete (ou as configurações de produção) e lista o que falta: Merchant account, a chave de API, a chave HMAC e, no modo de produção, Live URL prefix. Enquanto o modo de teste estiver ativado, a página mostra Test mode is on: payment links and refunds go to the Adyen test environment, no real money. Ao salvar, uma chave HMAC que não seja hexadecimal e um prefixo de URL de produção com caracteres diferentes de letras, dígitos e hífens não são salvos: um aviso indica o campo e o valor anterior é mantido.
Adyen
Enable/Disable: Enable Adyen payment gateway 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. Também é o nome do método de pagamento salvo no pedido. Padrão: Adyen. Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Adyen.
Conta Adyen
As chaves de API são criadas na Área do Cliente da Adyen, em Developers > API credentials. Preencha os dois conjuntos de chaves; a chave Test mode define qual deles é usado.
Test mode: usa o ambiente de teste da Adyen (sem dinheiro real). Quando ativado, os links de pagamento e os reembolsos vão para checkout-test.adyen.com com a chave de API de teste. Padrão: ativado. Desative para receber pagamentos reais. Enquanto estiver ativado, os clientes veem Test mode: no real payment is taken. abaixo do método de pagamento.
Merchant account: o nome da sua conta de comerciante Adyen (não a conta da empresa), por exemplo MyShopECOM. Normalmente é o mesmo na Área do Cliente de teste e na de produção.
Credenciais de teste
Usadas enquanto Test mode estiver ativado.
Test API key: da Área do Cliente de teste: Developers > API credentials > sua credencial > API key.
Test HMAC key: da Área do Cliente de teste: Developers > Webhooks > seu webhook Standard > HMAC key (hexadecimal). Obrigatória: webhooks sem assinatura válida são rejeitados.
Credenciais de produção
Usadas quando Test mode estiver desativado.
Live API key: da Área do Cliente de produção: Developers > API credentials > sua credencial > API key.
Live HMAC key: da Área do Cliente de produção: Developers > Webhooks > seu webhook Standard > HMAC key (hexadecimal).
Live URL prefix: da Área do Cliente de produção: Developers > API URLs, por exemplo 1797a841fbb37ca7-AdyenDemo a partir de https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Você pode colar a URL inteira; o prefixo é extraído dela ao salvar.
As chaves de API e HMAC salvas nunca são exibidas novamente. O campo fica vazio e a dica termina com Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.
Clear saved secrets: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Webhook
Os pedidos são criados somente pelos webhooks da Adyen. Na Área do Cliente (teste e produção), acesse Developers > Webhooks e adicione um Standard webhook com a URL exibida em Webhook URL nesta seção. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_adyen_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram, porque a Adyen não segue redirecionamentos. Escolha o método JSON, ative Generate HMAC key e copie a chave para Test HMAC key ou Live HMAC key.
O ambiente de cada notificação seleciona a chave HMAC, e uma notificação só é aplicada a um link de pagamento criado no mesmo ambiente e com a mesma conta de comerciante. Uma notificação de teste nunca confirma um pagamento real. Webhooks sem assinatura válida são rejeitados com HTTP 401, e a Adyen os reenvia depois. Sem o webhook, nenhum pedido é criado.
O módulo trata estes eventos:
Os demais eventos são adicionados às notas do pedido. Notificações que não são de um carrinho desta loja, por exemplo o botão de teste na Área do Cliente, são aceitas e ignoradas. O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
Avançado
Order status after payment: o status do pedido definido por um webhook AUTHORISATION bem-sucedido.
Divergências de valor ou moeda e capturas com falha sempre vão para Adyen payment on hold.
Debug log: grava chamadas de API e eventos de webhook em logs/adyg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros são sempre registrados, mesmo com a chave desligada. Os logs nunca contêm chaves de API ou HMAC nem dados pessoais dos clientes. Padrão: desativado.
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 módulo, os registros de pagamentos da Adyen (referências PSP, eventos de webhook, reembolsos) e os logs. O status de pedido Adyen payment on hold e os pedidos são mantidos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Adyen) e vê a nota You will be redirected to Adyen to complete the payment securely. Após confirmar, o módulo cria um link de pagamento da Adyen para o total do carrinho na moeda do carrinho e envia o cliente à página de pagamento da Adyen. Lá ele paga com qualquer método ativado na sua conta Adyen. O e-mail, o nome e o país de cobrança do cliente e o idioma da loja são passados à Adyen, e o pagamento aparece como Cart # com o número do carrinho. Nesse ponto, ainda não existe pedido.
Depois de pagar, o cliente volta à sua loja. O retorno não cria nem paga nenhum pedido: o pedido só é marcado como pago depois que a Adyen confirma com o webhook AUTHORISATION assinado e o valor e a moeda correspondem ao carrinho. Se o webhook já tiver chegado, o cliente vê a página padrão de confirmação do pedido com Your payment with Adyen has been received. (ou Your payment with Adyen has been received and is being reviewed by the store. para um pedido em espera). Se a Adyen cancelou o pagamento antes disso, a página mostra Your Adyen payment was not completed. Please contact us about this order. Se o webhook ainda não chegou, uma página de Payment confirmation mostra Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. com os botões Check again e Back to checkout, para um cliente que não concluiu o pagamento.
Se o pagamento for recusado, nenhum pedido é criado e o cliente pode tentar de novo. Quando o cliente inicia um novo pagamento para o mesmo carrinho, o link de pagamento anterior expira, então não pode mais ser pago. Se o carrinho já tiver um pedido, o cliente vai à confirmação desse pedido em vez de um novo pagamento.
Se o link de pagamento não puder ser criado, o cliente permanece na finalização de compra com Payment could not be initiated. Please try again or choose another payment method. O motivo é gravado no log. Se as configurações estiverem incompletas, a mensagem é Payment gateway is not configured properly. Please contact the store administrator.
Os desenvolvedores podem alterar a requisição do link de pagamento com o hook actionAdygPaymentLinkRequest.
O módulo não tem assinaturas nem pagamentos recorrentes, não salva cartões, não tem campos de cartão no site (Drop-in ou Components), não tem botões de captura ou cancelamento no PrestaShop e não usa autenticação básica para webhooks.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Adyen e não pagou, o pagamento foi recusado ou a Adyen ainda não confirmou o pagamento. Só existe o carrinho.
Payment accepted, Delivered or Adyen payment on hold: o pagamento foi autorizado. O status segue Order status after payment. O pagamento é registrado com a referência PSP da Adyen como ID da transação, e uma nota mostra o valor, a referência PSP e o método de pagamento.
Adyen payment on hold after payment: a Adyen confirmou um valor ou uma moeda diferente do total do carrinho (por exemplo, o carrinho foi alterado depois de iniciado o pagamento), uma captura falhou ou o pagamento chegou depois que o pedido foi cancelado. A nota explica. Verifique o pagamento na Área do Cliente e, então, atenda o pedido ou reembolse o pagamento.
Canceled: o pagamento deste pedido foi cancelado na Adyen.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se chegar um segundo pagamento bem-sucedido para um pedido já pago, por exemplo a partir de um link de pagamento antigo, o pedido não é alterado. Uma nota pede que você verifique na Área do Cliente se há uma cobrança duplicada e, se necessário, a reembolse por lá.
Bloco de pagamento Adyen
A página do pedido mostra um bloco Adyen payment com a referência PSP, o link de pagamento, a conta de comerciante e o ambiente, o status do pagamento, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Adyen notes: as notas que o módulo adiciona ao pedido (pagamento autorizado, divergência de valor, pagamento duplicado, captura, cancelamento, resultados de reembolsos), das mais recentes para as mais antigas. Essas notas são mensagens privadas do pedido; o PrestaShop 8.2 e 9 não as exibem em outro lugar da página do pedido.
Reembolsos
No bloco Adyen payment, informe o valor (é preenchido o valor ainda não reembolsado), opcionalmente um motivo, e clique em Refund via Adyen. Confirme a pergunta Refund this amount through Adyen? This cannot be undone. Reembolsos totais e parciais são aceitos. Você precisa da permissão para editar pedidos. Os reembolsos são feitos no valor e na moeda que a Adyen autorizou; assim, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado ao ambiente e à conta de comerciante em que o pagamento foi feito, então a chave de API desse ambiente precisa estar configurada. Se a Adyen não aceitar a solicitação, o bloco mostra o erro e nenhum reembolso é registrado.
A Adyen processa os reembolsos de forma assíncrona: a solicitação é adicionada ao histórico de reembolsos e às notas com o status received, e o resultado final chega pelo webhook REFUND ou REFUND_FAILED. Um reembolso que falhou deixa de contar como reembolsado. Quando os reembolsos enviados atingem o valor pago, o pedido passa para Refunded. Um reembolso parcial não altera o status. Com captura manual na Adyen, apenas pagamentos capturados podem ser reembolsados.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Adyen. Reembolsos feitos na Área do Cliente da Adyen chegam por webhook e são adicionados às notas. O status do pedido e as notas de crédito não são alterados automaticamente.
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 Adyen Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Adyen 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-adyen e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente 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, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Adyen 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 pode 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 os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 e 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 Adyen não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se as configurações do modo atual estão completas: Merchant account, a chave de API e a chave HMAC desse modo e, no modo de produção, Live URL prefix. A página de configurações lista o que falta. Em Payment > Preferences, confirme que o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: o webhook não está funcionando. Na Área do Cliente do ambiente que você usa (teste ou produção), verifique se o webhook Standard existe, se a URL dele é exatamente a exibida em Webhook URL e se o método é JSON. Confirme que a chave HMAC desse webhook está no campo correspondente (Test HMAC key ou Live HMAC key). Com uma chave HMAC inválida ou ausente, o módulo responde HTTP 401 e a Adyen reenvia a entrega depois, então o pedido é criado automaticamente assim que a chave for corrigida. O log mostra Webhook rejected: invalid HMAC signature ou que a chave HMAC não está configurada.
O webhook responde [rejected] HMAC key not configured: a chave HMAC do ambiente da notificação está vazia. Cole-a nas configurações.
O webhook responde [rejected] busy, retry later: o carrinho estava sendo processado por outra entrega no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Adyen reenvia o webhook automaticamente. O motivo está no log.
A URL do webhook mostra [rejected] POST required in the browser: isso é normal. A URL aceita apenas notificações da Adyen.
O aviso sobre a chave HMAC ao salvar: o campo precisa conter a chave HMAC hexadecimal da Área do Cliente. O valor anterior foi mantido.
O cliente vê Payment could not be initiated: veja o campo Log na página do módulo (erros são sempre registrados). Verifique a chave de API, a conta de comerciante e, no modo de produção, o prefixo de URL de produção.
O pedido está em Adyen payment on hold após o pagamento: leia a nota no pedido. O valor ou a moeda confirmados pela Adyen não correspondiam ao carrinho, uma captura falhou ou o pagamento chegou após um cancelamento. Também pode ser a configuração Order status after payment.
O reembolso falha: o pedido precisa ter uma referência PSP da Adyen, que chega com o webhook AUTHORISATION. As credenciais do ambiente em que o pagamento foi feito precisam estar definidas; caso contrário, o bloco informa que as credenciais não estão configuradas. Com captura manual, apenas pagamentos capturados podem ser reembolsados.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Adyen 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 módulo, os registros de pagamentos da Adyen (referências PSP, eventos de webhook, reembolsos) e os logs são removidos. Se estiver desativado, todos eles são mantidos para uma reinstalação posterior, para que pedidos pagos antes ainda possam ser reembolsados. O status de pedido Adyen payment on hold sempre permanece. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Adyen é uma marca comercial de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Adyen.