Traiter des commandes avec Checkout

Le moyen le plus rapide de développer et de tester des webhooks localement est d’utiliser l’interface de ligne de commande Stripe.

Dans un premier temps, suivez le guide d’installation de l’interface de ligne de commande Stripe.

Lorsque vous avez terminé, exécutez la commande suivante pour vérifier que votre installation fonctionne :

stripe status

✔ All services are online.

Si vous voyez un message de succès après avoir exécuté stripe status, vous pouvez passer à l’étape suivante.

Dans cette section, vous allez créer un petit gestionnaire d’événements afin que Stripe puisse vous envoyer un événement checkout.session.completed lorsque qu’un client effectue le règlement.

Tout d’abord, créez un nouveau routage pour votre gestionnaire d’événements. Commencez par imprimer l’événement que vous recevez. Vous vérifierez que la livraison fonctionne dans l’étape suivante :

# 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_VePHdqKTYQjKNInc7u56JBrQ'

require 'sinatra'

post '/webhook' do
  payload = request.body.read

  # For now, you only need to print out the webhook payload so you can see
  # the structure.
  puts payload.inspect

  status 200
end

Tests

Lancez votre serveur (par exemple, sur localhost:4242). Ensuite, configurez l’interface de ligne de commande Stripe pour qu’elle transmette les événements à votre serveur local afin que vous puissiez tester votre gestionnaire d’événements localement :

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

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

Ensuite, utilisez Checkout en tant que client :

• Cliquez sur votre bouton de règlement (vous avez dû le configurer dans le guide Accepter un paiement)
• Remplissez votre formulaire de paiement avec des données de test
  • Saisissez 4242 4242 4242 4242 comme numéro de carte bancaire
  • Saisissez n’importe quelle date future comme date d’expiration
  • Saisissez n’importe quel code CVC à 3 chiffres
  • Saisissez un code postal pour la facturation (90210)
• Cliquez sur le bouton Payer

Vous devriez voir :

• un checkout.session.completed à la sortie du stripe listen
• un relevé imprimé des journaux d’événements de votre serveur comprenant l’événement checkout.session.completed.

Maintenant que vous avez vérifié la réception de l’événement, vous pouvez renforcer la sécurité pour vous assurer que les événements proviennent uniquement de Stripe.

Vérifier que les événements proviennent de Stripe

N’importe qui peut PUBLIER des données sur votre gestionnaire d’événements. Avant de traiter un événement, vérifiez toujours qu’il provient bien de Stripe avant de lui faire confiance. La bibliothèque officielle Stripe propose une assistance intégrée pour vérifier les événements webhook, avec laquelle vous pourrez actualiser votre gestionnaire d’événements :

# 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_VePHdqKTYQjKNInc7u56JBrQ'

require 'sinatra'

# You can find your endpoint's secret in the output of the `stripe listen`
# command you ran earlier
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

  # Print out the event so you can look at it
  puts event.inspect

  status 200
end

Tests

Examinez le flux de test de l’étape précédente. Vous devriez encore voir l’événement checkout.session.completed s’imprimer avec succès.

Essayez maintenant de transmettre une requête non signée à votre endpoint :

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

Vous devriez obtenir une erreur 400 Bad Request parce que vous avez essayé d’envoyer une requête non signée à votre endpoint.

Maintenant que les bases du gestionnaire d’événements sont établies, vous pouvez passer au traitement de la commande.

Pour traiter la commande, vous devrez gérer l’événement checkout.session.completed. En fonction des moyens de paiement que vous acceptez (par exemple, carte bancaire, porte-monnaie électronique), vous aurez éventuellement aussi à gérer quelques événements supplémentaires après cette étape de base.

Gérer l’événementcheckout.session.completed

Maintenant que vous avez établi la structure de base et la sécurité pour vous assurer que tout événement que vous traitez provient de Stripe, vous pouvez gérer l’événement checkout.session.completed. Celui-ci comprend l’objet de la session Checkout, qui contient les informations concernant votre client et son paiement.

Lorsque vous gérez cet événement, il est également conseillé de :

• sauvegarder une copie de la commande dans votre propre base de données ;
• envoyer un reçu par e-mail au client ;
• rapprocher les postes et les quantités achetées par le client si vous utilisez line_item.adjustable_quantity. Si la session Checkout comporte de nombreux postes de facture, vous pouvez les parcourir à l’aide de la propriété line_items.

Ajoutez le code à votre gestionnaire d’événements pour traiter la commande :

# 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_VePHdqKTYQjKNInc7u56JBrQ'

require 'sinatra'

# You can find your endpoint's secret in the output of the `stripe listen`
# command you ran earlier
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'
    # Retrieve the session. If you require line items in the response, you may include them by expanding line_items.
    session = Stripe::Checkout::Session.retrieve({
      id: event['data']['object']['id'],
      expand: ['line_items'],
    })

    line_items = session.line_items
    fulfill_order(line_items)
  end

  status 200
end

def fulfill_order(line_items)
  # TODO: fill in with your own logic
  puts "Fulfilling order for #{line_items.inspect}"
end

Gérer le comportement de redirection

Vous pouvez configurer Checkout de façon à rediriger vos clients après avoir reçu des événements webhook. Checkout gère ces redirections déclenchées par le webhook de manière légèrement différente selon que vous utilisez le formulaire intégré ou une page hébergée par Stripe.

Tests

Vérifiez que stripe listen est toujours en cours d’exécution. Testez Checkout en tant qu’utilisateur comme dans les étapes précédentes. Votre gestionnaire d’événements devrait recevoir un événement checkout.session.completed et vous devriez l’avoir géré avec succès.

Lorsque vous recevez des paiements avec un moyen de paiement à notification différée, les fonds ne sont pas immédiatement disponibles. Le traitement des fonds peut prendre plusieurs jours. Vous devez donc retarder le traitement de la commande jusqu’à ce que les fonds soient disponibles sur votre compte. Une fois le paiement effectué, l’état du PaymentIntent sous-jacent passe de processing à succeeded.

Vous devrez gérer les événements Checkout suivants :

Ces événements contiennent tous l’objet Checkout Session.

Actualisez votre gestionnaire d’événements pour traiter la commande :

# 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_VePHdqKTYQjKNInc7u56JBrQ'

# You can find your endpoint's secret in the output of the `stripe listen`
# command you ran earlier
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

  case event['type']
  if event['type'] == 'checkout.session.completed'
    checkout_session = event['data']['object']

    fulfill_order(checkout_session)
  end
  when 'checkout.session.completed'
    checkout_session = event['data']['object']

    # Save an order in your database, marked as 'awaiting payment'
    create_order(checkout_session)

    # Check if the order is already paid (for example, from a card payment)
    #
    # A delayed notification payment will have an `unpaid` status, as
    # you're still waiting for funds to be transferred from the customer's
    # account.
    if checkout_session.payment_status == 'paid'
      fulfill_order(checkout_session)
    end
  when 'checkout.session.async_payment_succeeded'
    checkout_session = event['data']['object']

    # Fulfill the purchase...
    fulfill_order(checkout_session)
  when 'checkout.session.async_payment_failed'
    session = event['data']['object']

    # Send an email to the customer asking them to retry their order
    email_customer_about_failed_payment(checkout_session)
  end

  status 200
end

def fulfill_order(checkout_session)
  # TODO: fill in with your own logic
  puts "Fulfilling order for #{checkout_session.inspect}"
end

def create_order(checkout_session)
  # TODO: fill in with your own logic
  puts "Creating order for #{checkout_session.inspect}"
end

def email_customer_about_failed_payment(checkout_session)
  # TODO: fill in with your own logic
  puts "Emailing customer about payment failure for: #{checkout_session.inspect}"
end

Test

Vérifiez que stripe listen est toujours en cours d’exécution. Testez Checkout en tant qu’utilisateur, comme vous l’avez fait dans les étapes précédentes. Votre gestionnaire d’événements devrait recevoir un événement checkout.session.completed et vous devriez l’avoir géré avec succès.

Maintenant que vous avez suivi ces étapes, vous pouvez passer en mode production quand bon vous semble.

Une fois que vous avez déployé votre endpoint de gestionnaire d’événements en mode production, vous devez enregistrer votre URL de production auprès de Stripe. Suivez le guide pour enregistrer un webhook.