Skip to content
rdlabo.devdocs
日本語

Initialize

Import Stripe and call initialize with a publishable key. Do this once per JavaScript runtime, before you create or present any payment UI.

import { Stripe } from '@capacitor-community/stripe';

export async function initialize(): Promise<void> {
  await Stripe.initialize({
    publishableKey: 'Your Publishable Key',
  });
}

method initialize(...)

Configures the Stripe SDK. Call this once before using any payment method.

initialize(opts: StripeInitializationOptions) => Promise<void>

interface StripeInitializationOptions

Prop Type Description Since
publishableKey string Stripe publishable key for the account that creates the client-side payment UI. Never pass a secret key to the client application. 3.0.0
stripeAccount string Connected account ID used when making client-side calls on behalf of a Stripe Connect account. 3.0.0

Create a publishable key in the Stripe Dashboard. Never ship the secret key to the client.

Stripe Connect

Set optional stripeAccount to make plugin API calls for a connected account.

await Stripe.initialize({
  publishableKey: 'Your Publishable Key',
  stripeAccount: 'acct_xxxxxxxxxxxxx',
});

On Android, Google Pay can also read com.getcapacitor.community.stripe.stripe_account from application metadata. See Google Pay.

Redirect-based payment methods on iOS

Payment methods that leave your app for authentication, such as PayPal and some bank payment methods, require a return URL. On iOS, Stripe does not offer otherwise eligible redirect-based payment methods in PaymentSheet or PaymentFlow when returnURL is not configured. See Stripe's iOS return URL guide.

Register a custom URL scheme for your app in ios/App/App/Info.plist. Replace your-app with a scheme unique to your application:

ios/App/App/Info.plist
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>your-app</string>
    </array>
  </dict>
</array>

Pass a URL using that scheme to createPaymentSheet or createPaymentFlow, then forward matching app-open events to Stripe:

import { App } from '@capacitor/app';
import { Stripe } from '@capacitor-community/stripe';

const STRIPE_RETURN_URL = 'your-app://stripe-redirect';

await App.addListener('appUrlOpen', async ({ url }) => {
  if (url.startsWith(STRIPE_RETURN_URL)) {
    await Stripe.handleURLCallback({ url });
  }
});

await Stripe.createPaymentSheet({
  paymentIntentClientSecret,
  returnURL: STRIPE_RETURN_URL,
});

Use the same setup with createPaymentFlow. The custom scheme in Info.plist, the scheme in returnURL, and the URL checked by the listener must match. Payment-method availability also depends on the Intent, currency, country, Stripe account, Dashboard settings, and Stripe SDK support.

handleURLCallback

handleURLCallback is iOS only. It passes the incoming return URL to the Stripe SDK so redirect-based authentication can finish and the browser can close.

method handleURLCallback(...)

Passes an incoming return URL back to the Stripe SDK after redirect-based
authentication.

iOS only. Call this from your app URL handler when Stripe redirects back
to the application.

handleURLCallback(opts: StripeURLHandlingOptions) => Promise<void>

interface StripeURLHandlingOptions

Prop Type Description Since
url string Full callback URL received by the application. 4.0.0

The method is not implemented on Android or web. Only pass matching Stripe return URLs to it. If Stripe does not handle the URL, the promise rejects and you should continue with your normal deep-link handling.

Framework wiring

Call initialize from your chosen framework bootstrap. Prefer the canonical startup path on each guide:

  • Vanilla JS — call initialize after defineCustomElements()
  • Angular — provideAppInitializer at application startup
  • React — CapacitorStripeProvider initializes the plugin for you
Edit this page on GitHub