# How to create a Stripe App for Apideck Integration

Stripe Apps are extensions that run within the Stripe Dashboard, allowing you to build custom functionality and integrations directly in the Stripe ecosystem. This guide explains how to create a Stripe App that can integrate with Apideck to provide unified API access to Stripe data.

## Prerequisites

Before you begin, make sure you have the following:

1. A [Stripe account](https://dashboard.stripe.com/register) - You can sign up for free
2. An Apideck account  
3. [Node.js](https://nodejs.org/) installed and up to date
4. [Stripe CLI](https://stripe.com/docs/stripe-cli) version 1.12.4 or newer

## 1. Install Stripe CLI and Apps Plugin

First, you need to set up the development environment for Stripe Apps:

1. **Install Stripe CLI** (if not already installed):
   ```bash
   # Install using Homebrew (macOS/Linux)
   brew install stripe/stripe-cli/stripe
   
   # Connect CLI to your dashboard
   stripe login
   ```

2. **Verify CLI version** (must be 1.12.4 or newer):
   ```bash
   stripe version
   ```

3. **Install the Stripe Apps plugin**:
   ```bash
   stripe plugin install apps
   ```

4. **Verify the apps plugin version** (should be 1.5.12 or later):
   ```bash
   stripe apps -v
   ```

**💡 TIP**: If you need to upgrade the apps plugin, run `stripe plugin upgrade apps`

## 2. Create Your Stripe App

Now you can create your Stripe App using the CLI:

1. **Create a new app**:
   ```bash
   stripe apps create apideck-integration
   ```

2. **Follow the prompts**:
   - **ID**: Accept the auto-generated app ID or customize one (must be globally unique)
   - **Display name**: Enter a meaningful name like "Apideck Integration"

3. **Navigate to your app directory**:
   ```bash
   cd apideck-integration
   ```

**💡 TIP**: Your app ID must be globally unique across all Stripe Apps. Choose something descriptive and related to your integration.

## 3. Configure Your App Manifest

Your Stripe App uses a `stripe-app.json` manifest file to define its configuration. Based on the [Stripe Apps documentation](https://docs.stripe.com/stripe-apps/create-app):

1. **Open the `stripe-app.json` file** that was generated in your app directory
2. **Review the default structure** created by the CLI
3. **Customize the basic fields**:
   - **`id`**: Your app's unique identifier
   - **`version`**: App version number  
   - **`name`**: Display name shown in the Dashboard
   - **`icon`**: Path to your app icon

**Important**: For the complete manifest reference including UI extensions, webhooks, and permissions, refer to the [official App Manifest documentation](https://docs.stripe.com/stripe-apps/reference/manifest). The CLI-generated template will show you the exact syntax and available options.

**💡 TIP**: According to the [documentation](https://docs.stripe.com/stripe-apps/create-app), Stripe Apps only support React 17. Make sure any dependencies you install are compatible with this version.

## 4. Start Development and Preview

Now you can start developing and preview your app in the Stripe Dashboard:

1. **Start the development server**:
   ```bash
   stripe apps start
   ```

2. **Open your browser** (press Enter when prompted or manually navigate to the URL shown)

3. **Enable preview mode** in your Stripe Dashboard:
   - Click **Continue** to preview your app
   - Your app will appear as a UI extension in the specified Dashboard pages

4. **Test the app**: Navigate to a Customer details page to see your app in action

**💡 TIP**: The development server enables real-time updates. You can modify your code and see changes immediately in the Dashboard.

## 5. Plan Your Apideck Integration

Your Stripe App can integrate with external APIs to provide unified data access. Here's how to approach this:

1. **Understand your data sources**:
   - **Stripe API**: Access to your Stripe account data via API keys
   - **Apideck APIs**: Unified access to connected third-party systems
   - **Integration flow**: How data moves between Stripe, your app, and external systems

2. **Set up authentication**:
   - **Stripe credentials**: Get API keys from **Developers** → **API keys** in your Stripe Dashboard
   - **Apideck credentials**: Set up your Apideck account and get API keys
   - **Environment management**: Use appropriate test/live credentials for different environments

3. **Design your integration architecture**:
   - **Webhook handling**: Process Stripe events in your app's backend
   - **API client setup**: Configure clients for both Stripe and Apideck APIs
   - **Data transformation**: Map between Stripe data formats and unified API schemas

**For specific implementation guidance**:
- **Apideck setup**: See [Apideck getting started guide](https://developers.apideck.com/docs/getting-started)
- **Stripe App architecture**: See [Stripe Apps server-side logic documentation](https://docs.stripe.com/stripe-apps/build/add-server-side-logic)

## 6. Test Your Stripe App

Test your Stripe App development and functionality:

1. **Test the basic app functionality**:
   - Navigate to the appropriate Dashboard page where your app should appear
   - Verify the UI extension loads correctly
   - Test that your app responds to user interactions

2. **Test webhook functionality** (if implemented):
   According to the documentation, you can use Stripe CLI to forward webhooks:
   ```bash
   stripe listen --forward-to localhost:3000/webhooks
   ```

3. **Test with real Stripe data**:
   - Create test customers, invoices, or payments in your Stripe Dashboard
   - Verify your app processes and displays this data correctly
   - Test error handling for edge cases

**💡 TIP**: According to the [Stripe Apps documentation](https://docs.stripe.com/stripe-apps/create-app), use Stripe's test mode during development. Test data won't affect live accounts and you can use test card numbers for payments.

## 7. Deploy Your Stripe App

Once your app is ready, you can deploy it to make it available to users:

### Upload Your App
1. **Upload to Stripe**:
   ```bash
   stripe apps upload
   ```

2. **Test the uploaded version**:
   - Access your app through the Stripe Dashboard
   - Test all functionality in a real environment
   - Verify webhook integrations work correctly

### Distribution Options
Based on the [Stripe Apps documentation](https://docs.stripe.com/stripe-apps/create-app), you have several distribution options:

- **Private apps**: For your own Stripe account only
- **Unlisted apps**: Share with specific users via direct links  
- **Public marketplace**: Submit for review to be listed publicly

### Environment Management
- **Test mode**: Use test API keys (`sk_test_`, `pk_test_`) during development
- **Live mode**: Use live API keys (`sk_live_`, `pk_live_`) for production
- **App settings**: Configure different behaviors for test vs live mode in your app

## Start Building with Your Stripe App

Now that your Stripe App is configured, you can build powerful integrations:

### Integration Concepts

Your Stripe App can integrate with external APIs like Apideck to provide unified data access. Key integration patterns include:

**Webhook Processing**: 
- Handle Stripe webhook events in your app's backend
- Transform Stripe data formats to unified API formats
- Send processed data to external systems via API calls

**UI Extensions**:
- Display data from multiple systems within Stripe Dashboard
- Make API calls from your React components to fetch external data
- Present unified views of customer information across platforms

**For Implementation Details**:
- **Stripe Webhooks**: See [Stripe Apps webhook documentation](https://docs.stripe.com/stripe-apps/build/listen-to-events)
- **UI Extension SDK**: See [UI Extension SDK documentation](https://docs.stripe.com/stripe-apps/ui-extension-sdk)
- **Apideck API**: See [Apideck API documentation](https://developers.apideck.com/) for specific endpoints and data formats

**💡 TIP**: Start with the sample apps and documentation to understand the exact API patterns and SDK usage before building custom integrations.

## FAQ and Troubleshooting

### My app won't load in the Stripe Dashboard

Common issues include:
- **CLI version**: Ensure you're using Stripe CLI 1.12.4+ and apps plugin 1.5.12+
- **Browser compatibility**: Use Chrome or Firefox; Safari doesn't support the Dashboard
- **Development server**: Make sure `stripe apps start` is running
- **Permissions**: Check that your app manifest has the correct permissions

### App builds failing or dependencies not working

Stripe Apps specific issues:
- **React version**: Stripe Apps only support React 17 - ensure all dependencies are compatible
- **Node.js version**: Use the latest stable Node.js version
- **App manifest**: Verify your `stripe-app.json` file is properly formatted
- **UI extensions**: Ensure your viewport and component names match the manifest

### Webhook events not being received

Troubleshooting webhook integration:
1. **Local testing**: Use `stripe listen --forward-to localhost:3000/webhooks/stripe`
2. **Endpoint configuration**: Verify webhook endpoints in your app manifest
3. **Event filtering**: Check that you're listening for the correct event types
4. **Signature verification**: Implement proper webhook signature validation

### How do I deploy my app for others to use?

Based on the [Stripe Apps documentation](https://docs.stripe.com/stripe-apps/create-app):
- **Upload**: Use `stripe apps upload` to deploy your app
- **Distribution**: Choose between private, unlisted, or public marketplace distribution
- **Review process**: Public apps require Stripe review and approval
- **Account requirements**: Your Stripe account must be activated for marketplace distribution

### Can I integrate with multiple external APIs?

Yes, Stripe Apps can integrate with various services:
- **API calls**: Make requests to Apideck, CRMs, support systems, etc.
- **Authentication**: Store API keys securely using Stripe's secret management
- **Data transformation**: Convert between Stripe format and unified APIs
- **Real-time sync**: Use webhooks to keep data synchronized across systems

## Learn More

- [Stripe Apps Documentation](https://docs.stripe.com/stripe-apps/create-app) - Complete guide to building Stripe Apps
- [Stripe Apps CLI Reference](https://docs.stripe.com/stripe-apps/cli) - CLI commands and options
- [App Manifest Reference](https://docs.stripe.com/stripe-apps/reference/manifest) - Configuration options
- [UI Extension SDK](https://docs.stripe.com/stripe-apps/ui-extension-sdk) - Building Dashboard extensions
- [Apideck Unified APIs](https://developers.apideck.com/) - Integration possibilities
- [Example Stripe App for Apideck](https://github.com/apideck-samples/stripe-app) - Reference implementation