> ## Documentation Index
> Fetch the complete documentation index at: https://docs.etho.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment processors

> Connect Whop, Paddle, Polar, PayPal, Lemon Squeezy, Commas, Orb, or Slash and record each paid charge as a Connect purchase

Olympus can connect payment processors under **Settings > Integrations > Commerce**. Each paid charge becomes a purchase on a contact. Refunds and disputes attach as evidence. Revenue shows in Measure once the workspace reports from purchases.

Stripe customer connections use the same path. Existing Stripe reporting stays on the older event table until a per-workspace cutover finishes.

Slash stays locked until Slash grants API access.

## Before you start

You need:

* Workspace settings permission to connect, rotate, disconnect, or start a backfill.
* A live API credential that can read payments. Sandbox and test keys are rejected.
* CRM read access to view sync health and purchases.

Olympus never asks for a host or base URL. Provider hosts are fixed.

## Connect

<Steps>
  <Step title="Open the Commerce group">
    Go to **Settings > Integrations** and find the processor under Commerce.
  </Step>

  <Step title="Paste the live credential">
    Olympus verifies the key with a read call before it stores anything. If the key cannot read payments, the connect fails and nothing is saved.
  </Step>

  <Step title="Confirm the webhook">
    Most processors let Olympus register the webhook. Orb, and Stripe keys without webhook write access, show the exact URL to paste plus a signing-secret field. Until that secret is saved, the connection polls only.
  </Step>

  <Step title="Wait for backfill">
    Connect starts a 90-day backfill of paid charges. Historical purchases do not fire ad conversions.
  </Step>
</Steps>

Permissions needed:

| Processor     | Credential                      | Notes                                                            |
| ------------- | ------------------------------- | ---------------------------------------------------------------- |
| Whop          | Account API key                 | Needs `payment:basic:read` and `member:email:read`.              |
| Polar         | `polar_oat_` organization token | Production host only.                                            |
| Paddle        | `pdl_live_apikey_`              | Sandbox keys are rejected.                                       |
| PayPal        | Client id and secret            | The app needs Transaction Search.                                |
| Lemon Squeezy | API key                         | Test-mode orders are dropped. Lemon Squeezy is moving to Stripe. |
| Commas        | API key                         | Production host only.                                            |
| Orb           | API key                         | Paste the webhook URL and signing secret in Orb.                 |
| Slash         | API key                         | Locked until API access is granted.                              |
| Stripe        | Restricted live key `rk_live_`  | Legacy webhook URL still works during cutover.                   |

## Health

The tile shows webhook vs polling, last delivery, last poll, backfill progress, retries, dead letters, unattributed count, and test-mode drops. It never shows secrets, account ids, or raw payloads.

If a poll finds charges that no webhook delivered, the connection is marked degraded with a `webhook_silent` issue.

## Purchases

Each terminal successful payment is one purchase on one opportunity in the Payments pipeline. Renewals and later invoices are new purchases. Refunds and disputes stay on the original purchase.

Payments without a matchable email go to an unattributed queue. Slash bank-ledger credits also land there until someone picks one opportunity.

## Measure

Revenue, LTV, cohorts, and attribution include every connected processor once the workspace revenue source is `purchases`. Deal count and average deal size still count opportunities, so renewal-heavy sellers see more deals than purchases.

Stripe cutover walks back to the workspace's earliest Stripe event, matches by PaymentIntent per currency, and flips only when nothing is truly missing. Workspaces already on `purchases` are skipped.

## Runbook

* **Degraded / webhook silent.** Check that the provider still has the Olympus endpoint enabled. Rotate the signing secret if needed. The next poll should clear the issue after deliveries resume.
* **Dead letters.** Open the existing sync-run surface and retry. The payload is not shown in health.
* **Unattributed.** Match the email on the contact, or for Slash bank credits pick one opportunity from the closed candidate list. Do not invent a match from amount or memo.
* **Cutover mismatch.** A `stripe_cutover_truly_missing` issue means an old Stripe event has no purchase. Review before flipping that workspace.