VibeFox Quickpay 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 antigas do PHP.

Conta Quickpay: você precisa de dois valores do gerenciador do Quickpay: a chave de API de um usuário de API (para criar pagamentos, capturar e reembolsar) e a chave privada da conta (para verificar a assinatura dos callbacks do Quickpay). Nada além disso precisa ser configurado no Quickpay. Sua loja precisa estar acessível pela internet, sem proteção por senha, para que os callbacks do Quickpay possam chegar.

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 Quickpay Gateway na lista de módulos e clique em Configure.

3. Insira a 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. Cole a chave de API e a chave privada do gerenciador do Quickpay e clique em Test API key (veja Configuração).

5. Escolha o modo de captura e o status do pedido após o pagamento, ative Enable/Disable e clique em Save. Enquanto a sua conta Quickpay estiver em modo de teste, ative Test payments e faça um pagamento com um cartão de teste do Quickpay.

Na instalação, o módulo cria um status de pedido: Quickpay payment on hold. O PrestaShop ativa o novo módulo de pagamento para todas as moedas, países e grupos de clientes. O módulo fica vinculado aos países ativos no momento da instalação. Você pode alterar todos em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Até que a chave de API e a chave privada sejam salvas, a página mostra Quickpay precisa de configuração: informe a chave de API e a chave privada. Enquanto as duas não estiverem salvas, o método de pagamento fica oculto na finalização de compra. Enquanto Test payments estiver ativado, a página lembra você de desativá-lo quando a sua conta Quickpay entrar em produção.

Quickpay

Enable/Disable: Enable Quickpay ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Quickpay. Obrigatório: um título vazio não é salvo.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card or MobilePay on the Quickpay payment page.

Credenciais de API do Quickpay

No gerenciador do Quickpay (manage.quickpay.net), abra Settings > Integration. Copie a chave de API de um usuário de API (Settings > Users) e a chave privada da conta.

Callback URL: mostra a URL de callback da sua loja. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_quickpay_gateway/callback. O Quickpay a chama após cada operação de pagamento (autorização, captura, reembolso, cancelamento). Ela é enviada automaticamente com cada pagamento, então não é preciso configurar nada no Quickpay.

API key: a chave de API de um usuário de API do Quickpay. Ela é usada para criar pagamentos, capturar e reembolsar.

Private key: a chave privada da conta. Ela é usada para verificar a assinatura (HMAC-SHA256) dos callbacks do Quickpay. Sem ela nenhum pagamento pode ser confirmado, e os callbacks são rejeitados.

As chaves salvas nunca são mostradas novamente. O campo fica vazio e mostra Salva — deixe vazio para mantê-la. Digite um novo valor apenas para alterá-la.

Limpar segredos salvos: marque API key ou Private key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Test payments: aceita pagamentos feitos com cartões de teste do Quickpay. O Quickpay não tem um sandbox separado: enquanto a sua conta Quickpay estiver em modo de teste, os pagamentos são feitos com cartões de teste e marcados como tal. Ative isto apenas durante os testes. Quando está desativado, um pagamento de teste nunca marca um pedido como pago. Quando está ativado, a finalização de compra mostra Modo de teste: cartões de teste do Quickpay são aceitos. abaixo do método de pagamento. Padrão: desativado.

Test API key: este botão verifica a chave digitada no campo API key (ou a salva, se o campo estiver vazio) com uma requisição autenticada ao Quickpay, sem salvá-la. Ele responde Conexão bem-sucedida — a chave de API é válida., O Quickpay rejeitou a chave de API., A chave de API não está configurada. ou Falha na conexão: seguido do motivo.

Pagamento

Capture: quando o dinheiro é retirado do cartão.

Order status after payment: o status do pedido depois que o Quickpay confirma o pagamento capturado.

Avançado

Debug log: grava em logs/qpg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos, como callbacks rejeitados e erros da API do Quickpay, são sempre registrados. Ative para registrar também os detalhes de cada requisição e callback. Chaves de API, dados de cartão e dados de clientes nunca são registrados. Padrão: desativado.

Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para limpá-lo.

Delete data: quando ativado, desinstalar o módulo remove as configurações do gateway e o log. Os dados dos pedidos (pagamentos do Quickpay, reembolsos, notas) e o status Quickpay payment on hold 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 Quickpay, com um ícone de cartão) e confirma. O módulo cria um pagamento Quickpay para o carrinho na moeda do carrinho e um link de pagamento pelo total do carrinho, e envia o cliente para a janela de pagamento do Quickpay. Nesse momento, o pedido ainda não existe. O cliente paga ali com um dos métodos ativados na sua janela de pagamento do Quickpay. O e-mail do cliente é repassado ao Quickpay. A janela de pagamento abre no idioma do cliente quando o Quickpay o oferece (dinamarquês, alemão, inglês, espanhol, finlandês, francês, italiano, holandês, norueguês, polonês, sueco); caso contrário, em inglês.

Depois de pagar, o cliente volta para a sua loja. O retorno em si não marca nada como pago. O pedido só é marcado como pago depois que o Quickpay confirma: o callback assinado cria o pedido quando o valor capturado e a moeda correspondem ao carrinho. Em seguida, o cliente vê a página padrão de confirmação do pedido. Com Authorize only, o pedido é criado em Quickpay payment on hold, e você captura o pagamento depois. Se o callback ainda não tiver chegado quando o cliente voltar, uma página de Payment confirmation mostra O seu pagamento está sendo confirmado pelo Quickpay. Você receberá um e-mail assim que o pedido for confirmado. com os botões Check again e Back to checkout.

Se o cliente cancelar na janela de pagamento, o link de pagamento é excluído no Quickpay e o cliente volta à finalização de compra com a mensagem O pagamento foi cancelado. Você pode tentar novamente ou escolher outro método de pagamento. Se o cartão foi recusado, a mensagem é O pagamento não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. O carrinho é mantido. Uma nova tentativa reutiliza o pagamento Quickpay do carrinho com um link novo, então um link antigo nunca pode ser pago em paralelo. Enquanto um pagamento do carrinho estiver autorizado e aguardando a captura, nenhum segundo pagamento é iniciado; o cliente vê a página Payment confirmation.

Se o pagamento não puder ser iniciado, o cliente permanece na finalização de compra com a mensagem Não foi possível iniciar o pagamento pelo Quickpay. Tente novamente ou escolha outro método de pagamento. O motivo técnico é gravado no log. Se as chaves estiverem faltando, a mensagem é O Quickpay não está disponível no momento. Escolha outro método de pagamento.

O callback 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. Não há assinaturas ou pagamentos recorrentes, nem cartões salvos, nem captura parcial, não envia linhas de carrinho ou de fatura ao Quickpay e não tem métodos separados de MobilePay, Apple Pay ou Klarna: o cliente escolhe entre os métodos da sua janela de pagamento do Quickpay.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado ao Quickpay e não pagou, o cartão foi recusado, ou o pagamento está autorizado e aguarda a captura automática. Apenas o carrinho existe.

Payment accepted or Delivered: o Quickpay confirmou o pagamento capturado com o valor e a moeda corretos. O status segue Order status after payment. O pagamento é registrado com o ID de pagamento do Quickpay como ID da transação, e uma nota mostra o pagamento (marcado como TEST nos pagamentos de teste).

Quickpay payment on hold: o pagamento está apenas autorizado e aguarda Capture Quickpay payment; ou o Quickpay informou um valor ou moeda diferente do total do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou, ou um valor diferente foi capturado no gerenciador do Quickpay); ou a captura automática falhou e o valor ainda está apenas reservado. A nota explica o motivo. Quando o dinheiro foi capturado com um valor diferente, o pagamento é registrado no pedido com o valor capturado pelo Quickpay.

Canceled: você cancelou o pedido, ou o pagamento de um pedido em espera foi cancelado no gerenciador do Quickpay.

Refunded: o pagamento foi reembolsado integralmente pelo módulo.

Um pagamento que chega para um pedido já pago, cancelado ou reembolsado não altera o pedido. Uma nota pede que você verifique o pagamento no gerenciador do Quickpay, por exemplo para reembolsar um pagamento em duplicidade.

Ao cancelar um pedido não pago, o link de pagamento é excluído no Quickpay. Cancelar um pedido autorizado não libera automaticamente o valor reservado: uma nota lembra você de cancelar o pagamento no gerenciador do Quickpay; caso contrário, a reserva termina quando a autorização expira.

Bloco Quickpay

A página do pedido mostra um bloco Quickpay payment com o ID do pagamento, o status do pagamento, o valor e o valor reembolsado, um selo Test payment para pagamentos de teste, a lista de todos os pagamentos do Quickpay do carrinho (quando há mais de um), o histórico de reembolsos e as Quickpay notes do pedido. Captura e reembolsos exigem a permissão para editar pedidos; o acesso às páginas de módulos não é necessário.

Captura

Com Authorize only, clique em Capture Quickpay payment no bloco Quickpay e confirme Capturar o total do pedido pelo Quickpay? O total do pedido é capturado; a captura parcial não está disponível. Se o Quickpay confirmar de imediato, o pedido passa para o status de Order status after payment. Caso contrário, uma nota informa que a captura foi solicitada, e o pedido é marcado como pago quando o callback do Quickpay confirmar. Uma captura recusada é exibida no bloco e anotada no pedido.

Reembolsos

No bloco Quickpay, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Quickpay. Confirme a pergunta Reembolsar este valor pelo Quickpay? Isto não pode ser desfeito. Reembolsos totais e parciais são suportados para pagamentos capturados. Os reembolsos são feitos no valor e na moeda capturados pelo Quickpay; portanto, 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 Quickpay processa os reembolsos de forma assíncrona: o histórico de reembolsos mostra requested, e o callback o altera para confirmed ou failed e adiciona o resultado às notas. Se o Quickpay recusar o reembolso imediatamente, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status. Um pagamento autorizado que nunca foi capturado não pode ser reembolsado; cancele-o no gerenciador do Quickpay.

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 Quickpay.

Reembolsos feitos diretamente no gerenciador do Quickpay são apenas adicionados às notas. O status do pedido e as notas de crédito não são alterados automaticamente. Atualize-os manualmente, se necessário.

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 Quickpay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Quickpay 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 ficam a linha Product: presta-payment-quickpay e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas 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, o Quickpay não é exibido aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, 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ê: pode configurar o módulo antes de comprar uma chave, mas não 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 captura e 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 inserção da chave, 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

O Quickpay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se API key e Private key estão salvas. Sem as duas chaves, o método fica oculto. 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 callback do Quickpay não chegou à sua loja ou foi rejeitado. Verifique se a sua loja está acessível pela internet (sem proteção por senha) e se Private key é a chave privada da mesma conta Quickpay. Callbacks rejeitados são sempre gravados no log na página do módulo. Ative Debug log para ver cada callback.

O log mostra Callback rejected: invalid checksum.: a chave privada nas configurações não pertence à conta que enviou o callback. Copie-a novamente em Settings > Integration no gerenciador do Quickpay.

O log mostra Callback rejected: the private key is not configured.: informe a chave privada. Callbacks nunca são aceitos sem ela.

O log mostra Callback: no cart found for payment …: o callback pertence a um pagamento do Quickpay que esta loja não criou, por exemplo um pagamento feito fora do PrestaShop.

O log mostra Could not lock the cart ou Cannot create the order: outro callback do mesmo carrinho estava sendo aplicado naquele momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O callback recebe uma resposta de erro, então o Quickpay o envia de novo.

Um pagamento de teste não marcou o pedido como pago: Test payments está desativado. O log (e a nota, se o pedido existir) informa que o pagamento de teste não foi aceito. Ative a opção durante os testes e desative-a quando a sua conta entrar em produção.

O pedido está em Quickpay payment on hold após o pagamento: leia as notas no bloco Quickpay. O pagamento pode estar apenas autorizado e aguardando Capture Quickpay payment, o valor ou a moeda pagos podem diferir do pedido, ou a captura falhou. Capture, processe o pedido ou reembolse o pagamento.

Test API key mostra «O Quickpay rejeitou a chave de API.»: a chave está errada ou pertence a um usuário sem acesso à API. Copie a chave de API de um usuário de API no gerenciador do Quickpay.

O cliente vê «Não foi possível iniciar o pagamento pelo Quickpay.»: veja o campo Log na página do módulo. Ele mostra o erro do Quickpay, por exemplo uma moeda que a sua conta Quickpay não aceita.

O reembolso falha: o pedido precisa ter um pagamento do Quickpay capturado. A mensagem O pagamento do Quickpay deste pedido não foi capturado — não há nada a reembolsar. significa que o pagamento está apenas autorizado; capture-o ou cancele-o no gerenciador do Quickpay. Valor de reembolso inválido: no máximo … significa que o valor é maior do que o que resta do pagamento capturado.

Desenvolvedores podem alterar os parâmetros do link de pagamento do Quickpay com o hook actionQpgQuickpayLinkData.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Quickpay 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 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. Os pagamentos do Quickpay, os reembolsos e o status Quickpay 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.

O Quickpay é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pelo Quickpay.