Execute pedidos com o Checkout
Depois de integrar o Stripe Checkout ou criar um Stripe Payment Link para levar os clientes a um formulário de pagamento, você receber uma notificação após o pagamento para saber que pode executar o pedido.
Neste guia, você aprenderá a:
- Receber uma notificação de evento sempre que um cliente pagar você.
- Gerenciar o evento.
- Usar Stripe CLI para testar rapidamente seu novo gerenciador de eventos.
- Gerenciar outras formas de pagamento, se quiser.
- Acionar o gerenciador de eventos em produção.
Instalar a CLI da Stripe
A forma mais rápida de desenvolver e testar webhooks localmente é com a CLI da Stripe.
Para começar, siga o guia de instalação da CLI da Stripe.
Assim que tiver instalado a Stripe CLI e concluído o processo de login, você poderá passar para a próxima etapa.
Criar seu gerenciador de eventosLado do servidor
Nesta seção, você criará um pequeno gerenciador de eventos para que a Stripe possa enviar um evento checkout.session.completed
quando um cliente finalizar o checkout.
Primeiro, crie uma rota para seu gerenciador de eventos. Imprima o evento recebido. Na etapa seguinte, você verificará se a entrega está funcionando:
Testes
Execute seu servidor (em localhost:4242
, por exemplo). Depois configure a CLI da Stripe para encaminhar eventos para seu servidor local, permitindo testar seu gerenciador localmente:
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)
Acesse o Checkout como cliente:
- Clique no seu botão de checkout (que você deve ter configurado no guia Aceitar um pagamento)
- Preencha seu formulário de pagamento com dados de teste
- Insira o número de cartão
4242 4242 4242 4242
- Insira uma data futura qualquer para a validade
- Insira qualquer número de 3 dígitos no CVV
- Informe qualquer código postal para cobrança (
90210
)
- Insira o número de cartão
- Clique no botão Pagar
Você deve ver:
checkout.session.completed
na saída destripe listen
- Uma declaração PRINT dos logs de evento do seu servidor com o evento
checkout.session.completed
event
Agora a entrega do evento foi verificada, você pode acrescentar recursos de segurança para receber somente eventos da Stripe.
Verificar se os eventos foram originados pela Stripe
Qualquer um pode publicar (POST) dados no seu gerenciador de eventos. Para processar um evento, verifique sempre se ele veio da Stripe antes de aceitá-lo. A biblioteca oficial da Stripe tem suporte integrado para verificação de eventos de webhook, que você usará para atualizar seu gerenciador de eventos:
Testes
Siga o fluxo de teste da etapa anterior. O evento checkout.session.completed
deve continuar sendo impresso corretamente.
Agora tente atingir o endpoint com uma solicitação não assinada:
curl -X POST \ -H "Content-Type: application/json" \ --data '{ "fake": "unsigned request" }' \ -is http://localhost:4242/webhook HTTP/1.1 400 Bad Request ... more headers
Você deve receber um erro 400 Bad Request
, porque tentou enviar uma solicitação não assinada para seu endpoint.
Agora que o básico do gerenciador de eventos está configurado, você pode executar o pedido.
Executar o pedidoLado do servidor
Processe o evento checkout.session.completed
para executar o pedido. Dependendo das formas de pagamento aceitas (por exemplo, cartões ou carteiras digitais), pode ser necessário processar outros eventos. Este evento inclui o objeto Checkout Session, que contém detalhes sobre o cliente e seu pagamento. Quando processar esse evento, você também pode considerar:
- Salvar uma cópia do pedido no seu próprio banco de dados.
- Enviar um recibo ao cliente por e-mail.
- Reconciliar os itens de linha e a quantidade comprada pelo cliente se estiver usando
line_item.adjustable_quantity
. Se a sessão do Checkout tiver muitos itens de linha, você pode paginar por eles com line_items.
Gerencie o comportamento de redirecionamento
Você pode configurar o Checkout para redirecionar os clientes depois de receber eventos de webhook. O Checkout gerencia esses redirecionamentos acionados por webhook de maneira um pouco diferente quando você usa o formulário integrado ou uma página hospedada pela Stripe.
Página hospedada pela Stripe | Seu endpoint de webhook redireciona o cliente para o success_url depois que você reconhece que recebeu o evento. Quando o endpoint estiver desconectado ou o evento não for reconhecido corretamente, seu gerenciador redirecionará o cliente para success_url 10 segundos após o pagamento ter sido realizado. |
Formulário integrado | Seu endpoint de webhook redireciona imediatamente os clientes para o return_url . Você não precisa reconhecer que recebeu o evento. |
Testes
Verifique se stripe listen
ainda está em execução. Passe pelo Checkout como usuário de teste, assim como na etapa anterior. O gerenciador de eventos deve receber o evento checkout.session.completed
, e o gerenciamento deve acontecer corretamente.
Gerenciar formas de pagamento com notificação posteriorLado do servidor
Cuidado
Esta etapa só é necessária se você planeja usar alguma das seguintes formas de pagamento: débito automático Bacs, transferências bancárias, boleto, débitos pré-autorizados no Canadá, Konbini, OXXO, débito automático SEPA, SOFORT ou débito automático ACH.
Quando você recebe por formas de pagamento de notificação posterior, os fundos não são disponibilizados imediatamente. O processamento pode levar vários dias, então você deve aguardar para executar o pedido depois que os fundos chegarem à sua conta. Quando o pagamento for processando, o status correspondente do PaymentIntent passará de processing
para succeeded
.
Você precisa administrar os seguintes eventos do Checkout:
Nome do evento | Descrição | Próximas etapas |
---|---|---|
checkout.session.completed | O cliente autorizou o pagamento por débito enviando o formulário do Checkout. | Aguarde a confirmação ou falha do pagamento. |
checkout.session.async_payment_succeeded | O pagamento do cliente foi confirmado. | Execute o pedido de mercadorias ou serviços. |
checkout.session.async_payment_failed | O pagamento foi recusado ou houve outro erro. | Entre em contato com o cliente por e-mail e solicite que seja feito um novo pedido. |
Todos esses eventos incluem o objeto Checkout Session.
Atualize seu gerenciador de eventos para executar o pedido:
Testes
Verifique se stripe listen
ainda está em execução. Passe pelo Checkout como usuário de teste, assim como na etapa anterior. Seu gerenciador de eventos deve receber o evento checkout.session.completed
, e o gerenciamento deve acontecer corretamente.
Agora que essas etapas já foram executadas, você pode entrar em produção quando quiser.
Entrar em produção
Depois de implementar seu endpoint gerenciador de eventos de produção, será preciso registrar o URL de produção na Stripe. Siga o guia para registrar um webhook.