VibeFox Stripe for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 ou superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Conta no Stripe: você precisa das chaves secretas de API da sua conta do 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, porque 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

O download é um único arquivo zip com os pacotes das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3, wcp_stripe_gateway-oc3-(version).ocmod.zip, e o pacote do OpenCart 4, wcp_stripe_gateway.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_stripe_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Stripe Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão de lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, 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 dele (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.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_stripe_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Stripe Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença, as chaves do Stripe e o webhook como nas etapas 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL do webhook é diferente (veja Webhook).

Uma instalação nova começa com o método de pagamento desativado e o modo de teste ativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, 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 não tem segredo de assinatura do webhook (nesse caso, os pedidos são confirmados apenas quando o cliente volta à loja depois de pagar), e mostra O modo de teste está ativado: nenhum pagamento real será aceito. enquanto o modo de teste estiver ativado. Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter de 1 a 128 caracteres, Sort Order deve ser um número inteiro e Total deve ser um número igual ou maior que 0. Se uma chave ou um segredo não começar com o prefixo esperado, as configurações são salvas e um aviso que indica o campo é exibido acima delas.

Stripe Checkout

Enable/Disable: Enable Stripe 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. Também é o nome do método de pagamento salvo no pedido. Padrão: Stripe. Obrigatório.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely with your credit or debit card via Stripe.

Sort Order: a posição do Stripe entre os métodos de pagamento da finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer o Stripe apenas para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir antes de o Stripe ser oferecido. Deixe em branco para oferecer o Stripe em qualquer total.

Chaves de API

Copie as chaves secretas em Stripe Dashboard > Developers > API keys (a página tem um link para lá). As chaves de teste e as de produção são separadas. O modo de teste usa somente as chaves de teste, e o modo de produção usa somente as chaves de produção.

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: ativado. Desative para aceitar pagamentos reais. Enquanto estiver ativado, os clientes veem Modo de teste: nenhum pagamento real é aceito. na etapa Confirm Order.

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 de produção. 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 de produção.

As chaves e os segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo — deixe em branco para manter. Digite um valor novo somente se quiser alterá-lo. Para remover um valor salvo, marque Clear the saved value on save abaixo do campo e clique em Save.

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 de produção. Use a URL exibida em Endpoint URL nesta seção. No OpenCart 3, ela tem a forma de https://your-store/index.php?route=extension/payment/wcp_stripe_gateway/webhook; no OpenCart 4, de https://your-store/index.php?route=extension/wcp_stripe_gateway/payment/wcp_stripe_gateway.webhook. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie a URL exatamente como as configurações a mostram.

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 dele (whsec_...) no Stripe e cole em Test Webhook Secret ou em Live Webhook Secret. Webhooks sem uma assinatura válida são rejeitados. Um evento só é aceito se estiver 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ó é confirmado quando o cliente volta à loja depois de pagar.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido incompleto). O pedido só recebe um status depois que o Stripe confirma o pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido após um pagamento bem-sucedido. Padrão: Processing.

Awaiting Payment Status: um pagamento com confirmação posterior: a finalização de compra foi concluída, mas o Stripe ainda não confirmou o dinheiro. Padrão: Pending.

On Hold (Review) Status: o pagamento precisa da sua revisão (veja Status de pedido). Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Failed Payment Status: um pagamento com confirmação posterior falhou. Padrão: Failed.

Refunded Status: o pagamento foi totalmente reembolsado pela página do pedido. Padrão: Refunded.

Avançado

Logging: grava as requisições e os webhooks do Stripe em strg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para strg_debug.old.log.php. Chaves e dados dos clientes não são registrados. Padrão: desativado. Enquanto estiver desativado, nada é gravado, nem mesmo os erros.

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

Delete Data on Uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. As transações e os reembolsos do Stripe são sempre mantidos, então pedidos antigos continuam reembolsáveis. Padrão: desativado.

Importar / Exportar

Exportar: Download JSON salva as configurações em um arquivo JSON. As chaves secretas não são exportadas.

Importar: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves secretas salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão Stripe). Na etapa Confirm Order, o cliente vê a sua descrição e a nota Você será redirecionado para o Stripe para concluir o pagamento com segurança. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma sessão do Stripe Checkout pelo 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. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco de métodos de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. O e-mail do cliente é passado ao Stripe, e o pagamento aparece na página do Stripe como Order # com o número do pedido.

Depois de pagar, o cliente volta à 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 retorna. Depois disso, o pedido recebe seu status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Em um pagamento com confirmação posterior, a página também mostra Seu pagamento está sendo confirmado pelo Stripe. Você receberá um e-mail assim que ele for confirmado. Se o Stripe ainda não tiver confirmado o pagamento quando o cliente retornar, uma página de Confirmação de pagamento mostra o mesmo texto e um botão Check again; o webhook define o status do pedido assim que chegar.

Se o cliente cancelar na página do Stripe, a sessão do Stripe é encerrada 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 ou um pagamento com confirmação posterior tiver falhado, a mensagem é O pagamento não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. O carrinho é mantido. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. Cada nova tentativa (no OpenCart 3, o OpenCart cria um novo pedido sempre que a etapa Confirm Order é exibida; no OpenCart 4, o pedido da finalização de compra é atualizado) fecha as sessões abertas anteriores do Stripe do carrinho, então ele não pode ser pago duas vezes. Se uma sessão anterior já estiver paga, esse pagamento é confirmado em vez de iniciar um novo. Se outro pedido do mesmo carrinho já estiver pago com o Stripe, nenhum novo pagamento é iniciado e o cliente vê a página de sucesso do pedido. Uma alteração no carrinho, incluindo uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, se o pagamento com confirmação posterior falhou ou se você o cancelou), o cliente é enviado de volta à finalização de compra com a mensagem sobre o pagamento não concluído, e o próximo Confirm Order paga um novo pedido. Um pedido pago nunca aparece como pago para outro carrinho.

Se o Stripe não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, por exemplo O total do pedido está abaixo do valor mínimo que o Stripe pode cobrar nesta moeda. Escolha outro método de pagamento. O motivo técnico é gravado no log.

O webhook também funciona enquanto a loja está em modo de manutenção, porque o OpenCart deixa passar as requisições das extensões de pagamento.

A extensão aceita somente pagamentos com cartão, capturados imediatamente na página do Stripe. Não há cartões salvos, assinaturas ou pagamentos recorrentes, nem formulário de cartão no seu site, nem botões de Apple Pay ou Google Pay no seu site, e não há separação entre autorização e captura.

Pedidos e reembolsos

Status de pedido

Sem status (pedido incompleto): o cliente foi enviado ao Stripe e ainda não pagou, ou o Stripe ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processing): o pagamento foi confirmado. Uma nota mostra o pagamento do Stripe (pi_...), a sessão e como ele foi confirmado (webhook ou retorno).

Awaiting Payment Status (padrão Pending): o cliente concluiu a finalização de compra com um método de pagamento com confirmação posterior. Quando o Stripe confirma o pagamento, o pedido passa para Order Status After Payment; quando o pagamento falha, passa para Failed Payment Status. O OpenCart notifica o cliente sobre essas mudanças.

On Hold (Review) Status (padrão Pending): o Stripe informou um valor ou uma moeda diferentes do total do pedido, ou o pagamento chegou depois de o pedido ter sido cancelado ou ter mudado de status. A nota explica isso. Verifique o pedido e atenda-o ou reembolse o pagamento.

Refunded Status (padrão Refunded): o pagamento foi totalmente reembolsado pela extensão.

Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você o verifique e reembolse a duplicata no Stripe Dashboard. O mesmo vale quando o pagamento pertence a outro pedido de um carrinho que já está pago: esse pedido permanece sem status, e a nota é adicionada ao pedido pago.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Stripe Gateway

Em Sales > Orders, abra um pedido pago com o Stripe. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Stripe Gateway mostra o ID do pagamento no Stripe (com link para o pagamento no Stripe Dashboard) com um rótulo Test mode para pagamentos de teste, a Checkout Session, o Status do pagamento, os valores Paid / refunded, o formulário de reembolso, o histórico de reembolsos e as Stripe notes do pedido. A aba é exibida para usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox Stripe Gateway, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Stripe. Confirme a pergunta Reembolsar este valor pelo Stripe? Esta ação não pode ser desfeita. Reembolsos totais e parciais são suportados. Você precisa da permissão para modificar a extensão (definida em System > Users > User Groups). Os reembolsos são feitos no valor e na moeda que o Stripe cobrou, não no total do pedido. O reembolso é enviado no modo em que o pagamento foi feito (teste ou produção), então a chave secreta desse modo precisa estar definida. Se o Stripe não aceitar o reembolso, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico e às notas, com o ID do reembolso no Stripe. Um reembolso total define o pedido como Refunded Status sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que o Stripe confirma o pagamento.

As devoluções de produtos em Sales > Returns 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 não muda automaticamente. Atualize-o manualmente, se necessário.

Chave de licença

A extensão 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 Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-stripe e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Chave não encontrada, Esta chave pertence a outro produto, Limite de domínios atingido ou Licença expirada em 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja da configuração do OpenCart. 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 Stripe não é exibido aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê Este método de pagamento não está disponível. Escolha outro. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4, essa prévia não está disponível: a loja não vê o login no painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão 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 de produção. A página de configurações mostra um aviso quando a chave está faltando. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: o webhook não está funcionando. No Stripe Dashboard, verifique se o endpoint existe no modo que você usa (teste ou produção), se a URL dele é exatamente a exibida 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 recebe o status quando o cliente volta à loja depois de pagar.

O webhook responde «Webhook secret not configured»: nenhum segredo do webhook está configurado. 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 somente dentro de 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 de produção não foram trocados.

O webhook responde «Busy, retry»: o pedido estava sendo confirmado por outra requisição naquele mesmo momento, ou o status do pedido não pôde ser definido. 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 «O valor não parece correto» ao salvar: uma chave foi colada no campo errado. As chaves secretas começam com sk_test_ / rk_test_ ou sk_live_ / rk_live_, e os segredos de webhook com whsec_.

O cliente vê um erro após Confirm Order: ative o Logging e consulte o campo Log na página da extensão. Este método de pagamento não está disponível. Recarregue a página de finalização de compra. significa que a sessão de pagamento não corresponde mais ao pedido, ou que o método de pagamento foi desativado nesse meio tempo: o cliente recarrega a finalização de compra. Uma chave incorreta 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 pagamento real: pagamentos de teste e reais são mantidos separados. Altere Test Mode para o modo que você quer usar e utilize as chaves e o webhook desse modo.

Pedido em status de revisão após o pagamento: leia as notas na aba VibeFox Stripe Gateway (veja Status de pedido) e depois atenda o pedido ou reembolse o pagamento.

Não há formulário de reembolso na aba: a aba informa o motivo: o pagamento ainda não está confirmado, está totalmente reembolsado, ou o seu grupo de usuários não tem permissão para modificar a extensão.

O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está definida. Informe-a e tente novamente.

Para desenvolvedores: antes de a sessão do Stripe ser criada, a extensão dispara o evento do OpenCart strg_checkout_session_params com os parâmetros da sessão e o pedido.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Stripe Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos valores padrão em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, também são removidos os seus eventos e a sua ação de inicialização, que deixa o webhook passar no modo de manutenção). Se Delete Data on Uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo de teste, chaves, segredos de webhook, logging) e o log são removidos. Se estiver desativado, eles são mantidos para uma reinstalação posterior. As transações e os reembolsos do Stripe são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados depois de uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Stripe Gateway na lista de extensões instaladas. Depois, clique em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

Stripe é uma marca comercial de seu respectivo titular. Esta extensão não é afiliada nem endossada pelo Stripe.