OAuth Integration Setup

OAuth lets you connect payment processors to LostChurn without manually copying API keys. You authorize LostChurn through your provider's consent screen, and we handle the rest -- webhook registration, token storage, and automatic refresh.

Supported OAuth Providers

For providers without OAuth support (Braintree, Chargebee, Adyen, etc.), see Manual API Key Setup below.

How OAuth Works

The entire flow happens in your browser. LostChurn never sees your provider password -- you authorize directly on the provider's site.

Stripe OAuth

Stripe offers the fastest integration, typically requiring just two clicks.

Setup Steps

1. Go to Settings → Integrations → Stripe
2. Click Connect with Stripe
3. You will be redirected to Stripe's authorization page
4. Review the requested permissions and click Allow
5. You are redirected back to LostChurn with the connection active

What Happens Automatically

• LostChurn receives an access token scoped to your Stripe account
• A webhook endpoint is registered at https://api.lostchurn.com/webhooks/stripe/{merchant_id}
• Events are configured: invoice.payment_failed, invoice.payment_succeeded, customer.subscription.updated, and others
• Your existing Stripe webhooks are not affected

Paddle OAuth

Paddle uses OAuth 2.0 with a token exchange flow. Webhook registration must be completed manually.

Setup Steps

1. Go to Settings → Integrations → Paddle
2. Click Connect with Paddle
3. Authorize LostChurn on Paddle's consent screen
4. After redirect, LostChurn exchanges the authorization code for an access token
5. Manual step: In your Paddle dashboard, add the webhook URL shown in LostChurn's settings

Webhook Configuration

After OAuth completes, LostChurn displays the webhook URL you need to register in Paddle:

https://api.lostchurn.com/webhooks/paddle/{merchant_id}

In your Paddle dashboard:

1. Go to Developer Tools → Notifications
2. Create a new notification destination
3. Paste the URL above
4. Select events: transaction.payment_failed, transaction.completed, subscription.updated

Recurly OAuth

Recurly supports OAuth with automatic webhook registration.

Setup Steps

1. Go to Settings → Integrations → Recurly
2. Click Connect with Recurly
3. Authorize on Recurly's consent screen
4. LostChurn exchanges the code for tokens and registers webhooks automatically

Permissions Requested

• Read invoices and transactions
• Create charges (for payment retries)
• Read and manage subscriptions
• Register webhook endpoints

GoCardless OAuth

GoCardless uses OAuth 2.0 with separate sandbox and production environments.

Setup Steps

1. Go to Settings → Integrations → GoCardless
2. Select your environment: Sandbox or Production
3. Click Connect with GoCardless
4. Authorize on the GoCardless consent screen
5. LostChurn stores the access token and registers webhook endpoints

Environment URLs

Security

CSRF Protection

Every OAuth flow includes a cryptographically random state parameter. When the provider redirects back to LostChurn, we verify that the state matches the value we generated. This prevents cross-site request forgery attacks where a malicious site could trick you into connecting a different account.

Encrypted Token Storage

OAuth tokens are encrypted at rest using AES-256-GCM before being stored. The encryption key is managed separately from the database, so a database breach alone cannot expose your provider credentials.

Automatic Token Refresh

When a provider issues a refresh token (Stripe, Recurly, GoCardless), LostChurn automatically refreshes the access token before it expires. You do not need to re-authorize unless you explicitly revoke access.

Revoking Access

To disconnect a provider:

1. Go to Settings → Integrations → select the provider
2. Click Disconnect
3. Confirm the action

This revokes the OAuth token on the provider side and removes stored credentials from LostChurn. Any in-progress recoveries using that provider will be paused.

Manual API Key Fallback

For payment processors that do not support OAuth, you can connect using API keys:

1. Go to Settings → Integrations → select the provider
2. Enter your API key and secret (or equivalent credentials)
3. Click Verify & Connect
4. Register the webhook URL shown in your provider's dashboard

Providers requiring manual API key setup include:

• Braintree -- API keys from the Control Panel
• Chargebee -- API key from Settings → API Keys
• Adyen -- API key + merchant account from Customer Area
• Authorize.Net -- API Login ID + Transaction Key
• PayPal -- Client ID + Secret from Developer Dashboard
• Checkout.com -- Secret key from the Hub
• Nuvei -- Merchant ID + Secret Key
• Worldpay -- Service key from the dashboard

Troubleshooting OAuth Errors

"Invalid redirect URI"

The redirect URI registered with the provider does not match the one LostChurn sends. This usually means:

• Your provider app configuration has an outdated callback URL
• You are testing on a different environment (localhost vs. production)

Fix: Verify the redirect URI in your provider's developer settings matches https://app.lostchurn.com/api/oauth/callback/{provider}.

"Access denied" or "Authorization cancelled"

The user clicked "Deny" on the consent screen, or the browser was closed before completing authorization.

Fix: Try the connection flow again and click "Allow" on the consent screen.

"Invalid state parameter"

The state token from the callback does not match the one LostChurn generated. This can happen if:

• The authorization took too long (state tokens expire after 10 minutes)
• You have multiple browser tabs attempting OAuth simultaneously
• A browser extension interfered with the redirect

Fix: Close other tabs, disable interfering extensions, and retry the connection from a fresh page.

"Token exchange failed"

The authorization code could not be exchanged for an access token. This is usually a transient provider issue.

Fix: Wait a few minutes and retry. If the problem persists, check the provider's status page for outages.

Next Steps

• Stripe Integration -- detailed Stripe setup guide
• Quick Setup Wizard -- connect a provider as part of the guided setup
• Security -- learn more about how LostChurn protects your credentials