VibeFox Satispay for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior com a extensão OpenSSL. O módulo não é instalado em versões antigas do PHP nem sem OpenSSL.
Moeda: EUR. A Satispay cobra somente em euros, por isso o método de pagamento fica oculto quando a moeda do carrinho não é EUR.
Conta Satispay: uma conta Satispay Business. Você não copia nenhuma chave de API: o módulo se conecta com um código de ativação de uso único que você gera no Satispay Business Dashboard (veja Configuração). Para testes, você precisa de uma conta sandbox da Satispay, que solicita à Satispay para desenvolvedores.
Loja pública: sua loja precisa estar acessível pela internet, para que a Satispay possa chamá-la quando um pagamento mudar. Não é preciso configurar nada na Satispay para isso.
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 VibeFox Satispay 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. Escolha o ambiente: ative Sandbox Mode para testes; deixe-o desativado para pagamentos reais.
5. Cole um código de ativação desse ambiente em Activation Code e clique em Save. O campo Status então mostrará Connected com o Key ID.
6. Ative Enable/Disable e clique em Save. Teste um pagamento no sandbox, depois desative Sandbox Mode e conecte o ambiente de produção com um código de ativação de produção.
Na instalação, o módulo cria o status de pedido Satispay 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. Lá, o módulo precisa estar permitido para o euro.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Satispay Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira.
Finalização de compra
O que os clientes veem na lista de métodos de pagamento.
Enable/Disable: Enable Satispay payment ativa ou desativa o método de pagamento. Padrão: off.
Title: o nome do método de pagamento exibido na finalização de compra. É também o nome do método de pagamento salvo no pedido. Padrão: Satispay. Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.
Conexão com a Satispay
Status: o estado dos dois ambientes, por exemplo Live: Connected com o Key ID ou Sandbox: Not connected, e qual ambiente está em uso. Enquanto o ambiente em uso não estiver conectado, o campo mostra Satispay is hidden at checkout until the environment in use is connected.
Sandbox Mode: usa o ambiente sandbox (de testes) da Satispay. Pagamentos no sandbox não são cobrados. Padrão: off. Sandbox e produção têm chaves separadas: conecte cada ambiente com um código de ativação desse ambiente. Enquanto o sandbox estiver em uso, os clientes veem Sandbox mode: no real money is charged. abaixo do método de pagamento.
Activation Code: para conectar o ambiente selecionado acima, cole um novo código de ativação de 6 caracteres e clique em Save. Os códigos de produção são gerados no Satispay Business Dashboard, seção Online shop. Os códigos de sandbox vêm com uma conta sandbox da Satispay. O código é usado uma única vez e não é armazenado. Deixe o campo vazio para manter a conexão atual.
Ao salvar com um código, o módulo cria um par de chaves RSA, envia a chave pública e o código à Satispay, e guarda o Key ID e as chaves desse ambiente na configuração da loja. As chaves privadas nunca são exibidas. Em caso de sucesso, a página mostra, por exemplo, Satispay Live connected. Key ID: seguido do ID. Se a Satispay rejeitar o código, a página mostra Satispay activation failed: com a mensagem da Satispay e pede que você verifique se o código é desse ambiente e se ainda não foi usado. Um código com caracteres que não sejam letras ou dígitos é recusado antes de qualquer envio. Salvar um novo código para um ambiente substitui a conexão anterior dele.
Notificações de pagamento
Nada a configurar na Satispay. Cada pagamento tem sua própria URL de callback, que a Satispay chama quando o pagamento muda, e o módulo lê o pagamento novamente pela API da Satispay antes de criar ou alterar um pedido. O campo Callback URL mostra um exemplo dessa URL. Com URLs amigáveis, ela fica assim: https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}, possivelmente com um código de idioma como /en/. A URL precisa estar acessível pela internet: sem autenticação básica na frente. O callback funciona com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
Avançado
Debug log: grava chamadas à API e eventos de pagamento em logs/satispay_p_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 com esta opção desativada. Padrão: off.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, ao desinstalar o módulo são removidas as configurações, as chaves da Satispay dos dois ambientes e o registro. Os pagamentos e reembolsos da Satispay salvos para os pedidos e o status de pedido Satispay payment on hold são sempre mantidos. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Satispay) e confirma o pedido. O módulo cria um pagamento Satispay pelo total do carrinho em euros, com o número do carrinho como referência, e envia o cliente à página de pagamento da Satispay. No computador, o cliente escaneia o QR code com o aplicativo Satispay. No celular, o cliente confirma o pagamento no aplicativo. Nesse momento, ainda não existe pedido.
Após o pagamento, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Satispay confirma: o módulo lê o pagamento pela API da Satispay, verifica se ele foi criado para este carrinho e compara o status, o valor (em centavos) e a moeda com o carrinho. Isso acontece tanto quando a Satispay chama a URL de callback quanto quando o cliente retorna, o que vier primeiro. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Se a Satispay ainda não tiver confirmado o pagamento quando o cliente voltar, uma página Payment confirmation mostra Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. e um botão Check again. O callback cria o pedido assim que chega.
Se o cliente sair da página da Satispay sem pagar, o módulo cancela o pagamento na Satispay, para que a página abandonada não possa mais ser paga. O cliente volta à finalização de compra com a mensagem Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. A mesma mensagem aparece quando o cliente recusa o pagamento no aplicativo. O carrinho é mantido.
Antes de criar um novo pagamento Satispay para o mesmo carrinho, o anterior é verificado: um pagamento pendente é cancelado na Satispay e, se já tiver sido pago, o pedido é criado com ele, sem fazer um segundo pagamento.
Se o pagamento não puder ser iniciado, o cliente permanece na finalização de compra com uma mensagem curta: Satispay is not available at the moment. Please choose another payment method. quando a loja não está conectada ou a Satispay rejeita as chaves, ou Unable to create the Satispay payment. Please try again or choose another payment method. para outros erros. O motivo é gravado no registro.
O módulo aceita somente pagamentos únicos em euros. Não há assinaturas, métodos de pagamento salvos, pré-autorizações nem vale-refeição. Não há verificação agendada de pagamentos pendentes: se nem o callback da Satispay nem o retorno do cliente chegarem à sua loja, nenhum pedido é criado, e o pagamento fica visível no Satispay Dashboard.
Pedidos e reembolsos
Status de pedido
No order yet: o cliente foi enviado à Satispay e não pagou, ou a Satispay ainda não confirmou o pagamento. Existem apenas o carrinho e o pagamento Satispay do módulo.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o ID do pagamento Satispay como ID da transação, e uma nota mostra o pagamento Satispay, o valor e como foi verificado (callback, redirect or checkout).
Satispay payment on hold: a Satispay informou um valor ou uma moeda diferentes do total do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou), ou o pagamento foi aceito depois que o pedido havia sido cancelado. O dinheiro recebido fica registrado no pedido, e a nota explica o caso. Verifique o pagamento no Satispay Dashboard e, em seguida, atenda o pedido ou reembolse o pagamento. Se outro pagamento do mesmo carrinho, com o valor correto, for aceito depois, o pedido passa para Payment accepted.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se um segundo pagamento for aceito para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado pelo Satispay Dashboard. Uma confirmação repetida nunca reabre um pedido cancelado ou reembolsado.
Bloco de pagamento Satispay
A página do pedido mostra um bloco Satispay payment com o ID do pagamento Satispay, o status, o valor pago e reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos, a lista Satispay payments of this cart com cada tentativa de pagamento e seu ambiente, e as Satispay notes do pedido.
Reembolsos
No bloco Satispay payment, informe o valor (o valor ainda não reembolsado já vem preenchido), opcionalmente um motivo, e clique em Refund via Satispay. Confirme a pergunta Refund this amount through Satispay? This cannot be undone. Reembolsos totais e parciais são aceitos. Você precisa ter permissão para editar pedidos; o acesso às páginas de Modules não é necessário. Os reembolsos são limitados ao valor que a Satispay cobrou pelo pagamento, portanto, após uma divergência de valor, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado ao ambiente em que o pagamento foi feito (produção ou sandbox), por isso esse ambiente precisa continuar conectado. Um reembolso só é considerado concluído quando a Satispay o aceita: um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso da Satispay e o motivo. Se a Satispay não aceitar o reembolso, 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.
O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Satispay. Os reembolsos feitos no Satispay Dashboard não são registrados no PrestaShop. Atualize o pedido 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 Satispay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Satispay 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-satispay 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, a Satispay 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 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
A Satispay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o ambiente em uso está conectado (o campo Status mostra Connected para ele) e se a moeda do carrinho é EUR. Em Payment > Preferences, verifique se o módulo está permitido para o euro, para o país do cliente e para o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: o pedido é criado quando a Satispay chama sua loja ou quando o cliente retorna. Verifique se sua loja está acessível pela internet, sem autenticação básica na frente da URL de callback, e ative o Debug log para ver os callbacks no campo Log. O pagamento fica visível no Satispay Dashboard.
O callback responde Payment status unavailable, retry later. ou Not configured.: o módulo não conseguiu ler o pagamento na Satispay, ou o ambiente do pagamento não está conectado. Nenhum pedido é alterado. A Satispay chama novamente. Verifique o status da conexão e o registro.
O callback responde Busy, retry later.: o carrinho estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Satispay chama novamente. O registro mostra o motivo.
O callback responde Unknown payment. ou Missing or invalid payment_id.: o pagamento não foi criado por esta loja para este carrinho, ou a requisição não é um callback da Satispay. Nada é alterado.
A ativação falha: os códigos de ativação podem ser usados uma única vez. Verifique se o código pertence ao ambiente selecionado em Sandbox Mode (um código de produção para produção, um código de sandbox para o sandbox), gere um novo código e salve novamente. Se a página informar que não foi possível gerar um par de chaves RSA, peça à sua hospedagem que ative a extensão OpenSSL do PHP. Se a Satispay não puder ser acessada, verifique se seu servidor consegue abrir conexões HTTPS de saída.
A Satispay sumiu da finalização de compra depois de trocar de sandbox para produção: sandbox e produção usam chaves diferentes. Cole um código de ativação de produção com Sandbox Mode desativado e salve.
O cliente vê This payment method is not available.: o método de pagamento não é permitido para o carrinho (país, moeda ou grupo de clientes em Payment > Preferences), está desativado ou o ambiente em uso não está conectado.
O pedido está como Satispay payment on hold após o pagamento: leia as notas no bloco Satispay payment (veja Status de pedido), verifique o pagamento no Satispay Dashboard e, em seguida, atenda o pedido ou reembolse o pagamento.
O reembolso falha porque o ambiente não está mais conectado: o pagamento foi feito em produção ou em sandbox, e esse ambiente não tem mais chaves. Conecte-o novamente com um código de ativação, ou reembolse o pagamento pelo Satispay Dashboard.
O reembolso falha com Satispay did not accept the refund: a Satispay retornou um status diferente de accepted. O PrestaShop não registrou o reembolso, e uma nota informa isso. Verifique no Satispay Dashboard.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Satispay 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, as chaves da Satispay dos dois ambientes e o registro são removidos. Se estiver desativado, todas as configurações e chaves são mantidas para uma reinstalação posterior. Os pagamentos e reembolsos da Satispay salvos para os pedidos e o status de pedido Satispay payment on hold são sempre mantidos, por isso pedidos pagos antes ainda podem ser reembolsados após uma reinstalação, quando o ambiente estiver conectado novamente. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Satispay é marca comercial de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Satispay.