What is @stripe/stripe-js?
The @stripe/stripe-js package is a JavaScript library that allows developers to integrate Stripe's payment processing capabilities into their web applications. It provides a set of tools to create and manage payment elements, handle payment intents, and securely collect payment information.
What are @stripe/stripe-js's main functionalities?
Loading Stripe.js
This code sample demonstrates how to asynchronously load the Stripe.js library using the provided publishable key. The `loadStripe` function returns a Promise that resolves with the Stripe object.
import { loadStripe } from '@stripe/stripe-js';
const stripePromise = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
Creating a Payment Element
This code sample shows how to use the `Elements` provider to inject the Stripe object into the React component tree and create a `CardElement` that collects the user's card details.
import { Elements } from '@stripe/react-stripe-js';
import { CardElement } from '@stripe/react-stripe-js';
const stripePromise = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const CheckoutForm = () => {
return (
<Elements stripe={stripePromise}>
<CardElement />
</Elements>
);
};
Handling Payment Intents
This code sample illustrates how to confirm a card payment using a PaymentIntent's client secret. It uses the `confirmCardPayment` method to handle the payment process.
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const {error, paymentIntent} = await stripe.confirmCardPayment('{CLIENT_SECRET}', {
payment_method: {
card: cardElement,
billing_details: {
name: 'Jenny Rosen'
}
}
});
Other packages similar to @stripe/stripe-js
react-stripe-elements
This package provides React components for building forms with Stripe Elements. It is similar to @stripe/stripe-js but is designed specifically for React applications. It has been deprecated in favor of @stripe/react-stripe-js, which works with the newer Stripe.js.
braintree-web
Braintree's JavaScript SDK for integrating payment processing. It offers similar functionality to @stripe/stripe-js but is tailored for Braintree's payment platform, which is a different service owned by PayPal.
square-web-sdk
Square's Web Payments SDK is an alternative to @stripe/stripe-js for integrating Square's payment processing services. It provides a different set of APIs and is designed to work with Square's ecosystem.
Stripe.js ES Module
Use Stripe.js as an ES module.
Note: To be
PCI compliant, you
must load Stripe.js directly from https://js.stripe.com
. You cannot include it
in a bundle or host it yourself. This package wraps the global Stripe
function
provided by the Stripe.js script as an ES module.
Installation
Use npm
to install the Stripe.js module:
npm install @stripe/stripe-js
Usage
loadStripe
This function returns a Promise
that resolves with a newly created Stripe
object once Stripe.js has loaded. If necessary, it will load Stripe.js for you
by inserting the Stripe.js script tag. If you call loadStripe
in a server
environment it will resolve to null
.
import {loadStripe} from '@stripe/stripe-js';
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
We’ve placed a random API key in this example. Replace it with your
actual publishable API keys to
test this code through your Stripe account.
For more information on how to use Stripe.js once it loads, please refer to the
Stripe.js API reference or learn to
accept a payment with
Stripe.
TypeScript support
This package includes TypeScript declarations for Stripe.js. We support projects
using TypeScript versions >= 3.1.
Some methods in Stripe.js accept and return objects from the
Stripe API. The type declarations in
@stripe/stripe-js
for these objects in will always track the
latest version of the Stripe API. If
you would like to use these types but are using an older version of the Stripe
API, we recommend
updating to the latest version,
or ignoring and overriding the type definitions as necessary.
Note that we may release new minor and patch versions of
@stripe/stripe-js
with small but backwards-incompatible fixes to the type
declarations. These changes will not affect Stripe.js itself.
Ensuring Stripe.js is available everywhere
To best leverage Stripe’s advanced fraud functionality, ensure that Stripe.js is
loaded on every page, not just your checkout page. This allows Stripe to detect
anomalous behavior that may be indicative of fraud as customers browse your
website.
By default, this module will insert a <script>
tag that loads Stripe.js from
https://js.stripe.com
. This happens as a side effect immediately upon
importing this module. If you utilize code splitting or only include your
JavaScript app on your checkout page, the Stripe.js script will only be
available in parts of your site. To ensure Stripe.js is available everywhere,
you can perform either of the following steps:
Import as a side effect
Import @stripe/stripe-js
as a side effect in code that will be included
throughout your site (e.g. your root module). This will make sure the Stripe.js
script tag is inserted immediately upon page load.
import '@stripe/stripe-js';
Manually include the script tag
Manually add the Stripe.js script tag to the <head>
of each page on your site.
If an existing script tag is already present, this module will not insert a new
one. When you call loadStripe
, it will use the existing script tag.
<script src="https://js.stripe.com/v3" async></script>
Stripe.js Documentation
Contributing
If you would like to contribute to React Stripe.js, please make sure to read our
contributor guidelines.