Payment links are Stripe’s no-code tool for quickly getting started with collecting payments. One thing that can be a little tricky, though, is passing data with your payment links. In this blog post, we'll show you three ways to do it!
Here’s an example URL for a test mode payment link: https://buy.stripe.com/test_dR6bLT5Ckaz2fWoeVZ`. You can visit this page and test the flow with 4242 4242 4242 4242 any future expiration and any CVC code. Notice that by default this payment link will show you a Stripe hosted confirmation page thanking you for your test purchase.
I’ve also created this payment link that will redirect instead of showing the default confirmation page: https://buy.stripe.com/test_8wM8zHe8Qaz2dOg8xA.
The code for this demo is available here: https://replit.com/@stripe/confirmation#index.js. You can fork and remix directly on Replit to experiment.
client_reference_id query string parameters
The client_reference_id query string parameter is most useful when you want to associate payments with customers in your database. It's common to use the ID of the authenticated user in your database as the value for the client_reference_id.
https://buy.stripe.com/test_8wM8zHe8Qaz2dOg8xA?client_reference_id=my-customer-id
After the customer successfully pays, you can retrieve the related Checkout Session object that relates to their payment session. The Checkout Session will contain the client_reference_id you set.
There are two common ways to get the Checkout Session after successful payment. One is to listen for the checkout.session.completed webhook event notification, which Paul covers in depth in his article about fulfilment. The other is to use the Checkout Session ID embedded in the URL when the customer redirects back to your site. In the next section, you'll learn how to configure the PaymentLink so that the Checkout Session ID is available in the URL for your confirmation page.
Checkout Session ID placeholder
To configure a Payment Link to pass the Checkout Session's ID to the confirmation page, you'll need to update the Payment Link settings. From the Payment Link edit page, on the tab for "Confirmation page," select "Don't show a confirmation page" and instead enter the URL where your customer should redirect. Anywhere in that URL you can add the literal string {CHECKOUT_SESSION_ID}. Before Stripe redirects the customer to this URL, that placeholder will be replaced with the ID of the Checkout Session.
https://buy.stripe.com/test_9AQ7vDggYgXqaC48xC
UTM query string parameters
When marketing your business it can be useful to know which marketing campaigns or channels are driving the most conversion so you can invest more in what’s working. If you're running a campaign and want to track how many payments come through from each source, you can add UTM parameters to the query string. Payment Links currently supports the following UTM codes: utm_source, utm_content, utm_medium, utm_term, and utm_campaign. When customers complete a payment, they are redirected to a URL with the UTM code parameters specified in your Payment Link URL. Note that the UTM params are not available on the Checkout Session object.
https://buy.stripe.com/test_8wM8zHe8Qaz2dOg8xA?utm_source=replit&utm_medium=blog&utm_campaign=no-code&utm_term=no-code-payments
After completing payment successfully with that test link, look in the URL for the UTM params that were passed through.
Conclusion
Combining all three approaches enables us to pass a client reference ID in the query string for a specific user and re-retrieve the checkout session on our confirmation page using the Checkout Session’s ID in the query string. We can also build attribution with UTM params that passed through the query string URL in the redirect.
https://buy.stripe.com/test_9AQ7vDggYgXqaC48xC?client_reference_id=all-together&utm_source=replit&utm_medium=blog&utm_campaign=no-code&utm_term=no-code-payments
Using Stripe Payment Links is a great way to automate your payment flows without having to write any code. Developers can easily include the links in applications, and no-coders can use them to create payments pages without any technical knowledge. Additionally, you can track payments coming through from different sources by adding UTM parameters to the query string. This makes it easy to see how well your campaigns are performing. We hope you'll find these tools helpful as you start accepting payments on your website or application.
Top comments (4)
Hi, I found your article because I do this the same way as you do but client_reference_id in checkout.session.completed event is null.
Can you, please, verify in events that your client_reference_id field is non null?
Are you creating session before serving Payment Link or are you using raw Payment Link with client_reference_id url parameter?
Parameter prefilled_email seems to work fine.
Edit: "client_reference_id can be composed of alphanumeric characters, dashes, or underscores, and be any value up to 200 characters. Invalid values are silently dropped"
Ok, that's why. I was sending email address as reference which contains invalid character "@" and that's why it's dropped.
I have tried adding client_reference_id in Payment link and its only populating in checkout session completed but not getting populating in payment_intent.payment_failed when payment is failed.
I have also tried setting metadata in Payment Link but not receiving metadata back in neither checkout session completed nor payment_intent.payment_failed (Success/Failed).
Can someone plz help me to set metadata in Payment Link and receiving this metadata in payment_intent.payment_failed Event and checkout session completed Event
@rajesh_angira I am running into same issue. Were you able to figure this out? Please let me know. Thanks!
All this possibilities, pretty important when using payment links, should be better referenced when creating a payment link, especially {CHECKOUT_SESSION_ID}!
I came up with the idea of using CHECKOUT_SESSION_ID all by myself knowing already that Checkout worked similarly...