Polar integration #461

Genyus · 2025-07-31T07:24:24Z

Description

Adds support for Polar payments platform. Closes #441

Related to wasp-lang/wasp#3034 as we need to remove Stitches internally in order to be able to use the correct moduleResolution that Polar's SDK depends on in our tsconfig.

Contributor Checklist

Make sure to do the following steps if they are applicable to your PR:

Update e2e tests: If you changed the /template/app, then make sure to do any neccessary updates to /template/e2e-tests also.
Update demo app: If you changed the /template/app, then make sure to do any neccessary updates to /opensaas-sh/app_diff also. Check /opensaas-sh/README.md for details.
Update docs: If needed, update the /opensaas-sh/blog/src/content/docs.

- improve encapsulation and separation of concerns - simplify stats calculation

- add JSDoc comments for PaymentProcessor methods - improve JSDoc comments for exported object

- Enable processor selection by environment variable or specified override for testing scenarios - Refactor env var validation

- Add type-safety to webhook handler - Apply current Wasp env var validation

Genyus · 2025-07-31T07:41:24Z

@vincanger Still a WIP, but as I've gotten to the point where I can create orders and subscriptions, I thought I should share the changes I've made that affect other parts of the codebase for discussion.

Configurable provider selection

The current codebase requires the developer implementing the template to modify the codebase to select which payment provider to implement. I understand the reasoning behind this decision, but it also makes it impossible to implement e2e tests for multiple providers without modifying the codebase. To address this, I implemented a new PAYMENT_PROCESSOR_ID environment variable which can be used to select any one of the supported platforms.

Updated schema validation

OpenSaas currently uses a custom validation function to ensure the required env vars are set, but with the introduction of Zod validation, this seems redundant and so I implemented Zod-based validation for this provider, which could also be applied to the existing platforms, if desired.

Refactored stats job

The stats job previously contained functions for both Stripe and LemonSqueezy, which felt like a bit of code smell as it violates the open/closed principle, so I refactored that code to make the revenue calculation a function of the PaymentProcessor interface to be implemented by each integration.

vincanger

Did a quick review. I see out moduleResolution is causing import issues for the polar SDK. Hopefully we can get that sorted out quick. Everything looks to be on the right track though! The main thing I'd like to change at the moment is to remove comments that are redundant as many of them just repeat what's discernible from the function name.

template/app/src/payment/validation.ts

template/app/src/payment/polar/types.ts

template/app/src/payment/validation.ts

template/app/src/payment/paymentProcessor.ts

template/app/src/payment/polar/checkoutUtils.ts

- Fix order status checking - Remove redundant subscription status mapping type and custom status values - Remove redundant JSDoc comments

vincanger · 2025-08-07T09:37:54Z

Ok @Genyus I'd say go ahead with the implementation. It's looking good! I'm tagging @sodic here, as he will continue with the review from here on out.

FranjoMindek

Hey @Genyus,
went over the PR.

Great work on this.
I'm sorry that we are asking you to remove so much from PR, but we want to focus on getting only Polar working here first.
Also I would appreciate it if you could reduce the amount of unnecessary jsdocs/comments. Didn't want to point it out everywhere since there is a lot. Do take care to use it only when we need it.

For now I've only went through the code, didn't run anything yet.
After you implement changes I would like to actually test everything out with Polar sandbox account. I would recommend you do the same.

template/app/.env.server.example

template/app/main.wasp

template/app/src/analytics/stats.ts

template/app/src/payment/paymentProcessor.ts

template/app/src/payment/polar/webhook.ts

- Remove payment processors and types - Restore hard-coded payment processor references - Remove validation schemas

- Remove unnecessary try/catch blocks - Remove excessive JSDoc comments

- Remove env var and rely solely on polar.customerSessions.create call

- Refactor sandbox mode selection logic

Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

infomiho

Left some comments

infomiho · 2025-11-20T13:28:37Z

opensaas-sh/blog/src/content/docs/guides/payment-integrations/index.mdx

@@ -0,0 +1,95 @@
+---


I think we should name the folder payment-integrations, spaces in folder names make it annoying to cd into and it's not really common to have folders with spaces 🤷

That was the initial name, but since we have autogenerate turned on, it created payment-integrations title for the page. I need to change everything to manual mode, but I also think it's worth it. You are right.

opensaas-sh/blog/src/content/docs/guides/deploying.mdx

infomiho · 2025-11-20T13:33:31Z

opensaas-sh/blog/src/content/docs/guides/payment-integrations/index.mdx

+:::note[Which should I choose?]
+Stripe is the industry standard, is more configurable, and has cheaper fees.
+Lemon Squeezy acts a [Merchant of Record](https://www.lemonsqueezy.com/reporting/merchant-of-record). This means they take care of paying taxes in multiple countries for you, but charge higher fees per transaction.
+Polar is an open-source [Merchant of Record](https://docs.polar.sh/merchant-of-record/introduction#merchant-of-record) designed specifically for developers.


I know it's hard to write a good neutral description, but here we don't mention higher fees for Polar as well:

I've simplified it

infomiho · 2025-11-20T13:34:17Z

opensaas-sh/blog/src/content/docs/guides/payment-integrations/index.mdx

+    export const paymentProcessor: PaymentProcessor = stripePaymentProcessor;
+    // export const paymentProcessor: PaymentProcessor = lemonSqueezyPaymentProcessor;
+    // export const paymentProcessor: PaymentProcessor = polarPaymentProcessor;
+    export const paymentProcessor: PaymentProcessor = lemonSqueezyPaymentProcessor;


Two of them are uncommented?

This is because it represents actual file content and how you're supposed to change it:

infomiho · 2025-11-20T13:35:11Z

opensaas-sh/blog/src/content/docs/guides/payment-integrations/index.mdx

+
+First, go to `/src/payment/paymentProcessor.ts` and choose which payment processor you'd like to use:
+
+<Tabs syncKey="payment-provider">


I'd get rid of these tabs, they seem annoying to maintain in the docs for what should be one sentence: "uncomment one of the paymentProcessor variables to pick which payment processor you want to use"

The thing is that Open SaaS docs are really in detail.
And I want to keep that spirit.
But just adding more options make it unreadable.

e.g. I don't want to continue this chain:

The nice thing about these tabs is that they are connected.
e.g. When you select Polar on one of them, all of tabs change to use Polar.

They are a bit verbose to to maintain but still better than just listing everything.
And I don't want to simplify the instructions here.

infomiho · 2025-11-20T13:55:34Z

opensaas-sh/blog/src/content/docs/guides/payment-integrations/polar.mdx

+   - `order.paid`
+   - `subscription.updated`
+6. Click `Save`.
+7. Copy the generated webhook secret and add it to your `.env.server` file:


Suggested change

7. Copy the generated webhook secret and add it to your `.env.server` file:

7. Copy the generated webhook secret and set the `POLAR_WEBHOOK_SECRET` env variable value:

Same as here, this would be fine without the code block. #461 (comment)

infomiho · 2025-11-20T14:01:30Z

opensaas-sh/blog/src/content/docs/guides/payment-integrations/polar.mdx

+Before testing payments, make sure that you:
+- Created and set your `POLAR_ORGANIZATION_ACCESS_TOKEN` in `.env.server`.
+- Created your products and set their `<NAME>_PLAN_ID` in `.env.server`.
+- Created your webhook and set `POLAR_WEBHOOK_SECRET` in `.env.server`.
+- Your `ngrok` tunnel is running.


Suggested change

Before testing payments, make sure that you:

- Created and set your `POLAR_ORGANIZATION_ACCESS_TOKEN` in `.env.server`.

- Created your products and set their `<NAME>_PLAN_ID` in `.env.server`.

- Created your webhook and set `POLAR_WEBHOOK_SECRET` in `.env.server`.

- Your `ngrok` tunnel is running.

Before testing payments, make sure that you set all the required env variables in `.env.server` (`POLAR_ORGANIZATION_ACCESS_TOKEN`, `<NAME>_PLAN_ID` and `POLAR_WEBHOOK_SECRET` ) and that your `ngrok` tunnel is running.

Maybe you can simplify it like this

I like my example more when rendered, it's easier to keep track of the requirements when it's laid out nicely. Though I can change it if you want me to.

opensaas-sh/blog/src/content/docs/guides/Payment Integrations/polar.mdx

opensaas-sh/blog/src/content/docs/guides/Payment Integrations/stripe.mdx

# Conflicts: # opensaas-sh/app_diff/src/payment/user.ts.diff # template/app/src/payment/plans.ts # template/app/src/payment/user.ts

…polar.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

…index.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

…lemon-squeezy.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Genyus added 15 commits July 27, 2025 00:06

refactor: create explicit type for processor IDs

728bcd0

refactor: move revenue calculation to processors

61f5e73

- improve encapsulation and separation of concerns - simplify stats calculation

docs: improve comments

d3f3ed6

- add JSDoc comments for PaymentProcessor methods - improve JSDoc comments for exported object

fix: update imports after previous refactoring

51d05ca

refactor: convert processor IDs to enum values

f07fa91

feat: add validation of server env vars

2b42cc6

feat: add initial Polar integration

a0276a3

feat: implement total revenue calculation

0ebd0a3

feat: implement customer portal URL retrieval

e84670d

feat: implement checkout session creation

54292a7

feat: implement webhook handling

156823c

feat: add dynamic payment processor selection

2841121

- Enable processor selection by environment variable or specified override for testing scenarios - Refactor env var validation

fix: implement webhook handling

825eb66

- Add type-safety to webhook handler - Apply current Wasp env var validation

chore: rename file for consistency

6ad783b

Merge branch 'main' into polar

a97b79f

vincanger requested changes Aug 4, 2025

View reviewed changes

Genyus added 2 commits August 5, 2025 22:10

fix: address typing errors

eb68932

- Fix order status checking - Remove redundant subscription status mapping type and custom status values - Remove redundant JSDoc comments

fix: resolve type assignment error

fca11f9

infomiho requested a review from FranjoMindek August 7, 2025 14:34

FranjoMindek requested changes Aug 13, 2025

View reviewed changes

Genyus added 8 commits August 17, 2025 02:11

refactor: streamline payment processor integration

c71f29a

- Remove payment processors and types - Restore hard-coded payment processor references - Remove validation schemas

style: remove redundant JSDoc comments

732b9ed

refactor: simplify error handling

2410e01

- Remove unnecessary try/catch blocks - Remove excessive JSDoc comments

refactor: fix customer portal implementation

f65cc67

- Remove env var and rely solely on polar.customerSessions.create call

chore: update webhook response status codes

df213c9

refactor: remove iteration for single customer lookup

5f71cac

refactor: simplify webhook error handling

882df67

refactor: rename polar client

7d0eb4e

- Refactor sandbox mode selection logic

FranjoMindek and others added 11 commits November 19, 2025 08:30

Update opensaas-sh/blog/src/content/docs/start/guided-tour.md

f2a312e

Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/guides/payments-integration.mdx

d44fb78

Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/start/guided-tour.md

47afe8f

Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

update capital letters / indentation / and dots

7c17fe4

plan id

4d63d42

ensurePolarCustomer jsdocs

e5a5ac1

temp changes save

549d3ea

inline + naming + order

423df84

Merge branch 'main' into polar

ab3b106

consistency

c42acd6

polish docs

ade9221

FranjoMindek requested review from infomiho and vincanger November 19, 2025 16:54

FranjoMindek added 4 commits November 19, 2025 18:24

add tabs remove polar express

a084bc5

remove polar express diff

865a8a9

wording

ddd4e32

typo

9e65156

infomiho reviewed Nov 20, 2025

View reviewed changes

FranjoMindek and others added 12 commits November 20, 2025 16:31

Merge branch 'main' into polar

ae0efc6

# Conflicts: # opensaas-sh/app_diff/src/payment/user.ts.diff # template/app/src/payment/plans.ts # template/app/src/payment/user.ts

Update opensaas-sh/blog/src/content/docs/guides/Payment Integrations/…

4a3d7e9

…polar.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/guides/Payment Integrations/…

956c86c

…polar.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/guides/deploying.mdx

ed20c9f

Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/guides/Payment Integrations/…

904e8e5

…index.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/guides/Payment Integrations/…

fa50424

…index.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

Update opensaas-sh/blog/src/content/docs/guides/Payment Integrations/…

caf9825

…lemon-squeezy.mdx Co-authored-by: Mihovil Ilakovac <mihovil@ilakovac.com>

manual mode + fixes

b6ada50

fixes

0be93eb

fix deployment

6c417d9

live -> prod

cf2b918

fix links

de73cdc


		First, go to `/src/payment/paymentProcessor.ts` and choose which payment processor you'd like to use:

		<Tabs syncKey="payment-provider">

	7. Copy the generated webhook secret and add it to your `.env.server` file:
	7. Copy the generated webhook secret and set the `POLAR_WEBHOOK_SECRET` env variable value:

Uh oh!

Polar integration #461

Are you sure you want to change the base?

Polar integration #461

Conversation

Genyus commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Contributor Checklist

Uh oh!

Genyus commented Jul 31, 2025

Configurable provider selection

Updated schema validation

Refactored stats job

Uh oh!

vincanger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vincanger commented Aug 7, 2025

Uh oh!

FranjoMindek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

infomiho left a comment

Choose a reason for hiding this comment

Uh oh!

infomiho Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Genyus commented Jul 31, 2025 •

edited

Loading

infomiho Nov 20, 2025 •

edited

Loading

FranjoMindek Nov 20, 2025 •

edited

Loading

FranjoMindek Nov 20, 2025 •

edited

Loading