mirror of
https://github.com/hcengineering/platform.git
synced 2026-08-25 05:42:23 +02:00
95 lines
2.8 KiB
Markdown
95 lines
2.8 KiB
Markdown
# 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:**
|
|
```json
|
|
{
|
|
"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()`
|