1 | # Stripe.js ES Module
|
2 |
|
3 | Use [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),
|
7 | you must load Stripe.js directly from `https://js.stripe.com`. You cannot
|
8 | include 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 |
|
15 | Use `npm` to install the Stripe.js module:
|
16 |
|
17 | ```sh
|
18 | npm install @stripe/stripe-js
|
19 | ```
|
20 |
|
21 | ## Usage
|
22 |
|
23 | ### `loadStripe`
|
24 |
|
25 | This function returns a `Promise` that resolves with a newly created `Stripe`
|
26 | object once Stripe.js has loaded. It takes the same parameters passed when
|
27 | directly
|
28 | [initializing a `Stripe` instance](https://stripe.com/docs/js/initializing). If
|
29 | necessary, it will load Stripe.js for you by inserting the Stripe.js script tag.
|
30 | If you call `loadStripe` in a server environment it will resolve to `null`.
|
31 |
|
32 | ```js
|
33 | import {loadStripe} from '@stripe/stripe-js';
|
34 |
|
35 | const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
|
36 | ```
|
37 |
|
38 | We’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
|
40 | test this code through your Stripe account.
|
41 |
|
42 | For 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
|
45 | Stripe.
|
46 |
|
47 | If you have deployed a
|
48 | [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/Security/CSP),
|
49 | make sure to
|
50 | [include Stripe.js in your directives](https://stripe.com/docs/security/guide#content-security-policy).
|
51 |
|
52 | ## TypeScript support
|
53 |
|
54 | This package includes TypeScript declarations for Stripe.js. We support projects
|
55 | using TypeScript versions >= 3.1.
|
56 |
|
57 | Some 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
|
61 | you would like to use these types but are using an older version of the Stripe
|
62 | API, we recommend
|
63 | [updating to the latest version](https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api),
|
64 | or ignoring and overriding the type definitions as necessary.
|
65 |
|
66 | Note 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
|
68 | declarations. These changes will not affect Stripe.js itself.
|
69 |
|
70 | ## Ensuring Stripe.js is available everywhere
|
71 |
|
72 | To best leverage Stripe’s advanced fraud functionality, ensure that Stripe.js is
|
73 | loaded 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)
|
75 | that may be indicative of fraud as customers browse your website.
|
76 |
|
77 | By 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
|
79 | importing this module. If you utilize code splitting or only include your
|
80 | JavaScript app on your checkout page, the Stripe.js script will only be
|
81 | available in parts of your site. To ensure Stripe.js is available everywhere,
|
82 | you can perform either of the following steps:
|
83 |
|
84 | ### Import as a side effect
|
85 |
|
86 | Import `@stripe/stripe-js` as a side effect in code that will be included
|
87 | throughout your site (e.g. your root module). This will make sure the Stripe.js
|
88 | script tag is inserted immediately upon page load.
|
89 |
|
90 | ```js
|
91 | import '@stripe/stripe-js';
|
92 | ```
|
93 |
|
94 | ### Manually include the script tag
|
95 |
|
96 | Manually add the Stripe.js script tag to the `<head>` of each page on your site.
|
97 | If an existing script tag is already present, this module will not insert a new
|
98 | one. 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 |
|
107 | If you would like to use `loadStripe` in your application, but defer loading the
|
108 | Stripe.js script until `loadStripe` is first called, use the alternative
|
109 | `@stripe/stripe-js/pure` import path:
|
110 |
|
111 | ```js
|
112 | import {loadStripe} from '@stripe/stripe-js/pure';
|
113 |
|
114 | // Stripe.js will not be loaded until `loadStripe` is called
|
115 | const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
|
116 | ```
|
117 |
|
118 | ### Disabling advanced fraud detection signals
|
119 |
|
120 | If you would like to
|
121 | [disable advanced fraud detection](https://stripe.com/docs/disputes/prevention/advanced-fraud-detection#disabling-advanced-fraud-detection)
|
122 | altogether, use `loadStripe.setLoadParameters`:
|
123 |
|
124 | ```js
|
125 | import {loadStripe} from '@stripe/stripe-js/pure';
|
126 |
|
127 | loadStripe.setLoadParameters({advancedFraudSignals: false});
|
128 | const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
|
129 | ```
|
130 |
|
131 | The `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)
|