FunnelFox Billing manages the complete payment lifecycle, from initial charge through retries and recovery. This architecture enables features like PSP switching and intelligent routing without disrupting your subscription logic.
Key insight: FunnelFox separates subscription management from payment processing. PSPs only handle charge authorization while FunnelFox manages everything else - subscriptions, retries, and customer lifecycle.

​
Architecture Overview

​
Separation of Responsibilities

FunnelFox Billing creates a layer between your business logic and payment providers: Architecture Flow:
  • Customer to FunnelFox Billing
  • FunnelFox to Products & Subscriptions
  • FunnelFox to Payment Router
  • Router to Multiple PSPs (Stripe, PayPal, Adyen, etc.)
FunnelFox Manages:
  • Product catalog and pricing
  • Customer profiles and data
  • Subscription lifecycle
  • Retry logic and schedules
  • Grace periods
PSPs Handle:
  • Card authorization
  • Payment processing
  • Regulatory compliance
  • Settlement and payouts
This separation means you can switch PSPs instantly without touching your funnel logic or affecting active subscriptions.

​
Payment Routing

​
How Routing Works

FunnelFox intelligently routes each payment based on your configuration:
1

Payment initiated

Customer submits payment in your funnel checkout
2

Router evaluates

System checks routing rules and PSP availability
3

PSP selected

Primary PSP attempted first, fallback if needed
4

Charge processed

PSP authorizes card and processes payment
5

Result handled

FunnelFox updates subscription based on result

​
Routing Strategies

Most common setup for reliability:
  • Primary PSP: Handles 95%+ of transactions
  • Fallback PSP: Activated if primary fails
  • Automatic switchover on errors
  • No customer friction during issues
Example: Stripe primary, PayPal fallback
Coming soon: Smart routing based on real-time approval rates, allowing automatic optimization without manual configuration.

​
Retry Mechanism

​
Intelligent Recovery

When payments fail, FunnelFox automatically attempts recovery:
​
Retry Schedule
string
Attempts vary based on billing period:
  • Daily: Retry after 1 day
  • Weekly: Retry after 2, 4 days
  • Monthly: Retry after 3, 7, 14 days
  • Yearly: Retry after 7, 14, 21, 28 days
​
Decline Analysis
string
Different retry strategies based on decline reason:
  • Insufficient funds: Retry in 3-5 days
  • Expired card: Email for update, longer retry
  • Lost/stolen: No retry, immediate cancellation
  • Generic decline: Standard retry schedule

​
Grace Periods

Keep customers active during payment recovery: How Grace Periods Work:
  1. Payment fails on renewal date
  2. Subscription enters grace period
  3. Customer retains full access
  4. Retry attempts continue
  5. Success extends subscription
  6. Final failure triggers cancellation
Grace Period Lengths:
  • Daily subscriptions: 1 day
  • Weekly subscriptions: 3 days
  • Monthly subscriptions: 7-14 days
  • Annual subscriptions: 30 days
Billing cycle adjustment: If payment succeeds during grace period, the billing cycle shifts forward to the success date. This ensures customers only pay for periods with access.

​
Transaction Lifecycle

​
New Subscription Flow

1

Customer initiates

Enters card details in funnel checkout
2

Validation

Card validated and tokenized by PSP
3

Authorization

Initial payment authorized and captured
4

Subscription created

FunnelFox creates subscription record
5

Access granted

Customer gains immediate access
6

Confirmation

Email receipt and welcome message sent

​
Renewal Flow

1

Renewal triggered

System initiates charge before period ends
2

Payment attempt

Charge processed using stored payment method
3

Success path

If successful: Subscription extended, invoice sent
4

Failure path

If failed: Enter grace period, begin retry sequence
5

Recovery

Multiple retry attempts based on schedule
6

Resolution

Either payment recovers or subscription cancels

​
Supported PSPs

​
Current Integrations

FunnelFox Billing supports these payment providers:

Stripe

Best for: SaaS, digital products Strengths: Developer-friendly, global reach Regions: 40+ countries

PayPal

Best for: Consumer products Strengths: Customer trust, buyer protection Regions: 200+ countries

Adyen

Best for: Enterprise, high volume Strengths: Approval rates, unified commerce Regions: Global coverage

Checkout.com

Best for: Emerging markets Strengths: Local payment methods Regions: Strong in APAC, MENA
Additional providers can be added on request. Each PSP integration includes full support for cards, 3D Secure, and webhooks.

​
Advanced Features

​
Partial Refunds

Issue refunds without canceling subscriptions:
Refund part of current period for service issues. Subscription continues normally with full access maintained.

​
Subscription Migrations

Move subscriptions between PSPs seamlessly:
  1. Customer subscriptions identified for migration
  2. New payment method collected if needed
  3. Next renewal processes through new PSP
  4. Historical data preserved
  5. No service interruption

​
Monitoring & Analytics

​
Key Metrics

Track payment performance across PSPs:
​
Authorization Rate
percentage
Percentage of payment attempts that succeed. Target: >90% for established businesses.
​
Recovery Rate
percentage
Percentage of failed payments recovered through retries. Good: >30%, Excellent: >50%.
​
Churn Rate
percentage
Percentage of subscriptions lost to payment failures. Target: <5% involuntary churn.
​
PSP Performance
string
Compare approval rates, fees, and settlement times across providers to optimize routing.

​
Best Practices

​
Optimization Tips

Reduce Failures:
  • Collect billing ZIP/postal code
  • Use 3D Secure for high-risk transactions
  • Update cards before expiration
  • Send pre-dunning notifications
Improve Recovery:
  • Optimize retry timing for your audience
  • Test different dunning messages
  • Offer payment method updates via email
  • Consider grace period extensions
Maximize Revenue:
  • Route by approval probability
  • Use local payment methods
  • Implement smart retry logic
  • Monitor and adjust continuously

​
Troubleshooting

​
Next Steps