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

# Use FunnelFox with Primer

> Primer payments power FunnelFox's subscription engine

FunnelFox Payments is a subscription engine with a native Primer integration. FunnelFox is the system of record for your product catalog and subscription state: what each customer bought, what they have access to, and when they are charged next. Primer processes every payment, from the first checkout through each renewal, using your Primer account and the processors connected to it.

FunnelFox runs the recurring payment logic: it schedules and starts renewals and retries through Primer. You are not required to handle any logic to create payments and report the results back to the billing system. On your side, you add a checkout to your paywall and handle FunnelFox webhooks to keep access in your product in sync.

## How it works

```mermaid theme={"dark"}
sequenceDiagram
    participant C as Customer
    participant W as Your paywall
    participant F as FunnelFox
    participant P as Primer
    participant X as Processor
    participant M as Your backend
    C->>W: Selects a plan
    W->>F: Create checkout for a price point (FunnelFox Web SDK)
    C->>P: Pays via Primer Checkout
    P->>X: Authorise, vault the payment method
    X-->>P: Approved
    P-->>F: Payment result
    F->>M: Webhook: subscription started
    Note over F: Before each billing cycle
    F->>P: Renewal payment with the vaulted payment method
    P->>X: Process the renewal
    X-->>P: Approved or declined
    P-->>F: Result
    F->>M: Webhook: renewed, or recovery started
```

*Figure 1. FunnelFox owns the subscription and decides when to charge. Primer runs every payment.*

FunnelFox keeps what a customer can access separate from what they pay:

* **Offerings** are entitlements, such as access to a feature.
* **Price points** are versioned pricing configurations (currency, trial, renewal terms) that grant one or more offerings.
* **Purchases** are what a customer holds: a recurring subscription, a one-off lifetime purchase, or a consumable.

This lets you change what you charge without changing what existing customers can access.

A subscription moves through statuses such as `INTRO` (trial), `RECURRING`, `GRACE`, `RETRY`, `PAUSED`, `AUTORENEW_OFF` and `EXPIRED`. A `RECURRING` subscription is charged two hours before each billing cycle starts. See [subscription statuses](https://funnelfox.com/docs/billing/view-subscriptions-billing#status).

### Failed payment recovery

When a renewal fails, FunnelFox runs recovery:

* **Retry schedules.** Choose a long or a short schedule. Both adapt to the billing interval, and later attempts can be partial charges, for example 70% or 50% of the amount.
* **Grace period.** The customer keeps access while recovery is in progress.
* **Cascading.** A failed payment can be sent to a backup processor before the retry schedule starts.
* **Adaptive 3DS.** Payments are first attempted without 3DS. 3DS is triggered only when the issuer requires authentication. If the payment then cascades, the 3DS result is reused on the backup processor.

See FunnelFox documentation for [Retries and cascading](https://funnelfox.com/docs/billing/payments-retries) and [Adaptive 3DS](https://funnelfox.com/docs/billing/payments-adaptive-3ds).

### Who owns what

| FunnelFox | Your team | Primer |
| - | - | - |
| Offerings and price points, trials, subscription state and lifecycle, renewal scheduling, retries, grace periods, cascading, plan changes, pauses, cancellations and refunds, subscription webhooks | Paywall or funnel, customer identifiers, granting and revoking access based on FunnelFox webhooks | Checkout, vaulting and network tokens, payment processing across your connected processors, 3DS, decline codes |

## Things to plan for

* FunnelFox enables FunnelFox Payments for each account. Contact FunnelFox to set up a sandbox account. Your agreement with FunnelFox is separate from your Primer agreement.
* Checkout uses Primer's Checkout, either through the FunnelFox Web SDK or through FunnelFox funnels. Primer's Web SDK must load on the page before the FunnelFox SDK.
* The Subscription engine allows at most two charges per day per payment method token.
* FunnelFox offers dispute prevention through Ethoca and Verifi alerts, which refund a disputed transaction before it becomes a chargeback. It takes about two weeks to go live. See [Disputes](https://funnelfox.com/docs/billing/disputes).

## Set up FunnelFox with Primer

### Prerequisites

* A Primer account with at least one processor connected and a Workflow configured. See [Connect a processor](/docs/get-started/connect-a-processor).
* A Primer API key. See [Authentication](/docs/api-reference/get-started/authentication).
* A FunnelFox Payments account.

### Steps

1. **Connect Primer to FunnelFox.** In FunnelFox Payments, go to **Settings > Main** and add your Primer credentials under **Payment provider credentials**:
   * **Domain:** `https://api.sandbox.primer.io` for sandbox, or `https://api.primer.io` for production. FunnelFox uses the domain to tell whether you're in live mode.
   * **Private key:** your Primer API key.
   * **Webhook signing secret:** your Primer webhook signing secret, from the Primer Dashboard.
2. **Create offerings and price points** in FunnelFox. See [Offerings](https://funnelfox.com/docs/billing/settings-offerings) and [Price points](https://funnelfox.com/docs/billing/settings-price-points).
3. **Add checkout to your paywall.** In FunnelFox funnels, select FunnelFox Billing as the payment provider. On your own paywall, install `@funnelfox/billing` together with `@primer-io/checkout-web`, then call `createCheckout`. See the [Web SDK quickstart](https://funnelfox.com/docs/develop/web-sdk-quickstart).
4. **Handle FunnelFox webhooks** to grant and revoke access in your product. FunnelFox sends events for orders, subscriptions, one-off purchases, refunds and disputes. See [Webhooks](https://funnelfox.com/docs/develop/webhooks-billing).
5. **Configure recovery.** Choose your retry schedule in FunnelFox **Settings**, and set up cascading and Adaptive 3DS with FunnelFox.
6. **Test in sandbox** before you switch the domain to production. See [Testing](https://funnelfox.com/docs/billing/testing).

<Note>
  Payments are processed by your own Primer account, so they show up in the Primer Dashboard next to your other transactions.
</Note>

## Reference documentation

* [FunnelFox Subscription Engine documentation](https://funnelfox.com/docs/billing/subscription-engine-overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.