Build a custom checkout page that includes Link

Integrate Link using the Payment Element or Contact Details Element.

This guide walks you through how to accept payments with Link using the Payment Intents API and either the Payment Element or Contact Details Element.

There are three ways you can secure a customer email address for Link authentication and enrollment:

• Pass in an email address: You can pass an email address to the Payment Element using defaultValues . If you’re already collecting the email address and or customer’s phone number in the checkout flow, we recommend this approach.
• Collect an email address: You can collect an email address directly in the Payment Element. If you’re not collecting the email address anywhere in the checkout flow, we recommend this approach.
• Contact Details Element: You can use the Contact Details Element to create a single email input field for both email collection and Link authentication. We recommend doing this if you use the Address Element .

Collect a customer email address for Link authentication or enrollment

Set up Stripe Server-side

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

Command Line

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

# Available as a gem
sudo gem install stripe

Gemfile

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a PaymentIntent Server-side

Stripe uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process.

If you collect card details for future usage, see Set up future payments.

When you create a PaymentIntent, dynamically offer your customers the most relevant payment methods, including Link, by using dynamic payment methods. To use dynamic payment methods, don’t include the payment_method_types parameter.

Note

When your integration doesn’t set the payment_method_types parameter, some payment methods turn on automatically, including cards and wallets.

To add Link to your Elements integration using dynamic payment methods:

1. In your Dashboard payment method settings , turn on Link .
2. If you have an existing integration that manually lists payment methods, remove the payment_method_types parameter from your integration.

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern frontend framework like React. Create the server endpoint that serves the client secret:

main.rb

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

get '/secret' do
 intent = # ... Create or retrieve the PaymentIntent
 {client_secret: intent.client_secret}.to_json
end

And then fetch the client secret with JavaScript on the client side:

(async () => {
 const response = await fetch('/secret');
 const {client_secret: clientSecret} = await response.json();
 // Render the form using the clientSecret
})();

Collect customer email

Link authenticates a customer by using their email address. Depending on your checkout flow, you have the following options: pass an email to the Payment Element, collect it directly within the Payment Element, or use the Contact Details Element. Of these, Stripe recommends passing a customer email address to the Payment Element if available.

If any of the following apply to you:

• You want a single, optimized component for email collection and Link authentication.
• You need to collect a shipping address from your customer.

Then use the integration flow that implements these elements: the Contact Details Element, Payment Element and optional Address Element.

A Link -enabled checkout page has the Contact Details Element at the beginning, followed by the Address Element, and the Payment Element at the end. You can also display the Contact Details Element on separate pages, in this same order, for multi-page checkout flows.

Create a payment form using multiple Elements

The integration works as follows:

Set up your payment form Client-side

Now you can set up your custom payment form with the Elements prebuilt UI components. Your payment page address must start with https:// rather than http:// for your integration to work. You can test your integration without using HTTPS. Enable HTTPS when you’re ready to accept live payments.

The Contact Details Element renders an email address input. When Link matches a customer email with an existing Link account, it sends the customer a secure, one-time code to their phone to authenticate. If the customer successfully authenticates, Stripe displays their Link -saved addresses and payment methods automatically for them to use.

This integration also creates the Payment Element, which renders a dynamic form that allows your customer to pick a payment method type. The form automatically collects all necessary payments details for the payment method type selected by the customer. The Payment Element also handles the display of Link -saved payment methods for authenticated customers.

Set up Stripe Elements

Install React Stripe.js and the Stripe.js loader from the npm public registry.

Command Line

npm install --save @stripe/react-stripe-js @stripe/stripe-js

On your payment page, wrap your payment form with the Elements component, passing the client secret from the previous step. ​​If you already collect the customer’s email in another part of your form, replace your existing input with the ContactDetailsElement​.

If you don’t collect email, add the ContactDetailsElement​ to your checkout flow. You must place the ContactDetailsElement before the ShippingAddressElement (optional if you collect shipping addresses) and the PaymentElement for Link to autofill Link -saved details for your customer in the ShippingAddressElement and PaymentElement. You can also pass in the appearance option, customizing the Elements to match the design of your site.

If you have the customer’s email, pass it to the defaultValues option of the ContactDetailsElement. This prefills their email address and initiates the Link authentication process.

If you have other customer information, pass it to the defaultValues.billingDetails object for the PaymentElement. Prefilling as much information as possible simplifies Link account creation and reuse for your customers.

Then, render the ContactDetailsElement and PaymentElement components in your payment form:

Checkout.jsx

import {loadStripe} from "@stripe/stripe-js";
import {
 Elements,
 ContactDetailsElement,
 PaymentElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

// Customize the appearance of Elements using the Appearance API.
const appearance = {/* ... */};

// Enable the skeleton loader UI for the optimal loading experience.
const loader = 'auto';

The ContactDetailsElement, PaymentElement, and ShippingAddressElement don’t need to be on the same page. If you have a process where customer contact information, shipping details, and payment details display to the customer in separate steps, you can display each Element in the appropriate step or page. Include the ContactDetailsElement as the email input form in the contact info collection step to make sure the customer can take full advantage of the shipping and payment autofill provided by Link.

If you collect your customer’s email with the Contact Details Element early in the checkout flow, you don’t need to show it again on the shipping or payment pages.

Retrieve an email address

You can retrieve the email address details using the onChange prop on the ContactDetailsElement component. The onChange handler fires whenever the user updates the email field, or when a saved customer email is autofilled.

<ContactDetailsElement onChange={(event) => {
 setEmail(event.value.email);
}} />

Prefill a customer email address

The Contact Details Element accepts an email address. Providing a customer’s email address triggers the Link authentication flow as soon as the customer lands on the payment page using the defaultValues option.

<ContactDetailsElement options={{defaultValues: {email: 'foo@bar.com'}}}/>

Optional Prefill additional customer data Client-side

Optional Collect shipping addresses Client-side

Optional Customize the appearance Client-side

Submit the payment to Stripe Client-side

Use stripe.confirmPayment to complete the payment with details collected from your customer in the different Elements forms. Provide a return_url to this function to indicate where Stripe redirects the user after they complete the payment.

Your user might be first redirected to an intermediate site, like a bank authorization page, before Stripe redirects them to the return_url.

By default, card and bank payments immediately redirect to the return_url when a payment is successful. If you don’t want to redirect to the return_url, you can use if_required to change the behavior.

Checkout.jsx

The return_url corresponds to a page on your website that provides the payment status of the PaymentIntent when you render the return page. When Stripe redirects the customer to the return_url, you can use the following URL query parameters to verify payment status. You can also append your own query parameters when providing the return_url. These query parameters persist through the redirect process.

Optional Separate authorization and capture Server-side

Handle post-payment events Server-side

Stripe sends a payment_intent.succeeded event when the payment completes. Use a webhook to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Configure your integration to listen for these events rather than waiting on a callback from the client. When you wait on a callback from the client, the customer can close the browser window or quit the app before the callback executes. Setting up your integration to listen for asynchronous events enables you to accept different types of payment methods with a single integration.

In addition to handling the payment_intent.succeeded event, you can also handle two other important events when collecting payments with the Payment Element:

Test the integration

Caution

Don’t store real user data in sandbox Link accounts. Treat them as if they’re publicly available, because these test accounts are associated with your publishable key.

Link supports credit cards, debit cards, and qualified US bank account purchases.

You can create sandbox accounts for Link using any valid email address. The following table shows the fixed one-time passcode values that Stripe accepts for authenticating sandbox accounts:

For testing specific payment methods, refer to the Payment Element testing examples.

Multiple funding sources

Stripe automatically supports additional funding sources without changes to your integration. They use the same transaction settlement time and processing behavior as card and bank account payments.

Card authentication and 3D Secure

Link supports 3D Secure 2 (3DS2) authentication for card payments. 3DS2 requires customers to complete an additional verification step with the card issuer when paying. Payments that have been successfully authenticated using 3D Secure are covered by a liability shift.

To trigger 3DS2 authentication challenge flows with Link in a sandbox, use the following test card with any CVC, postal code, and future expiration date:.

In a sandbox, the authentication process displays a mock authentication page. On that page, you can either authorize or cancel the payment. Authorizing the payment simulates successful authentication and redirects you to the specified return URL. Clicking the Failure button simulates an unsuccessful attempt at authentication.

For more details, refer to the 3D Secure authentication page.

Note

When testing 3DS flows, only test cards for 3DS2 will trigger authentication on Link.

Optional Display customer-saved data Server-side Client-side

Optional Save Link payment methods Server-side Client-side

Disclose Stripe to your customers

Stripe collects information on customer interactions with Elements to provide services to you, prevent fraud, and improve its services. This includes using cookies and IP addresses to identify which Elements a customer saw during a single checkout session. You’re responsible for disclosing and obtaining all rights and consents necessary for Stripe to use data in these ways. For more information, visit our privacy center.

See also

• What’s Link
• Link with Elements
• Link in the Payment Element
• Explore the Contact Details Element
• Link in different payment integrations