Use FunnelFox with Primer

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

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.

​

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 and Adaptive 3DS.

​

Who owns what

​

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.

​

Set up FunnelFox with Primer

​

Prerequisites

• A Primer account with at least one processor connected and a Workflow configured. See Connect a processor.
• A Primer API key. See 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 and 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.
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.
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.

​

Reference documentation

• FunnelFox Subscription Engine documentation