basalt / subscriptions/src / PaddleBillingGateway
Class: PaddleBillingGateway
Defined in: subscriptions/src/drivers/paddle.ts:88
Paddle Billing gateway targeting the Paddle REST API directly — no SDK. HTTP goes through an injectable fetch; webhook signatures are verified with node:crypto using Paddle's Paddle-Signature scheme (ts=…;h1=…).
Paddle is checkout-first: createCheckoutSession creates a transaction (the subscription materializes once the customer pays, and its id arrives on the webhooks via gatewayRef). There is no server-side "create a paid subscription", so createSubscription throws CheckoutRequiredError — use Subscriptions.checkout().
Implements
Constructors
Constructor
> new PaddleBillingGateway(options): PaddleBillingGateway
Defined in: subscriptions/src/drivers/paddle.ts:97
Parameters
options
Returns
PaddleBillingGateway
Properties
name
> readonly name: "paddle" = 'paddle'
Defined in: subscriptions/src/drivers/paddle.ts:89
Implementation of
signatureHeader
> readonly signatureHeader: "paddle-signature" = 'paddle-signature'
Defined in: subscriptions/src/drivers/paddle.ts:90
Request header(s) carrying this gateway's webhook signature, lower-case (e.g. 'stripe-signature', 'paddle-signature', 'x-signature'). billingWebhookRoute reads the first one present. Omitted: the route falls back to stripe-signature / x-billing-signature.
Implementation of
BillingGateway.signatureHeader
Methods
cancelSubscription()
> cancelSubscription(gatewayRef, options): Promise<void>
Defined in: subscriptions/src/drivers/paddle.ts:117
Parameters
gatewayRef
string
options
atPeriodEnd
boolean
Returns
Promise<void>
Implementation of
BillingGateway.cancelSubscription
createCheckoutSession()
> createCheckoutSession(input): Promise<{ id: string; url: string; }>
Defined in: subscriptions/src/drivers/paddle.ts:123
Hosted Checkout session — returns a URL to redirect the customer to.
Parameters
input
Returns
Promise<{ id: string; url: string; }>
Implementation of
BillingGateway.createCheckoutSession
createPortalSession()
> createPortalSession(input): Promise<{ url: string; }>
Defined in: subscriptions/src/drivers/paddle.ts:135
Customer Portal session — returns a URL for self-service billing.
Parameters
input
Returns
Promise<{ url: string; }>
Implementation of
BillingGateway.createPortalSession
createSubscription()
> createSubscription(_input): Promise<{ gatewayRef: string; }>
Defined in: subscriptions/src/drivers/paddle.ts:113
Always throws CheckoutRequiredError. Creating a transaction here and returning its txn_… id as the subscription ref activated the plan before anything was paid, and left a ref that cancel/swap could not address (/subscriptions/txn_… does not exist).
Parameters
_input
Returns
Promise<{ gatewayRef: string; }>
Implementation of
BillingGateway.createSubscription
resumeSubscription()
> resumeSubscription(gatewayRef): Promise<void>
Defined in: subscriptions/src/drivers/paddle.ts:145
Withdraws a cancellation scheduled with cancelSubscription(ref, { atPeriodEnd: true }), so the gateway keeps renewing. Required by Subscriptions.resume() for a gateway-backed subscription.
Parameters
gatewayRef
string
Returns
Promise<void>
Implementation of
BillingGateway.resumeSubscription
swapSubscription()
> swapSubscription(gatewayRef, input): Promise<void>
Defined in: subscriptions/src/drivers/paddle.ts:150
Changes the plan on an existing subscription, applying proration.
Parameters
gatewayRef
string
input
Returns
Promise<void>
Implementation of
BillingGateway.swapSubscription
verifyWebhook()
> verifyWebhook(rawBody, signature): WebhookEvent | null
Defined in: subscriptions/src/drivers/paddle.ts:157
Verifies the signature and translates the payload. Throws WebhookInvalidError on a bad signature. Returns null for a verified event the gateway doesn't map to a domain event (gateways emit many event types we don't act on).
Parameters
rawBody
string
signature
string | undefined
Returns
WebhookEvent | null