Minilição · Português

Como aceitar um pagamento no seu site

Crie um Payment Link de teste, conecte-o à página fornecida e verifique o pagamento na sua conta do provedor sem criar um backend de pagamentos.

Começar a aula interativaLer as notas da aula

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.

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.

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.

O que você vai aprender

  • 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.

Arquivos da oficina

Etapa 1

Escolha um objetivo de pagamento sandbox

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

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.

Stripe: criar um Payment Link · Stripe: testes

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

Inspect individual files (optional)
How it works (optional)

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

Extra implementation exercise

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 2

Crie e conecte o link de teste

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

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.

Stripe: criar um Payment Link

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

Inspect individual files (optional)
How it works (optional)

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

Extra implementation exercise

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 3

Conclua um pagamento de teste no provedor

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

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.

Stripe: testes

Arquivos desta etapa

Start hereArquivos da oficina

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

    Inspect individual files (optional)
    How it works (optional)

    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

    Extra implementation exercise

    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 4

    Experimente cancelamento e acesso direto à página de retorno

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

    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

    Start hereArquivos da oficina

    Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

      Inspect individual files (optional)
      How it works (optional)

      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.

      Extra implementation exercise

      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 5

      Entregue o percurso básico de pagamento

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

      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

      Start hereArquivos da oficina

      Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

      Inspect individual files (optional)
      How it works (optional)

      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.

      Extra implementation exercise

      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.

      Continue aprendendo

      Explore as outras lições