VibeFox GoPay for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Moeda: a GoPay aceita CZK, EUR, PLN, USD, GBP, HUF, RON e BGN. Com outra moeda do carrinho, o método de pagamento fica oculto na finalização de compra.
Conta GoPay: você precisa do GoID, do Client ID e do Client Secret da sua conta de comerciante da GoPay. Eles ficam nas configurações de integração da conta. A conta sandbox (de teste) tem credenciais próprias. Não é preciso configurar nada na conta da GoPay para as notificações, mas a sua loja precisa estar acessível pela internet.
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, depois, encontre VibeFox GoPay Gateway na lista de módulos e clique em Configure.
3. Insira 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. Insira o GoID, o Client ID e o Client Secret do sandbox, mantenha Test Mode ativado, ative Enable/Disable e clique em Save.
5. Faça um pedido de teste. Quando tudo estiver funcionando, insira as credenciais de produção e desative Test Mode.
Ao instalar, o módulo cria o status de pedido GoPay payment on hold. O PrestaShop oferece o 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 estão na página do módulo: Modules > Module Manager > VibeFox GoPay Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Sandbox mode — test payments only ou Production mode — real payments. Ela avisa quando o GoID, o Client ID ou o Client Secret do modo atual está ausente, e quando a GoPay não aceita a moeda padrão da loja. Nos dois casos, a GoPay não é oferecida na finalização de compra. Ao salvar, os tokens de acesso da GoPay em cache são apagados, para que as novas credenciais sejam usadas imediatamente.
GoPay
Enable/Disable: Enable GoPay payment gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o título do método de pagamento exibido na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: GoPay. Obrigatório: um título vazio não é salvo.
Description: a descrição do método de pagamento exibida na finalização de compra. Padrão: Pay securely via GoPay - cards, wallets, bank transfers.
Credenciais de API
O GoID, o Client ID e o Client Secret são exibidos na sua conta de comerciante da 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: envia os pagamentos para gw.sandbox.gopay.com com as credenciais do sandbox. Nenhum dinheiro real é cobrado. Desative-o para aceitar pagamentos reais com as credenciais de produção. Padrão: ativado.
Sandbox GoID: o GoID da sua conta de teste (sandbox) da GoPay.
Sandbox Client ID: o Client ID OAuth da conta sandbox.
Sandbox Client Secret: o Client Secret OAuth da conta sandbox.
Production GoID: o seu ID de comerciante da GoPay (GoID).
Production Client ID: o Client ID OAuth fornecido pela GoPay.
Production Client Secret: o Client Secret OAuth fornecido pela GoPay.
Um GoID contém apenas dígitos, por exemplo 8123456789. Se você digitar outra coisa, a página exibe um erro e o valor anterior é mantido.
Os Client Secret salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Clear saved client secrets: marque a opção e clique em Save para remover os dois Client Secret salvos. Um campo vazio mantém o valor salvo.
Pagamento
Payment Page Language: o 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 carrinho do cliente; se a GoPay não tiver esse idioma, decide o país de cobrança, e caso contrário é usado o inglês. Você também pode fixar um dos 19 idiomas: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian ou Russian.
Order Status After Payment: o status do pedido definido quando o pagamento é confirmado.
Pagamentos que não correspondem ao pedido, pagamentos feitos após um cancelamento e pagamentos pré-autorizados sempre vão para GoPay payment on hold.
Notificações de pagamento
A notificação informa à sua loja que um pagamento foi feito. A Notification URL é exibida nesta seção e enviada à GoPay com cada pagamento, então nada precisa ser configurado na conta da GoPay. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_gopay_gateway/webhook, possivelmente com um código de idioma como /en/. Ela precisa estar acessível pela internet: sem proteção por senha nem firewall na frente. Funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição por país da sua loja.
As notificações da GoPay trazem apenas o ID do pagamento e nenhuma assinatura. Cada notificação é verificada consultando a API da GoPay sobre o status do pagamento, com as credenciais do modo em que o pagamento foi feito, e o pagamento precisa ser um que o módulo criou para um carrinho da sua loja. Quando o status não pode ser lido da GoPay, a sua loja responde com um erro e a GoPay repete a notificação. Sem notificações, um pedido só é criado quando o cliente volta à loja depois de pagar.
Avançado
Logging: grava os eventos da GoPay em logs/gopay_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Credenciais, tokens, dados de cartão e o e-mail e o nome do cliente nunca são registrados. Padrão: desativado.
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 do módulo, os tokens de acesso da GoPay em cache e o log. Os pedidos, seus dados de pagamento da GoPay e o status de pedido GoPay payment on hold permanecem sempre. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, GoPay) e confirma. O módulo cria um pagamento GoPay pelo total do carrinho, na moeda do carrinho, com os produtos, o frete e a embalagem para presente, e envia o cliente à página de pagamento da GoPay. Lá, a GoPay oferece os métodos de pagamento habilitados na sua conta GoPay, como cartões de pagamento, transferências bancárias e carteiras digitais. O nome de cobrança, o e-mail, o telefone e o endereço do cliente são repassados à GoPay; campos vazios não são enviados. O pagamento aparece na GoPay como Order PS- e o número do carrinho. Neste ponto, ainda não existe pedido.
Após pagar, o cliente retorna à sua loja. O pedido só é marcado como pago depois que a GoPay o confirma: pela notificação ou por uma consulta à API da GoPay quando o cliente retorna. Uma notificação e um retorno que chegam no mesmo momento são tratados um após o outro, de modo que apenas um pedido é criado. Em seguida, o cliente vê a página padrão de confirmação do pedido. Se o pedido foi para GoPay payment on hold, a página acrescenta Your payment is being reviewed. We will contact you if anything else is needed.
Se a GoPay ainda não tiver confirmado o pagamento quando o cliente retornar (por exemplo, uma transferência bancária está em trânsito, ou a GoPay não pode ser acessada), uma página Payment confirmation mostra GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. com um botão Check again.
Se o pagamento não foi concluído, foi cancelado ou expirou, o cliente volta à finalização de compra com 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. O carrinho é mantido, e uma nova tentativa cria um novo pagamento GoPay. Um carrinho que já tem pedido nunca é cobrado novamente.
Se a GoPay não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com 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 é gravado no log.
O cliente escolhe o método de pagamento na página da GoPay; ele não pode ser escolhido no PrestaShop. O módulo não oferece assinaturas nem pagamentos recorrentes, cartões salvos, formulário de pagamento integrado nem captura ou cancelamento de pré-autorizações pelo PrestaShop.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à GoPay e não pagou, ou a GoPay ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted or Delivered: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o ID do pagamento da GoPay como ID da transação, e uma nota mostra o ID do pagamento e o meio de pagamento.
GoPay payment on hold: a GoPay confirmou o pagamento, mas o valor, a moeda ou o número do pedido difere do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou); ou o pagamento chegou depois que o pedido foi cancelado; ou o pagamento é apenas pré-autorizado e o dinheiro ainda não foi capturado. A nota explica o motivo. Um pagamento pré-autorizado precisa ser capturado na GoPay; depois disso, o pedido passa ao status de pago quando a GoPay informa que o pagamento foi concluído.
Refunded: o pagamento GoPay do pedido foi totalmente reembolsado, pelo módulo ou na conta da GoPay.
Se outra tentativa de pagamento de um pedido já pago também for paga, o pedido não é alterado. Uma nota pede que você reembolse a duplicidade na conta da GoPay. Uma nota semelhante é adicionada quando um pagamento GoPay é feito para um pedido que já estava marcado como pago sem a GoPay, por exemplo manualmente. Um pedido cancelado ou reembolsado nunca é reaberto por uma notificação posterior.
Bloco de pagamento GoPay
A página do pedido mostra um bloco GoPay payment com o ID do pagamento da GoPay, o status e o meio de pagamento na GoPay, o valor do pagamento, os valores pago e reembolsado, um selo Sandbox para pagamentos de sandbox, o motivo de uma análise manual, o histórico de reembolsos e as GoPay notes do pedido.
Reembolsos
No bloco GoPay payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via GoPay. Confirme a pergunta Refund this amount through GoPay? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa da permissão para editar pedidos; o acesso às páginas de Modules não é necessário. A GoPay aceita reembolsos parciais somente até 24 horas após o pagamento. Os reembolsos são feitos no valor e na moeda cobrados pela GoPay; por isso, após uma divergência de valor ou moeda, você pode reembolsar até o montante que o cliente efetivamente pagou. 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 bloco mostra a mensagem da GoPay e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas; um reembolso que a GoPay aceitou para processamento posterior é anotado como aceito. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status.
O módulo não cria notas de crédito (credit slips). Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela GoPay.
Reembolsos feitos na conta da GoPay chegam por notificação. Um reembolso total altera o pedido para Refunded; um reembolso parcial acrescenta uma nota. Eles não são adicionados ao histórico de reembolsos do bloco.
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 GoPay Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox GoPay Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-gopay e o link Manage licenses and domains in your account, que abre a sua conta em 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 do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, a GoPay 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 continuam funcionando.
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, 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 GoPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o modo atual tem GoID, Client ID e Client Secret preenchidos, e se a moeda do carrinho é uma de CZK, EUR, PLN, USD, GBP, HUF, RON ou BGN. A página de configurações exibe um aviso quando as credenciais estão ausentes. Em Payment > Preferences, verifique se o módulo está liberado para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi aprovado, mas nenhum pedido foi criado: a GoPay não conseguiu acessar a Notification URL exibida nas configurações, e o cliente não voltou à loja. Remova a proteção por senha ou as regras de firewall que bloqueiam a URL. Verifique se as credenciais do modo em que o pagamento foi feito estão preenchidas, porque cada notificação é verificada com elas. Ative Logging e consulte o campo Log. A GoPay repete as notificações que não receberam uma resposta de sucesso.
Notification answers Order not found: o pagamento não foi criado por esta loja, ou o carrinho dele foi excluído.
Notification answers Payment state could not be verified: a API da GoPay não pôde ser acessada, ou as credenciais desse modo estão ausentes ou incorretas. A GoPay repete a notificação.
Notification answers Busy, retry later: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A GoPay repete a notificação. Ative Logging para ver o motivo.
O cliente vê um erro ao escolher a GoPay: ative Logging e consulte o campo Log. Credenciais erradas, ou credenciais do outro modo, são o motivo mais comum. Uma mensagem sobre os dados de cobrança significa que a GoPay não aceitou o e-mail, o telefone ou o 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 que você quer e use as credenciais desse modo.
O pedido está em GoPay payment on hold após o pagamento: leia as notas no bloco GoPay payment. O valor ou a moeda pagos eram diferentes do carrinho, o pagamento chegou depois que o pedido foi cancelado, ou o pagamento é apenas pré-autorizado.
O reembolso falha: leia a mensagem da GoPay no bloco. Um reembolso parcial só é possível até 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.
Para desenvolvedores: o hook actionGopayPaymentPayload altera a requisição de pagamento antes de ela ser enviada à GoPay.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox GoPay 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 tokens de acesso da GoPay em cache e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento da GoPay dos pedidos e o status de pedido GoPay payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
GoPay é uma marca de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela GoPay.