Stripe Integration

Connect your own Stripe 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/<your-org-slug>/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.

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, the in-app assistant or the CLI) can do the whole setup for you. Ask it, for example:

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.

The tools need an API token with the settings permission and are listed in the tools reference. The signing secret is never returned to an agent. From the CLI:

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:

5. Save the endpoint.

<Callout type="warn"> The webhook URL contains a secret token. Treat it like a password and never share it. </Callout>

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_...).

<Callout type="warn"> 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. </Callout>

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#