VibeFox GoPay for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.6 ou superior, instalado e ativo. O plugin não permite a ativação sem ele.
PHP: 8.0 ou superior.
Moeda: a GoPay aceita CZK, EUR, PLN, USD, GBP, HUF, RON e BGN. Com outra moeda, o método de pagamento fica oculto na finalização de compra.
Conta GoPay: você precisa do GoID, Client ID e Client Secret da sua conta de comerciante GoPay. Eles ficam nas configurações de integração da conta. A conta sandbox (de teste) tem credenciais próprias. Não é preciso configurar notificações na conta GoPay, mas sua loja precisa estar acessível pela internet.
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_gopay_gateway por FTP para /wp-content/plugins/.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > GoPay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Digite o GoID, Client ID e Client Secret do sandbox, mantenha Test Mode ativado e habilite Enable/Disable.
6. Faça um pedido de teste. Quando tudo estiver funcionando, digite as credenciais de produção e desmarque Test Mode.
Configuração
Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > GoPay. Abaixo da descrição do gateway, a página mostra Sandbox mode — test payments only ou Production mode — real payments. Ela avisa se o GoID, o Client ID ou o Client Secret do modo atual estiver faltando ou se a GoPay não aceitar a moeda da loja. Nos dois casos, a GoPay não é oferecida na finalização de compra. Na lista de métodos de pagamento, o gateway aparece como precisando de configuração até que as credenciais do modo atual sejam informadas. Ao salvar, os tokens de acesso da GoPay armazenados em cache são apagados para que as novas credenciais sejam usadas imediatamente.
Enable/Disable: Enable GoPay payment gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: título do método de pagamento exibido na finalização de compra. Padrão: GoPay.
Description: descrição do método de pagamento exibida na finalização de compra. Padrão: Pay securely via GoPay - cards, wallets, bank transfers.
Credenciais da API
O GoID, o Client ID e o Client Secret aparecem na sua conta de comerciante GoPay (configurações de integração). A conta sandbox (de teste) tem credenciais próprias. A documentação da API está em doc.gopay.com.
Test Mode: Enable sandbox/test mode envia pagamentos para gw.sandbox.gopay.com usando as credenciais do sandbox. Nenhum dinheiro real é cobrado. Desmarque para aceitar pagamentos reais com as credenciais de produção (gate.gopay.cz). Padrão: ativado.
Sandbox GoID: o GoID da sua conta GoPay sandbox (de teste).
Sandbox Client ID: o OAuth Client ID da conta sandbox.
Sandbox Client Secret: o OAuth Client Secret da conta sandbox.
Production GoID: seu ID de comerciante GoPay (GoID).
Production Client ID: o OAuth Client ID da GoPay.
Production Client Secret: o OAuth Client Secret da GoPay.
O GoID contém apenas dígitos, por exemplo, 8123456789. Se você digitar outro valor, a página mostrará um erro e manterá o valor anterior.
Pagamento
Payment Page Language: idioma da página de pagamento da GoPay. Padrão: Automatic (site language, then billing country). A opção automática usa o idioma do seu site; se a GoPay não oferecer esse idioma, será usado o país de cobrança e, caso contrário, o inglês. Você também pode fixar um dos 19 idiomas: tcheco, inglês, eslovaco, alemão, polonês, húngaro, romeno, búlgaro, croata, esloveno, estoniano, letão, lituano, francês, italiano, espanhol, português, ucraniano ou russo.
Order Status After Payment: status definido para o pedido quando o pagamento é confirmado. Ele é definido imediatamente, com uma única alteração de status e um único e-mail ao cliente.
Notificações de pagamento
A notificação informa à sua loja que um pagamento foi feito. A URL de notificação é enviada à GoPay com cada pagamento, então nada precisa ser configurado na conta GoPay. As configurações mostram a URL. Ela se parece com https://your-site/?gopay-api=gopay_payment_notification. Precisa estar acessível pela internet: sem proteção por senha, modo de manutenção ou firewall bloqueando o acesso.
As notificações da GoPay contêm apenas o ID do pagamento e não têm assinatura. Cada notificação é verificada consultando o status do pagamento na API da GoPay, e o pagamento precisa ter sido criado pelo plugin para um pedido da sua loja. Se não for possível consultar o status na GoPay, sua loja responde com um erro e a GoPay repete a notificação. Sem notificações, um pedido só é confirmado quando o cliente retorna à loja após pagar.
Avançado
Logging: Enable logging grava eventos da GoPay em WooCommerce > Status > Logs, origem wcp_gopay_gateway. Os erros são sempre registrados. Credenciais, tokens, dados do cartão, e-mail, telefone e endereço do cliente nunca são registrados. Padrão: desativado.
Delete Data on Uninstall: Delete plugin settings, cached access tokens and log files when uninstalled. Quando ativada, a exclusão do plugin remove as configurações do gateway, os tokens de acesso da GoPay armazenados em cache e os logs. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, GoPay) e faz o pedido. O plugin cria um pagamento GoPay pelo total do pedido na moeda do pedido, incluindo os itens, o frete e as taxas, e encaminha o cliente para a página de pagamento da GoPay. Nela, a GoPay oferece os métodos habilitados na sua conta, como cartões de pagamento, Apple Pay, Google Pay e transferências bancárias. O nome de cobrança, o e-mail, o telefone e o endereço do cliente são enviados à GoPay; campos vazios não são enviados. Na GoPay, o pagamento aparece como Order seguido do número do pedido.
Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago após a confirmação da GoPay: pela notificação ou por uma solicitação à API da GoPay quando o cliente retorna. Se uma notificação e um retorno chegarem ao mesmo tempo, eles serão processados um após o outro, então o pedido nunca será concluído duas vezes. Quando o pagamento é confirmado, o cliente chega à página de pedido recebido.
Se o pagamento não for concluído, for cancelado ou expirar, o cliente será levado à página Pay for order com a mensagem The GoPay payment was not completed. You can try again or choose another payment method. ou The GoPay payment was cancelled or has expired. You can try again or choose another payment method. Nessa página, o cliente pode pagar novamente um pedido não pago. Para um pedido que já foi pago, não é criado um segundo pagamento GoPay.
Se a GoPay não conseguir iniciar o pagamento, o cliente verá uma mensagem curta, por exemplo, GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. ou GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. O motivo técnico é adicionado às notas do pedido.
O método de pagamento funciona na finalização de compra clássica, nos blocos Cart e Checkout e na página Pay for order. No modo sandbox, o bloco Checkout mostra Sandbox mode: no real payment will be made. É compatível com WooCommerce High-Performance Order Storage (HPOS).
O cliente escolhe o método de pagamento na página da GoPay; não é possível escolhê-lo no WooCommerce. O plugin não oferece assinaturas nem pagamentos recorrentes, cartões salvos, formulário de pagamento integrado nem captura ou cancelamento de pré-autorizações pelo WooCommerce.
Pedidos e reembolsos
Status dos pedidos
Pending payment: o cliente foi encaminhado à GoPay e ainda não pagou, ou a GoPay ainda não confirmou o pagamento.
Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o ID do pagamento da GoPay e o instrumento de pagamento. O ID da transação é o ID do pagamento da GoPay.
On hold: a GoPay confirmou o pagamento, mas o valor ou a moeda difere do pedido; ou o pagamento chegou depois que o pedido foi cancelado; ou o pagamento está apenas pré-autorizado e o dinheiro ainda não foi capturado. A nota do pedido explica o motivo. Um pagamento pré-autorizado precisa ser capturado na GoPay e, depois, você conclui o pedido manualmente.
Failed: o último pagamento GoPay de um pedido não pago foi cancelado ou expirou.
Refunded: o pagamento GoPay do pedido foi totalmente reembolsado, por exemplo, na conta GoPay.
Se outra tentativa de pagamento de um pedido já pago também for paga, o pedido não muda. Uma nota solicita que você reembolse a duplicidade na conta GoPay. Uma nota semelhante é adicionada quando um pagamento GoPay é feito para um pedido já marcado como pago sem a GoPay, por exemplo, manualmente. Uma notificação posterior nunca reabre um pedido pago que você cancelou ou reembolsou.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via GoPay. São aceitos reembolsos totais e parciais. A GoPay só aceita reembolsos parciais 24 horas após o pagamento. O reembolso é enviado no modo em que o pagamento foi feito (sandbox ou produção), então as credenciais desse modo precisam estar configuradas. Se a GoPay recusar o reembolso, o WooCommerce exibirá a mensagem da GoPay e nenhum reembolso será registrado. Um reembolso bem-sucedido é adicionado às notas do pedido. Um reembolso aceito pela GoPay para processamento posterior também é registrado como aceito.
Reembolsos feitos na conta GoPay chegam por notificação. Um reembolso total altera o pedido para Reembolsado; um parcial adiciona uma nota. 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 > GoPay. Cole a chave em License key e clique em Activate. O bloco mostra o status, como a data até a qual a licença está ativa e seu domínio. Use Check now para conferir o status novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera o espaço do domínio. Libere o espaço na sua conta vibefox.net.
Sem uma chave ativa, a GoPay não aparece para os clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente verá This payment method is not available. Please choose another one. Os gerentes da loja conectados 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. Os 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 é preciso renová-la para receber atualizações e suporte. O status é verificado novamente em segundo plano de forma automática.
Solução de problemas
A GoPay não aparece na finalização de compra: confira se a licença está ativa, se Enable/Disable está ligado, se o modo atual tem GoID, Client ID e Client Secret e se a moeda é CZK, EUR, PLN, USD, GBP, HUF, RON ou BGN. Na página Pay for order, vale a moeda do pedido. A página de configurações mostra um aviso quando as credenciais ou a moeda estão incorretas.
O pagamento foi feito, mas o pedido continua Pending payment: a GoPay não conseguiu acessar a URL de notificação exibida nas configurações, e o cliente não retornou à loja. Remova a proteção por senha, o modo de manutenção ou as regras de firewall que bloqueiam a URL. Confira se as credenciais do modo usado no pagamento estão configuradas, pois cada notificação é verificada com elas. Consulte WooCommerce > Status > Logs, origem wcp_gopay_gateway. A GoPay repete as notificações que não recebem uma resposta de sucesso.
A notificação responde “Order not found”: o pagamento não foi criado por esta loja ou o pedido foi excluído.
A notificação responde “Payment state could not be verified”: não foi possível acessar a API da GoPay ou as credenciais desse modo estão incorretas. A GoPay repete a notificação.
O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou ative Logging. A nota mostra o erro da GoPay. A causa mais comum são credenciais incorretas ou credenciais do outro modo. Uma mensagem sobre os dados de cobrança significa que a GoPay não aceitou o e-mail, telefone ou endereço.
Pagamentos de teste não confirmam um pedido real: sandbox e produção são separados. Cada pagamento é verificado no modo em que foi criado. Altere Test Mode para o modo desejado e use as credenciais correspondentes.
O pedido fica On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos diferem do pedido, o pagamento chegou depois que o pedido foi cancelado ou o pagamento está apenas pré-autorizado.
O reembolso falha: leia a mensagem da GoPay. Um reembolso parcial só é possível 24 horas após o pagamento. Uma mensagem sobre o modo significa que o pagamento foi feito no modo sandbox ou produção e que as credenciais desse modo não estão configuradas.
O bloco de licença mostra um erro: siga a mensagem no bloco. Por exemplo, se a chave já estiver sendo usada em outro domínio, libere um espaço na sua conta 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 continuará funcionando com o último status conhecido.
Para desenvolvedores: o filtro gopay_p_payment_payload altera a solicitação de pagamento, e gopay_p_icon altera o ícone do método de pagamento.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua-o na página Plugins. A chave e o status da licença deste plugin são sempre removidos. As configurações do gateway, os tokens de acesso armazenados em cache e os logs só são removidos se Delete Data on Uninstall estiver ativado. Caso contrário, ficam guardados para uma reinstalação futura. Os IDs de pagamento GoPay salvos nos pedidos são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
GoPay é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela GoPay.