basalt / subscriptions/src / BillingGateway
Interface: BillingGateway
Defined in: subscriptions/src/gateway.ts:179
Payment gateway driver contract. The app talks to Basalt; only drivers talk to Stripe/Paddle/Lemon Squeezy. A driver translates raw webhook payloads into WebhookEvent — app code never sees gateway payloads.
Properties
name
> readonly name: string
Defined in: subscriptions/src/gateway.ts:180
signatureHeader?
> readonly optional signatureHeader?: string | readonly string[]
Defined in: subscriptions/src/gateway.ts:187
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.
Methods
cancelSubscription()
> cancelSubscription(gatewayRef, options): Promise<void>
Defined in: subscriptions/src/gateway.ts:189
Parameters
gatewayRef
string
options
atPeriodEnd
boolean
Returns
Promise<void>
createCheckoutSession()?
> optional createCheckoutSession(input): Promise<{ id: string; url: string; }>
Defined in: subscriptions/src/gateway.ts:198
Hosted Checkout session — returns a URL to redirect the customer to.
Parameters
input
Returns
Promise<{ id: string; url: string; }>
createPortalSession()?
> optional createPortalSession(input): Promise<{ url: string; }>
Defined in: subscriptions/src/gateway.ts:200
Customer Portal session — returns a URL for self-service billing.
Parameters
input
Returns
Promise<{ url: string; }>
createSubscription()
> createSubscription(input): Promise<{ gatewayRef: string; }>
Defined in: subscriptions/src/gateway.ts:188
Parameters
input
Returns
Promise<{ gatewayRef: string; }>
resumeSubscription()?
> optional resumeSubscription(gatewayRef): Promise<void>
Defined in: subscriptions/src/gateway.ts:208
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>
swapSubscription()?
> optional swapSubscription(gatewayRef, input): Promise<void>
Defined in: subscriptions/src/gateway.ts:202
Changes the plan on an existing subscription, applying proration.
Parameters
gatewayRef
string
input
Returns
Promise<void>
verifyWebhook()
> verifyWebhook(rawBody, signature): WebhookEvent | null
Defined in: subscriptions/src/gateway.ts:196
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