Payments

Directories are a wonderful way to earn money, so it comes with afull payment process built-in.

DirectoryFast provides a comprehensive monetization platform with multiple revenue streams, powered by Polar for secure payment processing.

Why Polar? Developer-first infrastructure with native TypeScript support, superior webhook handling, and seamless integration with modern auth systems.

Quick Setup

1. Create Polar Account

Sign up at polar.sh
Create an organization for your directory
Get your access token from the dashboard

2. Configure Environment Variables

Add these to your .env file:

# Polar Configuration
POLAR_ACCESS_TOKEN=your_polar_access_token
POLAR_WEBHOOK_SECRET=your_polar_webhook_secret

# Server Configuration (production/sandbox)
POLAR_SERVER=production  # or 'sandbox' for testing

3. Auto-Sync Products from Polar

NEW: DirectoryFast now automatically syncs products from your Polar dashboard:

Navigate to /dashboard/admin/monetization
Click "Sync from Polar" button to fetch all products
Products are automatically imported with current names and pricing
Assign feature types to enable different monetization features

4. Setup Webhooks

Webhook endpoint: https://yourdomain.com/api/polar/webhooks

Go to Polar dashboard → Settings → Webhooks
Create new webhook with your domain endpoint
Select events: order.created, subscription.created, subscription.updated
Add webhook secret to your environment variables

Monetization Features

Paid Submissions

NEW in v1.6.0 - Multiple submission tiers for faster processing:

Express Submission

Priority review queue
24-48 hour processing time
Standard listing placement
Submission status tracking

Premium Submission

Same-day review process
Featured placement for 7 days
Priority customer support
Social media promotion

Free Submission (Optional)

Manual review process
7-14 days processing time
Admin configurable (can be disabled)

Advertising System

NEW in v1.6.0 - Complete advertising platform with multiple placement options:

Available Ad Placements

Homepage Hero - Prime banner placement (up to 4 ads)
Product Page Sidebar - Product page sidebar placement (up to 4 ads)
Blog Sidebar - Blog post sidebar placement (up to 4 ads)
Collection Page - Collection page banner placement (up to 4 ads)
Category Page - Category page banner placement (up to 4 ads)

Ad Features

Monthly flat-rate pricing (no CPC/CPM complexity)
Capacity management (maximum ads per placement)
Real-time approval workflow
Revenue tracking and analytics
Campaign management dashboard

Product Management

Feature Type System

Products can be assigned different feature types in the admin dashboard:

featured - Traditional featured product listings
express_submission - Fast-track submission processing (24-48h)
premium_submission - Same-day review + featured placement
ads_homepage_hero - Homepage hero banner placement
ads_product_page - Product page sidebar placement
ads_blog_sidebar - Blog post sidebar placement
ads_collection_page - Collection page placement
ads_category_page - Category page placement
unused - Products not configured for any feature

Auto-Sync Capabilities

Automatic product discovery from Polar dashboard
Real-time price updates when syncing
Preserved manual configurations (slugs, feature types, status)
Batch import of all Polar products with one click
Error handling for missing or invalid products

Implementation Details

Enhanced Checkout Flow

// Product submission with tier selection
const handlePaidSubmission = async (submissionType: 'free' | 'express' | 'premium') => {
  try {
    const response = await fetch('/api/submit-paid', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        productTitle,
        productOwner,
        productCategory,
        productUrl,
        productComment,
        submissionType
      })
    });
    
    const { checkoutUrl } = await response.json();
    if (checkoutUrl) {
      window.location.href = checkoutUrl;
    }
  } catch (error) {
    console.error('Submission failed:', error);
  }
};

Advertising Checkout

// Ad campaign creation
const handleAdPurchase = async (campaignData: AdCampaignData) => {
  try {
    const response = await fetch('/api/ads/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ campaignData })
    });
    
    const { checkoutUrl } = await response.json();
    window.location.href = checkoutUrl;
  } catch (error) {
    console.error('Ad purchase failed:', error);
  }
};

Enhanced Webhook Processing

// Webhook handling for multiple payment types
if (event.type === 'order.created' && order.state === 'succeeded') {
  const { type, submissionType, campaign_id, ad_id } = order.metadata;
  
  // Route to appropriate handler
  if (type === 'paid_submission') {
    await handlePaidSubmission(payload, userEmail, orderId, metadata);
  } else if (campaign_id || ad_id) {
    await handleAdCampaignPayment(payload, userEmail, orderId, metadata);
  } else if (metadata.productSlug) {
    await handleFeaturedProduct(payload, userEmail, orderId, metadata);
  }
}

Admin Configuration

Monetization Dashboard

Access comprehensive monetization controls at /dashboard/admin/monetization:

Product Management - Sync and configure Polar products
Feature Type Assignment - Map products to directory features
Submission Settings - Configure paid submission options
Advertising Settings - Enable/disable advertising system
Revenue Analytics - Track income across all features

Settings Configuration

Enable features in /dashboard/admin/settings:

Polar Configuration - API keys and server settings
Advertising Toggle - Enable/disable advertising system
Submission Toggle - Enable/disable free submissions

Customer Portal

Users can manage their billing through:

Sidebar billing button in dashboard
Automatic redirection to Polar customer portal
Subscription management and billing history
Invoice downloads and payment tracking

Revenue Tracking

Analytics Dashboard

Track revenue across all monetization features:

Featured product revenue with duration tracking
Paid submission revenue by tier
Advertising revenue by placement and campaign
Monthly/annual revenue trends
Customer lifetime value tracking

Troubleshooting

Common Issues

Sync fails: Check POLAR_ACCESS_TOKEN validity
Webhook not receiving: Verify endpoint URL and secret
Products not appearing: Ensure products are active in Polar
Feature types not working: Check product configuration in monetization dashboard
Paid submissions failing: Verify feature type assignments for express_submission and premium_submission
Ads not displaying: Check advertising is enabled in settings and ad placements are configured

Debug Mode

Enable detailed logging by setting:

DEBUG_POLAR=true

This will log all Polar API interactions and webhook events for troubleshooting.

Webhook Testing

Test webhook delivery using Polar's webhook testing tools or ngrok for local development:

# For local development
ngrok http 3000
# Then use the ngrok URL + /api/polar/webhooks as your webhook endpoint

Migration from v1.5.x

If upgrading from previous versions:

Run database migrations: pnpm prisma db push
Update environment variables: Add any missing Polar configuration
Configure new features: Set up paid submissions and advertising in admin dashboard
Sync products: Use auto-sync to import existing Polar products
Test webhooks: Verify all payment types are processed correctly

PreviousIcons NextMonetization

Last updated 1 minute ago