huly-platform/services/payment/pod-payment

Payment Service

Provider-agnostic payment service supporting multiple subscription providers (Polar.sh, Stripe, etc.).

Architecture

Client (UI)
    ↓ POST /api/v1/subscriptions/:workspace/subscribe
Payment Service → Accounts Service (caller auth)
    ↓ Create checkout via provider API
Payment Provider (Polar.sh, Stripe, etc.)
    ↓ Webhook → POST /api/v1/webhooks/:provider
Payment Service → Accounts Service (upsert subscription)

Subscription Creation Flow

Step 1: Client Creates Checkout

Request:

POST /api/v1/subscriptions/:workspace/subscribe
Authorization: Bearer {token}

{
  "type": "tier" | "support",
  "plan": "common" | "rare" | "epic" | "legendary",
  "customerEmail"?: string,
  "customerName"?: string
}

Response:

{
  "checkoutId": "checkout_abc123",
  "checkoutUrl": "https://checkout.polar.sh/session/abc123"
}

Step 2: Payment

User is redirected to checkoutUrl and completes payment with the provider.

Step 3: Success Redirect

After payment, user is redirected to the success URL with these query parameters:

FRONT_URL/workbench/setting/setting/billing?payment=success&checkout_id={CHECKOUT_ID}

API Endpoints

Endpoint	Method	Purpose
/api/v1/subscriptions/:workspace/subscribe	POST	Create subscription checkout
/api/v1/subscriptions/:subscriptionId	GET	Get subscription details (admin only)
/api/v1/subscriptions/:subscriptionId/cancel	POST	Cancel subscription
/api/v1/webhooks/:provider	POST	Receive webhook events from payment provider

Environment Configuration

Required Variables

Variable	Description	Example
PORT	Port to listen on	3040
ACCOUNTS_URL	Accounts service URL	http://huly.local:3000
FRONT_URL	Frontend URL for redirects	https://huly.local:8087

Polar.sh Provider

To enable Polar.sh as the payment provider, set:

Variable	Description	Example
POLAR_ACCESS_TOKEN	Polar.sh API access token	polar_...
POLAR_WEBHOOK_SECRET	Webhook signature secret	whsec_...
POLAR_SUBSCRIPTION_PLANS	Plan to product IDs mapping	common@tier:prod_1a,prod_1b;rare@tier:prod_2;epic@tier:prod_3;legendary@tier:prod_4

Format: {plan}@{type}:{productIds};... where productIds are comma-separated uuids of products in your Polar.sh account.

Webhook endpoint is registered at /api/v1/webhooks/polar.

Multiple Providers

To support additional providers (Stripe, Lemonsqueezy, etc.):

1. Add environment variables for that provider
2. Create provider implementation extending PaymentProvider interface
3. Register in PaymentProviderFactory.create()
4. Provider registers its webhook endpoint via registerWebhookEndpoints()