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

infomiho

Left some comments

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

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

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

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

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>

infomiho · 2025-11-21T09:18:30Z

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

+
+## Deploying your App

+### Deploying to Fly.io


We are missing the Deploying to Railway section or we could rework this to be a Deploying with wasp deploy or similar so it cover some agnostic advice and then link to both providers in the Wasp docs for details.

We don't have to do it in this PR, but I'd create an issue and tackle it sooner than later.

I have a task to take care of this this sprint.

vincanger

Polar Docs look great. Just made a few small suggestions. Nice work :)

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

vincanger · 2025-11-21T09:44:05Z

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

+### Sandbox and Production Mode
+
+Polar features two separate environemnts: [sandbox](https://sandbox.polar.sh/dashboard) and [production](https://polar.sh/dashboard).
+They are fully isolated from each other, which means that you need to create seperate organizations for each of them. They also feature indepdendant products, sales, access tokens, etc.


you need to create seperate organizations for each of them

really? I know Stripe allows you to work in sandbox mode and then copy all those settings to production. That's not possible with Polar?

Nope. Sadly.

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

vincanger · 2025-11-21T09:48:48Z

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

+
+### Create and Use the Polar Webhook in Local Development
+
+Polar notifies your Wasp app about events through a webhook (for example, when a payment succeeds). During development, you need to expose your locally running Wasp server (started with `wasp start`) to the internet. Wasp server runs on port 3001 by default, so you can, for example, run `ngrok` on port 3001 to expose your server to the internet. `ngrok` will generate a public URL that you can give to Polar.


Suggested change

Polar notifies your Wasp app about events through a webhook (for example, when a payment succeeds). During development, you need to expose your locally running Wasp server (started with `wasp start`) to the internet. Wasp server runs on port 3001 by default, so you can, for example, run `ngrok` on port 3001 to expose your server to the internet. `ngrok` will generate a public URL that you can give to Polar.

Polar notifies your Wasp app about customer and payment events through a webhook. During development, your locally running Wasp server (started with `wasp start`) where the webhook endpoint is located is not yet available to Polar via the internet (it's running on port 3001 by default). We can make it available to Polar by installing and running `ngrok` on port 3001, which will generate a public URL for it.

Took half your suggestion and half mine. Now it looks like this:

I've also added commas after First, not seen on the image.

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

infomiho

I'm good 👍 good job

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 added 2 commits November 19, 2025 18:27

wording

ddd4e32

typo

9e65156

infomiho reviewed Nov 20, 2025

View reviewed changes

FranjoMindek and others added 15 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

deploying reminder

08729cf

improvements

f1fbfcb

our -> your

cadd982

infomiho reviewed Nov 21, 2025

View reviewed changes

FranjoMindek added 2 commits November 21, 2025 10:44

simplify

d52b96b

simplify

a92229b

vincanger reviewed Nov 21, 2025

View reviewed changes

improvements

8c9882a

infomiho approved these changes Nov 21, 2025

View reviewed changes

FranjoMindek added 4 commits November 21, 2025 11:34

update

f838e16

update note

0baaa9c

add commas

2548e3f

update wasp-app-runner

d4479f6

FranjoMindek mentioned this pull request Nov 21, 2025

Copy of Polar #575

Closed

FranjoMindek merged commit 7f2c074 into wasp-lang:main Nov 21, 2025
5 of 6 checks passed


		### Create and Use the Polar Webhook in Local Development

		Polar notifies your Wasp app about events through a webhook (for example, when a payment succeeds). During development, you need to expose your locally running Wasp server (started with `wasp start`) to the internet. Wasp server runs on port 3001 by default, so you can, for example, run `ngrok` on port 3001 to expose your server to the internet. `ngrok` will generate a public URL that you can give to Polar.

Uh oh!

Polar integration #461

Polar integration #461

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

infomiho Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

vincanger Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

vincanger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

vincanger Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vincanger Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Nov 21, 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!

Genyus commented Jul 31, 2025 •

edited

Loading

FranjoMindek Nov 21, 2025 •

edited

Loading