PayPal Integration

PayPal is one of the world's most widely used payment platforms, supporting both PayPal wallet payments and direct credit/debit card processing. LostChurn connects to PayPal via OAuth 2.0 and processes webhook notifications to detect and recover failed subscription payments.

Prerequisites

• An active PayPal Business account
• Access to the PayPal Developer Dashboard with admin permissions
• A PayPal REST API app created in the Developer Dashboard (or willingness to create one during setup)
• A LostChurn account with at least one workspace created

Connection Steps

LostChurn connects to PayPal using OAuth 2.0, which provides secure, token-based access without exposing long-lived API keys.

1. In your LostChurn dashboard, go to Settings > Integrations and click Connect PayPal.
2. You will be redirected to PayPal's consent page. Log in with your PayPal Business account.
3. Review the requested permissions:
   • Billing Agreements: Read and execute
   • Payments: Read and create
   • Subscriptions: Read and manage
   • Webhooks: Read and create
4. Click Grant Permission.
5. You are redirected back to LostChurn with OAuth tokens automatically configured.
6. LostChurn registers the required webhook subscriptions with PayPal. No manual webhook setup is needed.

Alternative: Manual API App Setup

If your organization requires manual credential management:

1. Go to the PayPal Developer Dashboard.
2. Click Create App.
3. Name the app LostChurn and select Merchant as the app type.
4. Copy the Client ID and Secret.
5. In your LostChurn dashboard, select Connect with API Credentials on the PayPal integration page.
6. Select your environment (Sandbox or Live), paste the Client ID and Secret, and click Save and Verify.

Webhook Configuration

If you connected via OAuth, LostChurn automatically registers webhooks. For manual connections:

1. In the PayPal Developer Dashboard, go to My Apps & Credentials and select the LostChurn app.
2. Scroll down to Webhooks and click Add Webhook.
3. Set the Webhook URL to:

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

4. Select the following event types:
   • PAYMENT.SALE.COMPLETED
   • PAYMENT.SALE.DENIED
   • PAYMENT.SALE.REFUNDED
   • PAYMENT.SALE.REVERSED
   • BILLING.SUBSCRIPTION.CREATED
   • BILLING.SUBSCRIPTION.ACTIVATED
   • BILLING.SUBSCRIPTION.UPDATED
   • BILLING.SUBSCRIPTION.CANCELLED
   • BILLING.SUBSCRIPTION.SUSPENDED
   • BILLING.SUBSCRIPTION.PAYMENT.FAILED
   • BILLING.SUBSCRIPTION.RE-ACTIVATED
   • BILLING.SUBSCRIPTION.EXPIRED
   • CUSTOMER.DISPUTE.CREATED
   • CUSTOMER.DISPUTE.RESOLVED
   • CUSTOMER.DISPUTE.UPDATED
5. Click Save.

Webhook Signature Verification

PayPal signs webhook notifications using its own certificate-based verification system. LostChurn verifies each incoming webhook by calling PayPal's POST /v1/notifications/verify-webhook-signature endpoint, which cryptographically validates that the notification originated from PayPal.

Verify Connection

1. In the PayPal Developer Dashboard, go to My Apps & Credentials, select the LostChurn app, and navigate to Webhooks.
2. Click Simulate Event next to the LostChurn webhook.
3. Select BILLING.SUBSCRIPTION.PAYMENT.FAILED as the event type and click Send Test.
4. In your LostChurn dashboard, navigate to Events and confirm the test event appears.
5. For a more thorough test in sandbox mode, create a test subscription using PayPal's sandbox buyer account and simulate a payment failure.

A successful connection shows a green Connected badge on the PayPal card in Settings > Integrations.

Supported Events

Provider-Specific Notes

PayPal Wallet vs. Card Payments

PayPal supports two primary payment types for subscriptions:

• PayPal Wallet: Customers pay using their PayPal balance, linked bank account, or PayPal Credit. Failed payments due to insufficient PayPal balance behave differently from card declines. LostChurn adjusts retry timing for wallet-based failures, which often resolve when the customer adds funds.
• Card Payments: Customers pay via credit or debit card processed through PayPal. These behave similarly to direct card payments and use the same decline code taxonomy.

LostChurn identifies the payment type from the webhook payload and applies the appropriate recovery strategy.

Sandbox Environment

PayPal provides a comprehensive sandbox at sandbox.paypal.com:

• Create sandbox buyer and seller accounts in the Developer Dashboard under Sandbox > Accounts.
• Sandbox transactions use simulated processing and do not charge real accounts.
• LostChurn labels sandbox events with a sandbox badge.

Reference Transactions

PayPal's reference transaction feature allows merchants to charge a customer's PayPal account without requiring re-authorization. If your PayPal account has reference transactions enabled, LostChurn can use them for retries, improving recovery rates by charging without requiring customer intervention.

Note that reference transactions require PayPal approval and are not available on all accounts. Contact PayPal support to check eligibility.

PayPal Subscriptions API vs. Billing Agreements

PayPal offers two subscription systems:

• Subscriptions API (current): Uses plan-based subscriptions with built-in lifecycle management. LostChurn supports this fully.
• Billing Agreements (legacy): Older system using billing agreement tokens. LostChurn supports billing agreements but recommends migrating to the Subscriptions API for richer event data.

Buyer Protection and Disputes

PayPal's buyer protection program means disputes are more common than with direct card payments. LostChurn automatically pauses all retry and dunning activity when a dispute is opened and resumes only after the dispute is resolved in the merchant's favor.

Rate Limits

PayPal enforces rate limits that vary by API endpoint and account tier. General limits are approximately:

• Standard accounts: 30 requests per second.
• High-volume accounts: Custom limits negotiated with PayPal.

LostChurn monitors PayPal's rate limit response headers and throttles requests accordingly. If you receive 429 errors in your LostChurn logs, contact PayPal to request a rate limit increase.

Multi-Currency

PayPal supports payments in 25+ currencies. LostChurn tracks recovery amounts in the original transaction currency and provides consolidated reporting in your configured base currency using PayPal's exchange rates.