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

# Stripe Integration

> Add one-time payments or subscriptions to your Aurora app with Stripe and Supabase Edge Functions

Aurora can help you add Stripe payments through chat. Connect Supabase, store your Stripe Secret Key securely, then describe the payment flow you want: one-time checkout, subscriptions, pricing tiers, customer portals, or role-based access.

Aurora can generate the checkout or portal Edge Functions, database tables with Row Level Security (RLS), and UI buttons needed for the flow. Webhooks are optional for simple flows and recommended for more advanced subscription or entitlement logic.

## Key takeaways

* Use Aurora chat for both subscriptions and one-time payments.
* Never paste your Stripe Secret Key into chat. Store it in **Settings > Secrets** or Supabase Edge Function secrets.
* Connect Supabase before asking Aurora to build payment flows that need secure backend logic.
* Tie subscriptions and entitlements to the authenticated user's Supabase `id`.
* Test in **Stripe Test Mode** before accepting live payments.
* Debug with the browser console, Supabase Edge Function logs, and Stripe Dashboard logs.

## Requirements

Before integrating Stripe, make sure you have:

* An Aurora project connected to Supabase. See [Supabase Integration](/integrations/supabase).
* A Stripe account with products and prices configured, or a clear price you want Aurora to create in code.
* For one-time sales: a working product, cart, or checkout entry point.
* For subscriptions: Supabase Auth, login flows, and the pricing tiers or Stripe Price IDs you want to use.
* A Stripe Secret Key stored securely as a backend-only secret, usually named `STRIPE_SECRET_KEY`.

<Warning>
  Do not expose Stripe secret keys in frontend code or variables prefixed with `VITE_`. Secret keys should only be available to server-side code or Supabase Edge Functions.
</Warning>

<Note>
  When testing payments, use Stripe Test Mode. The standard test card is `4242 4242 4242 4242`, with any future expiration date and any 3-digit CVC.
</Note>

## Stripe payment setup: chat-driven flow

Once Supabase is connected and your Stripe key is stored securely, tell Aurora what you need in chat. Aurora can scaffold the backend functions, database schema, and UI changes.

<Steps>
  <Step title="Prepare your project">
    Confirm that:

    * Supabase is connected.
    * Auth is enabled if payments should be linked to user accounts.
    * Your Stripe Secret Key is stored in **Settings > Secrets** or in Supabase Edge Function secrets.
    * You have product names, amounts, billing intervals, or Stripe Price IDs ready.
  </Step>

  <Step title="Describe the payment flow">
    Example prompts:

    * "Create a one-time checkout for my Digital Course at \$29."
    * "Add monthly and annual Premium subscription plans tied to each user's Supabase id."
    * "Add a customer billing portal button so subscribers can manage their plan."
    * "Restrict the Pro dashboard to users with an active subscription."
  </Step>

  <Step title="Review the generated changes">
    Aurora may propose Edge Functions, database tables, RLS policies, UI components, and environment variables. Review the generated code and any SQL before applying it.
  </Step>

  <Step title="Apply and deploy">
    Apply the changes, deploy the app, and test the full checkout flow in Stripe Test Mode before switching to live keys.
  </Step>
</Steps>

<Note>
  Subscriptions should always be linked to the authenticated user's Supabase `id` so access control can be enforced securely with RLS and server-side checks.
</Note>

## Securely store Stripe keys

To integrate Stripe securely:

<Steps>
  <Step title="Find your Stripe Secret Key">
    In the Stripe Dashboard, go to **Developers > API keys** and copy the Secret Key for the correct mode: test or live.
  </Step>

  <Step title="Store the key outside chat">
    Add the key to Aurora **Settings > Secrets** or to **Supabase > Edge Functions > Secrets**, depending on where the generated backend code will run.
  </Step>

  <Step title="Use a clear secret name">
    Use a name such as `STRIPE_SECRET_KEY`. If you are configuring webhooks, also store the signing secret as `STRIPE_WEBHOOK_SECRET`.
  </Step>
</Steps>

<Warning>
  Never paste a Stripe Secret Key directly into Aurora chat. Treat it like a production password: exposing it could allow unauthorized access to your Stripe account.
</Warning>

## Advanced integration: webhooks and Supabase

For subscriptions, entitlements, role-based access, invoices, and payment failure handling, use Supabase Edge Functions with Stripe webhooks. Webhooks let Stripe notify your backend when a checkout succeeds, a payment fails, or a subscription changes.

<Steps>
  <Step title="Ask Aurora to create webhook handling">
    In Chat mode, plan the tables and events first. Then ask Aurora to implement the Edge Function, database updates, and RLS policies.

    Example prompt: "Set up Stripe webhooks in Supabase for subscription created, updated, deleted, and checkout completed events. Store each user's active plan by Supabase user id."
  </Step>

  <Step title="Retrieve the Edge Function endpoint URL">
    After the function is created and deployed, copy its endpoint URL from Supabase.
  </Step>

  <Step title="Create a Stripe webhook endpoint">
    In Stripe Dashboard, go to **Developers > Webhooks > Create an event destination** and enter the Supabase Edge Function endpoint URL.
  </Step>

  <Step title="Select relevant webhook events">
    Common events include:

    * `checkout.session.completed`
    * `payment_intent.succeeded`
    * `payment_intent.payment_failed`
    * `customer.subscription.created`
    * `customer.subscription.updated`
    * `customer.subscription.deleted`
    * `invoice.payment_succeeded`
    * `invoice.payment_failed`
  </Step>

  <Step title="Store the webhook signing secret">
    Copy the webhook signing secret from Stripe and store it securely in Supabase Edge Function secrets, commonly as `STRIPE_WEBHOOK_SECRET`.
  </Step>

  <Step title="Verify entitlement updates">
    Complete a test checkout and confirm your database updates the correct user, plan, and subscription status.
  </Step>
</Steps>

<Info>
  If you are unsure which events or tables you need, use Aurora's Chat mode first. Ask it to explain the subscription lifecycle and draft the schema before implementing changes.
</Info>

## Testing your integration

* Use Stripe Test Mode for all setup and QA.
* Use test card `4242 4242 4242 4242`, any future expiration date, and any 3-digit CVC.
* Test both successful and failed payment paths.
* Confirm webhook events arrive in Stripe Dashboard logs.
* Confirm Supabase Edge Function logs show successful signature verification and database updates.
* Confirm the app UI reflects the payment state after checkout or subscription changes.

## Debugging and troubleshooting

<AccordionGroup>
  <Accordion title="Check browser console and network logs">
    <Steps>
      <Step title="Open Developer Tools">
        In Chrome, right-click the page, choose **Inspect**, then open the **Console** and **Network** tabs.
      </Step>

      <Step title="Look for failed requests">
        Check checkout session creation, portal session creation, and post-checkout redirects.
      </Step>

      <Step title="Share exact errors with Aurora">
        Copy error messages into Chat mode and ask Aurora to trace the likely cause before making more changes.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Review Supabase Edge Function logs">
    <Steps>
      <Step title="Open Supabase Dashboard">
        Go to your Supabase project dashboard.
      </Step>

      <Step title="Open Edge Function logs">
        Navigate to **Edge Functions > Logs** and inspect the function handling checkout or webhooks.
      </Step>

      <Step title="Check secrets and permissions">
        Verify that `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` are present and that your function can update the required tables.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Verify webhook events in Stripe">
    <Steps>
      <Step title="Open Stripe Dashboard">
        Go to **Developers > Webhooks**.
      </Step>

      <Step title="Inspect delivery attempts">
        Open the webhook endpoint and review recent event deliveries, response codes, and payloads.
      </Step>

      <Step title="Retry failed events">
        After fixing the issue, retry failed webhook deliveries from Stripe to confirm the handler works.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Use Chat mode for complex issues">
    <Steps>
      <Step title="Switch to Chat mode">
        Use Chat mode when you want Aurora to reason about the problem before editing code.
      </Step>

      <Step title="Explain the flow step by step">
        Include what you clicked, which event you expected, what happened instead, and any logs from Stripe or Supabase.
      </Step>

      <Step title="Implement after the plan is clear">
        Once the diagnosis makes sense, ask Aurora to implement the fix.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>