Connect your own [Stripe](https://stripe.com) account to Lumail. Every time a customer pays, starts a subscription, cancels or gets refunded, Lumail finds the matching subscriber by email and adds or removes the tags you chose. From there, your tags can start workflows, feed segments or stop a sales sequence. ## How It Works You connect your Stripe account in one click. Stripe then sends your payment events to Lumail, and for each event Lumail: 1. **Verifies** that the event is signed by Stripe and belongs to your connected account. 2. **Finds the customer email** in the event (or reads it from the Stripe customer) and creates the subscriber if it does not exist yet. 3. **Applies your tag rules** that match the event and the product. 4. **Records** the payment in the subscriber timeline (event type, amount, currency and product). Lumail only reads: payment events, the products of a Checkout session, the customer email and your product list. It never creates charges, never changes anything in your Stripe account and stores no Stripe API key or token. ## Setup Open **Settings -> Integrations -> Stripe**, at `https://lumail.io/orgs//settings/integrations/stripe`. Only organization owners and admins can configure it. ### Step 1: Connect with Stripe 1. Click **Connect with Stripe**. 2. On Stripe, pick the account to connect and authorize Lumail. 3. You are sent back to Lumail. The page shows the connected account, with a **Live** or **Test** badge. There is no URL or secret to copy. The page shows **Last event received** as soon as Stripe delivers an event. A Stripe account can be connected to one Lumail organization only. To move it, disconnect it from the first organization. ### Step 2: Create tag rules A rule says: **when** this happens in Stripe, **add** these tags and **remove** those tags. | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | When | `Payment succeeded`, `Subscription started`, `Subscription canceled` or `Payment refunded` | | Product | Optional. Pick a product or one of its prices from your Stripe account, or type an ID. Empty matches every product | | Add tags | Tags added to the subscriber. Tags that do not exist yet are created | | Remove tags | Tags removed from the subscriber | Examples: - **Payment succeeded**, any product -> add `customer`, remove `lead` - **Subscription started**, `prod_ABC123` -> add `pro-plan` - **Subscription canceled** -> add `churned`, remove `pro-plan` - **Payment refunded** -> add `refunded`, remove `customer` You can create up to 50 rules. No subscriber is created or changed when no rule matches an event. ## Let your AI agent set it up An AI agent connected to Lumail (the [MCP server](/docs/ai-integration), the in-app assistant or the [CLI](/docs/api-reference/cli)) can do the whole setup for you. Ask it, for example: ```text Connect my Stripe account to Lumail. Then tag buyers of the "Pro" plan with "customer-pro", and remove that tag when they cancel or get refunded. ``` The agent gives you a **Connect with Stripe** link. Open it while signed in to Lumail as an owner or admin and approve on Stripe: this is the only step you do yourself. The agent then checks the connection, reads your products and creates the rules. | Tool | What it does | | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `get_stripe_integration` | Status: connected or not, mode, account, test or live, last event, rules | | `start_stripe_connection` | Returns the Connect with Stripe link, or the webhook URL and events in manual mode | | `save_stripe_signing_secret` | Manual mode: saves the `whsec_...` secret you give the agent | | `list_stripe_products` | Products and prices of the connected account | | `add_stripe_tag_rule`, `update_stripe_tag_rule`, `remove_stripe_tag_rule`, `set_stripe_tag_rules` | Manage tag rules, with the same validation as this page | | `disconnect_stripe_integration` | Disconnects Stripe. Asks for a confirmation code first | The tools need an API token with the `settings` permission and are listed in the [tools reference](/docs/ai-integration/tools-reference). The signing secret is never returned to an agent. From the CLI: ```bash lumail tools run get_stripe_integration lumail tools run add_stripe_tag_rule --params '{"trigger":"payment_succeeded","addTags":["customer"]}' ``` ## Advanced: connect with a webhook endpoint Use this only if you cannot authorize Lumail on your Stripe account. On the Stripe integration page, open **Advanced: connect with a webhook endpoint**. Lumail then reads only what the events contain: see the limits in "Product filters" and "Customer email" below. ### Add the webhook endpoint in Stripe 1. In Lumail, click **Generate webhook URL** and copy the URL. 2. In Stripe, open **Developers -> Webhooks** and click **Add endpoint** (or **Add destination**). 3. Paste the Lumail URL as the endpoint URL. 4. Select these events: | Stripe event | Used for | | ------------------------------- | -------------------------------------------------------------------- | | `checkout.session.completed` | Payment succeeded, subscription started | | `invoice.paid` | Payment succeeded (first payment and renewals), subscription started | | `customer.subscription.created` | Subscription started | | `customer.subscription.deleted` | Subscription canceled | | `charge.refunded` | Payment refunded | 5. Save the endpoint. The webhook URL contains a secret token. Treat it like a password and never share it. ### Paste the signing secret 1. On the endpoint page in Stripe, reveal the **Signing secret**. It starts with `whsec_`. 2. Paste it in Lumail and click **Save secret**. Lumail stores the secret encrypted and never shows it again, only its last 4 characters. You can replace it at any time, for example after rolling the secret in Stripe. Use **Send test events** in Stripe, or make a test payment, to check the connection. Then create your tag rules: in this mode the product field takes a Stripe product ID (`prod_...`), price ID (`price_...`) or payment link ID (`plink_...`). Use one method per Stripe account. With both the connection and a webhook endpoint on the same account, keep only the connection and delete the endpoint in Stripe. ## Behavior Details ### One purchase, one application Stripe often sends several events for the same purchase, for example `checkout.session.completed` and `invoice.paid`. Lumail applies each rule once per purchase, and once per event if Stripe delivers the same event again. ### Product filters - **Invoices and subscriptions** carry their products and prices, so product rules work for subscriptions, renewals and invoiced payments. - **One-time Checkout payments**: with a connected account, Lumail reads the products of the Checkout session from Stripe, so product rules work. - **Refunds** do not carry the product. They only match rules without a product. With a webhook endpoint (advanced), Lumail cannot read the Checkout session: one-time Checkout payments without an invoice only match rules without a product, or a rule set to the payment link ID. To filter them by product, connect your account or enable invoice creation on your Checkout sessions or payment links in Stripe. ### Customer email - Payments use the email from Checkout, the invoice or the charge. - Subscription events only carry the Stripe customer ID. Lumail remembers the email of each customer it saw in a payment event. With a connected account, it reads the email of an unknown customer from Stripe. - With a webhook endpoint (advanced), a cancellation for a customer Lumail never saw paying is skipped. ### Subscription status - A payment does not resubscribe someone who unsubscribed: tags are applied, the subscription status stays the same. - Bounced, complained and banned subscribers are skipped. ### Amounts Amounts are recorded in the smallest currency unit, as Stripe sends them (`4900` for 49.00 EUR). ## Disconnect Click **Disconnect** on the Stripe integration page. Lumail revokes its access on your Stripe account, the webhook URL (if any) stops working, the signing secret and your rules are deleted. Tags already applied to your subscribers stay. If you added a webhook endpoint in Stripe, delete it there too. You can also revoke Lumail's access from your Stripe dashboard: Lumail then disconnects the account on its side and keeps your rules. ## Troubleshooting | Problem | Cause and fix | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "This Stripe account is already connected to another organization" | A Stripe account works with one Lumail organization. Disconnect it there first, or connect another Stripe account | | "The connection request expired" | The authorization took more than 10 minutes or the link was used twice. Click **Connect with Stripe** again | | Connected, but no event arrives | Check the badge: an account connected in test mode only receives test payments, and a live one only live payments | | Stripe shows `400 Invalid signature` | The signing secret saved in Lumail is not the one of this endpoint. Copy it again from the endpoint page in Stripe (test mode and live mode endpoints have different secrets) | | Stripe shows `400 Stripe signing secret is not configured` | Save the signing secret in Lumail (step 2) | | Stripe shows `401` | The webhook URL is wrong or the integration was disconnected. Generate a new URL and update the endpoint | | Events arrive but no tag is applied | No rule matches. Check the trigger and the product ID, and see "Product filters" above |