UNPKG

5.37 kBMarkdownView Raw
1# Stripe.js ES Module
2
3Use [Stripe.js](https://stripe.com/docs/stripe-js) as an ES module.
4
5**Note**: To be
6[PCI compliant](https://stripe.com/docs/security/guide#validating-pci-compliance),
7you must load Stripe.js directly from `https://js.stripe.com`. You cannot
8include it in a bundle or host it yourself. This package wraps the global
9`Stripe` function provided by the Stripe.js script as an ES module.
10
11[![npm version](https://img.shields.io/npm/v/@stripe/stripe-js.svg?style=flat-square)](https://www.npmjs.com/package/@stripe/stripe-js)
12
13## Installation
14
15Use `npm` to install the Stripe.js module:
16
17```sh
18npm install @stripe/stripe-js
19```
20
21## Usage
22
23### `loadStripe`
24
25This function returns a `Promise` that resolves with a newly created `Stripe`
26object once Stripe.js has loaded. It takes the same parameters passed when
27directly
28[initializing a `Stripe` instance](https://stripe.com/docs/js/initializing). If
29necessary, it will load Stripe.js for you by inserting the Stripe.js script tag.
30If you call `loadStripe` in a server environment it will resolve to `null`.
31
32```js
33import {loadStripe} from '@stripe/stripe-js';
34
35const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
36```
37
38We’ve placed a random API key in this example. Replace it with your
39[actual publishable API keys](https://dashboard.stripe.com/account/apikeys) to
40test this code through your Stripe account.
41
42For more information on how to use Stripe.js, please refer to the
43[Stripe.js API reference](https://stripe.com/docs/js) or learn to
44[accept a payment](https://stripe.com/docs/payments/accept-a-payment) with
45Stripe.
46
47If you have deployed a
48[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/Security/CSP),
49make sure to
50[include Stripe.js in your directives](https://stripe.com/docs/security/guide#content-security-policy).
51
52## TypeScript support
53
54This package includes TypeScript declarations for Stripe.js. We support projects
55using TypeScript versions >= 3.1.
56
57Some methods in Stripe.js accept and return objects from the
58[Stripe API](https://stripe.com/docs/api). The type declarations in
59`@stripe/stripe-js` for these objects in will always track the
60[latest version](https://stripe.com/docs/api/versioning) of the Stripe API. If
61you would like to use these types but are using an older version of the Stripe
62API, we recommend
63[updating to the latest version](https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api),
64or ignoring and overriding the type definitions as necessary.
65
66Note that we may release new [minor and patch](https://semver.org/) versions of
67`@stripe/stripe-js` with small but backwards-incompatible fixes to the type
68declarations. These changes will not affect Stripe.js itself.
69
70## Ensuring Stripe.js is available everywhere
71
72To best leverage Stripe’s advanced fraud functionality, ensure that Stripe.js is
73loaded on every page, not just your checkout page. This
74[allows Stripe to detect suspicious behavior](https://stripe.com/docs/disputes/prevention/advanced-fraud-detection)
75that may be indicative of fraud as customers browse your website.
76
77By default, this module will insert a `<script>` tag that loads Stripe.js from
78`https://js.stripe.com`. This happens as a side effect immediately upon
79importing this module. If you utilize code splitting or only include your
80JavaScript app on your checkout page, the Stripe.js script will only be
81available in parts of your site. To ensure Stripe.js is available everywhere,
82you can perform either of the following steps:
83
84### Import as a side effect
85
86Import `@stripe/stripe-js` as a side effect in code that will be included
87throughout your site (e.g. your root module). This will make sure the Stripe.js
88script tag is inserted immediately upon page load.
89
90```js
91import '@stripe/stripe-js';
92```
93
94### Manually include the script tag
95
96Manually add the Stripe.js script tag to the `<head>` of each page on your site.
97If an existing script tag is already present, this module will not insert a new
98one. When you call `loadStripe`, it will use the existing script tag.
99
100```html
101<!-- Somewhere in your site's <head> -->
102<script src="https://js.stripe.com/v3" async></script>
103```
104
105### Importing `loadStripe` without side effects
106
107If you would like to use `loadStripe` in your application, but defer loading the
108Stripe.js script until `loadStripe` is first called, use the alternative
109`@stripe/stripe-js/pure` import path:
110
111```js
112import {loadStripe} from '@stripe/stripe-js/pure';
113
114// Stripe.js will not be loaded until `loadStripe` is called
115const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
116```
117
118### Disabling advanced fraud detection signals
119
120If you would like to
121[disable advanced fraud detection](https://stripe.com/docs/disputes/prevention/advanced-fraud-detection#disabling-advanced-fraud-detection)
122altogether, use `loadStripe.setLoadParameters`:
123
124```js
125import {loadStripe} from '@stripe/stripe-js/pure';
126
127loadStripe.setLoadParameters({advancedFraudSignals: false});
128const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
129```
130
131The `loadStripe.setLoadParameters` function is only available when importing
132`loadStripe` from `@stripe/stripe-js/pure`.
133
134## Stripe.js Documentation
135
136- [Stripe.js Docs](https://stripe.com/docs/stripe-js)
137- [Stripe.js Reference](https://stripe.com/docs/js)
138- [React Stripe.js Docs](https://stripe.com/docs/stripe-js/react)