Stripe Elements Reference

Contents

• Including the JavaScript library
• The stripe object
• The elements object
• The Element
• The Element container

Including the JavaScript library

Elements is available as part of Stripe.js. To get started, include this script on your pages—it should always be loaded directly from https://js.stripe.com:

<script src="https://js.stripe.com/v3/"></script>

To best leverage Stripe’s advanced fraud functionality, include this script on every page on your site, not just the checkout page.

Setting your publishable key

Initializing a stripe object requires your Stripe publishable API key. This identifies your website to Stripe:

var stripe = Stripe('pk_test_6pRNASCoBOKtIshFeQd4XMUh');

const stripe = Stripe('pk_test_6pRNASCoBOKtIshFeQd4XMUh');

We've placed a random API key in the code. Replace it with your actual publishable API key to test this code through your Stripe account.

When you’re ready to accept live payments, replace the test key with your live key in production. Learn more about how API keys work in test mode and live mode.

The stripe object

• stripe.elements([options])
• stripe.createToken(element[, options])

stripe.elements([options])

var elements = stripe.elements();

const elements = stripe.elements();

This method creates an instance of elements, which manages a group of Elements. It accepts an optional options object. Available options are documented below.

Elements options

stripe.createToken(element[, options])

Use stripe.createToken to convert the payment data collected by Elements into a single-use token that you safely pass to your server and use when creating charges, setting up subscriptions, or sending transfers to debit cards attached to connected Stripe accounts.

stripe.createToken(card).then(function(result) {
  // handle result.error or result.token
});

const {token, error} = await stripe.createToken(card);

stripe.createToken takes two arguments:

• element: the Element you wish to tokenize data from. The Element will pull data from other Elements you’ve created on the same instance of elements to tokenize.
• options: an optional JavaScript object with any of the following parameters:

Although these fields are optional, we highly recommend collecting name and address. This information can be used to perform a number of verifications, such as CVC, ZIP, and address verification. Radar includes built-in rules that can block payments where the ZIP or CVC verifications with the cardholder’s bank failed.

stripe.createToken returns a Promise which resolves with a result object. This object has either:

• result.token: a Token was created successfully.
• result.error: there was an error. This includes client-side validation errors. Refer to the API reference for all possible errors.

The elements object

• elements.create(type[, options])

elements.create(type[, options])

var card = elements.create('card');

const card = elements.create('card');

This method creates an instance of a specific Element.

It takes the type of Element to create as well as an optional options object.

Element types

Element options

Here is an example that customizes the base and invalid states of a card Element:

var style = {
  base: {
    color: '#303238',
    fontSize: '16px',
    lineHeight: '48px',
    fontSmoothing: 'antialiased',
    '::placeholder': {
      color: '#ccc',
    },
  },
  invalid: {
    color: '#e5424d',
    ':focus': {
      color: '#303238',
    },
  },
};
var cardElement = elements.create('card', {style: style})

const style = {
  base: {
    color: '#303238',
    fontSize: '16px',
    lineHeight: '48px',
    fontSmoothing: 'antialiased',
    '::placeholder': {
      color: '#ccc',
    },
  },
  invalid: {
    color: '#e5424d',
    ':focus': {
      color: '#303238',
    },
  },
};
const cardElement = elements.create('card', {style})

The Element

• element.mount(domElement)
• element.on(event, handler)
• Other methods
  • element.blur()
  • element.focus()
  • element.unmount()
  • element.update(options)

element.mount(domElement)

You will need to create a container DOM element in order to mount an Element. If it has a label, it will be automatically focused when its label is clicked. There are two ways to do this:

1. Mount the instance within a <label>.

   <label>Card
     <div id="card-element"></div>
   </label>

2. Create a <label> with a for attribute, referencing the ID of your container.

   <label for="card-element">Card</label>
   <div id="card-element"></div>

The mount method attaches your element to the DOM. mount accepts either a CSS Selector (e.g. '#card-element') or a DOM element.

cardElement.mount('#card-element');

element.on(event, handler)

Attach an event listener to listen for Element events. The following events can be triggered:

Elements validates user input as it is typed. To help your customers catch mistakes, you should listen to change events on the card Element and display any errors:

card.addEventListener('change', function(event) {
  var displayError = document.getElementById('card-errors');
  if (event.error) {
    displayError.textContent = event.error.message;
  } else {
    displayError.textContent = '';
  }
});

card.addEventListener('change', ({error}) => {
  const displayError = document.getElementById('payment-errors');
  if (error) {
    displayError.textContent = error.message;
  }
});

Other methods

If you collect certain information in a different part of your interface (e.g. ZIP or postal code), use update() with the appropriate information.

document.querySelector('input[name="my-postal-code"]').on('change', function(event) {
  card.update({value: {postalCode: event.target.value}});
});

document.querySelector('input[name="my-postal-code"]').on('change', ({target}) => {
  card.update({value: {postalCode: target.value}});
});

You can also dynamically change the styles of an Element:

window.addEventListener('resize', function(event) {
  if (window.innerWidth <= 320) {
    card.update({style: {base: {fontSize: '13px'}}});
  } else {
    card.update({style: {base: {fontSize: '16px'}}});
  }
});

var previousBrand;
card.on('change', function(event) {
  if (event.brand !== previousBrand && event.brand === 'mastercard') {
    card.update({style: {base: {color: 'orange'}}});
    previousBrand = payload.brand;
  }
});

window.addEventListener('resize', (event) => {
  if (window.innerWidth <= 320) {
    card.update({style: {base: {fontSize: '13px'}}});
  } else {
    card.update({style: {base: {fontSize: '16px'}}});
  }
});

let previousBrand;
card.on('change', ({brand}) => {
  if (brand !== previousBrand && brand === 'mastercard') {
    card.update({style: {base: {color: 'orange'}}});
    previousBrand = payload.brand;
  }
});

The Element container

You should style the container you mount an Element to as if it were an <input> on your page. For example, to control padding and border on an Element, set these properties on the container. This is usually done by re-using the classes that you have applied to your DOM <input>s. Example:

<style>
 .my-input {
   padding: 10px;
   border: 1px solid #ccc;
 }
</style>

<form>
  <div>
    <label>Name</label>
    <input class="my-input">
  </div>
  <div>
    <label>Card</label>
    <!-- Using the same "my-input" class on the -->
    <!-- regular input above and on this container. -->
    <div class="my-input" id="card-element"></div>
  </div>
</form>

After the Element is mounted, the .StripeElement class is added to the container. Additionally, the following classes are automatically added to the container when the Element is complete, empty, focused, invalid, or autofilled by the browser:

• .StripeElement--complete
• .StripeElement--empty
• .StripeElement--focus
• .StripeElement--invalid
• .StripeElement--webkit-autofill (Chrome and Safari only)

You can override these class names using the classes option when you create an Element.