VibeFox Stripe for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Conta Stripe: você precisa das chaves de API secretas da sua conta Stripe e de um endpoint de webhook no Stripe Dashboard (veja Configuração). Só são usadas as chaves secretas e os segredos de assinatura dos webhooks. As chaves publicáveis (pk_...) não são necessárias, porque o Stripe Checkout é uma página hospedada pelo Stripe.
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 encontre depois o VibeFox Stripe 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. Cole suas chaves secretas do Stripe, configure o webhook no Stripe Dashboard e cole os segredos de assinatura (veja Configuração).
5. Ative Enable/Disable e clique em Save. Teste um pagamento no modo de teste com o cartão 4242 4242 4242 4242 e depois desative Test Mode.
Ao ser instalado, o módulo cria dois status de pedido: Awaiting Stripe payment e Stripe payment on hold. O PrestaShop ativa 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 ficam na página do módulo: Modules > Module Manager > VibeFox Stripe 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 o modo atual não tem chave secreta (o método de pagamento fica então oculto na finalização de compra) ou segredo de assinatura do webhook (os pedidos então são confirmados apenas quando o cliente volta para a loja). Enquanto o modo de teste estiver ativo, ela mostra também O modo de teste está ativo: nenhum pagamento real é cobrado.
Stripe Checkout
Enable/Disable: Enable Stripe Gateway ativa ou desativa o método de pagamento. Default: off.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. É também o nome do método de pagamento salvo no pedido. Default: Stripe. Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Default: Pay securely with your credit or debit card via Stripe.
Chaves de API
Copie as chaves secretas em Stripe Dashboard > Developers > API keys. As chaves de teste e as reais são separadas. O modo de teste usa somente as chaves de teste, e o modo real somente as chaves reais. Ao salvar, o módulo avisa se um valor não começa com o prefixo esperado, por exemplo quando uma chave publicável foi colada no lugar de uma chave secreta.
Test Mode: usa as chaves de teste do Stripe. Nenhum dinheiro real é cobrado; pague com cartões de teste do Stripe, como 4242 4242 4242 4242. Default: on. Desative para receber pagamentos reais. Enquanto estiver ativo, os clientes veem Modo de teste: nenhum pagamento real é efetuado. abaixo do método de pagamento.
Test Secret Key: a chave secreta do modo de teste. Começa com sk_test_ (ou rk_test_ para uma chave restrita).
Test Webhook Secret: o segredo de assinatura (whsec_...) do endpoint de webhook criado no modo de teste.
Live Secret Key: a chave secreta do modo real. Começa com sk_live_ (ou rk_live_ para uma chave restrita).
Live Webhook Secret: o segredo de assinatura (whsec_...) do endpoint de webhook criado no modo real.
As chaves e segredos salvos nunca são mostrados novamente. O campo fica vazio e mostra Salvo — deixe em branco para manter. Digite um novo valor somente se quiser alterá-lo.
Clear saved secrets: marque uma chave ou um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Webhook
O webhook avisa a sua loja de que um pagamento foi feito. No Stripe Dashboard > Developers > Webhooks, adicione um endpoint no modo de teste e outro no modo real. Use a URL mostrada em Endpoint URL nesta seção. Com URLs amigáveis ela tem este formato: https://your-shop/module/wcp_stripe_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram, pois o Stripe não segue redirecionamentos.
Selecione estes eventos para cada endpoint (eles também estão listados nesta seção):
Depois de criar cada endpoint, copie o segredo de assinatura (whsec_...) do Stripe e cole em Test Webhook Secret ou Live Webhook Secret. Webhooks sem assinatura válida são rejeitados. Um evento precisa ser assinado com o segredo do modo em que o pagamento foi feito, então um segredo de teste nunca confirma um pagamento real. Sem o webhook, um pedido só é criado quando o cliente volta para a loja depois de pagar.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido.
Pagamentos com prazo aguardam em Awaiting Stripe payment. Divergências de valor ou moeda sempre vão para Stripe payment on hold.
Avançado
Logging: grava as requisições ao Stripe e os webhooks em logs/strg_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. Default: off. Enquanto estiver desativado, nada é gravado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ativo, desinstalar o módulo remove as configurações do gateway e o log. As transações e os reembolsos do Stripe e os status de pedido do módulo sempre são mantidos, para que os pedidos existentes continuem funcionando. Default: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Stripe) e vê a nota Você será redirecionado ao Stripe para concluir o pagamento com segurança. Depois de confirmar, o módulo cria uma sessão do Stripe Checkout para o total do carrinho na moeda do carrinho e envia o cliente para a página de pagamento do Stripe. Lá o cliente paga com cartão de crédito ou débito. O e-mail do cliente é passado ao Stripe, e o pagamento aparece na página do Stripe como Cart # seguido do número do carrinho. Nesse momento ainda não existe pedido.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que o Stripe confirma: pelo webhook assinado ou por uma requisição do servidor ao Stripe quando o cliente volta. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Seu pagamento com o Stripe foi recebido. Para um pagamento com prazo, a página mostra Seu pagamento está sendo confirmado pelo Stripe. Você receberá um e-mail assim que for confirmado. Se um pagamento com prazo falhar depois, a página mostra Seu pagamento com o Stripe não foi concluído. Entre em contato conosco sobre este pedido. Se o Stripe ainda não tiver confirmado o pagamento quando o cliente voltar, uma página de Confirmação de pagamento mostra o mesmo texto e um botão Check again; o webhook cria o pedido assim que chegar.
Se o cliente cancelar na página do Stripe, a sessão do Stripe é fechada e o cliente volta à finalização de compra com O pagamento foi cancelado. Você pode tentar novamente ou escolher outro método de pagamento. Se o pagamento não tiver sido concluído, a mensagem é O pagamento não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. O carrinho é mantido. Cada nova tentativa fecha a sessão anterior do Stripe, de modo que o carrinho não pode ser pago duas vezes. Se a sessão anterior já estiver paga, o pedido é criado em vez de um novo pagamento.
Se o Stripe não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo O valor do pedido está abaixo do mínimo que o Stripe pode cobrar nesta moeda. Escolha outro método de pagamento. O motivo técnico é gravado no log.
Se um cupom do carrinho deixar de ser válido entre o pagamento e a sua confirmação, o PrestaShop o remove do pedido. O pedido então vai para Stripe payment on hold com uma nota, porque o cliente pagou o preço com o desconto.
O webhook 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 com cartão, cobrados imediatamente na página do Stripe. Não há cartões salvos, assinaturas ou pagamentos recorrentes, formulário de cartão no site, botões de Apple Pay ou Google Pay no seu site, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente foi enviado ao Stripe e não pagou, ou o Stripe ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted, Delivered or Stripe payment on hold: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o ID de pagamento do Stripe (pi_...) como ID da transação, e uma nota mostra o pagamento do Stripe, a sessão e como foi confirmado (webhook ou retorno).
Awaiting Stripe payment: o cliente concluiu a finalização de compra com um método de pagamento com prazo. O pedido passa para o status pago quando o Stripe confirma o pagamento.
Stripe payment on hold after payment: o Stripe informou um valor ou moeda diferente do total do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou), um cupom foi removido, ou o pagamento chegou depois que o pedido havia sido cancelado. A nota explica. Verifique o pedido e atenda-o ou reembolse o pagamento.
Payment error: um pagamento com prazo falhou.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você verifique e reembolse a duplicata no Stripe Dashboard.
Bloco Stripe payment
A página do pedido mostra um bloco Stripe payment com o ID de pagamento do Stripe (com link para o pagamento no Stripe Dashboard), a Checkout Session, o status do pagamento, o valor cobrado pelo Stripe e o valor reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Stripe notes do pedido.
Reembolsos
No bloco Stripe payment, informe o valor (é preenchido o valor ainda não reembolsado), opcionalmente um motivo, e clique em Refund via Stripe. Confirme a pergunta Reembolsar este valor pelo Stripe? Esta ação não pode ser desfeita. São aceitos reembolsos totais e parciais. Você precisa da permissão para editar pedidos. Os reembolsos são feitos no valor e na moeda cobrados pelo Stripe, então, 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 reembolso é enviado no modo em que o pagamento foi feito (teste ou real), por isso a chave secreta desse modo precisa estar configurada. Se o Stripe 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 de reembolso do Stripe. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que o Stripe confirma o pagamento.
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 Stripe.
Os reembolsos feitos no Stripe Dashboard chegam pelo webhook charge.refunded e são adicionados às notas com o total reembolsado no Stripe. 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 Stripe Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Stripe Gateway > Configure, acima das configurações. Cole 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 digitar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-stripe 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 de alterar o endereço da loja, ou depois de 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 multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o Stripe não é mostrado 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 loja do PrestaShop não sabe que você está logado no 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 precisam de 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 inserida, 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 Stripe não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem uma chave secreta: Test Secret Key no modo de teste, Live Secret Key no modo real. A página de configurações mostra um aviso quando a chave está faltando. 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 webhook não está funcionando. No Stripe Dashboard, verifique se o endpoint existe no modo que você usa (teste ou real), se a URL dele é exatamente a mostrada em Endpoint URL e se os quatro eventos estão selecionados. Verifique se o segredo de assinatura desse endpoint está no campo correspondente (Test Webhook Secret ou Live Webhook Secret). O Stripe Dashboard mostra a resposta da sua loja para cada webhook. O pedido também é criado quando o cliente volta para a loja depois de pagar.
O webhook responde Webhook secret not configured: nenhum segredo de webhook está definido. Cole o segredo de assinatura nas configurações.
O webhook responde Invalid signature: o segredo de assinatura pertence a outro endpoint ou outro modo, ou o relógio do servidor está errado. As assinaturas do Stripe são aceitas em até 5 minutos do horário do servidor. A resposta também é Invalid signature quando um evento de um pagamento real é assinado com o segredo de teste, ou o contrário: verifique se os segredos de teste e real não estão trocados.
O webhook responde Busy, retry: o pedido estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). O Stripe repete o webhook automaticamente. Ative o Logging para ver o motivo.
A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições do Stripe.
Aviso de que o valor não parece correto ao salvar: uma chave foi colada no campo errado. Chaves secretas começam com sk_test_ / rk_test_ ou sk_live_ / rk_live_, segredos de webhook com whsec_.
O cliente vê um erro ao escolher o Stripe: ative o Logging e veja o campo Log na página do módulo. Uma chave errada gera a mensagem de que o método de pagamento não está configurado corretamente. Um total de pedido abaixo do mínimo do Stripe para a moeda (por exemplo 0.50 EUR) não pode ser pago pelo Stripe.
Pagamentos de teste não confirmam um pagamento real: pagamentos de teste e reais são mantidos separados. Mude o Test Mode para o modo desejado e use as chaves e o webhook desse modo.
O pedido está em Stripe payment on hold após o pagamento: leia as notas no bloco Stripe payment (veja Status do pedido) e depois atenda o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou real, e a chave secreta desse modo não está definida. Informe-a e tente novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Stripe Gateway e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. Se Delete Data on Uninstall estiver ativo, 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 Stripe e os status de pedido Awaiting Stripe payment e Stripe payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
O Stripe é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pelo Stripe.