Polar Payment Gateway by ALT

Polar Payment Gateway by ALT

Accept payments via Polar.sh Checkout – Standalone WordPress payment solution without WooCommerce dependency.

Author: Nam Truong
Website: https://namncn.com
Plugin URI: https://namncn.com/product/alt-polar-payment-gateway

Features

• ✅ Standalone solution – No WooCommerce required
• 💳 Complete Polar.sh Checkout API integration
• 🔄 Subscription support for recurring payments
• 💰 Dynamic pricing with ad-hoc prices
• 🎨 Customizable payment forms via shortcodes
• 📊 Order management dashboard
• 🔔 Webhook support for payment confirmation
• 💱 Multi-currency support (USD, EUR, GBP, VND)
• 🐛 Debug logging
• 🌐 Translation ready

Requirements

• WordPress 5.8+
• PHP 7.4+
• Polar.sh account with Access Token

Installation

1. Upload plugin folder to /wp-content/plugins/
2. Activate the plugin through WordPress admin
3. Go to Polar Orders → Settings
4. Configure your Polar API credentials

Quick Setup

Step 1: Get Polar Access Token

1. Go to https://polar.sh → Settings → API Tokens
2. Create new token with checkout permissions
3. Copy the Access Token

Step 2: Create Product on Polar

1. Go to https://polar.sh → Products → Create Product
2. Set price type to “Pay what you want” or “Custom”
3. Copy the Product ID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Step 3: Configure Plugin

1. Polar Orders → Settings
2. Enter:
   • Polar Access Token: Your API token from Step 1
   • Product Mapping: Select “Single Product + Dynamic Pricing”
   • Default Product ID: Product ID from Step 2
   • Success URL: URL to redirect after payment (e.g., /payment-success/)
3. Save changes

Step 4: Setup Webhook

1. Copy Webhook URL from settings page sidebar
2. Go to Polar Dashboard → Settings → Webhooks
3. Add new webhook endpoint with the copied URL
4. Select events: checkout.updated, order.created, subscription.created

Usage

Basic Payment Form

[polar_payment_form]

This creates a complete payment form with customer name, email, and amount fields.

Fixed Amount Payment

[polar_payment_form amount="99.99" currency="usd" show_amount="no"]

Create a form with pre-defined amount (amount field hidden from user).

Specific Product

[polar_payment_form product_id="YOUR_PRODUCT_ID"]

Use a specific Polar Product ID instead of the default one.

Custom Button Text

[polar_payment_form button_text="Subscribe Now" amount="29.99"]

Without Custom Fields

[polar_payment_form custom_fields="no"]

Hide the optional note field.

Complete Example

[polar_payment_form 
    amount="49.99" 
    currency="usd" 
    product_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    button_text="Join Premium" 
    show_amount="no"
    custom_fields="no"]

Shortcode Parameters

Product Mapping Modes

1. Single Product + Dynamic Pricing (Recommended)

Uses one Polar Product with dynamically calculated prices based on payment amount.

Best for: Most use cases, donations, flexible pricing

2. Single Product

Uses one Polar Product with fixed catalog price from Polar.

Best for: Fixed-price products, subscriptions

3. Custom

Allows each shortcode to specify its own product_id parameter.

Best for: Multiple products, advanced setups

Order Management

View Orders

Navigate to Polar Orders in WordPress admin to view all payment orders.

Order Details

Each order shows:

• Order ID
• Customer information
• Payment amount and currency
• Polar Checkout ID
• Subscription ID (if applicable)
• Payment status
• Timestamps

Order Statuses

• Pending – Order created, awaiting payment
• Processing – Payment in progress
• Completed – Payment successful
• Failed – Payment failed
• Cancelled – Order cancelled

Webhook Events

The plugin handles these Polar webhook events:

• checkout.updated – Payment status updated
• order.created – Order completed
• subscription.created – Recurring subscription created

Development Hooks

Actions

// Fired when payment is completed
do_action('polar_payment_completed', $order, $webhook_data);

// Fired when subscription is created
do_action('polar_subscription_created', $order, $webhook_data);

Example Usage

add_action('polar_payment_completed', 'my_custom_handler', 10, 2);

function my_custom_handler($order, $data) {
    // Send custom email
    // Update user meta
    // Trigger other integrations
    error_log('Payment completed: ' . $order->order_id);
}

Database Schema

The plugin creates a custom table wp_polar_orders with these fields:

• id – Auto-increment primary key
• order_id – Unique order identifier
• customer_email – Customer email
• customer_name – Customer name
• amount – Payment amount
• currency – Currency code
• status – Order status
• polar_checkout_id – Polar checkout session ID
• polar_checkout_url – Checkout page URL
• polar_subscription_id – Subscription ID (if applicable)
• metadata – JSON metadata
• created_at – Created timestamp
• updated_at – Updated timestamp

Troubleshooting

Error: Access Token not configured

Solution: Enter your Polar Access Token in plugin settings.

Error: Product ID is not configured

Solution:

1. Create a product on Polar.sh
2. Copy the Product ID
3. Enter it in plugin settings

Webhook not working

Solutions:

1. Verify webhook URL is correctly added in Polar Dashboard
2. Check that your site is accessible from the internet (webhooks won’t work on localhost)
3. Enable debug mode and check logs at wp-content/polar-payment.log

Payments not completing automatically

Solutions:

1. Ensure webhook is properly configured
2. Check webhook events include checkout.updated and order.created
3. Enable debug logging to see webhook requests

Debug Logging

1. Go to Polar Orders → Settings
2. Enable Debug Mode
3. Check logs at wp-content/polar-payment.log

Security

• All user inputs are sanitized and validated
• Nonce verification on all AJAX requests
• SQL injection prevention with prepared statements
• XSS protection with proper escaping
• Secure API communication via HTTPS

Support

• Polar Documentation: https://docs.polar.sh
• Polar Dashboard: https://polar.sh/dashboard
• Plugin Support: support@namncn.com

License

GPL v2 or later

Changelog

1.0.0 (2026-02-06)

• 🎉 Initial release
• ✨ Standalone payment gateway (no WooCommerce)
• ✨ Shortcode-based payment forms
• ✨ Custom order management system
• ✨ Webhook integration
• ✨ Subscription support
• ✨ Multi-currency support
• ✨ Admin dashboard
• ✨ Debug logging
• 🌐 Translation ready

Credits

Based on the WooCommerce version of Polar Payment Gateway, adapted for standalone WordPress use.

Developed with ❤️ by Nam Truong