Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Build with LLMsStripe for Visual Studio CodeStripe health alertsFile uploads
Security and privacy
Security
Privacy
Extend Stripe
Stripe Apps
    Overview
    Get started
    Create an app
    How Stripe Apps work
    Sample apps
    Build an app
    Store secrets
    API authentication methods
    Authorization flows
    Server-side logic
    Listen to events
    Handle different modes
    Enable sandbox support
    App settings page
    Build a UI
    Onboarding
    Distribute your app
    Distribution options
    Upload your app
    Versions and releases
    Test your app
    Publish your app
    Promote your app
    Add deep links
    Create install links
    Assign roles in UI extensions
    Post-install actions
    App analytics
    Embedded components for Apps
    Embed third-party Stripe Apps
    Migrating to Stripe Apps
    Migrate or build an extension
    Migrate a plugin to Stripe Apps or Stripe Connect
      Migrate a plugin to an OAuth app
      Migrate a plugin to a RAK app
      Legacy plugins
    Reference
    App manifest
    CLI
    Extension SDK
    Permissions
    Viewports
    Design patterns
    Components
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsStripe AppsMigrate a plugin to Stripe Apps or Stripe Connect

Migrate a plugin to an OAuth 2.0 app

Learn how to migrate your plugin to OAuth authentication through Stripe Apps.

Copy page

Use this guide to migrate your plugin to a Stripe app that uses OAuth 2.0 for authentication, also known as an OAuth 2.0 app.

Previously, Stripe allowed plugins to request the standard API keys of a user to integrate with their products. As of September 30, 2024, Stripe requires all plugin developers to adopt secure authentication methods (restricted API Key, OAuth 2.0, or Stripe Connect) to protect users against fraud. All existing and new plugin developers must use one of these secure authorization methods. Migrating your plugin to an OAuth 2.0 app meets this requirement.

For more information about OAuth 2.0, see OAuth 2.0 for Stripe Apps.

Before you begin

  • Review Migrate a plugin to Stripe Apps or Stripe Connect.
  • If you use Stripe Connect and want to migrate an existing plugin through Stripe Apps, you must create a new Stripe account. Currently, a Stripe account with Connect enabled can’t publish an app.
  • You can only create one public app per account. If your account already has a public app and you want to publish another one, you must create a new Stripe account. You can still create multiple private apps in tandem with the public app on the same account.

Install the Stripe CLI plugin

  1. Sign in to the Stripe Dashboard.
  2. If you haven’t already, install the Stripe CLI and log in using the same account.
    Command Line
    homebrew
    # Install Homebrew to run this command: https://brew.sh/ brew install stripe/stripe-cli/stripe # Connect the CLI to your dashboard stripe login

    For additional install options, see Get started with the Stripe CLI.

  3. Verify that you’re using CLI version 1.12.4 or newer. You can check by running:
    Command Line
    stripe version
    If your Stripe CLI version is older than 1.12.4, update to the latest Stripe CLI version.
  4. Verify that the node is installed and up to date.
    Command Line
    node -v
    You can manage your app’s dependencies with NPM or Yarn. Make sure that you use the latest stable version. If you plan to publish your app to the App Marketplace, there are additional restrictions:
    • Your must have an activated account.
    • You can’t publish an app on a Connect enabled Stripe account.

Develop your app

  1. Install the Stripe Apps CLI plugin: To start building a Stripe app, install the Stripe Apps CLI plugin:

    Command Line
    stripe plugin install apps

    If you already have the apps plugin installed, verify that you’re on version 1.5.12 or later.

    Command Line
    stripe apps -v # apps version 1.5.12

    If you need to upgrade the apps plugin, you can run:

    Command Line
    stripe plugin upgrade apps
  2. Create your Stripe app by running `stripe apps create <app-name> in the CLI:

    • When naming your app, Stripe prohibits the following terms: Authenticator, RAK, Generator, RAK Auth, App, Generator App, Stripe.
    • Here are some examples of acceptable names: Analytics Pro by DataWiz, Invoice Manager by PayFlow.
    • If you’re developing an app for a third-party service, use this naming convention: [App Functionality] by [Developer Name]. For example, Hubspot Sync by Boomi.
  3. Edit the following fields in the app manifest:

    • Set stripe_api_access_type to oauth.
    • Set distribution_type to public.
    • Set your allowed_redirect_uris. These are the URLs you redirect users to after installing your app using OAuth. The first one in the list is the default redirect.

    For example:

    Command Line
    { "id": "<YOUR_APP_ID>", "version": "0.0.1", "name": "Your Stripe App", "icon": "./[YOUR_APP]_icon_32.png", "permissions": [ // Your app permissions here ], "stripe_api_access_type": "oauth", "distribution_type": "public", "allowed_redirect_uris": [ // Your redirect URIs here ] }
  4. Add all the permissions that your app requires using the stripe apps grant permission "PERMISSION_NAME" "EXPLANATION" command.

  5. (Optional) Add UI extensions to your app. We recommend adding a settings view to allow your users to configure settings or to link to your app’s documentation. If your app’s only purpose is for authentication, make sure to remove any unnecessary UI or UX code. This helps keep your app focused on its primary function.

  6. Upload your app to Stripe using the stripe apps upload command. After you upload your OAuth 2.0 app, you can’t change the API authentication method.

  7. Configure OAuth 2.0 to work with your app and your OAuth provider.

    • Make sure you use the correct OAuth install link to begin the OAuth flow for your users.
    • You must provide a callback URL in your app manifest which can receive the OAuth authorization code.
    • You must use your secret key to exchange the authorization code for the OAuth access and refresh tokens applicable with the user’s account.
    • You must periodically use the refresh token to obtain a new access token to avoid requiring your users to authenticate each time their access token expires.

Test your app

You can test your OAuth App on your own account or with other accounts:

  1. From the Developer’s Dashboard > Apps, select the app you want to test externally.
  2. On the app’s details page, click the External test tab, then click Get Started.
    • If you don’t see the External test tab, verify if you’ve selected public distribution from Create a release.
  3. Complete the following fields to configure external testing (which you can edit at any time):
    • Link access: Choose whether anyone can install the app using the link or to restrict to invited users only.
    • Version: Select a version for users to install. Changing the version updates all current users to the new version.
  4. Copy the authorize link in the Test OAuth section. Send this link to users to install the app on their account. These users must have administrator rights to install the app. After a user installs the test version of your app, all members of the account can use it.

For more information about external testing, see Test your app externally.

Publish and distribute your app

To publish your app to the Stripe App Marketplace:

  1. Submit your app for review.
  2. After Stripe approves your app, publish your app to Stripe App Marketplace.

To distribute your app:

  1. View your installed apps, and click the app you want to distribute. On the app’s details page, click the Settings tab.
  2. Identify the OAuth install link from when you developed your app. This link is mode-specific. You must specify live or test mode depending on your use case. You can also configure the app manifest to enable installation in sandbox environments.
  3. Consistently use the same OAuth install link across your product and in user communications. Some examples to consider include:
    • Update your documentation to instruct users to install the Stripe OAuth 2.0 app, and remove any steps that refer to copying and pasting API keys.
    • Add the OAuth install link to your plugin onboarding to help users install the app.
    • Use the OAuth install link in email communications with users to help them update their existing installations.

Migrate your exisiting users

After you migrate your plugin to a Stripe App, you must migrate your existing users. The approach might vary depending on how you usually interact with your users, but here are some general key steps for all plugins:

  1. Notify your existing users to update their connection to Stripe using your OAuth Install Link. This can be through email, in your plugin’s UI, through in-product notifications, in your release notes, or many other ways.
  2. After a user installs your app and completes the OAuth flow, delete the previous secret API key.
  3. Track user migration progress. If possible, track the progress of user migrations. Follow up with users who haven’t migrated to ensure a smooth transition over time.

OptionalMonitor and improve the health of your app

You can explore and implement the following actions to proactively improve the health of your app:

  • To promote your app, consider joining the Stripe Partner Ecosystem as part of the Apps Track. All app developers are eligible for to join the partner program, and apps that achieve certain milestones can unlock additional partner benefits as they grow.
  • To extend the Stripe Dashboard and provide customized functionality for your users, Build a UI Extension.
  • Track your App Analytics to gain insights into the performance of your App Marketplace listing, such as user installation metrics.

OptionalConfigure payments

If you’re building an app that helps users process payments, review these guidelines:

Securely collect payment details

Stripe users are subject to PCI compliance, which specifies how to securely store, process, and transmit credit card data. Businesses face penalties for non-compliance or potential breaches.

Because you’re making API calls on behalf of a Stripe user, you must transmit credit card data securely using client-side tokenization. Customers submit their personal information through their web browser or mobile app directly to Stripe, and in return, Stripe sends a simple token to you. This allows your users to securely collect card details without sensitive data ever touching their server.

If your plugin includes a client-side payment form in the browser, we recommend that you use either:

  • Stripe Elements: A set of prebuilt UI components for building your web checkout flow. It’s available as a feature of Stripe.js, our foundational JavaScript library for building payment flows.
  • Stripe Checkout: A low-code payment integration that creates a customizable form for collecting payments. You can embed Checkout directly in your website or redirect customers to a Stripe-hosted payment page.

Both of these options provide client-side tokenization.

If your plugin only operates in a back-end environment, include a note in your documentation asking users to tokenize payment details using Elements or Checkout. Tokenization helps Stripe users process as safely as possible on our platform.

Add the Express Checkout Element

The Express Checkout Element provides a single integration for accepting payments through one-click payment buttons, including Apple Pay, Google Pay, Link, or PayPal. This integration allows you to display multiple buttons at the same time. Customers see different payment buttons depending on what their device and browser combination supports.

Enable multiple payment methods

Stripe supports multiple payment methods, aside from credit cards. To learn more about payment methods, see Payment methods.

The Payment Methods API enables your users to collect payments using additional payment methods (for example, Alipay, iDEAL, Sofort). You can add these payment methods using one integration path.

Verify that HTTPS is enabled

If your plugin presents a payment form in a web browser, it must check that the form is being served over HTTPS. We require our users to enable HTTPS. Present a clear error to your user if they’re not properly secured.

The following example shows how to verify whether your users have HTTPS enabled:

Command Line
// This example uses Express const express = require('express'); const app = express(); app.get('/', function(request, response) { if (!request.secure) { // Present an error to the user } }); app.listen(3000);

If your plugin has a front-end component, check whether HTTPS is being used from the browser. For example, using JavaScript:

Command Line
// This example checks for HTTPS from the browser if (window.location.protocol !== "https:") { // Present an error to the user }

See also

  • Migrate a plugin to Stripe Apps or Stripe Connect.
  • Migrate a plugin to an RAK app
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc