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

# Stripe

> Integration details and setup guide for the Stripe connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                         |
| ----------------------------------- | ----------------------------------------------- |
| **Authentication**                  | API Key (Bearer Token)                          |
| **Two-Way Sync**                    | Yes                                             |
| **Events Supported**                | Yes (extensive webhook events)                  |
| **Realtime**                        | Yes (Webhooks)                                  |
| **Supports Rate Limiting**          | Yes (varies by request type)                    |
| **Authentication Scopes Supported** | N/A (API Key-based with restricted keys option) |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Stripe**:

* **Customers** - Customer records and metadata
* **Charges** - Payment charges
* **Payment Intents** - Modern payment flows
* **Invoices** - Invoices and line items
* **Subscriptions** - Recurring billing subscriptions
* **Products & Prices** - Product catalog and pricing
* **Payment Methods** - Saved payment methods
* **Refunds** - Refund transactions
* **Disputes** - Chargebacks and disputes
* **Payouts** - Transfers to bank accounts

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                                                 |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Stripe is free to start with no setup fees. You only pay transaction fees when you process payments. [Create free account](https://dashboard.stripe.com/register) |
| **Requires paid sandbox**                          | No. Test mode is available for free with unlimited test transactions.                                                                                                  |
| **Requires partnership to obtain authentication?** | No. Anyone can create a Stripe account and obtain API keys.                                                                                                            |

***

### Authentication (API Key)

Stripe uses secret API keys for authentication via Bearer token.

<step>
  ## Step 1: Create a Stripe Account

  1. Visit **Stripe** ([https://stripe.com/](https://stripe.com/))
  2. Click **Start now** or **Sign up**
  3. Complete the registration with your email
  4. Verify your email address
  5. Complete your business profile (for production use)
</step>

<step>
  ## Step 2: Access API Keys

  1. Log into your Stripe Dashboard ([https://dashboard.stripe.com/](https://dashboard.stripe.com/))
  2. Click **Developers** in the left sidebar
  3. Navigate to **API keys**
  4. You'll see two sets of keys:
     * **Test mode keys** (for development)
     * **Live mode keys** (for production, available after account activation)
</step>

<step>
  ## Step 3: Retrieve Your Secret Key

  1. In the API keys page, find the **Secret key** section
  2. Click **Reveal test key** (or live key for production)
  3. Copy the secret key (format: `sk_test_...` or `sk_live_...`)
  4. Store this key securely—it grants full access to your Stripe account
  5. Never expose secret keys in client-side code or public repositories
</step>

<step>
  ## Step 4: Create Restricted API Keys (Optional, Recommended)

  1. In the API keys page, scroll to **Restricted keys**
  2. Click **Create restricted key**
  3. Name your key (e.g., "Alloy Integration")
  4. Select specific permissions needed for your integration:
     * **Customers**: Read and Write
     * **Charges**: Read
     * **Payment Intents**: Read and Write
     * **Invoices**: Read and Write
     * **Subscriptions**: Read and Write
  5. Click **Create key**
  6. Copy the restricted key (format: `rk_test_...` or `rk_live_...`)
</step>

<step>
  ## Step 5: Connect to Alloy Automation

  1. In Alloy Automation, configure your Stripe connector
  2. Provide your **Secret API Key** or **Restricted API Key**
  3. The API key will be used as a Bearer token in the Authorization header
  4. Test the connection by retrieving customer or product data
</step>

***

## Use Cases

### 1) Subscription management automation

Sync Stripe subscription data with CRM, billing, or customer success platforms to trigger onboarding workflows, usage tracking, and renewal reminders based on subscription events.

### 2) Revenue recognition and reporting

Extract payment, invoice, and payout data from Stripe to integrate with accounting systems, ERPs, or business intelligence tools for accurate financial reporting and reconciliation.

### 3) Customer lifecycle automation

Connect Stripe customer and payment data with marketing automation platforms to trigger targeted campaigns based on purchase behavior, subscription status, or payment failures.

### 4) Failed payment recovery

Automatically detect failed payments, subscription cancellations, or payment method updates in Stripe and trigger dunning workflows, customer notifications, or support ticket creation.

### 5) Multi-currency and international payments

Sync payment data across different currencies and payment methods from Stripe to centralized systems, enabling global financial reporting and compliance tracking.

***

## API Gotchas

* **API Versioning:** Stripe uses dated API versions (e.g., `2023-10-16`). Your account is pinned to a specific version. To upgrade, test thoroughly in test mode, then upgrade your account version in the Dashboard. Stripe maintains backward compatibility but adds new features in newer versions.

* **Idempotency Keys:** For POST requests that create objects (charges, customers, subscriptions), use idempotency keys (`Idempotency-Key` header) to safely retry requests without creating duplicates. Stripe stores idempotency keys for 24 hours.

* **Webhook Signature Verification:** Always verify webhook signatures using the `Stripe-Signature` header and your webhook signing secret. This prevents malicious webhook events from reaching your system.

* **Pagination with starting\_after:** Stripe uses cursor-based pagination with the `starting_after` parameter. To paginate through results, use the `id` of the last object from the previous page as the `starting_after` value for the next request.

* **Expandable Properties:** Stripe API responses often contain object IDs (e.g., `customer: "cus_xxx"`). Use the `expand` parameter to include full object details in a single request (e.g., `expand[]=customer`) instead of making separate API calls.

* **Rate Limiting:** Stripe doesn't publish specific rate limits but does throttle requests under extreme load. Implement exponential backoff for 429 responses. Most integrations won't hit limits with normal usage patterns.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.