Stripe.js

https://github.com/stripe/stripe-js
Admin
Stripe.js is a lightweight JavaScript library that provides a secure and customizable way to collect...
Tokens:103,709
Snippets:557
Trust Score:9.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies with yarn install

Source: https://github.com/stripe/stripe-js/blob/master/CONTRIBUTING.md

Run this command in the project root to install all required dependencies before development.

```sh
yarn install
```

--------------------------------

### confirmSetup example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Example of confirming a SetupIntent with the Payment Element. Creates elements with a client secret, mounts the payment element, then calls confirmSetup with redirect: 'if_required' and handles any error.

```javascript
const elements = stripe.elements({clientSecret: 'seti_xxx_secret_yyy'});
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

const {error} = await stripe.confirmSetup({
  elements,
  confirmParams: {return_url: 'https://example.com/return'},
  redirect: 'if_required',
});
if (error) showError(error.message);
```

--------------------------------

### registerAppInfo Usage Example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-object.md

JavaScript example showing how to call stripe.registerAppInfo with a WrapperLibrary object.

```javascript
stripe.registerAppInfo({
  name: 'my-react-library',
  version: '1.2.3',
  url: 'https://example.com',
});
```

--------------------------------

### Create and use StripeAddressElement

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-address.md

JavaScript example showing how to create an address element with mode 'shipping', require phone, restrict to US and CA, listen for change events, mount it, and get its value asynchronously.

```javascript
const addressElement = elements.create('address', {
  mode: 'shipping',
  fields: {phone: 'always'},
  validation: {phone: {required: 'always'}},
  allowedCountries: ['US', 'CA'],
});
addressElement.on('change', ({complete, value}) => {
  console.log('Address complete:', complete, value);
});
addressElement.mount('#shipping-address');

const {complete, value} = await addressElement.getValue();
if (complete) {
  // value.address.line1, value.name, ...
}
```

--------------------------------

### Basic card tokenization example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-tokens-sources.md

JavaScript example showing how to create a card element, mount it, and call stripe.createToken with the element and card data. The resulting token or error is handled.

```javascript
const cardElement = elements.create('card');
cardElement.mount('#card-element');

const {token, error} = await stripe.createToken(cardElement, {
  name: 'Jenny Rosen',
  address_country: 'US',
});
if (error) showError(error.message);
```

--------------------------------

### createPaymentMethod JavaScript Example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-payment-intents.md

Example of creating a card PaymentMethod with billing details. Logs error message if creation fails.

```javascript
const {error, paymentMethod} = await stripe.createPaymentMethod({
  type: 'card',
  card: cardElement,
  billing_details: {name: 'Jenny Rosen'},
});
if (error) console.error(error.message);
```

--------------------------------

### confirm*Setup family

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

All confirm*Setup methods share the signature (clientSecret: string, data?: Data, options?: Options): Promise<SetupIntentResult>. They automatically run next actions (3DS, mandate modal, redirects). The following methods are available: confirmCardSetup, confirmCashappSetup, confirmBlikSetup, confirmIdealSetup, confirmAmazonPaySetup, confirmPayPalSetup, confirmSepaDebitSetup, confirmSofortSetup, confirmAuBecsDebitSetup, confirmBacsDebitSetup, confirmBancontactSetup, confirmAcssDebitSetup, confirmUsBankAccountSetup.

```APIDOC
## confirm*Setup family

### Description
All confirm*Setup methods share the signature `(clientSecret: string, data?: Data, options?: Options): Promise<SetupIntentResult>`. They automatically run next actions (3DS, mandate modal, redirects).

### Methods

| Method | Data type | Options type | Notes |
|---|---|---|---|
| `confirmCardSetup` | `ConfirmCardSetupData` | `ConfirmCardSetupOptions` | |
| `confirmCashappSetup` | `ConfirmCashappSetupData` | `ConfirmCashappSetupOptions` | |
| `confirmBlikSetup` | `ConfirmBlikSetupData` | `ConfirmBlikSetupOptions` | `data` required; `payment_method_options.blik.code` (6-digit BLIK code) required |
| `confirmIdealSetup` | `ConfirmIdealSetupData` | — | |
| `confirmAmazonPaySetup` | `ConfirmAmazonPaySetupData` | — | `return_url` required |
| `confirmPayPalSetup` | `ConfirmPayPalSetupData` | — | `return_url` required |
| `confirmSepaDebitSetup` | `ConfirmSepaDebitSetupData` | — | |
| `confirmSofortSetup` | `ConfirmSofortSetupData` | `ConfirmSofortSetupOptions` | |
| `confirmAuBecsDebitSetup` | `ConfirmAuBecsDebitSetupData` | — | beta |
| `confirmBacsDebitSetup` | `ConfirmBacsDebitSetupData` | — | |
| `confirmBancontactSetup` | `ConfirmBancontactSetupData` | — | |
| `confirmAcssDebitSetup` | `ConfirmAcssDebitSetupData` | `ConfirmAcssDebitSetupOptions` | pops bank-account modal; options `{skipMandate?: boolean}` |
| `confirmUsBankAccountSetup` | `ConfirmUsBankAccountSetupData` | — | |

### Parameters

All methods accept the following parameters:

- `clientSecret` (string) - Required - The client secret of the SetupIntent.
- `data` (Data) - Optional - The data object specific to the method. Data types with no dedicated entry extend `SetupIntentConfirmParams` and add `payment_method?: string | Omit<CreatePaymentMethodXxxData, 'type'>` (a PaymentMethod id, or data to create one — optional if already attached).
- `options` (Options) - Optional - Options object. Options types (`ConfirmCardSetupOptions`, `ConfirmCashappSetupOptions`, `ConfirmBlikSetupOptions`, `ConfirmSofortSetupOptions`) each define `handleActions?: boolean` (default `true`; `false` defers next-action handling to you).

### Return Value

Returns a `Promise<SetupIntentResult>`.

### Example

```js
const {error, setupIntent} = await stripe.confirmCardSetup(
  'seti_xxx_secret_yyy',
  {
    payment_method: {
      card: cardElement,
      billing_details: {name: 'Jenny Rosen'},
    },
  }
);
if (error) showError(error.message);
```
```

--------------------------------

### Example: dynamic shipping with shippingaddresschange

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/payment-request.md

JavaScript example showing how to handle the 'shippingaddresschange' event and call updateWith to provide updated total, display items, and shipping options.

```JavaScript
paymentRequest.on('shippingaddresschange', (event) => {
  event.updateWith({
    status: 'success',
    total: {label: 'Total', amount: 1500},
    displayItems: [{label: 'Shipping', amount: 400}],
    shippingOptions: [
      {id: 'standard', label: 'Standard', detail: '3-5 days', amount: 400},
      {id: 'express', label: 'Express', detail: '1-2 days', amount: 900},
    ],
  });
});
```

--------------------------------

### Full lifecycle example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-group.md

Example showing the complete lifecycle of Stripe Elements: loading Stripe, creating elements, mounting a payment element, submitting, confirming payment, updating, and listening for events.

```APIDOC
## Example: full lifecycle

### Description
Demonstrates the complete lifecycle of Stripe Elements, from loading Stripe to confirming a payment and updating the elements.

### Code
```js
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements({
  clientSecret: 'pi_xxx_secret_yyy',
  appearance: {theme: 'stripe'},
});

const paymentElement = elements.create('payment', {layout: 'tabs'});
paymentElement.mount('#payment-element');

await elements.submit();                 // validate + collect wallet data
const {error} = await stripe.confirmPayment({
  elements,
  confirmParams: {return_url: 'https://example.com/return'},
  redirect: 'if_required',
});

elements.update({locale: 'fr'});         // shallow merge; resolves when applied
elements.on('update-end', () => console.log('updated'));
```
```

--------------------------------

### Example: Dynamic Shipping

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/payment-request.md

Example of handling the 'shippingaddresschange' event to update shipping options dynamically.

```APIDOC
## Example: Dynamic Shipping

### Description
This example shows how to listen for the 'shippingaddresschange' event and call `updateWith` to provide updated shipping options and totals.

### Code Example
```js
paymentRequest.on('shippingaddresschange', (event) => {
  event.updateWith({
    status: 'success',
    total: {label: 'Total', amount: 1500},
    displayItems: [{label: 'Shipping', amount: 400}],
    shippingOptions: [
      {id: 'standard', label: 'Standard', detail: '3-5 days', amount: 400},
      {id: 'express', label: 'Express', detail: '1-2 days', amount: 900},
    ],
  });
});
```
```

--------------------------------

### SetupIntent

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/types.md

The SetupIntent object represents a setup intent in Stripe. It contains details about the setup, including status, payment method, and usage.

```APIDOC
## SetupIntent

### Description
The SetupIntent object represents a setup intent in Stripe. It contains details about the setup, including status, payment method, and usage.

### Shape
```typescript
{
  id: string;
  object: 'setup_intent';
  cancellation_reason: string | null;
  client_secret: string | null;
  created: number;
  description: string | null;
  last_setup_error: object | null;
  livemode: boolean;
  next_action: object | null;
  payment_method: string | null;
  payment_method_types: Array<string>;
  status: SetupIntent.Status;
  usage: string;
}
```

### Source
`types/api/setup-intents.d.ts:6`
```

--------------------------------

### Install @stripe/stripe-js with npm

Source: https://github.com/stripe/stripe-js/blob/master/README.md

Use this command to install the Stripe.js module. Requires Node.js v12.16 and TypeScript v3.1.1 or later.

```sh
npm install @stripe/stripe-js
```

--------------------------------

### confirmCardSetup example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Example of calling stripe.confirmCardSetup with a client secret and payment method data, including a card element and billing details. The result contains error and setupIntent; on error, showError is called with the error message.

```javascript
const {error, setupIntent} = await stripe.confirmCardSetup(
  'seti_xxx_secret_yyy',
  {
    payment_method: {
      card: cardElement,
      billing_details: {name: 'Jenny Rosen'},
    },
  }
);
if (error) showError(error.message);
```

--------------------------------

### Embedded Checkout example with fetchClientSecret

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/embedded-checkout.md

JavaScript example showing how to create an embedded Checkout page with a lazy client secret fetch, handle completion, track analytics, and mount it to a DOM element.

```javascript
const embeddedCheckout = await stripe.createEmbeddedCheckoutPage({
  fetchClientSecret: async () => {
    const res = await fetch('/create-checkout-session', {method: 'POST'});
    return (await res.json()).clientSecret;
  },
  onComplete: () => {
    embeddedCheckout.unmount();
    showSuccessUI();
  },
  onAnalyticsEvent: (event) => {
    track(event.eventType, event.details);
  },
});

embeddedCheckout.mount('#checkout');
```

--------------------------------

### Initialize Checkout SDK and Handle Payment

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/checkout-sdk.md

Initializes the Checkout SDK with a client secret and appearance options, creates a payment element with a tabs layout, mounts it, listens for changes to update the UI, loads available actions, and confirms the payment on button click. The example shows error handling for loadActions and confirm.

```javascript
const sdk = stripe.initCheckoutElementsSdk({
  clientSecret: csClientSecret,
  elementsOptions: {appearance: {theme: 'night'}},
});

const checkoutElements = sdk.createPaymentElement({
  layout: {type: 'tabs'},
});
checkoutElements.mount('#payment-element');

sdk.on('change', (session) => {
  payButton.disabled = !session.canConfirm;
  totalLabel.textContent = session.total.amount;
});

const {type, actions, error} = await sdk.loadActions();
if (type === 'error') {
  console.error(error.message);
  return;
}
payButton.addEventListener('click', async () => {
  const result = await actions.confirm({returnUrl: 'https://example.com/return'});
  if (result.type === 'error') showError(result.error.message);
});
```

--------------------------------

### Create and use a card element

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-card.md

Example of creating a card element with options, listening to the change event to enable a pay button, mounting it, and creating a payment method. The change event provides complete and error fields.

```JavaScript
const cardElement = elements.create('card', {
  style: {base: {fontSize: '16px', color: '#424770'}},
  hidePostalCode: true,
});
cardElement.on('change', ({complete, error}) => {
  payButton.disabled = !complete;
  if (error) showError(error.message);
});
cardElement.mount('#card-element');

const {error} = await stripe.createPaymentMethod({
  type: 'card',
  card: cardElement,
});
if (error) console.error(error.message);
```

--------------------------------

### loadStripe with options and error handling

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/load-stripe.md

Example using the pure entry point '@stripe/stripe-js/pure' with constructor options (stripeAccount, apiVersion, locale) and error handling. It checks for null to handle server-side rendering environments.

```javascript
import {loadStripe} from '@stripe/stripe-js/pure';

try {
  const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
    stripeAccount: 'acct_24BFMpJ1svR5A89k',
    apiVersion: '2024-06-20',
    locale: 'auto',
  });
  if (stripe === null) {
    // server-side render / SSR environment
    return;
  }
} catch (error) {
  console.error('Stripe.js failed to load', error);
}
```

--------------------------------

### Create and Mount Express Checkout Element

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-express-checkout.md

This example shows how to create an Express Checkout Element with specified options, handle the 'confirm' event to confirm a payment, and mount the element to the DOM.

```APIDOC
## Create and Mount Express Checkout Element

### Description
Creates an Express Checkout Element with the specified options, attaches a 'confirm' event listener to handle payment confirmation, and mounts the element to the DOM.

### Method
`elements.create`

### Parameters
#### Options
- **buttonHeight** (number) - Optional - The height of the payment button in pixels.
- **buttonType** (object) - Optional - An object specifying the button type for each payment method. Example: `{applePay: 'buy', googlePay: 'pay'}`.
- **layout** (object) - Optional - An object specifying the layout of the element. Example: `{maxColumns: 2, type: 'single'}`.
- **paymentMethods** (object) - Optional - An object specifying the payment methods to display. Example: `{applePay: 'auto', googlePay: 'auto'}`.

### Event: 'confirm'
- **event** (object) - The event object containing a `resolve` function to resolve the payment confirmation result.

### Request Example
```js
const expressCheckoutElement = elements.create('expressCheckout', {
  buttonHeight: 48,
  buttonType: {applePay: 'buy', googlePay: 'pay'},
  layout: {maxColumns: 2, type: 'single'},
  paymentMethods: {applePay: 'auto', googlePay: 'auto'},
});

expressCheckoutElement.on('confirm', async (event) => {
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {return_url: 'https://example.com/return'},
    redirect: 'if_required',
  });
  event.resolve({error});
});
expressCheckoutElement.mount('#express-checkout');
```

### Response
#### Success Response
- **error** (object) - Optional - An error object if the payment confirmation fails; otherwise `null`.

#### Response Example
```js
// The event.resolve({error}) call resolves the confirm event with the result.
```
```

--------------------------------

### processOrder example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-orders.md

Example of using processOrder with the Payment Element. Creates an Elements instance with the order client secret, mounts the payment element, and calls processOrder with redirect 'if_required'.

```javascript
const elements = stripe.elements({clientSecret: orderClientSecret});
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

const {error, order} = await stripe.processOrder({
  elements,
  confirmParams: {return_url: 'https://example.com/return'},
  redirect: 'if_required',
});
if (error) showError(error.message);
```

--------------------------------

### Create and use a card number element

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-card.md

Example of creating a card number element with a placeholder, listening to the networkschange event to log the detected card network, and mounting it.

```JavaScript
const number = elements.create('cardNumber', {placeholder: '4242 4242 4242 4242'});
number.on('networkschange', ({network}) => {
  console.log('Card network:', network);
});
number.mount('#card-number');
```

--------------------------------

### verifyIdentity Usage Example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-object.md

JavaScript example showing how to call stripe.verifyIdentity with a client secret and handle the result, logging an error or the verification session ID.

```javascript
const {verificationSession, error} = await stripe.verifyIdentity(
  'vs_xxx_secret_yyy'
);
if (error) {
  console.error(error.message);
} else {
  console.log('Verified', verificationSession.id);
}
```

--------------------------------

### Basic payment request flow

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/payment-request.md

JavaScript example showing the typical usage: create a paymentRequest, check canMakePayment, handle the paymentmethod event with confirmPayment, and show the payment interface on a button click. Requires an existing Elements instance and clientSecret.

```javascript
const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {label: 'Demo total', amount: 1099},
  requestPayerName: true,
  requestPayerEmail: true,
});

const canMake = await paymentRequest.canMakePayment();
if (!canMake) return;

paymentRequest.on('paymentmethod', async (event) => {
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {return_url: 'https://example.com/return'},
    redirect: 'if_required',
  });
  if (error) {
    event.complete('fail');
    showError(error.message);
  } else {
    event.complete('success');
  }
});

button.addEventListener('click', () => paymentRequest.show());
```

--------------------------------

### Basic loadStripe usage

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/load-stripe.md

Basic example importing loadStripe from '@stripe/stripe-js' and using it to create a Stripe instance and then an Elements instance with a client secret.

```javascript
import {loadStripe} from '@stripe/stripe-js';

const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements({clientSecret: 'pi_xxx_secret_yyy'});
```

--------------------------------

### Creating and managing a card element

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-base.md

Example of creating a card element with custom style and classes, attaching a change event handler, mounting it, and demonstrating lifecycle methods. Note that unmount allows re-mounting, while destroy is permanent.

```JavaScript
const cardElement = elements.create('card', {
  style: {
    base: {fontSize: '16px', color: '#32325d'},
    invalid: {color: '#fa755a'},
  },
  classes: {base: 'my-card-element'},
});
cardElement.on('change', (event) => {
  if (event.complete) enablePayButton();
  if (event.error) showValidation(event.error.message);
});
cardElement.mount('#card-element');

// lifecycle
cardElement.focus();
cardElement.blur();
cardElement.clear();
cardElement.unmount();   // re-mountable
cardElement.mount('#card-element');
cardElement.destroy();   // permanent
```

--------------------------------

### Create Elements instance with client secret

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-object.md

JavaScript example showing how to load Stripe with a test publishable key, create an Elements instance using a client secret, create a payment element, and mount it to a DOM element with id 'payment-element'.

```javascript
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements({clientSecret: 'pi_xxx_secret_yyy'});
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');
```

--------------------------------

### Example usage of loadStripe.setLoadParameters

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/load-stripe.md

Shows how to disable advanced fraud signals before loading Stripe.js. Must be called before the first loadStripe call.

```javascript
import {loadStripe} from '@stripe/stripe-js/pure';

loadStripe.setLoadParameters({advancedFraudSignals: false});
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
```

--------------------------------

### Full lifecycle example using loadStripe and elements

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-group.md

Shows the complete flow: load Stripe.js, create Elements with a client secret, mount a payment element, submit, confirm payment, and update locale. Note that elements.update performs a shallow merge and resolves when applied, and the 'update-end' event fires after update.

```javascript
const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements({
  clientSecret: 'pi_xxx_secret_yyy',
  appearance: {theme: 'stripe'},
});

const paymentElement = elements.create('payment', {layout: 'tabs'});
paymentElement.mount('#payment-element');

await elements.submit();                 // validate + collect wallet data
const {error} = await stripe.confirmPayment({
  elements,
  confirmParams: {return_url: 'https://example.com/return'},
  redirect: 'if_required',
});

elements.update({locale: 'fr'});         // shallow merge; resolves when applied
elements.on('update-end', () => console.log('updated'));
```

--------------------------------

### Create and mount issuingCardNumberDisplay element

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-other.md

Example of creating an issuingCardNumberDisplay element with required issuingCard and nonce options, then mounting it to a DOM element with id 'card-number-display'.

```JavaScript
const display = elements.create('issuingCardNumberDisplay', {
  issuingCard: 'ic_xxx',
  nonce: 'ek_nonce',
});
display.mount('#card-number-display');
```

--------------------------------

### SetupIntentConfirmParams

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/types.md

Parameters for confirming a SetupIntent. Includes optional fields such as description, metadata, payment_method, payment_method_options, return_url, usage, and expand.

```APIDOC
## SetupIntentConfirmParams

### Description
Parameters for confirming a SetupIntent. Includes optional fields such as description, metadata, payment_method, payment_method_options, return_url, usage, and expand.

### Shape
```typescript
{
  description?: string;
  metadata?: object;
  payment_method?: string;
  payment_method_options?: object;
  return_url?: string;
  usage?: 'off_session' | 'on_session';
  expand?: Array<string>;
}
```

### Source
`types/api/setup-intents.d.ts:197`
```

--------------------------------

### confirmSetup

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Confirms a SetupIntent using data collected by the Payment Element. It has four overloads depending on whether elements or clientSecret is provided and the redirect behavior.

```APIDOC
## confirmSetup

### Description
Confirms a SetupIntent using data collected by the Payment Element. Behavioral contract mirrors confirmPayment. Resolves with Promise<SetupIntentResult>.

### Method
confirmSetup

### Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `options.elements` | `StripeElements` | no* | Elements instance collecting payment details (*required unless `clientSecret` given). |
| `options.clientSecret` | `string` | no* | SetupIntent client secret (*required unless `elements` given). |
| `options.confirmParams` | `Partial<ConfirmSetupData>` or `ConfirmSetupData` | no / yes | See below. |
| `options.redirect` | `'if_required'` or `'always'` (default) | yes / no | Same semantics as `confirmPayment.redirect`. |

### ConfirmSetupData

```ts
export interface ConfirmSetupData extends SetupIntentConfirmParams {
  return_url: string;
  payment_method_data?: {
    billing_details?: PaymentMethodCreateParams.BillingDetails;
    allow_redisplay?: 'always' | 'limited' | 'unspecified';
    metadata?: Record<string, string>;
  };
  confirmation_token?: string;
  payment_method?: string;
  expand?: Array<string>;
}
```

`SetupIntentConfirmParams` adds API-level fields: `description?`, `metadata?`, `payment_method_options?`, `return_url?`, `usage?: 'off_session' | 'on_session'`, `expand?`.

### Overloads

```ts
confirmSetup(options: {
  elements: StripeElements;
  confirmParams?: Partial<setupIntents.ConfirmSetupData>;
  redirect: 'if_required';
}): Promise<SetupIntentResult>;

confirmSetup(options: {
  elements?: StripeElements;
  clientSecret: string;
  confirmParams?: Partial<setupIntents.ConfirmSetupData>;
  redirect: 'if_required';
}): Promise<SetupIntentResult>;

confirmSetup(options: {
  elements: StripeElements;
  confirmParams: setupIntents.ConfirmSetupData;
  redirect?: 'always';
}): Promise<never | {error: StripeError}>;

confirmSetup(options: {
  elements?: StripeElements;
  clientSecret: string;
  confirmParams: setupIntents.ConfirmSetupData;
  redirect?: 'always';
}): Promise<never | {error: StripeError}>;
```

### Example

```js
const elements = stripe.elements({clientSecret: 'seti_xxx_secret_yyy'});
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

const {error} = await stripe.confirmSetup({
  elements,
  confirmParams: {return_url: 'https://example.com/return'},
  redirect: 'if_required',
});
if (error) showError(error.message);
```

```

--------------------------------

### retrieveSetupIntent

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Retrieves a SetupIntent using its client secret.

```APIDOC
## retrieveSetupIntent

### Description
Retrieves a SetupIntent using its client secret.

### Method
retrieveSetupIntent

### Signature
```ts
retrieveSetupIntent(clientSecret: string): Promise<SetupIntentResult>;
```

### Parameters
- `clientSecret` (string) - Required - Client secret of the SetupIntent.

### Return Value
`Promise<SetupIntentResult>`
```

--------------------------------

### handleCardAction JavaScript Example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-payment-intents.md

Example usage of handleCardAction. It calls the method with a client secret and handles the result, showing an error message if an error occurs.

```javascript
const {error, paymentIntent} = await stripe.handleCardAction(clientSecret);
if (error) {
  showError(error.message);
}
```

--------------------------------

### confirmCardPayment usage example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-payment-intents.md

JavaScript example that calls stripe.confirmCardPayment with a client secret, payment method card element, billing details, and handleActions option. It checks for an error and displays the error message if present.

```javascript
const {error, paymentIntent} = await stripe.confirmCardPayment(
  'pi_xxx_secret_yyy',
  {
    payment_method: {
      card: cardElement,
      billing_details: {name: 'Jenny Rosen'},
    },
  },
  {handleActions: true}
);
if (error) {
  showError(error.message);
}
```

--------------------------------

### PII token error handling example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-tokens-sources.md

JavaScript example for creating a PII token with a personal ID number. Shows error handling with StripeError type and sending the token ID to the server on success.

```javascript
const {token, error} = await stripe.createToken('pii', {
  personal_id_number: '123456789',
});
if (error) {
  // StripeError with type e.g. 'invalid_request_error'
  showError(`${error.type}: ${error.message}`);
} else {
  sendToServer(token.id);
}
```

--------------------------------

### confirmSetup overloads

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Four overloads of confirmSetup, each returning Promise<SetupIntentResult>. The first two use redirect: 'if_required', the last two use redirect: 'always' (default). The first and third require elements, the second and fourth require clientSecret.

```typescript
confirmSetup(options: {
  elements: StripeElements;
  confirmParams?: Partial<setupIntents.ConfirmSetupData>;
  redirect: 'if_required';
}): Promise<SetupIntentResult>;

confirmSetup(options: {
  elements?: StripeElements;
  clientSecret: string;
  confirmParams?: Partial<setupIntents.ConfirmSetupData>;
  redirect: 'if_required';
}): Promise<SetupIntentResult>;

confirmSetup(options: {
  elements: StripeElements;
  confirmParams: setupIntents.ConfirmSetupData;
  redirect?: 'always';
}): Promise<never | {error: StripeError}>;

confirmSetup(options: {
  elements?: StripeElements;
  clientSecret: string;
  confirmParams: setupIntents.ConfirmSetupData;
  redirect?: 'always';
}): Promise<never | {error: StripeError}>;
```

--------------------------------

### loadStripe Error Handling

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/errors.md

Example of catching errors from loadStripe, including 'Failed to load Stripe.js' and 'Stripe.js not available'.

```APIDOC
## loadStripe Error Handling

### Description
Demonstrates how to catch errors thrown or rejected by the `loadStripe` function from `@stripe/stripe-js`.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **publishableKey** (string) - Required - The Stripe publishable key.

### Request Example
```js
import {loadStripe} from '@stripe/stripe-js';

try {
  const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
} catch (error) {
  // error instanceof Error; message is 'Failed to load Stripe.js' (with .cause)
  // or 'Stripe.js not available'
  console.error('Stripe.js load failed:', error);
}
```

### Response
#### Success Response
- **stripe** (Stripe) - The Stripe.js instance.

#### Error Responses
- **Error: Failed to load Stripe.js** - Triggered when the script fails to download or execute. The original cause is attached via the `{cause}` option. The promise is rejected, and with `await` it throws at the await site. `loadScript` automatically retries once; if both attempts fail, the cached promise is cleared so a later call can try again.
- **Error: Stripe.js not available** - Triggered when the script's `load` event fires but `window.Stripe` is not defined. The promise is rejected.
- **Error: Expected document.body not to be null. Stripe.js requires a <body> element.** - Triggered when script injection is needed but the document has neither a `<head>` nor a `<body>` element. This is thrown synchronously inside `injectScript`, caught inside `loadScript`, and turned into a rejection of the `loadStripe` promise.
```

--------------------------------

### Initialize Checkout SDKs

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/checkout-sdk.md

Shows the TypeScript signatures for initializing the Elements and Checkout form SDKs. Use initCheckoutElementsSdk for ui_mode: 'elements' and initCheckoutFormSdk for ui_mode: 'form' (beta).

```typescript
initCheckoutElementsSdk(options: StripeCheckoutElementsSdkOptions): StripeCheckoutElementsSdk;
initCheckoutFormSdk(options: StripeCheckoutFormSdkOptions): StripeCheckoutFormSdk;
```

--------------------------------

### ConfirmSetupData interface

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

The ConfirmSetupData interface extends SetupIntentConfirmParams and adds return_url as required, plus optional payment_method_data, confirmation_token, payment_method, and expand fields.

```typescript
export interface ConfirmSetupData extends SetupIntentConfirmParams {
  return_url: string;
  payment_method_data?: {
    billing_details?: PaymentMethodCreateParams.BillingDetails;
    allow_redisplay?: 'always' | 'limited' | 'unspecified';
    metadata?: Record<string, string>;
  };
  confirmation_token?: string;
  payment_method?: string;
  expand?: Array<string>;
}
```

--------------------------------

### loadStripe runtime implementation

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/load-stripe.md

The runtime implementation of loadStripe from src/index.ts:30. It marks that load was called, records the start time, and re-loads the script if previous attempts were unsuccessful.

```typescript
export const loadStripe: LoadStripe = (...args) => {
  loadCalled = true;
  const startTime = Date.now();

  // if previous attempts are unsuccessful, will re-load script
  return getStripePromise().then((maybeStripe) =>
    initStripe(maybeStripe, args, startTime)
  );
};
```

--------------------------------

### Invalid load parameters error example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/errors.md

Demonstrates the synchronous throw from loadStripe.setLoadParameters when called with an invalid parameter type. The error message includes the received parameters in JSON format.

```javascript
import {loadStripe} from '@stripe/stripe-js/pure';

try {
  loadStripe.setLoadParameters({advancedFraudSignals: 'no'}); // wrong type
} catch (error) {
  console.error(error.message);
  // "invalid load parameters; expected object of shape\n\n
  //  {advancedFraudSignals: boolean}\n\nbut received\n\n
  //  {\"advancedFraudSignals\":\"no\"}"
}
```

--------------------------------

### verifyMicrodepositsForSetup

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Verifies microdeposits for a SetupIntent. Accepts the client secret and optional data containing either the amounts or the descriptor code.

```APIDOC
## verifyMicrodepositsForSetup

### Description
Verifies microdeposits for a SetupIntent. Accepts the client secret and optional data containing either the amounts or the descriptor code.

### Method
verifyMicrodepositsForSetup

### Signature
```ts
verifyMicrodepositsForSetup(
  clientSecret: string,
  data?: setupIntents.VerifyMicrodepositsForSetupData
): Promise<SetupIntentResult>;
```

### Parameters
- `clientSecret` (string) - Required - Client secret of the SetupIntent.
- `data.amounts` (Array<number>) - Optional - Two positive integers, in cents, equal to the microdeposits sent to the bank account.
- `data.descriptor_code` (string) - Optional - Six-character code starting with `SM` present in the microdeposit.

### Return Value
`Promise<SetupIntentResult>`
```

--------------------------------

### Re-collected CVC flow with cardCvc element

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-card.md

Example of creating a cardCvc element, mounting it, and using stripe.createToken('cvc_update', element) to obtain a CVC token. The token id is logged on success.

```JavaScript
const cvcElement = elements.create('cardCvc', {placeholder: 'CVC'});
cvcElement.mount('#cvc-field');

const {token, error} = await stripe.createToken('cvc_update', cvcElement);
if (error) showError(error.message);
else console.log('CVC token', token.id);
```

--------------------------------

### Mode-specific StripeElementsOptions types

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/elements-group.md

Defines the three mode-specific option types: payment, subscription, and setup. Each narrows the base mode options with specific required or optional fields like amount and currency.

```typescript
type StripeElementsOptionsModePayment =
  StripeElementsOptionsModeBase & {mode: 'payment'; amount: number; currency: string};
type StripeElementsOptionsModeSubscription =
  StripeElementsOptionsModeBase & {mode: 'subscription'; amount: number; currency: string};
type StripeElementsOptionsModeSetup =
  StripeElementsOptionsModeBase & {mode: 'setup'; currency?: string};
```

--------------------------------

### collectBankAccountForSetup

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-setup-intents.md

Collects bank account details for a SetupIntent. Accepts an options object containing the client secret, optional pre-collected consent, parameters, and optional expand array.

```APIDOC
## collectBankAccountForSetup

### Description
Collects bank account details for a SetupIntent. Accepts an options object containing the client secret, optional pre-collected consent, parameters, and optional expand array.

### Method
collectBankAccountForSetup

### Signature
```ts
collectBankAccountForSetup(
  options: setupIntents.CollectBankAccountForSetupOptions
): Promise<SetupIntentResult>;
```

### Parameters
- `options.clientSecret` (string) - Required - Client secret of the SetupIntent.
- `options.preCollectedConsent` (PreCollectedConsent) - Optional - Pre-collected consent.
- `options.params` (CollectBankAccountParams) - Required - Parameters for collecting bank account.
- `options.expand` (Array<string>) - Optional - Array of fields to expand.

### Return Value
`Promise<SetupIntentResult>`
```

--------------------------------

### registerAppInfo(wrapperLibrary: WrapperLibrary): void

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-object.md

Registers a frontend open source library with Stripe.js.

```APIDOC
## `registerAppInfo`

### Description
Registers a frontend open source library with Stripe.js.

### Method
`registerAppInfo`

### Signature
```ts
registerAppInfo(wrapperLibrary: WrapperLibrary): void;
```

### Parameters
- `wrapperLibrary` (WrapperLibrary) - Required - Metadata about the calling library.

### WrapperLibrary Interface
```ts
export interface WrapperLibrary {
  name: string;              // your library's name, max length 30
  partner_id?: string;       // required for Stripe Verified Partners, optional otherwise
  version?: string;          // your library's version, in the format of x.x.x
  url?: string;              // the URL for your library's website with your contact details
}
```

### Example
```js
stripe.registerAppInfo({
  name: 'my-react-library',
  version: '1.2.3',
  url: 'https://example.com',
});
```
```

--------------------------------

### Cannot change load parameters after loadStripe error example

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/errors.md

Shows the synchronous throw from loadStripe.setLoadParameters when called after loadStripe has already been invoked with different values. The error message is 'You cannot change load parameters after calling loadStripe'.

```javascript
import {loadStripe} from '@stripe/stripe-js/pure';

loadStripe.setLoadParameters({advancedFraudSignals: true});
await loadStripe('pk_test_...');
try {
  loadStripe.setLoadParameters({advancedFraudSignals: false});
} catch (error) {
  console.error(error.message); // "You cannot change load parameters after calling loadStripe"
}
```

--------------------------------

### initCheckoutFormSdk

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-object.md

Initializes a Checkout form SDK instance for the Checkout form integration pattern (ui_mode: "form"). Requires beta access.

```APIDOC
## initCheckoutFormSdk

### Description
Initializes a Checkout form SDK instance for the Checkout form integration pattern (`ui_mode: "form"`). Requires beta access.

### Method
initCheckoutFormSdk

### Signature
```ts
initCheckoutFormSdk(
  options: StripeCheckoutFormSdkOptions
): StripeCheckoutFormSdk;
```

### Parameters
- **options** (StripeCheckoutFormSdkOptions) - Required - Options for initializing the Checkout form SDK.

### Returns
- **StripeCheckoutFormSdk** - The initialized Checkout form SDK instance.
```

--------------------------------

### Client-side API type modules

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/types.md

Overview of the TypeScript modules under types/stripe-js that define the client-side API types, including the Stripe interface, Elements, Payment Intents, Setup Intents, Payment Request, and Checkout SDK types.

```APIDOC
## Client-side API type modules

### Description
Overview of the TypeScript modules under `types/stripe-js` that define the client-side API types, including the `Stripe` interface, Elements, Payment Intents, Setup Intents, Payment Request, and Checkout SDK types.

### Modules

| Module (file) | Primary exports | Documented in |
|---|---|---|
| `stripe.d.ts` | `Stripe` (interface, ~90 methods), `StripeConstructor`, `StripeConstructorOptions`, `StripeError`, `StripeErrorType`, `WrapperLibrary`, `*Result` unions (`PaymentIntentResult`, `SetupIntentResult`, `PaymentIntentOrSetupIntentResult`, `ProcessOrderResult`, `RetrieveOrderResult`, `PaymentMethodResult`, `ConfirmationTokenResult`, `TokenResult`, `VerificationSessionResult`, `FinancialConnectionsSessionResult`, `CollectBankAccountTokenResult`, `EphemeralKeyNonceResult`, `RadarSessionPayload`) | [stripe-object.md](./api-reference/stripe-object.md), [stripe-constructor.md](./api-reference/stripe-constructor.md) |
| `elements-group.d.ts` | `StripeElements`, `StripeElementType`, `StripeElement`, `StripeElementLocale`, `CardNetworkBrand`, `StripeElementsOptions` (+`ClientSecret`/`Mode` variants), `StripeElementsUpdateOptions`, `CssFontSource`, `CustomFontSource`, `Appearance`, `CustomerOptions`, `CustomPaymentMethod` | [elements-group.md](./api-reference/elements-group.md) |
| `elements/base.d.ts` | `StripeElementBase`, `StripeElementStyle`, `StripeElementStyleVariant`, `StripeElementCSSProperties`, `StripeElementClasses`, `StripeElementChangeEvent` | [elements-base.md](./api-reference/elements-base.md) |
| `elements/{card,card-number,card-expiry,card-cvc,iban,au-bank-account,link-authentication,link-signup,contact-details,payment-method-messaging,tax-id,terms,currency-selector,shipping-address}.d.ts` | `StripeXxxElement` (+`XxxElementOptions`, `XxxElementChangeEvent` per element) | [elements-card.md](./api-reference/elements-card.md), [elements-other.md](./api-reference/elements-other.md), [elements-address.md](./api-reference/elements-address.md) |
| `elements/payment.d.ts` | `StripePaymentElement`, `StripePaymentElementOptions`, `StripePaymentElementUpdateOptions`, `DefaultValuesOption`, `FieldsOption`, `BillingDetailsFieldsOption`, `PaymentElementPaymentMethodType`, `TermsOption`, `PaymentWalletsOption`, `PaymentWalletOptionsOption`, `Layout`, `LayoutObject`, `StripePaymentElementChangeEvent`, `CardDetailsChange/SavedPaymentMethodUpdate/SavedPaymentMethodRemove/AvailablePaymentMethodsChange` events | [elements-payment.md](./api-reference/elements-payment.md) |
| `elements/express-checkout.d.ts` | `StripeExpressCheckoutElement`, `StripeExpressCheckoutElementOptions`/`UpdateOptions`, `ExpressPaymentType`, `BillingDetails`, `ShippingAddress`, `ShippingRate`, `LineItem`, `ButtonThemeOption`, `ButtonTypeOption`, `LayoutOption`, `AvailablePaymentMethods`, `…ChangeEvent`, `ClickResolveDetails`, `ChangeResolveDetails` | [elements-express-checkout.md](./api-reference/elements-express-checkout.md) |
| `elements/address.d.ts` | `StripeAddressElement`, `ContactOption`, `AddressMode`, `StripeAddressElementOptions`, `StripeAddressElementChangeEvent`, `AddressElementGetValueOptions`, `StripeAddressElementGetElementOptions` | [elements-address.md](./api-reference/elements-address.md) |
| `payment-intents.d.ts` | `CreatePaymentMethodData` (+ 36 `CreatePaymentMethodXxxData`), `ConfirmPaymentData`, ~30 `ConfirmXxxPaymentData`/`ConfirmXxxPaymentOptions`, `CollectBankAccountParams`, `CollectBankAccountPaymentMethodData`, `VerifyMicrodepositsForPaymentData`, `CollectBankAccountForPaymentOptions` | [stripe-payment-intents.md](./api-reference/stripe-payment-intents.md) |
| `setup-intents.d.ts` | `ConfirmSetupData`, `ConfirmXxxSetupData`/`Options` (13 methods), `VerifyMicrodepositsForSetupData`, `CollectBankAccountForSetupOptions` | [stripe-setup-intents.md](./api-reference/stripe-setup-intents.md) |
| `payment-request.d.ts` | `PaymentRequest`, `PaymentRequestOptions`/`UpdateOptions`/`UpdateDetails`, `PaymentRequestItem`, `PaymentRequestShippingOption`, `PaymentRequestWallet`, `PaymentRequestCompleteStatus`, `PaymentRequestEvent` + 5 sub-events, `PaymentRequestShippingAddress` | [payment-request.md](./api-reference/payment-request.md) |
| `checkout.d.ts` | `StripeCheckoutElementsSdk`/`FormSdk`, `…SdkOptions`, `StripeCheckoutSession`, ~45 `StripeCheckout*` value types, `StripeCheckoutLoadActionsSuccess` (+`Form` variant) and all `…Result` unions | [checkout-sdk.md](./api-reference/checkout-sdk.md) |
```

--------------------------------

### initCheckoutFormSdk

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/api-reference/stripe-object.md

Initializes the Checkout Form SDK with the provided options.

```APIDOC
## initCheckoutFormSdk

### Description
Initializes the Checkout Form SDK with the provided options.

### Method
Function call

### Signature
`initCheckoutFormSdk(options: StripeCheckoutFormSdkOptions): StripeCheckoutFormSdk;`

### Parameters
- **options** (StripeCheckoutFormSdkOptions) - Required - Options for initializing the Checkout Form SDK.

### Returns
StripeCheckoutFormSdk - The initialized Checkout Form SDK instance.
```

--------------------------------

### Load Stripe with loadStripe

Source: https://github.com/stripe/stripe-js/blob/master/README.md

Use this snippet to load Stripe.js and create a Stripe instance. It returns a Promise that resolves to a Stripe object, or null in a server environment. Replace the placeholder API key with your actual publishable key.

```javascript
import {loadStripe} from '@stripe/stripe-js';

const stripe = await loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
```

--------------------------------

### SourceCreateParams

Source: https://github.com/stripe/stripe-js/blob/master/_autodocs/types.md

Legacy source creation parameters.

```APIDOC
## SourceCreateParams

### Description
Legacy source creation parameters.

### Source
`types/api/sources.d.ts:721`
```
Tokens:
Raw