I wired all three into the same codebase. Here is what you find out only by doing it.

Different billing providers have header names and verification methods. That's about the thing you can count on, but what about the rest? Let's take a look:

• Stripe's webhook signature comes in the Stripe-Signature header.
• Paddle's webhook signature comes in the Paddle-Signature header. It looks like this: ts=1704067200;h1=abc123def456.
• Lemon Squeezy's webhook signature comes in the X-Signature header.

When you connect one billing provider you just learn its API, but when you connect three providers behind the same interface you really learn what billing is all about. You see what it looks like under all the software development kits (SDKs) and provider documentation.

The problem with integrating each provider

Most billing code is written using a providers SDK. It works fine until your business needs to switch providers or you want to run your tests without hitting a live API.

That's when you realize that your checkout logic, webhook handlers and subscription queries are all mixed up with Stripe's details. If you want to switch providers you have to rewrite the application layer.

A better approach would be to figure out what billing really means before deciding which provider to use.

The six-method protocol

In Python, a Protocol defines a contract through structural subtyping. Any class implementing the right methods satisfies it, without inheritance.

For billing, six methods cover the full lifecycle:

class BillingProvider(Protocol):
    async def list_plans(self) -> list[PlanResponse]: ...

    async def create_checkout(
        self, organization_id: str, plan_id: str,
        success_url: str, cancel_url: str

    ) -> CheckoutResponse: ...
    async def create_portal_session(
        self, organization_id: str, return_url: str
    ) -> PortalResponse: ...

    async def get_subscription(
        self, organization_id: str
    ) -> SubscriptionResponse | None: ...

    async def cancel_subscription(
        self, organization_id: str
    ) -> SubscriptionResponse: ...

    async def handle_webhook(
        self, payload: bytes, signature: str
    ) -> dict: ...

The domain layer relies on the protocol. We have three adapters that use this protocol. Our application does not directly use Stripe, Paddle or Lemon Squeezy. It only uses a BillingProvider.

What implementing three adapters reveals

Webhook verification

Stripe delegates to its SDK:

event = stripe.Webhook.construct_event(
    payload, signature, self.config.webhook_secret
)

Paddle uses a custom header format: ts=1704067200;h1=abc123. You split it, extract timestamp and hash, then verify manually:

parts = dict(part.split("=", 1) for part in signature.split(";"))
ts = parts.get("ts", "")
h1 = parts.get("h1", "")

expected = hmac.new(
    secret.encode(),
    f"{ts}:{payload.decode()}".encode(),
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, h1):
    raise ValueError("Invalid Paddle webhook signature")

Lemon Squeezy uses a direct HMAC-SHA256 over the raw payload:

expected = hmac.new(
    secret.encode(),
    payload,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, signature):
    raise ValueError("Invalid Lemon Squeezy webhook signature")

Here is the rule for all three: you have to check the bytes before you do any JSON parsing. The signature is for the payload. If you parse the JSON first and then check it does not work because the JSON can change the bytes without you noticing.

Event types

After you have checked the payload you still need to know what is going on. Each provider names event types differently.

Notice that Lemon Squeezy uses subscription_cancelled with two l's (the L letter), while Paddle uses subscription.canceled with only one l. A silly change that can make you debug code for hours.

Checkout URL location

You've created the checkout. Now you need the URL to redirect the user. Each provider puts it somewhere different.

Stripe: session.url

Paddle nests it inside a checkout object, but not reliably:

url = result.get("checkout", {}).get("url") or result.get("url", "")

Lemon Squeezy uses JSON:API format, so everything lives under data.attributes:

url = data["data"]["attributes"]["url"]

Portal sessions

The portal page is where customers can upgrade or downgrade or cancel. This page works differently depending on who is providing it.

Stripe requires creating a session before returning a URL:

session = await stripe_client.billing_portal.sessions.create_async(
    customer=customer_id,
    return_url=return_url
)
return PortalResponse(url=session.url)

Paddle returns the portal URL directly on the customer object. No session creation:

customer = await self._get_customer(organization_id)
return PortalResponse(url=customer.portal_url)

Lemon Squeezy stores it nested under customer.urls:

portal_url = customer_data["attributes"]["urls"]["customer_portal"]

Status values

Subscription statuses look the same until they don't:

trialing versus on_trial. canceled versus cancelled.

These won't cause an error. They can cause your query for trials to return zero rows on two out of three providers, and you will spend an afternoon figuring out why.

Normalize at the adapter boundary - what enters the database should come from your vocabulary, and should not be copied from provider documents.

Plan feature metadata

Each provider has a different convention for storing the feature list shown on a pricing page.

Stripe uses marketing_features on the product, falling back to product metadata:

features = [f.name for f in product.marketing_features] \
    if product.marketing_features \
    else product.metadata.get("features", "").split(",")

Paddle uses custom_data, falling back to description lines:

features = product.custom_data.get("features", []) \
    if product.custom_data \
    else [line for line in product.description.split("\n") if line.strip()]

Lemon Squeezy parses variant description lines directly.

None of these options are wrong. They show three ways to think about where information about features is stored. The adapter keeps this hidden from the rest of the application.

What the abstraction makes visible

When we look at three adapters one thing becomes clear: the differences are not about the business logic.

The core ideas common for all three providers are the same:

• how to define a subscription
• when it starts
• when it ends
• is it active or cancelled

The differences are about how we connect to them: the names of headers, the structure of URLs, the words we use for events, the strings we use for status.

Why hexagonal architecture

The hexagonal architecture draws a line between these two concerns. The main part of the application does not know what a Stripe-Signature is. The main part of the application knows what a SubscriptionResponse is.

This has an effect on testing. With the protocol as the boundary each adapter can be tested alone using made payloads and real HMAC signatures. We do not need API accounts and we do not need to mock providers that might not behave like they do in production. All 110 tests across the domain, providers, configs, router, webhook and repository layers can run offline.

Choosing between the three

Once the architecture is in place choosing a provider is a business decision. The technical differences are real and quite limited.

Stripe has the mature software development kit and the best documentation. It also has the complex rules to follow when selling outside the US.

Paddle and Lemon Squeezy are both services that handle payments and taxes for us, send VAT and sales tax on our behalf. If we are selling to customers in the EU and do not want to register for tax in countries this matters even more.

Lemon Squeezy has the simplest way of working. JSON:API is a bit wordy but consistent. The webhook verification is the simplest of the three to do correctly.

Paddle has the flexible pricing models. We can charge based on usage, seats or custom plans. The ts=...;h1=... Signature format is the trickiest to get right and the easiest to get wrong without noticing.

If you take one thing from each section

First write down the six protocol methods as ideas before you look at the Stripe documentation. This one step helps you understand what billing means in your code without getting confused with what Stripe calls things. If you think about Stripe early it can mess up your understanding of what billing means.

Make status strings and event types consistent at the adapter boundary. The webhook handler should not see things like on_trial or subscription_cancelled.

When you check signatures use the bytes, not a re-serialized dictionary. If you convert JSON back and forth it can quietly change the bytes. That can cause a really bad kind of bug if someone tampers with the payload.

Do not pretend to check webhook signature verification in tests. Instead create a HMAC and use the real verification function. The Paddle format has cases that a pretend version will not catch, like what happens when the ts key is there but empty.

These patterns took me a while to get right. If you'd rather skip that, Billing Foundation is a paid starter kit that ships all three adapters already wired behind this Protocol, with 110 tests, a FastAPI backend, Next.js 16, PostgreSQL, Redis, Docker Compose, and an interactive (12-section) step-by-step tutorial runs in any browser.

You can start with a billing layer that you know works instead of debugging special cases like ts=...;h1=....

What's your experience ?

If you're running billing in production: which provider, and what's the edge case you hit that the documentation didn't mention?