Set up future Link payments

First, you need a Stripe account. Register now.

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

# For detailed setup, see our quickstarts at https://stripe.com/docs/development/quickstart
bundle add stripe

To set up a payment method for future payments, you must attach it to a Customer. Create a Customer object when your customer creates an account with your business. Customer objects allow for reusing payment methods and tracking across multiple payments.

curl https://api.stripe.com/v1/customers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -X "POST"

A SetupIntent is an object that represents your intent to set up a customer’s payment method for future payments during a session and tracks the status of that session. Create a SetupIntent on your server with link and the other payment methods you want to support:

curl https://api.stripe.com/v1/setup_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]"=card \
  -d "payment_method_types[]"=link

To see how to set up other payment methods, see the Set up future payments guide.

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

get '/secret' do
  intent = # ... Create or retrieve the SetupIntent
  {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.

Collect email with Elements (recommended)

Pass email to 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 payment form. A Link-enabled checkout page has the Link Authentication Element at the beginning, followed by the optional Address Element, and the Payment Element at the end. You can also display the Link Element on separate pages, in this same order, for multi-page checkout flows.

Use combinations of Elements to compose your payment experience.

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';

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

export default function CheckoutForm() {
  return (
    <form>
      <h3>Contact info</h3>
      <LinkAuthenticationElement
        // Optional prop for prefilling customer information
        options={{
          defaultValues: {
            email: 'foo@bar.com',
          },
        }}
      />
      <h3>Payment</h3>
      <PaymentElement
        // Optional prop for prefilling customer information
        options={{
          defaultValues: {
            billingDetails: {
              name: 'John Doe',
              phone: '888-888-8888',
            },
          },
        }}
      />;
      <button type="submit">Submit</button>
    </form>
  );
}

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

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

Use stripe.confirmSetup to complete the setup with the details you collected. Provide a return_url to this function so that Stripe can redirect users after they complete their setup. When a payment is successful, Stripe immediately redirects Link and card payments to the return_url.

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.confirmSetup({
      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>
  );
}

To provide your customers with the best experience, 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 three following steps:

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

# Your route for redirecting before showing the results of the payment
get '/order/complete' do
  intent = Stripe::SetupIntent.retrieve({
    id: params[:setup_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 SetupIntent, 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::SetupIntent.retrieve({
    id: params[:setup_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 SetupIntent.
      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

    redirect '/order/success', 307
  else
    redirect '/checkout', 307
  end
end

1. When you create the SetupIntent, 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::SetupIntent.create({
    customer: '{{CUSTOMER_ID}}',
    payment_method_types: ['link', 'card'],
    # The Link Persistent Token is attached to the SetupIntent.
    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 SetupIntent with the persistent_token value explicitly if you create the SetupIntent 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 in Elements, Stripe either provides a randomly generated value for you to store in a cookie on your domain (e.g. 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). We use these cookies to help remember the end user on that browser for Link. You should ensure that your own privacy policy tells your end users about this type of data collection, and also update your cookie banner accordingly after reviewing the cookies placed on your website. Here is a paragraph you could add to your privacy policy if it does not already include such a disclosure:

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.

When you’re ready to charge your customer, use the Customer and PaymentMethod IDs to create a PaymentIntent. To find a payment method to charge, list the payment methods associated with your customer.

curl https://api.stripe.com/v1/payment_methods \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "type"="link" \
  -G

When you have the Customer and PaymentMethod IDs, create a PaymentIntent with the amount and currency of the payment with these parameters:

• Set the value of the PaymentIntent’s confirm property to true, which causes confirmation to occur immediately when the PaymentIntent is created.
• Set payment_method to the ID of the PaymentMethod
• Set customer to the ID of the Customer.
• Set off_session to true. This causes the PaymentIntent to send an error if authentication is required when your customer isn’t actively using your site or app.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d amount=1099 \
  -d currency=usd \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d off_session=true \
  -d confirm=true

Currently Link only works with credit cards, debit cards, and US bank accounts (for qualifying purchases). To give your customers more payment options at checkout, Stripe is working to add additional funding sources to Link. Periodically test your checkout flow to confirm the look and feel of your payments page is what you expect.

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

Currently, Link only works with credit cards, debit cards, and US bank accounts for qualifying purchases. But as Stripe adds additional funding sources, Link automatically supports them with instant confirmation for your company’s payments, and the same transaction settlement timeline and guarantees as cards and bank account-funded payments. This adaptive support means that you don’t need to update your integration to let your customers save and reuse their preferred payment method on your domain.

To test that your integration can handle additional funding sources, provide an email in the form of {any_prefix}+multiple_funding_sources@{any_domain} when you’re testing your check out flow with Link.

Card authentication and 3D Secure

Link supports 3D Secure (3DS) authentication for card payments. 3DS 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 3DS 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.