> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe App Sandbox

## Overview

<CardGroup cols={3}>
  <Card title="Pre-built tooling" icon="screwdriver-wrench" href="#pre-built-tooling" />

  <Card title="Pre-built integrations" icon="square-check" href="#pre-built-integrations" />

  <Card title="Access requirements" icon="triangle-exclamation" href="#access-requirements" />

  <Card title="Setup guide" icon="rocket" href="#setup-guide" />

  <Card title="Useful links" icon="circle-info" href="#useful-links" />

  <Card title="API gotchas" icon="biohazard" href="#api-gotchas" />
</CardGroup>

## Pre-built tooling

<AccordionGroup>
  <Accordion title="✅ Authorization">
    | Tools                           | Status |
    | ------------------------------- | ------ |
    | Pre-built authorization (OAuth) | ✅      |
    | Credentials auto-refresh        | ✅      |
    | Pre-built authorization UI      | ✅      |
    | Custom authorization UI         | ✅      |
    | End-user authorization guide    | ✅      |
    | Expired credentials detection   | ✅      |
  </Accordion>

  <Accordion title="✅ Read & write data">
    | Tools                                     | Status                         |
    | ----------------------------------------- | ------------------------------ |
    | Pre-built integrations                    | 🚫 (time to contribute: \<48h) |
    | API unification                           | ✅                              |
    | 2-way sync                                | ✅                              |
    | Webhooks from Nango on data modifications | ✅                              |
    | Real-time webhooks from 3rd-party API     | 🚫 (time to contribute: \<48h) |
    | Proxy requests                            | ✅                              |
  </Accordion>

  <Accordion title="✅ Observability & data quality">
    | Tools                   | Status |
    | ----------------------- | ------ |
    | HTTP request logging    | ✅      |
    | End-to-end type safety  | ✅      |
    | Data runtime validation | ✅      |
    | OpenTelemetry export    | ✅      |
    | Slack alerts on errors  | ✅      |
    | Integration status API  | ✅      |
  </Accordion>

  <Accordion title="✅ Customization">
    | Tools                              | Status                         |
    | ---------------------------------- | ------------------------------ |
    | Create or customize use-cases      | ✅                              |
    | Pre-configured pagination          | 🚫 (time to contribute: \<48h) |
    | Pre-configured rate-limit handling | 🚫 (time to contribute: \<48h) |
    | Per-customer configurations        | ✅                              |
  </Accordion>
</AccordionGroup>

*No pre-built syncs or actions available yet.*

<Tip>Not seeing the integration you need? [Build your own](/guides/functions/functions-guide) independently.</Tip>

| Pre-Requisites        | Status | Comment                                                                                                                                                                                                                                 |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Paid dev account**  | ✅      | You must have an activated Stripe account (submit business info). No charges required, but activation is mandatory.                                                                                                                     |
| **Paid test account** | ✅      | Stripe does not require or support a paid **test** account. Sandbox accounts are available by default in every account.                                                                                                                 |
| **Partnership**       | ✅      | Not required to develop or publish apps, but Stripe may offer [partnership](https://docs.stripe.com/partners#:~:text=To%20become%20a%20Stripe%20partner,the%20Stripe%20Partner%20Ecosystem%20Agreement.) options for higher visibility. |
| **App review**        | ❌      | Required if you want to publish the app publicly on the Stripe App Marketplace. Stripe will review your app before approval.                                                                                                            |
| **Security audit**    | ✅      | Not strictly required, but apps must follow Stripe’s [security best practices](https://stripe.com/docs/security). A formal audit may be needed depending on your app’s access level and data usage.                                     |

## Setup guide

<Steps>
  <Step title="Create a Stripe account">
    If you don't already have one, sign up for a [Stripe account](https://dashboard.stripe.com/register).
  </Step>

  <Step title="Install Stripe CLI">
    1. If you haven't already, install the [Stripe CLI](https://docs.stripe.com/stripe-cli#install).
    2. Log in using your Stripe account:
       ```shell theme={null}
       stripe login
       ```
  </Step>

  <Step title="Install the Stripe Apps CLI plugin">
    1. Run the following command to install the Stripe Apps plugin:
       ```shell theme={null}
       stripe plugin install apps
       ```
    2. Verify the plugin version is 1.5.12 or newer:
       ```shell theme={null}
       stripe apps -v
       ```
  </Step>

  <Step title="Create your Stripe App">
    1. Create a new app project using the CLI:
       ```shell theme={null}
       stripe apps create my-stripe-app
       ```
    2. This creates a local project folder with a manifest and app code.
  </Step>

  <Step title="Edit the app manifest">
    Open the **stripe-app.json** file and update these fields:

    * **stripe\_api\_access\_type**: Set to **oauth**
    * **distribution\_type**: Set to **public**
    * **allowed\_redirect\_uris**: Add your redirect URI as **[https://api.nango.dev/oauth/callback](https://api.nango.dev/oauth/callback)**
    * **sandbox\_install\_compatible**: Set to **true**
      Example:

    ```json theme={null}
    {
      "id": "com.example.my-app",
      "version": "0.0.1",
      "name": "My Stripe App",
      "icon": "./icon.png",
      "permissions": [],
      "stripe_api_access_type": "oauth",
      "distribution_type": "public",
      "sandbox_install_compatible": true,
      "allowed_redirect_uris": [
        "https://api.nango.dev/oauth/callback"
      ]
    }
    ```
  </Step>

  <Step title="Add required permissions and UI (optional)">
    1. Add [permissions](https://docs.stripe.com/stripe-apps/reference/permissions) your app requires to access Stripe resources in the manifest (e.g., **read\_only**, **customers:read**, etc.).

    ```json theme={null}
    "permissions": [
        {
            "permission": "customer_read",
            "purpose": "Receive access to the customer’s phone number"
        }
    ]
    ```

    2. Optionally add a **settings view** or other UI extensions if your app has a user-facing configuration.
  </Step>

  <Step title="Upload your app to Stripe (requires live account)">
    1. Ensure you're logged into a fully activated (non-sandbox) Stripe account.
    2. Upload your app to Stripe:
       ```shell theme={null}
       stripe apps upload
       ```

    <Note>[Sandbox accounts](https://docs.stripe.com/stripe-apps/enable-sandbox-support#enable-sandbox-installs-for-your-public-app) cannot upload apps. You must activate your account first.</Note>
  </Step>

  <Step title="Obtain your Client ID and Client Secret">
    1. Go to your app's details page in the Stripe Dashboard.
    2. Open the <strong>External test</strong> tab.
    3. Click <strong>Get started</strong> if you haven’t already configured the external test OAuth setup.
    4. After setup, Stripe will generate OAuth installation links in the **Test OAuth** section. Your <strong>Client ID</strong> will be included in the **Sandbox link** as a query parameter (e.g., <code>client\_id=...</code>).
    5. To obtain your <strong>Client Secret</strong>, go to the <strong>API Keys</strong> page in the Stripe Dashboard and copy your <strong>Secret key</strong> (starts with <code>sk\_test\_...</code>).

    ⚠️ Make sure that your <strong>client\_id</strong> and <strong>secret key</strong> come from the same Stripe sandbox account and environment. Mixing keys from different environments or accounts will result in authorization errors like <em>"Authorization code provided does not belong to you."</em>
    Save these credentials securely as you'll need them when configuring your integration in Nango.
  </Step>

  <Step title="Next">
    Follow the [*Quickstart*](/getting-started/quickstart).
  </Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

<UsefulLinks />

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/stripe-app.mdx)</Note>

<CommonScopes />

## API gotchas

* The Stripe App Sandbox is a test environment that simulates real installs and OAuth flows without affecting live data. Use it for external development or testing purposes.

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/stripe-app.mdx)</Note>

<Card title="Connect to Stripe App Sandbox" icon="link" href="/integrations/all/stripe-app-sandbox/connect" horizontal>
  Guide to connect to Stripe App Sandbox using Connect UI
</Card>