Fulfil Checkout and Payment Link payments
Learn how to fulfil payments received with Checkout and Payment Links.
When you receive a payment, you might need to take action to provide your customer with what they paid for. For example, you might need to grant them access to a service, or you might need to ship them physical goods. This process is known as fulfilment, and you have two ways to handle this process when using Checkout and Payment Links:
- Manually: You can manually fulfil orders using information that Stripe makes available to you. For example, you can monitor the Dashboard, check payment notification emails, or look at reports and then fulfil orders.
- Automatically: You can build an automated fulfilment system. Recommended
The first option works for low volume or experimental ventures, but for most situations we recommend automating fulfilment. The rest of this guide shows you how to build an automatic fulfilment system.
Automatic fulfilment![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The automatic fulfilment system outlined below uses a combination of webhooks and a redirect to your website to trigger fulfilment. You must use webhooks to make sure fulfilment happens for every payment, and redirects let your customers access services or fulfilment details immediately after paying.
Note
Payment Links use Checkout, so all the information below applies to both Payment Links and Checkout unless otherwise noted.
Create a fulfilment functionServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Create a function on your server to fulfil Checkout payments. Webhooks trigger this function, and it’s called when customers are sent to your website after completing Checkout. This guide refers to this function as fulfill_
, but you can name the function whatever you wish.
Your fulfill_
function must:
- Correctly handle being called multiple times with the same Checkout Session ID.
- Accept a Checkout Session ID as an argument.
- Retrieve the Checkout Session from the API with the line_items property expanded.
- Check the payment_status property to determine if it requires fulfilment.
- Perform fulfilment of the line items.
- Record fulfilment status for the provided Checkout Session.
Use the code below as a starting point for your fulfill_
function. The TODO
comments indicate any functionality you must implement.
Note
The code snippets below might name the fulfill_
function fulfillCheckout
or FulfillCheckout
depending on the language selected, but they all represent the same function.
Note
If a Checkout Session has many line items, use auto-pagination with the API for Checkout line items to retrieve all of them.
Depending on the payment methods you accept and your business needs, you might want to have your fulfill_
function do the following:
- Provision access to services.
- Trigger shipment of goods.
- Save a copy of the payment details and line items in your own database.
- Send the customer a custom receipt email if you don’t have Stripe’s receipts enabled.
- Reconcile line items and quantities purchased if you allow customers to adjust quantities in Checkout.
- Update inventory or stock records.
Create a payment event handlerServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To trigger fulfilment, create a webhook event handler to listen for payment events and trigger your fulfill_
function.
When someone pays you with Checkout, it creates a checkout.
event. Set up an endpoint on your server to accept, process, and confirm receipt of these events.
Some payment methods aren’t instant, such as ACH direct debit and other bank transfers. Funds won’t be immediately available when Checkout completes. Delayed payment methods generate a checkout.
event when payment succeeds later.
Note
The webhook secret (whsec_
) shown in the code below comes from either the Stripe CLI or your webhook endpoint. You can use the Stripe CLI for local testing, and Stripe uses a webhook endpoint to send events to your handler when it’s running on a server. See the next section for more details.
You might also want to listen for and handle checkout.
events. For example, you can send an email to your customer when a delayed payment fails.
Test your event handler locally![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The quickest way to develop and test your webhook event handler is with the Stripe CLI. If you don’t have the Stripe CLI, follow the install guide to get started.
When the Stripe CLI is installed, you can test your event handler locally. Run your server (for example, on localhost:4242
), then run the stripe listen command to get the Stripe CLI to forward events to your local server:
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)
Add the webhook secret (whsec_
) to your event handling code, then test fulfilment by going through Checkout as a customer:
- Press the checkout button that takes you to Checkout, or visit your Payment Link
- Provide the following test data in Checkout:
- Enter
4242 4242 4242 4242
as the card number - Enter any future date for card expiry
- Enter any 3-digit number for CVV
- Enter any billing postal code (
90210
)
- Enter
- Press the Pay button
When the payment completes, verify the following:
- On your command line, where
stripe listen
is running, it shows acheckout.
event forwarded to your local server.session. completed - Your server logs show the expected output from your
fulfill_
function.checkout
Create a webhook endpoint![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After testing locally, get your webhook event handler up and running on your server. Next, create a webhook endpoint to send checkout.
events to your server, then test the Checkout flow again.
Configure a landing page URLRecommended![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Configure Checkout to send your customer to a page on your website after they complete Checkout. Include the {CHECKOUT_
placeholder in your page’s URL, which is replaced with the Checkout Session ID when your customer is redirected from Checkout.
Hosted Checkout![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
For Checkout Sessions with the default ui_mode of hosted
, set the success_
.
Note
When you have a webhook endpoint set up to listen for checkout.
events and you set a success_
, Checkout waits for your server to respond to the webhook event delivery before redirecting your customer. If you use this approach, make sure your server responds to checkout.
events as quickly as possible.
Checkout with a non-default ui_mode![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
For Checkout Sessions with ui_mode not set to hosted
, set the return_
.
Payment Links![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
For Payment Links you create with the API, set the after_completion.redirect.url.
For Payment Links you create in the Dashboard:
- Go to the After Payment tab.
- Select Don’t show confirmation page.
- Provide the URL to your landing page that includes the
{CHECKOUT_
placeholder (for example,SESSION_ ID} https://example.
)com/after-checkout?session_ id={CHECKOUT_ SESSION_ ID}
Trigger fulfilment on your landing pageRecommended![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Listening to webhooks is required to make sure you always trigger fulfilment for every payment, but webhooks can sometimes be delayed. To optimise your payment flow and guarantee immediate fulfilment when your customer is present, trigger fulfilment from your landing page as well.
Use the Checkout Session ID from the URL you specified in the previous step to do the following:
- When your server receives a request for your Checkout landing page, extract the Checkout Session ID from the URL.
- Run your
fulfill_
function with the ID provided.checkout - Render the page after the fulfilment attempt is complete.
When you render your landing page, you can display the following:
- Details from the fulfilment process.
- Links or information about services the customer now has access to.
- Shipping or logistical details for physical goods.
Webhooks are required
You can’t rely on triggering fulfilment only from your Checkout landing page, because your customers aren’t guaranteed to visit that page. For example, someone can pay successfully in Checkout and then lose their connection to the internet before your landing page loads.
Set up a webhook event handler to get Stripe to send payment events directly to your server, bypassing the client entirely. Webhooks are the most reliable way to know when you get paid. If webhook event delivery fails, we retry several times.