VOXIBLY
← Voltar às funcionalidades

Integração da gateway de pagamento Stripe no checkout (Projeto Aurora)

Transforme um pedido falado num brief estruturado, pronto a entregar.

Amostra de um resultado real

Resumo

O Marco, da equipa de Pagamentos, ditou um brief para ligar a gateway de pagamento Stripe ao checkout do e-shop Projeto Aurora. O objetivo é substituir a faturação manual atual por pagamentos com cartão online, com suporte para Apple Pay e Google Pay. O prazo para a entrada em produção é 15 de julho, com um MVP no ambiente de testes até ao final de junho.

Minutas detalhadas

O que tem de ser construído

O objetivo é adicionar pagamentos com cartão através do Stripe ao checkout existente do Projeto Aurora. Depois de preencher o carrinho, o cliente escolhe um método de pagamento e paga na própria página, sem ser redirecionado para uma gateway externa. O Marco frisou que o formulário de pagamento deve ser incorporado através do Stripe Elements, para se manter dentro do design do e-shop.

Além do cartão habitual, devem ser suportados o Apple Pay e o Google Pay, porque, segundo as análises, as encomendas móveis representam mais de metade do tráfego. O pagamento em numerário e por fatura mantêm-se disponíveis como alternativas; o Stripe é apenas uma terceira opção adicional.

Requisitos técnicos e salvaguardas

A fiabilidade da confirmação do pagamento é fundamental. O estado da encomenda nunca pode mudar com base na resposta do navegador, mas exclusivamente através de um webhook do Stripe no backend (o evento payment_intent.succeeded). O Marco avisou explicitamente contra uma situação em que o cliente paga mas a ligação cai e a encomenda fica pendurada como não paga.

Cada chamada tem de ser idempotente (executá-la de novo não cria um segundo pagamento) através de uma idempotency key. Os webhooks têm de ser verificados por assinatura para que não possam ser forjados. Em caso de falha do Stripe, é exigido um fallback — o checkout não pode cair por completo; a opção de cartão é apenas ocultada e os restantes métodos de pagamento são oferecidos.

Tarefas

  • Criar um endpoint de backend para criar um PaymentIntent com o Stripe (montante, moeda, idempotency key). · responsável equipa de backend · prazo até 27 de junho alta
  • Integrar o Stripe Elements no checkout do frontend (cartão, Apple Pay, Google Pay) no design do e-shop. · responsável equipa de frontend · prazo até 30 de junho alta
  • Implementar um handler de webhook para payment_intent.succeeded e payment_intent.payment_failed com verificação de assinatura. · responsável equipa de backend · prazo até 27 de junho alta
  • Adicionar um fallback: quando o Stripe estiver indisponível, ocultar o pagamento com cartão e oferecer numerário e fatura. · responsável equipa de frontend · prazo até 3 de julho média
  • Preparar cenários de teste (sucesso, falha de cartão, falha de webhook, pagamento duplicado) no ambiente de testes. · responsável Lúcia (QA) · prazo até 8 de julho média

Decisões

  • O formulário de pagamento será incorporado através do Stripe Elements diretamente no checkout, sem redirecionamento para uma página externa. 💬 da transcrição: „"Quero isto por dentro, no mesmo design, e não a atirar a pessoa para uma página de terceiros."“
  • A confirmação do pagamento é tratada pelo webhook payment_intent.succeeded do lado do servidor, não pela resposta do cliente. 💬 da transcrição: „"A fonte da verdade é o webhook no backend, ponto final."“
  • O Apple Pay e o Google Pay fazem parte do primeiro MVP, não de uma fase posterior. 💬 da transcrição: „"Tratem o Apple Pay e o Google Pay como parte da base, não como um extra para depois."“

Principais insights

  • O estado da encomenda é controlado exclusivamente pelo webhook do lado do servidor, não pela resposta do navegador — isto protege contra a perda de um pagamento quando a ligação cai. 💬 da transcrição: „"Nunca, e quero mesmo dizer nunca, confirmem uma encomenda com base no que volta ao navegador. Só com base no webhook no servidor."“
  • As encomendas móveis representam mais de 50 % do tráfego, e é por isso que o Apple Pay e o Google Pay fazem parte do MVP, não de uma segunda fase. 💬 da transcrição: „"Mais de metade das pessoas compra pelo telemóvel, por isso o Apple Pay e o Google Pay têm de estar lá logo, não algures mais tarde."“
  • Se o Stripe falhar, o checkout inteiro não pode partir — só o pagamento com cartão é ocultado, e o numerário e a fatura mantêm-se. 💬 da transcrição: „"Se o Stripe cair, não deixem o checkout inteiro ir abaixo. Simplesmente escondam a opção de cartão e as pessoas pagam de outra maneira."“

Dados

  • 15 de julho data Entrada em produção Prazo para o lançamento da gateway de pagamento em operação real.
  • final de junho data MVP no ambiente de testes Uma integração funcional pronta para testes.
  • alta prioridade Prioridade da tarefa O Marco sinalizou os pagamentos com cartão como bloqueadores para a campanha de verão.
  • mais de 50 % Quota de encomendas móveis A razão para incluir o Apple Pay e o Google Pay no MVP.

Incerto / riscos

  • Não está especificado se se deve suportar a gravação de cartões para pagamentos recorrentes (saved cards), ou apenas pagamentos pontuais.
  • O Marco não mencionou um limite concreto para reembolsos automáticos (refunds) — é preciso acertar isso com a equipa de suporte.
  • Não ficou definido em que moedas se pagará (apenas CZK, ou também EUR para clientes estrangeiros).

Brief para implementador

Brief de implementação — Integração da gateway de pagamento Stripe (Projeto Aurora)

Objetivo

Adicionar pagamentos com cartão através do Stripe ao checkout existente do e-shop Projeto Aurora, incluindo Apple Pay e Google Pay, como terceiro método de pagamento a par do numerário e da fatura.

Âmbito (scope)

  • Formulário de pagamento incorporado através do Stripe Elements diretamente no checkout (sem redirecionamento para uma gateway externa).
  • Suporte para os métodos de pagamento: cartão, Apple Pay, Google Pay.
  • Confirmação de pagamentos do lado do servidor através de webhooks (fonte da verdade = backend, não o navegador).
  • Fallback quando o Stripe estiver indisponível (degradação suave sem derrubar todo o checkout).

Fora do âmbito (out of scope)

  • Gravação de cartões para pagamentos recorrentes (saved cards) — não tratado por agora, à espera de decisão.
  • Reembolsos através da UI de administração — para o MVP, os reembolsos pelo Stripe Dashboard são suficientes.

Requisitos funcionais

  1. Criação do pagamento
    • O endpoint de backend cria um PaymentIntent (montante, moeda, idempotency_key).
    • O frontend solicita o client_secret e renderiza o Stripe Elements.
  2. Confirmação do pagamento
    • O estado da encomenda é alterado exclusivamente pelo webhook payment_intent.succeeded.
    • A resposta do cliente serve apenas para mostrar o ecrã de "obrigado", nunca para confirmar a encomenda.
  3. Falha do pagamento
    • Webhook payment_intent.payment_failed → a encomenda mantém-se no estado "a aguardar pagamento" e o cliente recebe a opção de tentar de novo.
  4. Fallback
    • Quando o Stripe estiver indisponível, o pagamento com cartão é ocultado e mostram-se numerário + fatura. O checkout não pode cair por completo.

Requisitos não funcionais

  • Idempotência: cada chamada de PaymentIntent usa uma idempotency key (reenviar não cria um segundo pagamento).
  • Segurança dos webhooks: verificação de assinatura (Stripe-Signature), rejeição de pedidos não verificados.
  • Secrets: as chaves de API do Stripe exclusivamente no GCP Secret Manager, nunca no código nem num ficheiro .env no git.
  • Registo (logging): cada falha de pagamento e cada webhook recebido vão para structured logging (Cloud Logging).

Critérios de aceitação

  • O cliente paga com cartão e a encomenda é marcada como paga apenas depois de o webhook payment_intent.succeeded ser recebido.
  • O Apple Pay e o Google Pay aparecem em dispositivos suportados e funcionam de ponta a ponta.
  • Se a ligação cair após o pagamento (navegador fechado), a encomenda continua a ser marcada como paga graças ao webhook.
  • Submeter um pagamento duas vezes não cria dois pagamentos (verificado através da idempotency key).
  • Um webhook forjado sem assinatura válida é rejeitado (HTTP 400).
  • Durante uma falha simulada do Stripe, o checkout não parte — o pagamento com cartão simplesmente desaparece.

Prazos

  • MVP no ambiente de testes: final de junho
  • Produção: 15 de julho

Questões em aberto

  • Gravação de cartões para pagamentos recorrentes — sim/não?
  • Moedas: apenas CZK, ou também EUR?
  • Limite para reembolso automático?

Amostra da transcrição

Marco (requisitante)

Pronto, vamos aos pagamentos. Quero que finalmente metamos pagamentos com cartão via Stripe no checkout da Aurora. Neste momento as pessoas pagam ou em numerário na entrega ou por fatura, e isso está a travar-nos.

Marco (requisitante)

O importante é que isto se mantenha por dentro, no mesmo design. Nada de atirar a pessoa para uma página de terceiros. Vamos incorporá-lo através dos Elements deles, para parecer parte do e-shop.

Marco (requisitante)

E agora a parte mais importante. Nunca, e quero mesmo dizer nunca, confirmem uma encomenda com base no que volta ao navegador. Só com base no webhook no servidor. Já tivemos um caso em que uma pessoa pagou, a ligação dela caiu e a encomenda ficou pendurada como não paga. Isso não se pode repetir.

Marco (requisitante)

Tratem o Apple Pay e o Google Pay como parte da base, não como um extra para depois. Mais de metade das pessoas compra pelo telemóvel, por isso isto tem de estar lá logo.

Marco (requisitante)

E mais uma coisa. Se o Stripe cair, não deixem o checkout inteiro ir abaixo. Simplesmente escondam a opção de cartão e as pessoas pagam de outra maneira. Não quero perder uma venda inteira por causa de uma falha da gateway.

Marco (requisitante)

Em última análise quero isto em produção até 15 de julho, por causa da campanha de verão. No ambiente de testes, que esteja a funcionar até ao final de junho, para a Lúcia ter tempo de o testar a fundo.

Experimentar o Voxibly