Bridge Payments Docs

Appearance

Polar Integration ​

Bridge Payments provides a rich, modern integration with Polar.sh, perfect for developers, open-source maintainers, and SaaS businesses looking for a developer-centric billing platform.

Overview ​

Unlike traditional gateways, Polar acts as a Merchant of Record. This means Polar handles taxes, VAT, compliance, and invoicing.

Here is exactly what is supported up to today by the Bridge Payments Polar adapter:

✅ Currently Supported ​

  • Checkout & Payment Intents: Bridge Payments directly maps your internal Product IDs to Polar Products and generates hosted checkout URLs (createPaymentIntent).
  • Customers: Fully syncs customer creation, retrieval, updates, and deletion.
  • Subscriptions:
    • Subscribing customers to recurring products via Checkout Links.
    • Retrieving active subscription details and history (getSubscription).
    • Listing all subscriptions for a specific customer (listCustomerSubscriptions).
  • Webhooks: Verifies incoming Polar webhooks and syncs their status securely to the Bridge Payments database.
  • Admin Product Sync: You can sync your local Bridge Payments catalog to Polar using the Admin Sync Operations, automatically mapping Benefit and Product IDs.
  • Hosted Checkout: Fully utilizes Polar's native hosted checkout for secure handling of 3D Secure, Apple Pay, and local payment methods without storing PCI data.

❌ What is NOT Supported (by design) ​

Due to Polar acting as a Merchant of Record, some features are heavily abstracted away and managed directly within the Polar Dashboard:

  • Direct Payment Method Management: Endpoints like createPaymentMethod or attachPaymentMethodToCustomer are disabled. Polar securely handles card tokens on its own interface.
  • API Refunds: Native API refunds are not supported via Bridge. All refunds should be processed manually through the Polar Dashboard.
  • Manual Subscription Creation API: You cannot artificially "attach" a subscription in the backend via createSubscription(). Subscriptions must be securely initiated via the hosted Checkout flow provided by createPaymentIntent() with a recurring product_id.
  • Manual Capture: Auto-capture cannot be disabled (Polar defaults to immediate capture).

Capabilities Summary ​

The Polar underlying adapter advertises the following capability flags back to Bridge Payments:

json
{
  "supports_payment_intents": true,
  "supports_customers": true,
  "supports_subscriptions": true,
  "supports_webhooks": true,
  "supports_3d_secure": true, // Automatically handled by Polar checkouts
  
  "supports_saved_payment_methods": false,
  "supports_refunds": false,
  "supports_manual_capture": false,

  "currencies": ["USD", "EUR", "GBP", "SEK", "NOK", "DKK"],
  "payment_methods": ["CREDIT_CARD", "DEBIT_CARD"]
}

Getting Started ​

1. Get Polar API Keys ​

  1. Log into your Polar Dashboard.
  2. Generate an Access Token under Settings → Developer.
  3. Create an Organization if you haven't already.

2. Configure Bridge ​

Update your Pubflow / Bridge Payments instance environments:

bash
# Polar API tokens
POLAR_ACCESS_TOKEN=polar_pat_...
POLAR_ORGANIZATION_ID=... # Optional but recommended
POLAR_WEBHOOK_SECRET=whsec_...

3. Sync Products ​

Run the Admin Sync Endpoint to ensure your Local Products translate cleanly to Polar Products.

Sync All Products with Specific Provider (Admin)​

POST
/bridge-payment/admin/sync/provider/{providerId}

Admin endpoint to bulk synchronize all products with a specific payment provider (e.g., Stripe or Polar).

Authorizations​

SessionAuth

Session ID from Flowless authentication

TypeAPI Key (header: X-Session-ID)

Parameters​

Path Parameters

providerId*

Payment provider ID

Typestring
Required
Valid values
"stripe""paypal""polar""authorize_net"

Request Body​

application/json
JSON
{
"force": false,
"dryRun": false,
"updatePrices": false,
"product_ids": [
"string"
]
}

Responses​

Provider sync completed

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​

Powered by VitePress OpenAPI

When syncing, Bridge Payments will talk to Polar, creating necessary "Benefits" and returning a matching polar_product_id to be cached in your local database provider_mappings.

4. Create a Payment Intent (Checkout) ​

When a user intends to buy via Polar, create a Payment Intent specifying provider_id: "polar".

json
POST /bridge-payment/payments/intents
{
  "total_cents": 2900,
  "currency": "USD",
  "provider_id": "polar",
  "metadata": {
    "product_id": "prod_local_123"
  }
}

The response will embed a next_action.url, which points to the Polar Checkout Page. You should redirect your user to this URL immediately.

After successful payment, the user will be redirected back to your CALLBACK_URL and Webhooks will process the fulfillment asynchronously.