@stripe/crypto
v0.0.4
Published
Stripe Crypto loading utility
Downloads
5,629
Maintainers
forestfang-stripeReadme
Stripe Crypto JS ES Module
Use Stripe Crypto JS SDK as an ES module.
Note: This package dynamically loads the Stripe Crypto JS SDK from
https://crypto-js.stripe.com and
Stripe.js from https://js.stripe.com. 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.
Installation
Use npm to install the Stripe.js and Stripe Crypto JS module:
npm install @stripe/stripe-js @stripe/cryptoUsage
loadStripeOnramp
This function returns a Promise that resolves with a newly created
StripeOnramp object once Stripe Crypto JS SDK has loaded. If necessary, it
will load Stripe Crypto JS and Stripe.js for you by inserting the script tags.
If you call loadStripeOnramp in a server environment it will resolve to
null.
import {loadStripeOnramp} from '@stripe/crypto';
const stripeOnramp = await loadStripeOnramp('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 Crypto JS SDK, please refer to the Stripe Crypto docs.
If you have deployed a Content Security Policy, make sure to include Stripe.js in your directives.
TypeScript support
This package includes TypeScript declarations for Stripe Crypto JS SDK. We support projects using TypeScript versions >= 3.1.
Some methods in Stripe Crypto JS SDK accept and return objects from the
Stripe API. The type declarations in
@stripe/crypto 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/crypto with small but backwards-incompatible fixes to the type
declarations. These changes will not affect Stripe Crypto JS SDK itself.
Ensuring Stripe.js is available everywhere
To best leverage Stripe’s advanced fraud functionality, ensure that Stripe.js (not Stripe Crypto JS SDK) is loaded on every page, not just your page that integrates with Stripe Crypto. This allows Stripe to detect suspicious 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 loadStripeOnramp, it will use the existing script tag.
<!-- Somewhere in your site's <head> -->
<script src="https://js.stripe.com/v3" async></script>Importing loadStripeOnramp without side effects
If you would like to use loadStripeOnramp in your application, but defer
loading the Stripe.js script until loadStripeOnramp is first called, use the
alternative @stripe/crypto/pure import path:
import {loadStripeOnramp} from '@stripe/crypto/pure';
// Stripe.js will not be loaded until `loadStripe` is called
const stripeOnramp = await loadStripeOnramp('pk_test_TYooMQauvdEDq54NiTphI7jx');Disabling advanced fraud detection signals
If you would like to
disable advanced fraud detection
altogether, use loadStripe.setLoadParameters:
import {loadStripe} from '@stripe/stripe-js/pure';
import {loadStripeOnramp} from '@stripe/crypto/pure';
loadStripe.setLoadParameters({advancedFraudSignals: false});
const stripeOnramp = await loadStripeOnramp('pk_test_TYooMQauvdEDq54NiTphI7jx');The loadStripe.setLoadParameters function is only available when importing
loadStripe from @stripe/stripe-js/pure.