VibeFox Adyen for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin se recusa a ser ativado sem ele.
PHP: 8.0 ou superior.
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 fica em ca-test.adyen.com, e a de produção em ca-live.adyen.com. As chaves de teste e de produção são separadas.
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_adyen_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Adyen > 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 a 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.
6. Na Área do Cliente da Adyen (teste e produção), adicione um webhook Standard com a URL exibida nas configurações do plugin (veja Configuração).
7. Ative Enable/Disable. Faça um pagamento de teste com Test mode ativado e, depois, desmarque-o.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Adyen. 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, em modo de produção, Live URL prefix. Ao salvar, uma chave HMAC que não seja hexadecimal e um prefixo de URL de produção com caracteres diferentes de letras, números e hífens são rejeitados com um erro, e o valor anterior é mantido.
Geral
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. Padrão: Adyen.
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 opção Test mode seleciona qual deles é usado.
Test mode: Use the Adyen test environment (no real money). 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. Desmarque para receber pagamentos reais.
Merchant account: o nome da sua conta de comerciante Adyen (não a conta da empresa), por exemplo MyShopECOM. Geralmente é o mesmo na Área do Cliente de teste e na de produção.
Credenciais de teste
Usadas enquanto o Test mode estiver ativado.
Test API key: na Área do Cliente de teste: Developers > API credentials > sua credencial > API key.
Test HMAC key: na Á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 o Test mode está desativado.
Live API key: na Área do Cliente de produção: Developers > API credentials > sua credencial > API key.
Live HMAC key: na Área do Cliente de produção: Developers > Webhooks > seu webhook Standard > HMAC key (hexadecimal).
Live URL prefix: na Á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.
Webhook
Os pedidos só são marcados como pagos por webhooks da Adyen. Na Área do Cliente (teste e produção), acesse Developers > Webhooks e adicione um Standard webhook com a URL exibida nesta seção das configurações. Ela tem a forma https://your-site/wc-api/adyg_adyen_webhook/. 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 define qual chave HMAC é usada. Webhooks sem assinatura válida são rejeitados, e a Adyen os reenvia depois. Sem o webhook, os pedidos continuam com o status Pagamento pendente.
O plugin trata estes eventos:
Outros eventos são adicionados às notas do pedido. Notificações que não são de um pedido desta loja, por exemplo o botão de teste na Área do Cliente, são aceitas e ignoradas.
Avançado
Order status after payment: o status do pedido definido após um pagamento bem-sucedido, em uma única mudança de status.
Debug log: Log API calls and webhook events em WooCommerce > Status > Logs, origem wcp_adyen_gateway. Erros são sempre registrados. Os logs nunca contêm chaves de API ou HMAC nem dados pessoais do comprador. Padrão: desativado.
Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Adyen) e faz o pedido. O plugin cria um link de pagamento da Adyen para o total do pedido na moeda do pedido e envia o cliente à página de pagamento da Adyen. Ali, o cliente paga com qualquer método ativado na sua conta Adyen. O e-mail de faturamento, o nome e o país do cliente e o idioma da loja são enviados à Adyen, e o pagamento aparece como Order # seguido do número do pedido.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O retorno em si não marca o pedido como pago: o pedido só é marcado como pago depois que a Adyen confirma com o webhook AUTHORISATION assinado e o valor e a moeda coincidem com o pedido.
Se o pagamento for recusado, o pedido passa a Falhou e o cliente pode tentar de novo. Quando o cliente inicia um novo pagamento para o mesmo pedido, por exemplo pela página Pay for order, o link de pagamento anterior é expirado e não pode mais ser pago.
Se o link de pagamento não puder ser criado, o cliente vê Payment could not be initiated. Please try again or choose another payment method. O motivo é adicionado às notas do pedido. Se as configurações estiverem incompletas, o cliente vê Payment gateway is not configured properly. Please contact the store administrator.
Para moedas sem casas decimais, como JPY, KRW, IDR ou VND, defina WooCommerce > Settings > General > Number of decimals como 0. Caso contrário, o total é arredondado para uma unidade inteira.
O método de pagamento funciona na finalização de compra clássica e no bloco de Finalização de compra. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).
O plugin 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 WooCommerce e não usa autenticação básica para webhooks.
Pedidos e reembolsos
Status do pedido
Pending payment: o link de pagamento foi criado e a Adyen ainda não confirmou o pagamento. A nota do pedido mostra o link de pagamento, o valor e o ambiente.
Processing, Completed or On Hold: o pagamento foi autorizado. O status segue a opção Order status after payment. A nota do pedido mostra o valor, a referência PSP e o método de pagamento. O ID da transação é a referência PSP da Adyen.
On hold after payment: a Adyen confirmou um valor ou uma moeda diferente do total do pedido. A nota do pedido mostra os dois, e o pedido não é marcado como pago. Um pedido pago também é colocado em espera quando uma captura falha, porque o dinheiro não foi recebido. Verifique o pagamento na Área do Cliente.
Failed: o pagamento foi recusado. Pedidos pagos, em espera e cancelados não são alterados por um pagamento recusado.
Cancelled: o pagamento deste pedido foi cancelado na Adyen.
Se chegar um segundo pagamento bem-sucedido para um pedido que já está pago, por exemplo a partir de um link de pagamento antigo, o pedido não é alterado novamente. Uma nota pede que você verifique na Área do Cliente se há uma cobrança duplicada e, se necessário, faça o reembolso ali.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Adyen. São compatíveis reembolsos totais e parciais. 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 definida. A Adyen processa os reembolsos de forma assíncrona: a solicitação é anotada no pedido, e o resultado final é adicionado como nota do pedido pelo webhook REFUND ou REFUND_FAILED. Se a Adyen não aceitar a solicitação, o WooCommerce mostra o erro e nenhum reembolso é registrado. Com captura manual na Adyen, somente pagamentos capturados podem ser reembolsados.
Reembolsos feitos na Área do Cliente da Adyen chegam por webhook e são adicionados às notas do pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce.
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 > Adyen. 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 Adyen 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: pagamentos já iniciados continuam sendo confirmados, 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 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, em modo de produção, Live URL prefix. A página de configurações lista o que falta.
O pagamento foi feito, mas o pedido continua com o status Pending payment: 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 é exatamente a exibida nas configurações e se o método é JSON. Verifique se 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 plugin responde HTTP 401, e a Adyen reenvia a entrega depois; assim, o pedido é atualizado automaticamente quando a chave for corrigida. O log mostra Webhook rejected: invalid HMAC signature ou a informação de que a chave HMAC não está configurada.
O webhook responde busy, retry later: o pedido estava sendo processado por outra entrega no mesmo momento. A Adyen reenvia o webhook automaticamente.
Erro de chave HMAC ao salvar: o campo deve conter a chave HMAC hexadecimal da Área do Cliente. O valor anterior foi mantido.
O cliente vê a mensagem Payment could not be initiated: abra as notas do pedido ou ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_adyen_gateway. Verifique a chave de API, a conta de comerciante e, em modo de produção, o prefixo de URL de produção.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor ou a moeda confirmados pela Adyen não correspondiam ao pedido, ou uma captura falhou. Também pode ser a opção Order status after payment.
O reembolso falha: o pedido precisa de 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. Com captura manual, somente pagamentos capturados podem ser reembolsados.
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 dados da Adyen armazenados nos pedidos (referências PSP, links de pagamento, eventos processados) 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 Adyen é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Adyen.