Build a custom checkout page that includes Link

First, create a Stripe account or sign in.

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

# Available as a gem
sudo gem install stripe

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

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.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "automatic_payment_methods[enabled]"=true

Retrieve the client secret

Included in the returned PaymentIntent is a client secret, which the client side uses to securely complete the payment process instead of passing the entire PaymentIntent object. You can use different approaches to pass the client secret to the client side.

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

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

Link authenticates customer accounts using their email address. Use the Link Authentication Element, an email input Element, to both collect a customer’s email during the payment process and enable your customer to authenticate to Link.

If you previously collected email ahead of the payment process or prefer to use your own email input field, you can pass a customer’s email into the Payment Element. In this scenario, you only integrate the Payment Element, and a customer authenticates to Link directly in the payment form.

Use the Link Authentication Element (recommended)

Pass emails to the Payment Element

Collect emails with the Payment Element

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 Link Authentication Element, Payment Element and optional Address Element on your checkout page.

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

Use combinations of Elements to compose your checkout page

The integration works as follows:

Now you can set up your custom payment form with the Elements prebuilt UI components.

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

import {loadStripe} from "@stripe/stripe-js";
import {
  Elements,
  LinkAuthenticationElement,
  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';

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

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

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.

import {loadStripe} from "@stripe/stripe-js";
import {
  useStripe,
  useElements,
  Elements,
  LinkAuthenticationElement,
  PaymentElement,
  // If collecting shipping
  AddressElement,
} from "@stripe/react-stripe-js";

const stripe = loadStripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

const appearance = {/* ... */};

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

const CheckoutPage =({clientSecret}) => (
  <Elements stripe={stripe} options={{clientSecret, appearance, loader}}>
    <CheckoutForm />
  </Elements>
);

export default function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  const handleSubmit = async (event) => {
    event.preventDefault();

    const {error} = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url: "https://example.com/order/123/complete",
      },
    });

    if (error) {
      // handle error
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <h3>Contact info</h3>
      <LinkAuthenticationElement />
      {/* If collecting shipping */}
      <h3>Shipping</h3>
      <AddressElement options={{mode: 'shipping', allowedCountries: ['US']}} />
      <h3>Payment</h3>
      <PaymentElement />

      <button type="submit">Submit</button>
    </form>
  );
}

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.

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:

You can persist a Link session for your customers and automatically log them in to Link, without additional authentication. This works automatically for browsers that support persistent third-party local storage, such as Chrome and Firefox. For browsers that don’t, like Safari, you can enable persistent sessions in the following steps:

1. Retrieve a persistent_token from the PaymentIntent after an attempt to confirm it:

# Your route for redirecting before showing the results of the payment
get '/order/complete' do
  intent = Stripe::PaymentIntent.retrieve({
    id: params[:payment_intent],
    expand: ['payment_method'],
  })
  status = intent.status

  if status == 'succeeded' || status == 'processing'
    #  If a valid Link session (created during the Link authentication flow
    #  by the Payment Element code) is associated with the PaymentIntent, it
    #  will be made available on the Payment Method object.
    link_persistent_token = intent.payment_method&.link&.persistent_token

    #  If the payment was successful, show the customer a confirmation page
    redirect '/order/success', 307
  else
    #  If payment failed, display a message or allow the customer to try again
    redirect '/checkout', 307
  end
end

1. To remember the customer across browser sessions, set a cookie with the persistent_token value with the HTTP response on the server side:

LINK_PERSISTENT_TOKEN_COOKIE_NAME = 'stripe.link.persistent_token'

get '/order/complete' do
  intent = Stripe::PaymentIntent.retrieve({
    id: params[:payment_intent],
    expand: ['payment_method'],
  })
  status = intent.status

  if status == 'succeeded' || status == 'processing'
    link_persistent_token = intent.payment_method&.link&.persistent_token

    if !link_persistent_token.nil?
      # Set the cookie from the value returned on the PaymentIntent.
      response.set_cookie(
        LINK_PERSISTENT_TOKEN_COOKIE_NAME,
        {
          value: link_persistent_token,
          same_site: :strict,
          secure: true,
          httponly: true,
          expires: Time.now + (60 * 60 * 24 * 90), # 90 days from now.
        }
      )
    end

1. When you create the PaymentIntent, pass in the persistent_token value as an additional option:

# Makes cookies accessible with cookies[:name].
require 'sinatra/cookies'

LINK_PERSISTENT_TOKEN_COOKIE_NAME = 'stripe.link.persistent_token'

get '/secret' do
  intent = Stripe::PaymentIntent.create({
    amount: 1099,
    currency: 'usd',
    # In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
    automatic_payment_methods: {enabled: true}
    # The Link Persistent Token is attached to the PaymentIntent.
    payment_method_options: {
      link: {
        persistent_token: cookies[LINK_PERSISTENT_TOKEN_COOKIE_NAME],
      },
    }
  })
  {client_secret: intent.client_secret}.to_json
end

You might need to update the PaymentIntent with the persistent_token value explicitly if you create the PaymentIntent before involving the customer in confirming the payment later. You might want to use this type of configuration for recurring charges where you contact customers to confirm their payment.

Privacy implications

Based on your integration choice for Link, Stripe either provides a randomly generated value for you to store in a cookie on your domain (for example, on your checkout flow domain) or for storage on a local cache on the Stripe domain (which is also considered a cookie from a legal perspective). Stripe uses these cookies to help remember the end user on that browser for Link.

Make sure that your privacy policy tells your end users about this type of data collection, and also make sure to update your cookie banner accordingly after reviewing the cookies placed on your website. If your privacy policy doesn’t include this information, consider adding the following paragraph (or something similar) to it:

We use Stripe for payment, analytics, and other business services. Stripe collects identifying information about the devices that connect to its services, including via cookies. Stripe uses this information to operate and improve the services it provides to us, including for fraud detection. You can learn more about Stripe and read its privacy policy at https://stripe.com/privacy.

Currently, Link only works with credit cards, debit cards, and qualified US bank account purchases. Link requires domain registration.

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

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

Multiple funding sources

As Stripe adds additional funding source support, you don’t need to update your integration. Stripe automatically supports them with the same transaction settlement time and guarantees 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 test mode, use the following test card with any CVC, postal code, and future expiration date: 4000000000003220

.

In test mode, 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.