AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

stripe-apps

Build, modify, or review Stripe Apps and extensions using the relevant documentation and reference guides. Use for custom Stripe Dashboard UI, stripe-app.yaml, @stripe/ui-extension-sdk, @stripe/extensibility-sdk, script extensions, extension interfaces, custom workflow actions, and apps that authenticate to Stripe or react to events. Also use when deciding whether a Stripe extension can support the user's billing or workflow requirements.

Original source
stripe
License
MIT
Pinned revision
1e24cf59cb0dd78df298afc3b7d372e5a5055ece

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read stripe--stripe-apps at revision 1e24cf59cb0dd78df298afc3b7d372e5a5055ece, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 13

references/backend.md

Backend — when and how to add server-side logic

When you need a backend

You need a backend if your app needs to:

  • Store data long-term (user preferences, linked accounts, custom records)
  • Call APIs that require server-side secrets (API keys that can’t be in the browser)
  • Run logic when the user isn’t in the Dashboard (webhooks, scheduled jobs)
  • Call third-party services securely (email providers, CRMs, spreadsheet APIs)
  • Perform actions that take longer than the UI can wait for

You don’t need a backend if:

  • Your app only reads and displays Stripe data (use the SDK client directly in the UI)
  • You only need to store a small amount of sensitive data — use the Secret Store API instead

Canonical documentation

Before writing back-end code, read these pages using an available documentation tool:

| Topic | URL | | --- | --- | | Backend implementation + fetchStripeSignature | https://docs.stripe.com/stripe-apps/build-backend | | Authentication types (determines backend pattern) | https://docs.stripe.com/stripe-apps/api-authentication | | Events and webhooks | https://docs.stripe.com/stripe-apps/events | | Secret Store API | https://docs.stripe.com/stripe-apps/store-secrets |

Backend architecture decisions

Authentication type determines the backend pattern

Your app’s stripe_api_access_type controls how the backend authenticates. See authentication.md for the full breakdown of auth types and when to use each one.

CORS configuration

CORS (Access-Control-Allow-Origin: *) is needed ONLY on endpoints called by the UI extension. The UI runs in a sandboxed iframe with a null origin — specific origin allowlisting won’t work.

Webhook endpoints do NOT need CORS — they receive requests from Stripe’s servers, not from the browser.

fetchStripeSignature verification

fetchStripeSignature is how the UI extension authenticates requests to your backend. The signed payload and verification method are documented at https://docs.stripe.com/stripe-apps/build-backend.

Key facts:

  • The signing secret (starts with absec_...) is generated on first stripe apps upload
  • The default signed payload contains user_id and account_id (field order matters)
  • Extra data can be included by passing it to fetchStripeSignature(payload)
  • Verification uses stripe.webhooks.signature.verifyHeader()

Webhook configuration

Webhook setup depends on your app’s distribution and auth type:

| App type | Webhook setup | | --- | --- | | Private (your account only) | ONE standard webhook endpoint | | Public with platform keys | ONE webhook with “Listen to events on Connected accounts” enabled | | Public with restricted API keys | Can’t use Connect webhook fanout — each merchant manages their own webhooks |

The event_read permission MUST be declared in your manifest, plus read permissions for each event type you want to receive.

Read https://docs.stripe.com/stripe-apps/events for the full setup guide.

For firewall allowlisting of inbound webhook traffic, see https://docs.stripe.com/ips for Stripe’s IP addresses.

Secret Store API

Plain-language: “Stripe has a built-in secure place to store passwords, tokens, and API keys for your app — you don’t need to build your own database for secrets.”

Two scopes

| Scope | Use for | Example | | --- | --- | --- | | account | Shared across all users of an account | The business’s API key for an email service | | user | Per-user secrets | An individual user’s OAuth access token |

Limits and restrictions

  • Maximum 10 secrets per scope (account and user separately)
  • Always list and delete before adding more if approaching the limit
  • Do not store PCI-sensitive data (card numbers, CVVs, bank account numbers)

Declaring the permission

In stripe-app.yaml:

declarations:
  stripe_api_access:
    permissions:
      - permission: secret_write
        purpose: Store third-party credentials for the app

Implementation

For the correct code patterns to read, write, and delete secrets, read: https://docs.stripe.com/stripe-apps/store-secrets

Local development with a backend

Run your backend locally alongside stripe apps start:

# Terminal 1: start the app preview
stripe apps start

# Terminal 2: start your backend server
node server.js

For webhook forwarding during local development, see references/webhooks.md.