Stripe Integration

Stripe is LostChurn's primary integration and offers the deepest feature support. You can connect via OAuth for the fastest setup or use restricted API keys for more granular control over permissions.

Prerequisites

• An active Stripe account (any plan, including Stripe's free tier)
• Access to the Stripe Dashboard with admin or developer permissions
• A LostChurn account with at least one workspace created

If you plan to test the integration before going live, ensure you have access to Stripe's test mode (toggled in the top-right corner of the Stripe Dashboard).

Connection Steps

Option A: OAuth (Recommended)

OAuth is the fastest way to connect Stripe. LostChurn requests only the permissions it needs and Stripe handles credential management automatically.

1. In your LostChurn dashboard, navigate to Settings > Integrations.
2. Click Connect Stripe.
3. You will be redirected to Stripe's OAuth authorization page. Review the requested permissions and click Connect my Stripe account.
4. Stripe redirects you back to LostChurn. You will see a confirmation message with your Stripe account name and ID.
5. LostChurn automatically creates the required webhook endpoint in your Stripe account. No manual webhook setup is needed with OAuth.

Option B: Restricted API Key

If your organization requires manual control over API key permissions, you can connect with a restricted key instead.

1. In the Stripe Dashboard, go to Developers > API Keys.
2. Click Create restricted key.
3. Name the key LostChurn and grant the following permissions:
   • Charges: Read
   • Customers: Read and Write
   • Invoices: Read and Write
   • Payment Intents: Read and Write
   • Subscriptions: Read and Write
   • Events: Read
   • Webhook Endpoints: Read and Write
4. Click Create key and copy the key (it starts with rk_live_ or rk_test_).
5. In your LostChurn dashboard, go to Settings > Integrations > Stripe and click Connect with API Key.
6. Paste the restricted key and click Save.

Webhook Configuration

If you connected via OAuth, LostChurn automatically registers the webhook endpoint. If you used an API key, you need to set up the webhook manually.

Manual Webhook Setup

1. In the Stripe Dashboard, go to Developers > Webhooks.
2. Click Add endpoint.
3. Set the endpoint URL to:

   https://webhooks.lostchurn.com/v1/stripe

4. Under Events to send, select the following events:
   • invoice.payment_failed
   • invoice.payment_succeeded
   • invoice.payment_action_required
   • customer.subscription.deleted
   • customer.subscription.updated
   • customer.subscription.paused
   • customer.subscription.resumed
   • charge.failed
   • charge.succeeded
   • charge.refunded
   • charge.dispute.created
   • payment_intent.payment_failed
   • payment_intent.succeeded
   • payment_method.updated
   • payment_method.detached
5. Click Add endpoint.
6. On the endpoint detail page, click Reveal under Signing secret. Copy the secret (it starts with whsec_).
7. In your LostChurn dashboard, go to Settings > Integrations > Stripe and paste the webhook signing secret into the Webhook Secret field.

Webhook Signing Secret

LostChurn uses the webhook signing secret to verify that incoming events genuinely originated from Stripe. This prevents spoofed or tampered webhook payloads from triggering recovery actions. Never share your webhook signing secret or commit it to version control.

Verify Connection

After connecting, verify that events flow correctly:

1. In the Stripe Dashboard, go to Developers > Webhooks and select the LostChurn endpoint.
2. Click Send test webhook.
3. Select invoice.payment_failed as the event type and click Send test webhook.
4. In your LostChurn dashboard, go to Events and confirm the test event appears within a few seconds. It will be labeled with a test badge.
5. Alternatively, use the Stripe CLI to send test events from your terminal:

   stripe trigger invoice.payment_failed

A successful connection shows a green Connected badge on the Stripe card in Settings > Integrations and the test event appears in your Events feed with all fields parsed correctly.

Supported Events

Provider-Specific Notes

Test Mode vs. Live Mode

Stripe provides completely separate test and live environments. LostChurn respects this separation:

• Test mode keys (starting with sk_test_ or rk_test_) connect to Stripe's sandbox. All events, retries, and dunning emails operate in test mode only. Dunning emails are sent but clearly marked as test emails.
• Live mode keys (starting with sk_live_ or rk_live_) process real payments. Retries will charge real payment methods.

You can connect both test and live mode simultaneously. LostChurn shows them as separate connections in the dashboard.

Stripe CLI Testing

For local development and testing, you can forward Stripe webhook events to a local LostChurn instance using the Stripe CLI:

stripe listen --forward-to localhost:3000/v1/stripe

This is particularly useful for testing custom recovery campaigns before deploying them.

API Version

LostChurn targets Stripe API version 2024-12-18.acacia. Stripe automatically translates events to your account's configured API version. If you experience issues with event payloads, check that your Stripe account API version is 2023-10-16 or later under Developers > API Version.

Rate Limits

LostChurn respects Stripe's rate limits of 100 requests per second in live mode and 25 requests per second in test mode. Retry attempts are automatically throttled and distributed across time windows to stay well within these limits. If you have a Stripe Scale or custom plan with higher rate limits, contact LostChurn support to adjust your throughput settings.

Idempotency

All retry requests made by LostChurn include an idempotency key derived from the original payment intent or invoice ID. This guarantees that a retry is never accidentally duplicated, even if there is a network interruption between LostChurn and Stripe.

Multi-Currency Support

LostChurn fully supports Stripe's multi-currency invoicing. Failed payment amounts, recovery metrics, and revenue dashboards are all displayed in the original transaction currency. Summary statistics can be viewed in your configured base currency using Stripe's exchange rates.