Migrate a plugin to a RAK app

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

Use this guide to migrate your existing plugin to a Stripe App that uses Restricted API Keys (RAKs) for authentication, also known as a RAK App. For more information about RAKs, see Customize API access with restricted API keys.

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 a RAK app meets this requirement.

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

Sign in to the Stripe Dashboard.
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.
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.
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

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
```
Create your app using our template:
Command Line
```
stripe apps create <app-name> --template restricted-api-key-app
```
- When naming your app, Stripe prohibits the following terms: Authenticator, RAK, Generator, RAK Auth, App, Generator App, Stripe.
- 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, Analytics Pro by DataWiz, or Invoice Manager by PayFlow.
Add all the permissions that your app requires.
Edit your app settings page. If you use the template above, Stripe automatically creates a settings view. Add instructions or links to your own documentation on the settings page for your users to reference when they set up your app.
Upload your app. After you upload your RAK app, you can’t change the API authentication method.

Test your app

In the Dashboard, test the restricted API key on your own account:

Install your app in test mode (including sandbox environments) on your account.
View your installed apps, and click your recently installed app.
From the app settings page, click View API keys. Copy this secret key to test your integration.

Test your app with other live accounts before you publish your app. Use the external testing feature to invite up to 25 users to test your app on their accounts:

From the Developer’s Dashboard > Apps, select the app you want to test externally.
On the app’s details page, click the External test tab, and click Get Started.
- If you don’t see this tab, verify if you’ve selected public distribution from Create a release.
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.
Click the invite link to copy and send it to your users so they can 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:

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

To distribute your app:

View your installed apps, and click the app you want to distribute. On the app’s details page, click the Settings tab.
Copy the install link for your app. Any user who clicks this link is directed to the install flow for your app.
Consistently use the same install link across your product and in user communications. Some examples to consider include:
- Update your documentation to instruct users to install the Stripe RAK app. Your users must copy and paste the restricted API key into your website or plugin configuration.
- Add the install link to your plugin onboarding to help users install the app and copy the restricted API key more easily.
- Use the 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 guidelines that apply to most plugins:

Notify your users. Inform your existing users to update their connection to Stripe using your install link by email, within your plugin’s UI, using in-product notifications, in release notes, or any other communication method.
Update API Keys. After a user installs your app and provides their new restricted API key, delete their previous secret API key.
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, including 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
}