Fulfill orders with CheckoutBeta
Beta
The Custom Checkout integration is in private beta. To request access, click here.
After your customer pays, you need notification that you can fulfill their order.
This guide explains how to do the following:
- Receive an event notification when a customer pays you.
- Handle the event.
- Use Stripe CLI to quickly test your new event handler.
- Optionally, handle additional payment methods.
- Turn on your event handler in production.
Install Stripe CLI
The quickest way to develop and test webhooks locally is with the Stripe CLI.
First, install the Stripe CLI and log in following the Stripe CLI install guide.
Create your event handlerServer-side
In this section, you’ll create a small event handler so Stripe can send you a checkout.session.completed
event when a customer completes checkout.
First, create a new route for your event handler. Start by printing out the event you receive. You’ll verify that delivery is working in the next step:
Testing
Run your server (for example, on localhost:4242
). Next, set up Stripe CLI to forward events to your local server, so you can test your event handler locally:
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)
Next, complete your checkout form as a customer. You should see:
- A
checkout.session.completed
in thestripe listen
output - A print statement from your server’s event logs with the
checkout.session.completed
event
Now that you’ve verified event delivery, you can add security to make sure that events are only coming from Stripe.
Verify events came from Stripe
Anyone can POST data to your event handler. Before processing an event, always verify that it came from Stripe. The official Stripe library has built-in support for verifying webhook events.
Testing
Go through the testing flow from the previous step. If it succeeds, you see the checkout.session.completed
event printed out.
Next, try hitting the endpoint with an unsigned request:
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
You should get a 400 Bad Request
error, because you tried to send an unsigned request to your endpoint.
Now that the basics of the event handler are set up, you can move on to fulfilling the order.
Fulfill the orderServer-side
Handle the checkout.session.completed
event to fulfill the order. Depending on which payment methods you accept (for example, cards or mobile wallets), you might have some additional events to handle. This event includes the Checkout Session object, which contains details about your customer and their payment.
When handling this event, you can also do the following:
- Save a copy of the order in your own database.
- Send the customer a receipt email.
- Reconcile the line items and quantity purchased by the customer if using
line_item.adjustable_quantity
. If the Checkout Session has many line items, you can paginate them with the line_items property.
Testing
Ensure that stripe listen
is still running. Verify that your event handler is receiving and handling the checkout.session.completed
even by going through your checkout as a test user, just like in the prior steps.
Handle delayed notification payment methodsServer-side
Caution
This step is only required if you plan to use any of the following payment methods: Bacs Direct Debit, Bank transfers, Boleto, Canadian pre-authorized debits, Konbini, OXXO, SEPA Direct Debit, SOFORT, or ACH Direct Debit.
When receiving payments with a delayed notification payment method, funds aren’t immediately available. It can take multiple days for funds to process so you should delay order fulfillment until the funds are available in your account. After the payment succeeds, the underlying PaymentIntent status changes from processing
to succeeded
.
You’ll need to handle the following Checkout events:
Event Name | Description | Next steps |
---|---|---|
checkout.session.completed | The customer has successfully authorized the debit payment by submitting the Checkout form. | Wait for the payment to succeed or fail. |
checkout.session.async_payment_succeeded | The customer’s payment succeeded. | Fulfill the purchased goods or services. |
checkout.session.async_payment_failed | The payment was declined, or failed for some other reason. | Contact the customer via email and request that they place a new order. |
These events all include the Checkout Session object.
Update your event handler to fulfill the order:
Testing
Ensure that stripe listen
is still running. Go through Checkout as a test user, like you did in the prior steps. Your event handler should receive a checkout.session.completed
event, and you should have successfully handled it.
Now that you’ve completed these steps, you’re ready to go live in production whenever you decide to do so.
Go live in production
After you’ve deployed your event handler endpoint to production, you need to register your live URL with Stripe. Follow the guide to register a webhook.