VibeFox SimplePay 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 da loja: HUF, EUR ou USD. O SimplePay não aceita outras moedas, e o método de pagamento não é oferecido para carrinhos em outras moedas.
Contas de comerciante do SimplePay: o SimplePay fornece uma conta de comerciante separada para cada moeda, e contas separadas para produção e sandbox. Para cada conta, você precisa do seu MERCHANT e da sua SECRET KEY no painel de comerciante do SimplePay (admin.simplepay.hu para produção, sandbox.simplepay.hu para sandbox), account > Technical data. Se você vende somente em HUF, a conta em HUF é suficiente. Nenhuma outra chave é necessária.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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 o VibeFox SimplePay 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 o MERCHANT e a SECRET KEY das suas contas do SimplePay para cada moeda em que você vende: contas sandbox para testes e contas de produção para pagamentos reais (veja Configuração).
5. Copie a IPN URL exibida na página Configure para cada conta de comerciante (produção e sandbox) no painel de comerciante do SimplePay.
6. Ative Enable/Disable e clique em Save. Teste um pagamento com Sandbox mode ativado e, em seguida, desative Sandbox mode para receber pagamentos reais.
Ao instalar, o módulo cria o status de pedido SimplePay 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 estão na página do módulo: Modules > Module Manager > VibeFox SimplePay 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 avisa quando a moeda padrão da loja não é suportada pelo SimplePay, ou quando não há conta de comerciante para ela no modo atual. Nos dois casos, o método de pagamento não é oferecido para carrinhos nessa moeda. Enquanto o modo sandbox estiver ativado, a página mostra Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.
SimplePay (OTP)
Enable/Disable: Enable SimplePay 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. Ele também é o nome do método de pagamento salvo no pedido. Padrão: SimplePay (Card Payment). Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit or debit card via SimplePay. Comerciantes húngaros podem colocar aqui a declaração de transferência de dados do SimplePay (com o link).
Sandbox mode: usa o sandbox do SimplePay para pagamentos de teste com as contas sandbox. Ele troca tanto o endereço da API quanto as contas de comerciante. Nenhum dinheiro real é cobrado. Padrão: ativado. Desative para receber pagamentos reais com as contas de produção. Enquanto estiver ativado, os clientes veem Sandbox mode: no real payment is taken. abaixo do método de pagamento. Pedidos iniciados no sandbox são sempre reembolsados no sandbox.
Contas de comerciante de produção
As contas usadas quando o Sandbox mode está desativado. Preencha as contas das moedas em que a sua loja vende. Os valores de MERCHANT e SECRET KEY estão no painel de comerciante do SimplePay (admin.simplepay.hu), account > Technical data. Uma conta só é usada quando os dois campos estão preenchidos.
HUF account — Merchant ID: o MERCHANT da sua conta de produção em HUF.
HUF account — Secret key: a SECRET KEY da sua conta de produção em HUF.
EUR account — Merchant ID e EUR account — Secret key: o mesmo para a sua conta de produção em EUR.
USD account — Merchant ID e USD account — Secret key: o mesmo para a sua conta de produção em USD.
Contas de comerciante sandbox
As contas usadas quando o Sandbox mode está ativado. Os campos são os mesmos das contas de produção: HUF account — Merchant ID, HUF account — Secret key e os mesmos pares para EUR e USD. Pegue os valores no painel de comerciante sandbox do SimplePay (sandbox.simplepay.hu), account > Technical data.
As secret keys salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
IPN URL
O IPN é a mensagem que o SimplePay envia à sua loja quando o status do pagamento muda. É a forma normal de criar um pedido. A seção mostra o IPN URL da sua loja. Com URLs amigáveis, ele tem este formato: https://your-shop/module/wcp_simplepay_gateway/ipn, possivelmente com um código de idioma, como /en/. Defina esta URL em cada conta de comerciante, de produção e sandbox, no painel de comerciante do SimplePay. Copie a URL exatamente como as configurações a mostram, porque um IPN redirecionado se perde.
O IPN precisa ser assinado com a SECRET KEY da conta de comerciante que ele indica, no modo (sandbox ou produção) em que o pagamento foi iniciado. IPNs sem assinatura válida são rejeitados. O módulo confirma cada IPN válido ao SimplePay na forma assinada que o SimplePay exige. São usados estes status de IPN:
Os status recusado, cancelado e expirado são registrados apenas para a última tentativa de pagamento de um carrinho que ainda não tem pedido. Os outros status são registrados no log e não alteram nada. Sem o IPN, um pedido só é criado quando o cliente volta à loja após um pagamento bem-sucedido.
Clear saved secret keys: marque uma secret key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido.
Um pagamento com valor ou moeda diferentes do pedido sempre vai para SimplePay payment on hold.
Avançado
Logging: grava chamadas à API, IPNs e retornos em logs/simplepay_op_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados de clientes não são registrados. Erros são sempre registrados, mesmo quando esta opção está desativada. 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 gateway e o log. Os dados de pedidos (transações e reembolsos do SimplePay) são sempre mantidos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão SimplePay (Card Payment)) e vê a nota You will be redirected to the SimplePay payment page to pay by card. Depois de confirmar, o módulo inicia um pagamento com cartão do SimplePay pelo total do carrinho na moeda do carrinho, com a conta de comerciante dessa moeda no modo atual, e envia o cliente à página de pagamento do SimplePay. O e-mail do cliente e, quando estiver completo, o endereço de cobrança são passados ao SimplePay. A página de pagamento usa o idioma da loja quando o SimplePay o suporta; caso contrário, inglês. Um pagamento iniciado pode ser concluído em até 30 minutos. Neste ponto, ainda não existe pedido.
Depois de um pagamento bem-sucedido, o cliente volta à sua loja. O retorno sozinho nunca paga um pedido: o módulo pede ao SimplePay o status da transação com uma requisição assinada, então o pedido é criado mesmo se o IPN chegar atrasado. O pedido só é marcado como pago depois que o SimplePay o confirma. Então o cliente vê a página padrão de confirmação do pedido com Successful transaction. SimplePay transaction ID: e o ID. Se o SimplePay ainda não tiver confirmado o pagamento, uma página Payment confirmation mostra Your payment is being confirmed by SimplePay. SimplePay transaction ID: com o ID e um botão Check again; o IPN cria o pedido assim que chegar.
Se o pagamento falhar, for cancelado ou expirar, o cliente volta à finalização de compra com a mensagem do SimplePay e o ID da transação, por exemplo Cancelled payment. You cancelled the payment ou Timeout. The time allowed to complete the payment has expired. Em caso de falha, o cliente é orientado a verificar os dados informados e a entrar em contato com o banco emissor do cartão. O carrinho é mantido e o cliente pode tentar de novo. Cada nova tentativa recebe sua própria referência do SimplePay: PS, o número do carrinho e o número da tentativa, por exemplo PS123-1, PS123-2.
Se o SimplePay não conseguir iniciar o pagamento, o cliente vê The SimplePay payment could not be started. Please try again or choose another payment method. Se a moeda do carrinho não tiver conta de comerciante, a mensagem é SimplePay is not available for the currency of this order. Please choose another payment method. O motivo técnico é gravado no log.
O IPN funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo aceita apenas pagamentos únicos com cartão, capturados na página do SimplePay. Não há cartões salvos nem pagamentos com um clique, assinaturas ou pagamentos recorrentes, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente foi enviado ao SimplePay e não pagou, o pagamento falhou, foi cancelado ou expirou, ou o SimplePay 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 da transação do SimplePay, e uma nota mostra o ID da transação e se o IPN ou a consulta de status o confirmou.
SimplePay payment on hold: o total ou a moeda do carrinho foram alterados depois que o pagamento foi iniciado, então o valor pago difere do pedido. Nenhum pagamento é registrado. A nota mostra os dois valores. Confira o pedido e atenda-o, ou reembolse o pagamento no painel de comerciante do SimplePay. Se outra tentativa do mesmo carrinho for paga depois com o valor correto, o pedido passa para o status pago.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Um pedido pago, reembolsado ou entregue nunca é reaberto por um IPN atrasado. Se um segundo pagamento for bem-sucedido para um pedido já pago, o pedido não é alterado. Uma nota pede que você verifique isso no painel do SimplePay e reembolse se for uma duplicata.
Bloco de pagamento do SimplePay
A página do pedido mostra um bloco SimplePay payment com o ID da transação, a referência do pedido (orderRef), a conta de comerciante e o modo, o status no SimplePay, os valores pagos e reembolsados, um selo Sandbox para pagamentos sandbox, as tentativas de pagamento do carrinho (quando houve mais de uma), o histórico de reembolsos e as SimplePay notes do pedido.
Reembolsos
No bloco SimplePay payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via SimplePay (OTP). Confirme a pergunta Refund this amount via SimplePay? 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 Módulos não é necessário. Reembolsos em HUF devem ser em forints inteiros. O reembolso é enviado para a transação do SimplePay que pagou o pedido, com o valor e a moeda dela, usando a conta de comerciante e o modo (sandbox ou produção) desse pagamento, então essa conta precisa continuar nas configurações. Se o SimplePay não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID da transação de reembolso do SimplePay e o motivo, se você tiver informado um. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Um pedido em espera após uma divergência de valor não pode ser reembolsado pelo bloco: reembolse-o no painel de comerciante do SimplePay.
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 pelo SimplePay. Reembolsos feitos no painel de comerciante do SimplePay não são sincronizados com o PrestaShop. Registre-os 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 SimplePay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox SimplePay 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-simplepay 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 domínio: o domínio da loja principal, também em uma configuração multistore. 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, o SimplePay 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 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 pelo IPN, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado automaticamente 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. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
O SimplePay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se a moeda do carrinho é HUF, EUR ou USD, e se essa moeda tem Merchant ID e Secret key no modo atual: as contas sandbox enquanto Sandbox mode estiver ativado, as contas de produção enquanto estiver desativado. Em Payment > Preferences, verifique se 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 IPN não chegou à loja. No painel de comerciante do SimplePay, verifique o IPN URL da conta de comerciante que você usa (produção ou sandbox, conforme a moeda do carrinho). Ele precisa ser exatamente a URL exibida nas configurações, e o seu servidor precisa estar acessível pela internet. O pedido também é criado quando o cliente volta à loja depois de pagar.
O IPN responde Invalid signature: o IPN indica uma conta de comerciante que não está nas configurações, a Secret key dela está errada, ou ele foi assinado pela conta de outro modo que não o do pagamento. Informe o MERCHANT e a SECRET KEY exatamente como o painel de comerciante do SimplePay os mostra. O SimplePay repete IPNs não confirmados.
O IPN responde Order not found ou Unknown transaction: o IPN é de um pagamento que esta loja não iniciou. Nada é alterado.
O IPN responde Busy, retry: 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). O SimplePay tenta o IPN novamente. O motivo é gravado no log.
O cliente vê The SimplePay payment could not be started: veja o campo Log na página do módulo. Uma secret key incorreta gera Invalid response signature from SimplePay. Check the secret key of the merchant account. Erros do SimplePay são registrados com os códigos de erro.
Depois de alternar entre sandbox e produção: novos pagamentos usam as contas do novo modo. Pagamentos iniciados antes mantêm a conta de comerciante e o modo com que foram iniciados: os IPNs, as consultas de status e os reembolsos deles usam essa conta. Mantenha as contas do modo anterior nas configurações enquanto houver pagamentos abertos ou que possam ser reembolsados.
O pedido fica em SimplePay payment on hold depois do pagamento: leia as notas no bloco SimplePay payment. O total ou a moeda do carrinho foram alterados depois que o pagamento foi iniciado. Atenda o pedido ou reembolse o pagamento no painel de comerciante do SimplePay.
O reembolso falha: leia a mensagem no bloco. SimplePay refunds in HUF must be whole amounts. significa que o valor em HUF tinha casas decimais. Se a mensagem disser que a conta de comerciante deste pagamento não está configurada, informe novamente a conta (moeda e modo) com que o pagamento foi feito. Se o SimplePay reembolsou um valor diferente, a mensagem pede que você confira o reembolso no painel do SimplePay.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox SimplePay 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 gateway 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 do SimplePay e o status de pedido SimplePay payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
SimplePay é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo SimplePay.