LiçõesComo aceitar um pagamento no seu site

Minilição 26 de 30 · Operar e manter seu site

Escolha um objetivo de pagamento sandbox

Para quem é esta lição?

Para quem quer um botão de pagamento num site. O percurso básico usa uma página hospedada de pagamento e um assistente de programação para o link; código de servidor, configuração de banco e programação de webhooks são aprofundamentos opcionais.

Comece com um checkout hospedado em vez de coletar dados de cartão por conta própria.

Objetivo desta lição

  • Crie um link de checkout sandbox claramente identificado.
  • Conecte e teste o botão de pagamento do site.
  • Verifique estados reais de pago e cancelado no provedor em vez de confiar numa página de retorno.
Explicação, exemplo resolvido e prática

Antes de começar

Sua própria conta Stripe elegível com ambiente sandbox ou de teste e a página fornecida. Um assistente de programação pode configurar o link público de teste. O percurso básico não precisa de Supabase, chave secreta de API no navegador ou servidor próprio.

Confira os conhecimentos iniciais

São habilidades úteis, não cursos obrigatórios bloqueados. Se já as domina, comece aqui; caso contrário, abra a preparação. Os arquivos fornecidos dispensam um site pessoal anterior.

  1. Como publicar seu site pelo GitHub

    Conecte um repositório de prática à hospedagem.

Tempo estimado: 35–53 min

Estimativas com os arquivos iniciais e as contas e ferramentas necessárias já prontas. Configuração, filas de publicação e esperas de e-mail ou DNS exigem tempo adicional. Elegibilidade, ativação e lançamento real do negócio ficam fora do laboratório. Não são usados fundos nem dados reais de cartão.

Entenda a ideia

Use seu próprio ambiente Stripe de teste e um produto e preço fictícios. Abra a página fornecida com seu assistente e decida o que o botão de pagamento deve descrever.

Mantenha este exercício no modo de teste. Um visitante abrir um endereço de sucesso não comprova que houve pagamento.

Um exemplo concreto

Como exemplo, o produto pode ser “Sample digital workshop”, com preço único de teste de USD 5. O botão deve dizer que abre um checkout de teste; nem a página nem esta aula prometem entrega automática do produto.

Use a página pública fornecida para um exercício básico de Payment Link hospedado. Ajude-me a criar um produto e preço de teste na minha própria sandbox Stripe e colocar apenas sua URL pública de checkout de teste na configuração da página. Não configure o percurso opcional de banco e webhook nem use credenciais reais de produção. Ajude a publicar apenas a página de prática pretendida e verificar um pagamento de teste no Dashboard do provedor. A página de retorno não comprova pagamento.

Arquivos desta etapa

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

Examinar arquivos individuais (opcional)

Experimente

Que item e preço de teste seu botão descreverá e onde você verificará o pagamento?

Mostrar uma solução comentada

Meu produto ilustrativo é “Sample digital workshop” por USD 5 no ambiente de teste Stripe. O botão abre seu checkout hospedado. Conferiria estado pago, valor e moeda no registro correspondente da minha conta; visitar success.html não comprovaria pagamento.

O que uma boa resposta inclui

  • Identifica um produto fictício de teste, valor e moeda.
  • Identifica o registro do provedor como o lugar para verificar o pagamento.
Como funciona (opcional)

Aceite um pagamento de teste em checkout hospedado

Comece com uma página de teste do provedor e um limite claro de sucesso.

Um Payment Link hospedado deixa o provedor coletar dados de pagamento sem campos de cartão na sua página. Esta prática usa apenas ambiente e cartões de teste do Stripe.

O site abre o checkout, enquanto o servidor recebe eventos assinados e registra um recibo. A página de retorno é só navegação: qualquer pessoa pode abrir uma URL, então sua presença não comprova pagamento.

Exemplo resolvido

Abrir success.html diretamente não deve criar recibo. Uma sessão paga verificada do Payment Link de teste configurado pode criar um mesmo se o cliente nunca voltar ao site.

Stripe: depois de pagar por Payment Link · Stripe: testes

Exercício técnico complementar

Um usuário visita /success.html?paid=true. O sistema deve conceder um produto pago?

Mostrar uma solução comentada

Não. O visitante controla o parâmetro. Use evento verificado ou consulta ao provedor no servidor vinculada à transação pretendida.

  • Rejeita URLs controladas por quem chama como prova de pagamento.
  • Exige estado de pagamento verificado do provedor.

Etapa 1 · Como aceitar um pagamento no seu site

Crie e conecte o link de teste

Use o painel do provedor e deixe o assistente editar a página.

Explicação, exemplo resolvido e prática

Entenda a ideia

Crie o produto, preço de pagamento único e Payment Link de teste na sua própria conta. Abra o checkout público sem sessão iniciada e depois dê essa URL de teste ao assistente para conectar na página pública fornecida.

Verifique item, valor, moeda e ambiente de teste antes de continuar. Só a URL pública do checkout de teste pertence a esta página; nenhuma chave privada de assinatura ou API é necessária para o link básico.

Um exemplo concreto

Uma configuração correta abre o checkout público de teste sem login. Uma página de configurações da conta Stripe ou o marcador test_REPLACE intacto não é um link utilizável de checkout.

Arquivos desta etapa

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

Examinar arquivos individuais (opcional)

Experimente

O botão do site abre o checkout sandbox pretendido com item e preço corretos?

Mostrar uma solução comentada

Verificação ilustrativa: O link abre o checkout público de “Sample digital workshop”, USD 5, sem pedir login da minha conta Stripe. Só esse link público está na página; a rota básica não precisa de chave API nem segredo de webhook.

O que uma boa resposta inclui

  • Compara o checkout hospedado sem login com produto, valor, moeda e modo de teste esperados.
  • Usa somente o Payment Link público de teste na configuração da página.
Como funciona (opcional)

Configure o checkout separado de teste

Separe URLs públicas, credenciais de servidor e segredos de webhook.

Siga START-HERE.txt para criar Payment Link de teste de pagamento único, tabela e destino webhook. Instale a dependência Stripe fixada e preserve o arquivo de bloqueio gerado.

Coloque só a URL pública de teste em config.js. O ambiente do servidor inclui chave secreta de teste, segredo de assinatura do endpoint, ID esperado do Payment Link e chave privada do banco. O código rejeita credenciais de produção de propósito.

Para a sequência local completa, abra run-locally.txt: prepare o ambiente privado da raiz, vincule apenas o projeto de prática e inicie o proxy de funções do Netlify. server-env.example.txt lista nomes de variáveis sem segredos reais. Abrir apenas o HTML não executa o servidor.

Exemplo resolvido

O segredo de assinatura comprova os eventos de qual endpoint você aceita. Não é o Payment Link público nem a chave API; copiar o segredo errado causa falha de assinatura.

Node.js: estado de suporte das versões

Exercício técnico complementar

O que pertence a public/config.js: a URL de teste ou o segredo de assinatura whsec?

Mostrar uma solução comentada

Apenas a URL pública. Guarde segredo webhook e chaves secretas do provedor e banco em variáveis do servidor.

  • Mantém segredos de assinatura e API no servidor.
  • Usa apenas o destino público do checkout no navegador.

Etapa 2 · Como aceitar um pagamento no seu site

Conclua um pagamento de teste no provedor

Use as instruções oficiais de teste e examine o resultado na conta.

Explicação, exemplo resolvido e prática

Entenda a ideia

Siga o guia de testes vinculado do Stripe apenas dentro da sandbox. Conclua um checkout descartável de teste e depois encontre o pagamento ou sessão real na sua conta.

Verifique lá valor esperado, moeda e estado pago. Um fluxo de página concluído ainda pode diferir do estado final do pagamento, sobretudo em métodos liquidados mais tarde.

Um exemplo concreto

“Checkout concluído” e “pagamento confirmado como pago” nem sempre são a mesma observação.

Arquivos desta etapa

Comece aquiArquivos da oficina

Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

    Examinar arquivos individuais (opcional)

    Experimente

    O que o registro do provedor realmente informou sobre seu pagamento de teste?

    Mostrar uma solução comentada

    Resultado ilustrativo: O pagamento correspondente está pago por USD 5, de acordo com o preço escolhido. Se o provedor mostrar processamento ou não pago, registraria esse estado em vez de chamar o pedido de pago só porque o checkout terminou.

    O que uma boa resposta inclui

    • Encontra o pagamento de teste correspondente e seu estado pago real na conta do provedor.
    • Compara valor e moeda registrados com o preço de teste escolhido.
    Como funciona (opcional)

    Verifique o evento e registre o estado pago uma vez

    Autentique os dados brutos antes de interpretar o JSON.

    O manipulador passa os bytes brutos inalterados e Stripe-Signature ao SDK oficial. Interpretar ou reformatar JSON antes pode mudar os bytes e quebrar a verificação.

    Aceita apenas tipos esperados, modo de teste, payment_link correspondente e payment_status=paid. Métodos demorados podem concluir checkout antes de pagar; só a conclusão não basta. Um session_id único torna inofensiva a inserção repetida de recibo.

    Dois IDs de evento podem descrever a mesma sessão: conclusão e depois sucesso assíncrono. A chave primária session_id com on_conflict=session_id e resolution=ignore-duplicates torna a inserção durável repetível. Uma falha de banco não é escondida: retorna 503 para permitir nova entrega.

    Exemplo resolvido

    A mesma sessão paga entregue duas vezes ainda tem uma única chave primária. Falha do banco retorna 503 para repetir em vez de confirmar um evento cujo resultado foi perdido.

    Stripe: verificação de assinatura webhook e novas tentativas

    Exercício técnico complementar

    Por que checkout.session.completed com payment_status=unpaid ainda não pode ser tratado como pedido pago?

    Mostrar uma solução comentada

    Alguns métodos confirmam depois. Espere estado pago verificado, incluindo evento assíncrono quando aplicável, antes de registrar um recibo pago.

    • Separa conclusão do checkout de estado de pagamento confirmado.
    • Espera a confirmação adequada de pagamento.

    Etapa 3 · Como aceitar um pagamento no seu site

    Experimente cancelamento e acesso direto à página de retorno

    Verifique que o visitante não consegue fabricar um resultado pago apenas navegando.

    Explicação, exemplo resolvido e prática

    Entenda a ideia

    Inicie outro checkout de teste e saia sem concluir o pagamento ou use um caminho de cancelamento que ele realmente ofereça. Separadamente, abra success.html direto. Compare os dois com os registros de teste no provedor.

    Um checkout abandonado pode ficar incompleto ou aberto, não necessariamente com o rótulo literal “canceled”. Nenhuma ação deve ser relatada como uma nova compra paga. A página básica não entrega produto automaticamente.

    Um exemplo concreto

    Abrir success.html ou acrescentar paid=true à URL não cria um pagamento pago correspondente no Stripe. Voltar ao site e comprovar pagamento são operações separadas.

    Arquivos desta etapa

    Comece aquiArquivos da oficina

    Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

      Examinar arquivos individuais (opcional)

      Experimente

      O que o cancelamento e a visita direta à página de retorno comprovaram e o que não comprovaram?

      Mostrar uma solução comentada

      Nesta verificação ilustrativa, o segundo checkout ficou incompleto e não gerou novo pagamento pago. Abrir success.html mostrou só a mensagem de retorno. Nenhuma ação comprova compra, e a página básica não concede acesso automático ao produto.

      O que uma boa resposta inclui

      • Distingue checkout cancelado ou incompleto de um pagamento correspondente pago.
      • Reconhece que acessar a página de retorno diretamente não comprova pagamento nem libera entrega.
      Como funciona (opcional)

      Acompanhe um pagamento de teste de ponta a ponta

      Relacione sessão, evento assinado e recibo armazenado.

      Use apenas cartões oficiais de teste no checkout de teste. Encontre a sessão e a entrega webhook na sua conta e examine a tabela privada payment_receipts no projeto.

      Compare valor e moeda com a sessão. Reenvie o mesmo evento legítimo e confirme que continua uma linha. Tente solicitação sem assinatura e visita direta à página de sucesso; nenhuma deve criar pagamento.

      Exemplo resolvido

      Uma resposta webhook 200 prova que o manipulador confirmou algo. Confira recibo e sessão em vez de supor que todo evento corresponde ao produto pretendido.

      Exercício técnico complementar

      O webhook retorna 200 para um evento sem relação. Deve existir um recibo?

      Mostrar uma solução comentada

      Não. O manipulador confirma eventos ignorados sem recibo. Só uma sessão paga de teste correspondente deve criar o registro pretendido.

      • Entende os eventos ignorados intencionalmente.
      • Relaciona o estado armazenado à sessão paga específica.

      Etapa 4 · Como aceitar um pagamento no seu site

      Entregue o percurso básico de pagamento

      Conclua um link útil sem alegar um sistema completo de comércio.

      Explicação, exemplo resolvido e prática

      Entenda a ideia

      Repita as verificações do botão do site e do pagamento sandbox após qualquer correção. Salve a página e o link de prática e um registro com dados sensíveis ocultados de tentativas bem-sucedidas e canceladas ou não concluídas.

      Antes de vendas reais, confirme elegibilidade do negócio e conta, preço, moeda, condições e processo operacional. Acesso automático, eventos assinados e recuperação de banco pertencem ao material avançado opcional abaixo.

      Um exemplo concreto

      Um botão funcional de checkout hospedado é um pequeno resultado válido; não comprova a existência de um backend de entrega ainda não criado.

      Arquivos desta etapa

      Comece aquiArquivos da oficina

      Abra ou baixe os arquivos abaixo. Ao salvar o projeto, mantenha as pastas indicadas nos nomes dos arquivos.

      Examinar arquivos individuais (opcional)

      Experimente

      Apresente o percurso de teste e os resultados reais da sandbox, além do que for necessário antes de um lançamento real.

      O que entregar: Seu link e página de checkout de teste e observações reais de pagamento e cancelamento na sandbox; nenhuma cobrança real.

      Mostrar uma solução comentada

      Entrega ilustrativa: A página abre o checkout de teste de USD 5; um pagamento correspondente está pago por USD 5; a tentativa abandonada não está paga; abrir o retorno diretamente não muda nenhum registro. Não testei cobrança real nem entrega automática. Antes de lançar, ainda preciso de conta elegível, termos reais e um processo de entrega verificado.

      O que uma boa resposta inclui

      • Entrega a rota pública de teste configurada, com resultados de pagamento e tentativa incompleta/cancelada.
      • Informa que cobrança real e entrega automática estão fora do teste básico concluído.
      Como funciona (opcional)

      Sua tarefa: ensaiar recuperação sem cobranças reais

      Um fluxo de pagamento precisa se recuperar de uma escrita perdida no banco.

      No projeto descartável, use temporariamente uma configuração inválida de banco e reenvie o evento pago legítimo. Observe resposta sem sucesso e nenhum recibo novo. Restaure e reenvie, e verifique exatamente uma linha correspondente.

      Explique o que falta antes de vender de verdade: conta e negócio suportados, preço, moeda e termos corretos, entrega durável do produto, conciliação, reembolsos e monitoramento. Esta oficina só registra recibos de teste.

      Exemplo resolvido

      Se o armazenamento falha, mas o endpoint diz sucesso, as novas tentativas podem parar antes de existir o registro. Falha honesta faz parte de um pagamento confiável.

      O roteiro completo de referência está em reference/assignment-walkthrough.txt. Compare as etapas com seu resultado; preencha o registro de teste com observações do seu próprio projeto.

      Exercício técnico complementar

      Demonstre uma tentativa de armazenamento com falha e recuperação bem-sucedida sem duplicatas.

      Mostrar uma solução comentada

      Instale dependências com npm install no projeto separado; ele gera package-lock.json, que deve ser preservado. Use só Payment Link de teste e credenciais sk_test_. O link público não é o segredo de assinatura webhook.

      Encontre a sessão paga de teste, sua entrega assinada e o recibo privado com mesmo session_id, valor e moeda. Reenvie: chave primária e ignore-duplicates precisam deixar um recibo. Uma solicitação sem assinatura ou visita direta ao sucesso não cria nenhum.

      Para ensaiar falha, altere SUPABASE_URL temporariamente apenas no ambiente local ou servidor descartável para um destino inválido de teste. Reenvie o evento legítimo e observe falha que permita repetição. Restaure, reenvie e verifique um recibo durável. Nunca mude produção nem use cartão real.

      • Falha de persistência não confirma processamento bem-sucedido.
      • A recuperação cria um recibo; nenhum dado real de pagamento nem fundo real é usado.

      Esta lição foi útil?

      Deixe uma curtida ou compartilhe com alguém que possa aproveitar.