# Stripe Allow Suger to manage your Stripe seamlessly, including customers, payments. --- ## Overview Stripe is a popular online payment processing platform that allows businesses and individuals to accept payments over the internet. It provides a range of tools and services that simplify the process of setting up and managing online payments, including online payment gateway integration, merchant account services, and developer-friendly APIs. By connecting Suger to your stripe, we can build customized automation workflow in manage of customer, coupon and payment. ## Prerequisites Before connecting, get the following credentials from your [Stripe Dashboard](https://dashboard.stripe.com/apikeys): - **Public Key**: Your standard identifiable key. - **Secret Key or Restricted Key**: A standard Secret Key works, but Suger strongly recommends using a **Restricted Key** so you can grant least-privilege access scoped specifically to marketplace operations. See [Use Restricted Keys](#use-restricted-keys) for the required permissions. ## Create Integration In your [Suger Console Integration](https://console.suger.io/settings?tab=integrations), you will see the **Stripe** integration connection. Click the `Connect` button to create an integration with your stripe instance. This will open an dialog for you to input. > Stripe integration connection dialog in Suger Console The Public Key and Secret Key can be found in the stripe dashboard [apikeys](https://dashboard.stripe.com/apikeys). > Public Key and Secret Key location in Stripe dashboard ### Stripe Test Mode If you want to use stripe in your test environment with stripe test mode, use keys in stripe test mode dashboard [test apikeys](https://dashboard.stripe.com/test/apikeys). You may need a test suger organization to build a complete test environment. Or you can create the integration with test mode keys and then switch to live mode keys after the test is finished. ### Use Restricted Keys You can use stripe restricted keys with specific access limits and permissions for greater security. The Restricted key provided to the suger must have the following permissions. - Core resources - Balance - Read - Charges - Write - Customers - Write - Customer session - Write - Disputes - Write - Events - Read - PaymentIntents - Write - PaymentMethods - Write - Products - Write - SetupIntents - Write - Sources - Write - All Checkout resources - Write - All Billing resources - Write - All Order resources - Write - Webhook resources - Webhook Endpoints-Write > Stripe restricted key permissions configuration See more about stripe keys [stripe docs](https://docs.stripe.com/keys). Once the integration process is finished, you can proceed by clicking the `VERIFY` button. This action triggers the Suger service to test the connection to the APIs of your stripe instance. If everything is configured correctly, the integration status will be updated as `VERIFIED`. ## Manage Buyers & Customers When you use Suger's metering and billing with Stripe, each of your customers is represented by a Suger [buyer](https://doc.suger.io/billing/buyer/) that is linked to a **customer** in your Stripe account. Suger stores the Stripe customer ID on the buyer and uses it for every Stripe operation on that buyer's behalf — collecting payment methods, charging via PaymentIntents, applying charges to invoices, and matching incoming Stripe webhooks. ### How the link is established The link between a Suger buyer and a Stripe customer is established **when the buyer is created**, based on the optional **Stripe Customer ID** field: - **Stripe Customer ID provided** — Suger connects the buyer to that existing Stripe customer. It verifies the customer exists, tags it with a `sugerBuyerId` metadata entry pointing back to the Suger buyer, and imports the customer's saved payment methods into the buyer's wallet. No new Stripe customer is created. - **Stripe Customer ID left blank** — Suger automatically creates a new Stripe customer, populated from the buyer's name, description, and company address, and tagged with the same `sugerBuyerId` metadata. > **Duplicate protection:** If another buyer in your organization is already linked to the Stripe Customer ID you provide, buyer creation is rejected. This prevents two Suger buyers from pointing at the same Stripe customer. ### The link is set only at creation The Stripe Customer ID **cannot be changed after the buyer is created**. Editing a buyer does not re-connect it to a different Stripe customer or create a new one — only the create step performs the connect-or-create logic. To link a buyer to a different Stripe customer, create a new buyer. ### Payment methods and wallets Payment methods are collected securely through the Stripe SDK; sensitive card details are never stored in Suger. A buyer's wallet supports the following types, which map to Stripe payment methods: | Wallet type | Stripe payment method | Typical currency | |---|---|---| | Card | Card | All | | ACH Debit | US bank account | USD | | SEPA Debit | SEPA debit | EUR | | BACS Debit | BACS debit | GBP | | Credit | — (managed by Suger) | Buyer's currency | Credit is a Suger-managed balance rather than a Stripe object; it functions like store credit and is applied automatically during invoice payment. A default payment method can be set for a buyer to prioritize it when paying invoices. ## Create User Integration (MCP) This integration acts **on behalf of the individual user** (a member of the Stripe account), not the organization. Each team member connects their own Stripe account so that Suger AI operates with their personal permissions. See [Stripe MCP documentation](https://docs.stripe.com/mcp?mcp-client=other) for details. The Stripe MCP integration uses a dedicated OAuth 2.1 app registered with Stripe. The token it issues is scoped exclusively to `mcp.stripe.com` and is the credential used by Suger AI. ### Prerequisites Enable MCP access for your Stripe account before connecting: 1. Go to your [Stripe Dashboard](https://dashboard.stripe.com) → **Settings** → **Team and security**. 2. Under the **MCP access** section, enable MCP access for your account. > MCP access toggle in Stripe Team and security settings ### Connect 1. In the User Integrations section, find **Stripe MCP (User)** and click **Connect Stripe Account**. 2. You will be redirected to Stripe to authorize the MCP-scoped application. 3. After authorization, you will be redirected back to Suger. The integration status is set to `Verified` automatically. ## Create User Integration (OAuth) Connect your personal Stripe account to Suger via [Stripe Connect](https://docs.stripe.com/connect) OAuth. 1. In the User Integrations section, find **Stripe (User)** and click **Connect Stripe**. 2. You will be redirected to Stripe's authorization page. Review the permissions and click **Connect**. 3. After authorization, you will be redirected back to Suger with the integration connected. > **Note:** If your Stripe account is already **controlled by another platform**, this connection will fail. Since June 2021, Stripe does not allow a second platform using `read_write` OAuth scope to connect to a controlled account. You must disconnect from the controlling platform first. See [Stripe's OAuth reference](https://docs.stripe.com/connect/oauth-reference) for details. ## Suger AI Tools Suger AI connects to Stripe's MCP server using the integration's credentials. > MCP server URL: `https://mcp.stripe.com` > > Two integration levels are supported. The user-level MCP token takes precedence when both are connected. > > | Integration | Level | Auth | > |---|---|---| > | Stripe | Org | API key | > | Stripe MCP (User) | User | OAuth (PKCE) | > > See [Stripe MCP documentation](https://docs.stripe.com/mcp) for the full list of available tools. ## Edit Integration You can edit the integration to update the following fields: - **Enable Entitlement End Soon Notification**: When enabled, specify the number of days (10-60) before an entitlement ends to trigger notifications. Suger will send an initial notification when Stripe Marketplace entitlements approach ending, followed by reminders every 5 days. To configure recipients, follow the [email notification configuration guide](https://doc.suger.io/get-started/email-notification#configuration) and add the scope `END_SOON.ENTITLEMENT`. ## Delete Integration The stripe integration can be deleted like all other integrations. Once the deletion is triggered, no time window or methods to recover.