VibeFox Stripe for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
HTTPS: seu site deve usar HTTPS para pagamentos reais.
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ó as chaves secretas e os segredos de assinatura dos webhooks são usados. As chaves publicáveis (pk_...) não são necessárias, pois o Stripe Checkout é uma página hospedada pelo Stripe.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_stripe_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Stripe > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Cole suas chaves secretas do Stripe, configure o webhook no Stripe Dashboard e cole seus segredos de assinatura (veja Configuração).
6. Ative Enable/Disable. Teste um pagamento no modo de teste com o cartão 4242 4242 4242 4242 e depois desmarque Test Mode.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Stripe. 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 no checkout) ou segredo de assinatura do webhook, e mostra Test mode is on: no real payments are taken. enquanto o modo de teste estiver ativo. Na lista de métodos de pagamento, o Stripe aparece como precisando de configuração até que o modo atual tenha uma chave secreta.
Geral
Enable/Disable: Enable Stripe Gateway liga ou desliga o método de pagamento. Padrão: desligado.
Title: o nome do método de pagamento que os clientes veem no checkout. Padrão: Stripe.
Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely with your credit or debit card via Stripe.
Chaves de API
Copie as chaves secretas em Stripe Dashboard > Developers > API keys. Chaves de teste e reais são separadas. O modo de teste usa apenas as chaves de teste, e o modo real apenas as chaves reais. Ao salvar, o plugin 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: Enable 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. Padrão: ligado. Desmarque para aceitar pagamentos reais.
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.
Webhook
O webhook informa à sua loja que um pagamento foi feito. Em Stripe Dashboard > Developers > Webhooks, adicione um endpoint no modo de teste e outro no modo real. Use a URL exibida nesta seção das configurações. Ela tem a forma https://your-site/wc-api/strg_stripe_webhook/. Se o seu site usa um prefixo de idioma nas URLs, copie a URL exatamente como as configurações a mostram, porque o Stripe não segue redirecionamentos.
Selecione estes eventos para cada endpoint:
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. Sem o webhook, um pedido só é confirmado 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. O status é definido de uma vez, sem uma segunda mudança de status.
Avançado
Logging: Enable logging grava as requisições e os webhooks do Stripe em WooCommerce > Status > Logs, origem wcp_stripe_gateway. Chaves e dados do cliente não são registrados. Padrão: desligado.
Delete Data on Uninstall: quando ligado, excluir o plugin remove as configurações do gateway, os dados do Stripe armazenados nos pedidos e os logs. Padrão: desligado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Stripe) e faz o pedido. O plugin cria uma sessão do Stripe Checkout para o total do pedido na moeda do pedido 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 de cobrança do cliente é repassado ao Stripe, e o pagamento aparece na página do Stripe como Order # e o número do pedido.
Após pagar, o cliente volta para a página de pedido recebido da 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 chega a essa página. Se o pagamento ainda não estiver confirmado, a página mostra Your payment is being confirmed by Stripe. You will receive an e-mail as soon as it is confirmed.
Se o cliente cancelar na página do Stripe, o pedido é cancelado da forma padrão do WooCommerce. Um cliente pode pagar de novo um pedido não pago, por exemplo pela página Pay for order. Cada nova tentativa fecha a sessão anterior do Stripe, então o pedido não pode ser pago duas vezes.
Se o Stripe não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo de que o total do pedido está abaixo do valor mínimo que o Stripe pode cobrar nesta moeda, e pode escolher outro método de pagamento. O motivo técnico é adicionado às notas do pedido e ao log. Gerentes da loja que estiverem logados também veem o motivo na mensagem.
O método de pagamento funciona no checkout clássico, no bloco Finalizar compra e na página Pay for order. Ele é compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita apenas pagamentos com cartão, cobrados imediatamente na página do Stripe. Não há cartões salvos, assinaturas ou pagamentos recorrentes, nem formulário de cartão no site, nem botões de Apple Pay ou Google Pay no seu site, nem autorização e captura separadas.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado ao Stripe e ainda não pagou, ou o Stripe ainda não confirmou o pagamento.
Processing, Completed or On Hold: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o pagamento do Stripe e como ele foi confirmado (webhook ou retorno). O ID da transação é o ID do pagamento do Stripe (pi_...) e, na tela do pedido, ele leva ao pagamento no Stripe Dashboard.
On hold after payment: o Stripe informou um valor ou uma moeda diferentes do total do pedido (por exemplo, o pedido foi editado depois que o pagamento começou), ou o pagamento chegou depois que o pedido havia sido cancelado. A nota do pedido explica. Verifique o pedido e atenda-o ou reembolse o pagamento.
Failed: um pagamento com atraso falhou.
Cancelled: o cliente cancelou na página do Stripe, ou o pedido foi cancelado por você ou pelo tempo limite de reserva de estoque do WooCommerce. A sessão aberta do Stripe do pedido é fechada, então ele não pode mais ser pago.
Se um segundo pagamento chegar para um pedido que já está pago, o pedido não é alterado de novo. Uma nota pede que você verifique e reembolse a duplicata no Stripe Dashboard.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Stripe. Reembolsos totais e parciais são aceitos. O reembolso é enviado no modo em que o pagamento foi feito (teste ou real), então a chave secreta desse modo precisa estar configurada. Se o Stripe não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso do Stripe.
Reembolsos feitos no Stripe Dashboard chegam pelo webhook charge.refunded e são adicionados às notas do pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Stripe.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Stripe. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta na vibefox.net.
Sem uma chave ativa, o Stripe não é mostrado aos clientes no checkout. Se mesmo assim um pagamento for iniciado, o cliente vê This payment method is not available. Please choose another one. Gerentes da loja logados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado de novo automaticamente em segundo plano.
Solução de problemas
O Stripe não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ligado e se o modo atual tem 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.
O pagamento foi feito, mas o pedido continua em Pending payment: 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 é exatamente a exibida nas configurações e se os quatro eventos estão selecionados. Confira 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 é confirmado quando o cliente volta para a loja depois de pagar.
O webhook responde Webhook secret not configured: nenhum dos segredos 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 a 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.
O webhook responde Busy, retry: o pedido estava sendo confirmado por outra requisição no mesmo momento. O Stripe repete o webhook automaticamente.
Aviso ao salvar: o valor não parece correto: uma chave foi colada no campo errado. Chaves secretas começam com sk_test_ / rk_test_ ou sk_live_ / rk_live_, e segredos de webhook com whsec_.
O cliente vê um erro ao fazer o pedido: abra as notas do pedido ou ative Logging e veja WooCommerce > Status > Logs, origem wcp_stripe_gateway. Uma chave errada ou ausente 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 com o Stripe.
Pagamentos de teste não confirmam um pedido real: pagamentos de teste e reais são mantidos separados. Um pagamento de teste nunca confirma um pedido real, e vice-versa. Mude Test Mode para o modo desejado e use as chaves e o webhook desse modo.
O pedido está On hold after payment: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido, ou o pagamento chegou depois que o pedido foi cancelado. 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. Insira-a e tente novamente.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway, os dados do Stripe armazenados nos pedidos e os logs são removidos somente se Delete Data on Uninstall estiver ligado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Stripe é uma marca registrada de seu respectivo titular. Este plugin não é afiliado ao Stripe nem endossado por ele.