@lunora/payment — Dodo Payments

Dodo Payments is a Merchant-of-Record (MoR) for software, SaaS, and digital products. Unlike a raw payment processor, Dodo is the legal seller of your product: it runs hosted checkout, calculates, collects, and remits sales tax / VAT / GST across 190+ jurisdictions, issues compliant invoices, and owns chargebacks and disputes. Your app never touches card data or a tax engine — you sell to Dodo's checkout, Dodo sells to the customer.

The @lunora/payment Dodo adapter (createDodoPaymentsAdapter) normalizes Dodo onto the same provider-agnostic ctx.payments surface as every other provider: hosted checkout, subscriptions, first-class refunds, usage metering, a native customer portal, and webhook sync through the shared payment/subscription state machine. As with every adapter, the package never imports the dodopayments SDK — you inject a client, so dodopayments stays an optional peer dependency.

The adapter advertises these capabilities:

Dodo Payments vs. Stripe — when to choose it

Practical consequences of the MoR model in this adapter:

• No manual capture / authorize. Dodo captures at checkout. capturePayment and cancelPayment throw PROVIDER_ERROR — they are not part of an MoR flow.
• Refunds are first-class. Unlike some MoRs (Creem's refundPayment throws), Dodo exposes refunds.create, so the adapter's refundPayment really issues a refund. It flows back in through the refund.succeeded webhook — see Refunds.
• Product-based, not price-based. Dodo checkout takes product ids; the cross-provider priceId field carries a Dodo product_id.

Prerequisites

Both secrets are scaffolded into your .dev.vars when @lunora/payment is detected:

DODO_PAYMENTS_API_KEY=<your-dodo-payments-api-key>
DODO_PAYMENTS_WEBHOOK_KEY=<your-dodo-payments-webhook-secret>

Install

Add the package and the Dodo SDK (an optional peer — the adapter takes the client by injection):

pnpm add @lunora/payment dodopayments

npm install @lunora/payment dodopayments

yarn add @lunora/payment dodopayments

bun add @lunora/payment dodopayments

Configure

ctx.payments is wired by codegen onto ActionCtx whenever a lunora/ source imports @lunora/payment or reads ctx.payments. The adapter — which carries your Dodo secrets — comes from a payment(env) thunk you pass to createShardDO().

import type { DodoPaymentsClientLike } from "@lunora/payment/dodopayments";
import { createDodoPaymentsAdapter } from "@lunora/payment/dodopayments";
import DodoPayments from "dodopayments";
import { createShardDO } from "./_generated/shard";

export const ShardDO = createShardDO({
    payment: (env) => ({
        adapter: createDodoPaymentsAdapter({
            client: new DodoPayments({
                bearerToken: env.DODO_PAYMENTS_API_KEY,
                // Drop `environment` (or set "live_mode") for production.
                environment: "test_mode",
            }) as unknown as DodoPaymentsClientLike,
            webhookSecret: env.DODO_PAYMENTS_WEBHOOK_KEY,
            // Optional clock-skew tolerance for the signed webhook timestamp (seconds; default 300).
            webhookToleranceSeconds: 300,
        }),
        // Plan → features/limits map. Required only if you gate features with `check` / `listBalances`.
        entitlements: {
            plans: {
                pro: { features: ["export"], limits: { api_calls: 1000 }, priceIds: ["<dodo-product-id>"] },
            },
        },
        observability: (event) => console.log("[payment]", event.type, event),
    }),
});

createDodoPaymentsAdapter accepts:

Checkout & subscribe

Call the facade from an action. Every method authorizes the caller against the referenceId first (the default rule ties referenceId to ctx.auth.userId), so a caller can only act on its own subscriptions. attach is the plan-oriented alias of createCheckout with mode defaulting to "subscription".

import { action, v } from "./_generated/server";

// `priceId` is a Dodo PRODUCT id — Dodo is product-based.
export const subscribe = action.input({ productId: v.string() }).action(async ({ ctx, args: { productId } }): Promise<{ url: string }> => {
    const { url } = await ctx.payments.attach({
        referenceId: ctx.auth.userId,
        priceId: productId,
        successUrl: "https://app.test/done",
        cancelUrl: "https://app.test/cancel",
    });

    return { url };
});

Under the hood the adapter calls Dodo's checkoutSessions.create with product_cart: [{ product_id, quantity }] and returns the session's checkout_url (as url) and session_id (as id). It reuses the reference's stored Dodo customer — attaching it by customer.customer_id when known — and pins the framework-controlled referenceId into checkout metadata last, so caller-supplied metadata can never override the attributed owner. Redirect the browser to the returned url; Dodo hosts the checkout.

Manage subscriptions

// Cancel now, or at period end.
await ctx.payments.cancelSubscription(subscriptionId, { atPeriodEnd: true });

// List a reference's synced subscriptions.
const subs = await ctx.payments.listSubscriptions(ctx.auth.userId);

The adapter maps these onto Dodo's subscriptions API:

• Cancel at period end → subscriptions.update(id, { cancel_at_next_billing_date: true }) (the subscription runs to the end of the paid period, then stops).
• Cancel immediately → subscriptions.update(id, { status: "cancelled" }).

Change plan or quantity

An upgrade / downgrade or a seat-count change goes through Dodo's dedicated change-plan endpoint, which is prorated immediately:

// Adapter surface reached through `ctx.payments.adapter` — a plan and/or quantity change.
await ctx.payments.adapter.updateSubscription(subscriptionId, { priceId: "<new-dodo-product-id>", quantity: 3 });

Entitlements: check and track

Entitlements are derived from already-synced subscription state — cheap and in-Worker, no extra call to Dodo. A plan is granted when an active subscription holds one of its configured priceIds (Dodo product ids).

import { action } from "./_generated/server";

// Is this reference allowed to consume one api_call right now?
export const canCall = action.action(async ({ ctx }): Promise<{ allowed: boolean; balance?: number }> => {
    const result = await ctx.payments.check({ referenceId: ctx.auth.userId, featureId: "api_calls" });

    return { allowed: result.allowed, balance: result.balance };
});

// Record one unit of metered usage (exactly-once by idempotency key).
export const recordCall = action.action(async ({ ctx }): Promise<{ recorded: boolean }> => {
    const result = await ctx.payments.track({ referenceId: ctx.auth.userId, featureId: "api_calls" });

    return { recorded: result.recorded };
});

track writes a durable, append-only usage ledger that check sums over the current billing period. Because Dodo advertises usageMetering, each recorded delta is also forwarded to Dodo's usage-event ingestion (usageEvents.ingest) — one event per usage record, event_name = your featureId, keyed to the Dodo customer by customer_id, with the amount carried in metadata.value and a stable event_id (the idempotency key) that dedupes retries. This forward is best-effort: a Dodo reporting failure is observed, never thrown, and the local ledger check reads is always updated.

Webhooks

Dodo signs webhooks with the Standard Webhooks scheme (the same scheme svix and Polar use): three headers — webhook-id, webhook-timestamp, and webhook-signature — over base64(HMAC_SHA256(secret, "{id}.{timestamp}.{body}")). The adapter verifies them against webhookSecret (the whsec_ prefix is stripped and the remainder base64-decoded to the key) with a replay-window check.

Create the endpoint in Dodo

Route the raw body into a Lunora action

Signature verification needs the raw request body, so the endpoint runs at the Worker edge via httpAction (no ctx.db), forwarding the raw body and the three Standard-Webhooks headers into the shard via ctx.runAction, where ctx.payments and its store exist:

import { httpAction, httpRouter } from "lunorash/server";
import { processDodoWebhook } from "./billing";

export const app = httpRouter();

app.post(
    "/payment/webhook",
    httpAction(async (ctx, request) => {
        const body = await request.text();

        return Response.json(
            await ctx.runAction(processDodoWebhook, {
                body,
                webhookId: request.headers.get("webhook-id") ?? "",
                webhookTimestamp: request.headers.get("webhook-timestamp") ?? "",
                webhookSignature: request.headers.get("webhook-signature") ?? "",
            }),
        );
    }),
);

import { internalAction, v } from "./_generated/server";

export const processDodoWebhook = internalAction
    .input({ body: v.string(), webhookId: v.string(), webhookTimestamp: v.string(), webhookSignature: v.string() })
    .action(async ({ ctx, args }): Promise<{ applied: boolean; status: number }> => {
        const request = new Request("https://internal/payment/webhook", {
            body: args.body,
            headers: {
                "webhook-id": args.webhookId,
                "webhook-timestamp": args.webhookTimestamp,
                "webhook-signature": args.webhookSignature,
            },
            method: "POST",
        });
        const response = await ctx.payments.handleWebhook(request);
        const result = (await response.json()) as { applied?: boolean };

        return { applied: result.applied ?? false, status: response.status };
    });

handleWebhook verifies the signature, normalizes the Dodo event into a WebhookAction, and applies it through the state machine. Once verified it always returns 200 so Dodo stops retrying — a duplicate or out-of-order event is acknowledged, not re-applied. Standard Webhooks carries no body id, so the adapter uses the webhook-id header as the idempotency key backing the append-only events log.

Event mapping

The adapter translates these Dodo events into normalized transitions:

Dodo's subscription status values — pending, active, on_hold, cancelled, failed, expired — map onto Lunora's subscription states. For safety, pending (first payment not completed), failed, and on_hold (dunning) all map to non-entitling past_due, not an entitling state — an unrecognized status also fails closed to past_due.

Refunds

Unlike some Merchants-of-Record, Dodo refunds are first-class: the adapter's refundPayment calls refunds.create with payment_id, an optional minor-unit amount (omit for a full refund), and an optional reason. Reach it through the adapter on the facade:

// Full refund of a payment session.
await ctx.payments.adapter.refundPayment({ sessionId: paymentId, reason: "customer_request" });

// Partial refund — amount is Money (integer minor units + currency).
import { money } from "@lunora/payment";

await ctx.payments.adapter.refundPayment({ sessionId: paymentId, amount: money(500n, "USD") });

Billing portal

Dodo ships a native hosted customer portal. createPortalSession mints a Dodo customer portal session (customers.customerPortal.create) and returns its link:

const { url } = await ctx.payments.createPortalSession(ctx.auth.userId, "https://app.test/account");

The customer is derived from the store (never a caller-supplied id — no IDOR). Dodo's portal is a session URL, so the returnUrl argument is accepted for interface parity but Dodo controls the in-portal navigation.

Tax, invoices & the MoR model

Because merchantOfRecord is true, Dodo — not you — is the seller of record: it calculates and remits VAT / sales tax / GST across 190+ jurisdictions, generates compliant invoices, and absorbs chargebacks and disputes. Your Lunora app only records the normalized payment/subscription state; it never stores tax lines or card data. The stored Money is Dodo's total_amount (tax-inclusive) in integer minor units.

Limitations

Troubleshooting

See also

• @lunora/payment — the provider-agnostic ctx.payments API and data model
• @lunora/scheduler — drive the reconciliation sweep
• Studio — the Payments panel (synced customers, subscriptions, webhook events)
• Dodo Payments docs · Webhook events · Standard Webhooks