Executar pedidos

Crie uma função no seu servidor para executar pagamentos bem-sucedidos. Os webhooks acionam essa função, que é chamada quando os clientes são enviados ao seu site após a conclusão do checkout. Este guia refere-se a esta função como fulfill_checkout, mas você usar o nome que quiser para a função.

Sua função fulfill_checkout deve:

1. Gerencie corretamente a repetição de chamados com o mesmo ID de sessão do Checkout.
2. Aceite um ID de sessão do Checkout como argumento.
3. Acesse a sessão do Checkout na API com a propriedade line_items expandida.
4. Verifique a propriedade payment_status para saber se é preciso executá-la.
5. Fazer a execução dos itens de linha.
6. Registre o status de execução da sessão do Checkout informada.

Use o código abaixo como ponto de partida para sua função fulfill_checkout. Os comentários TODO indicam funções que você precisa implementar.

def fulfill_checkout(session_id)
  # Set your secret key. Remember to switch to your live secret key in production.
  # See your keys here: https://dashboard.stripe.com/apikeys
  Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

  puts "Fullfilling Checkout Session #{session_id}"

  # TODO: Make this function safe to run multiple times,
  # even concurrently, with the same session ID

  # TODO: Make sure fulfillment hasn't already been
  # performed for this Checkout Session

  # Retrieve the Checkout Session from the API with line_items expanded
  checkout_session = Stripe::Checkout::Session.retrieve({
    id: session_id,
    expand: ['line_items'],
  })

  # Check the Checkout Session's payment_status property
  # to determine if fulfillment should be performed
  if checkout_session.payment_status != 'unpaid'
    # TODO: Perform fulfillment of the line items

    # TODO: Record/save fulfillment status for this
    # Checkout Session
  end
end

Dependendo das formas de pagamento aceitas e das necessidades da sua empresa, pode ser necessário que a função fulfill_checkout faça o seguinte:

• Providenciar acesso a serviços.
• Acionar envio de mercadorias.
• Salve uma cópia dos dados de pagamento e dos itens de linha no seu próprio banco de dados.
• Envie um e-mail de recibo personalizado ao cliente se não ativar os recibos da Stripe.
• Reconcilie itens de linha e quantidades compradas se permitir que os clientes ajustem quantidades no Checkout.
• Atualize os registros de estoque ou inventário.

Para acionar a execução, crie um gerenciador de eventos de webhook para ouvir eventos de pagamento e acionar sua função fulfill_checkout.

Quando alguém paga você, é criado um evento checkout.session.completed. Configure um endpoint no seu servidor para aceitar, processar e confirmar o recebimento desses eventos.

Formas de pagamento imediatas e postergadas

Algumas formas de pagamento não são instantâneas, como débito automático ACH e outras transferências bancárias. Isso significa que os fundos não estarão imediatamente disponíveis quando o Checkout for concluído. Formas de pagamento postergadas geram um evento checkout.session.async_payment_succeeded quando o pagamento é bem-sucedido posteriormente. O status do objeto permanece em processamento até que o status do pagamento seja bem-sucedido ou falhe.

require 'sinatra'

# Use the secret provided by Stripe CLI for local testing
# or your webhook endpoint's secret.
endpoint_secret = 'whsec_...'

post '/webhook' do
  event = nil

  # Verify webhook signature and extract the event
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    payload = request.body.read
    event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret)
  rescue JSON::ParserError => e
    # Invalid payload
    return status 400
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    return status 400
  end

  if event['type'] == 'checkout.session.completed' ||
  event['type'] == 'checkout.session.async_payment_succeeded'
    fulfill_checkout(event['data']['object']['id'])
  end

  status 200
end

Você também pode escutar e gerenciar eventos checkout.session.async_payment_failed. Por exemplo, você pode enviar um e-mail ao cliente quando um pagamento postergado falhar.

A maneira mais rápida de desenvolver e testar seu gerenciador de eventos de webhook é com a Stripe CLI. Se não tiver a Stripe CLI, siga o guia de instalação para começar.

Quando a Stripe CLI é instalada, você pode testar o gerenciador de eventos localmente. Execute seu servidor (por exemplo, em localhost:4242) e execute o comando stripe listen para que a Stripe CLI encaminhe eventos ao servidor local:

stripe listen --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)

Adicione o segredo do webhook (whsec_...) ao código de tratamento do evento e teste a execução ao passar pelo checkout como cliente.

Quando o pagamento for concluído, verifique o seguinte:

• Na linha de comando, onde stripe listen está sendo executado, um evento checkout.session.completed é exibido e encaminhado ao servidor local.
• Seus logs do servidor mostram a saída esperada da sua função fulfill_checkout.

Depois de testar localmente, coloque seu gerenciador de eventos de webhook em funcionamento no servidor. Em seguida, crie um endpoint de webhook para enviar eventos checkout.session.completed ao seu servidor e teste o fluxo do Checkout novamente.

É necessário ouvir webhooks para garantir que você sempre acione a execução de cada pagamento, mas os webhooks podem sofrer atrasos. Para otimizar seu fluxo de pagamento e garantir o atendimento imediato quando o cliente estiver presente, acione também a execução na sua página de destino. Você pode configurar a página de chegada passando return_url ao criar a Sessão de Checkout ou passando returnUrl para confirm no frontend.

Use o ID da Sessão de Checkout do URL especificado para fazer o seguinte:

1. Quando o servidor receber uma solicitação para a página inicial do Checkout, extraia o ID da Sessão de Checkout do URL.
2. Execute a função fulfill_checkout com o ID fornecido.
3. Renderize a página após a conclusão da tentativa de execução.

Ao renderizar sua página de destino, você pode exibir o seguinte:

• Detalhes do processo de execução.
• Links ou informações sobre serviços aos quais o cliente agora tem acesso.
• Dados de envio ou logística de mercadorias físicas.