Stripe Integration Service Reference

Service Overview

StripeIntegrationService connects verified Stripe webhook events to Subscrio customers and subscriptions. Your infrastructure is responsible for signature verification—call processStripeEvent only after Stripe’s SDK validates the payload. The built-in handlers now cover customer lifecycle, subscription lifecycle, successful invoices, and a helper for bootstrapping Subscrio subscriptions that reference Stripe customers/prices.

• Store the Subscrio customer key in Stripe metadata (subscrioCustomerKey) whenever you create a Stripe customer or subscription—this allows webhooks to backfill Customer.externalBillingId automatically.
• Persist Stripe customer IDs in Customer.externalBillingId. If it’s missing, the webhook handler will backfill it using the metadata described above.
• Persist Stripe price IDs in BillingCycle.externalProductId so events can map to billing cycles (and therefore plans). Once the price is mapped, Subscrio can create and update subscriptions with no additional customization.

Accessing the Service

import { Subscrio } from 'core.typescript';

const subscrio = new Subscrio({ database: { connectionString: process.env.DATABASE_URL! } });
const stripeService = subscrio.stripe;

using Subscrio.Core;

var subscrio = new Subscrio(config);
var stripeService = subscrio.Stripe;

Method Catalog

(Handlers invoked internally by processStripeEvent are described for completeness.)

Method Reference

processStripeEvent

Description

Routes a verified Stripe.Event to the appropriate handler (subscription lifecycle or invoice events).

Signature

processStripeEvent(event: Stripe.Event): Promise<void>

Task ProcessStripeEventAsync(Event stripeEvent)

Inputs

Returns

Expected Results

• Switches on event.type and handles:
• customer.created
• customer.updated
• customer.deleted
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.payment_succeeded
• Unhandled event types are ignored (logged in development).
• Missing entities (customer, plan, billing cycle, subscription) throw so you can fix data mapping.

Potential Errors

Example

import Stripe from 'stripe';

const event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
await stripeService.processStripeEvent(event);

using Stripe;

var stripeEvent = EventUtility.ConstructEvent(body, sig, webhookSecret);
await stripeService.ProcessStripeEventAsync(stripeEvent);

Internal Handlers

• handleCustomerCreated/Updated
• Resolves existing customers by externalBillingId or subscrioCustomerKey metadata and backfills the Stripe customer ID.
• handleCustomerDeleted
• Clears externalBillingId when Stripe deletes a customer.
• handleSubscriptionCreated
• Resolves the customer, billing cycle (via externalProductId), and owning plan.
• Subscription Linking Behavior:
  1. First checks if a subscription with the Stripe subscription ID already exists (already linked).
  2. If metadata contains subscrioSubscriptionKey, looks up the existing Subscrio subscription by key.
  3. If found and belongs to the customer, updates the existing subscription (links Stripe ID, updates plan/billing cycle, preserves feature overrides).
  4. If no existing subscription found, creates a new subscription.
• Sets stripeSubscriptionId, period dates, and metadata on the subscription.
• handleSubscriptionUpdated
• Syncs plan/billing-cycle changes, period dates, and cancellation status for an existing subscription.
• handleSubscriptionDeleted
• Calls subscription.expire() when Stripe marks the subscription deleted so the computed status becomes expired.
• handlePaymentSucceeded
• Updates the subscription’s currentPeriodStart/currentPeriodEnd from the invoice line’s billing period after a successful payment.

createStripeSubscription

Description

Bootstraps a Subscrio subscription linked to Stripe metadata (customer/billing-cycle) while you build deeper automation.

Signature

createStripeSubscription(
  customerKey: string,
  planKey: string,
  billingCycleKey: string,
  stripePriceId: string
): Promise<Subscription>

Task<SubscriptionDto> CreateStripeSubscriptionAsync(
    string customerKey,
    string planKey,
    string billingCycleKey,
    string stripePriceId
)

Inputs

Returns

Expected Results

• Validates entities and ensures customer has externalBillingId.
• Generates a subscription key (or use one you pass in metadata), sets activation/current period timestamps, and saves the subscription.
• Leaves a placeholder stripeSubscriptionId for later reconciliation—webhooks will attach the real Stripe subscription once you pass the metadata described above.

Potential Errors

Example

const sub = await stripeService.createStripeSubscription(
  'cust_123',
  'pro-plan',
  'pro-plan-annual',
  'price_ABC123'
);
console.log(sub.key);

var sub = await stripeService.CreateStripeSubscriptionAsync(
    "cust_123",
    "pro-plan",
    "pro-plan-annual",
    "price_ABC123"
);
Console.WriteLine(sub.Key);

createCheckoutSession

Description

Generates a Stripe Checkout Session URL for subscription purchases. This helper method: - Automatically creates Stripe customers if they don't exist (sets proper metadata) - Supports linking to existing Subscrio subscriptions via subscriptionKey parameter - Provides full access to Stripe Checkout options including quantity, trial periods, and custom metadata - Sets all required metadata for webhook reconciliation

When a customer completes checkout, the webhook handler will: - If subscriptionKey was provided: update the existing subscription (link Stripe ID, update plan/billing cycle) - If no subscriptionKey: create a new subscription

Signature

createCheckoutSession(params: {
  customerKey: string;
  billingCycleKey: string;
  subscriptionKey?: string;  // Optional: existing subscription key to update
  stripeSecretKey?: string;  // Optional: override config Stripe key
  successUrl: string;
  cancelUrl: string;
  // Convenience options
  quantity?: number;
  customerEmail?: string;
  customerName?: string;
  allowPromotionCodes?: boolean;
  billingAddressCollection?: 'auto' | 'required';
  paymentMethodTypes?: Stripe.Checkout.SessionCreateParams.PaymentMethodType[];
  trialPeriodDays?: number;
  metadata?: Record<string, string>;  // Additional custom metadata
  // Full Stripe API access
  stripeOptions?: Partial<Stripe.Checkout.SessionCreateParams>;
}): Promise<{ url: string; sessionId: string }>

Task<(string Url, string SessionId)> CreateCheckoutSessionAsync(
    string customerKey,
    string billingCycleKey,
    string successUrl,
    string cancelUrl,
    string? subscriptionKey = null,
    string? stripeSecretKey = null,
    int? quantity = null,
    string? customerEmail = null,
    string? customerName = null,
    bool? allowPromotionCodes = null,
    int? trialPeriodDays = null,
    IReadOnlyDictionary<string, string>? metadata = null
)

Inputs

Input Properties

Returns

Expected Results

• Stripe Customer Creation: If customer doesn't have externalBillingId, creates Stripe customer automatically with subscrioCustomerKey metadata.
• Metadata Setup: Sets subscrioCustomerKey and optionally subscrioSubscriptionKey in both session and subscription metadata.
• Subscription Linking: If subscriptionKey provided, validates subscription exists and belongs to customer. Webhook will update this subscription when checkout completes.
• Full Stripe Support: All Stripe Checkout options accessible via convenience parameters or stripeOptions for complete API access.

Potential Errors

Example: New Subscription

const { url, sessionId } = await subscrio.stripe.createCheckoutSession({
  customerKey: 'customer_123',
  billingCycleKey: 'pro-monthly',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel',
  quantity: 2,
  allowPromotionCodes: true,
  customerEmail: 'user@example.com'
});
window.location.href = url;

var (url, sessionId) = await subscrio.Stripe.CreateCheckoutSessionAsync(
    customerKey: "customer_123",
    billingCycleKey: "pro-monthly",
    successUrl: "https://yourapp.com/success",
    cancelUrl: "https://yourapp.com/cancel",
    quantity: 2,
    allowPromotionCodes: true,
    customerEmail: "user@example.com"
);
return Redirect(url);

Example: Update Existing Subscription

// Create checkout to update existing subscription (change plan/billing cycle)
const { url, sessionId } = await subscrio.stripe.createCheckoutSession({
  customerKey: 'customer_123',
  billingCycleKey: 'pro-annual',
  subscriptionKey: 'sub_456',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel'
});

// When checkout completes, webhook will update subscription 'sub_456'
// with new plan/billing cycle and link Stripe subscription ID

// Create checkout to update existing subscription (change plan/billing cycle)
var (url, sessionId) = await subscrio.Stripe.CreateCheckoutSessionAsync(
    customerKey: "customer_123",
    billingCycleKey: "pro-annual",
    successUrl: "https://yourapp.com/success",
    cancelUrl: "https://yourapp.com/cancel",
    subscriptionKey: "sub_456"
);

// When checkout completes, webhook will update subscription 'sub_456'
// with new plan/billing cycle and link Stripe subscription ID
return Redirect(url);

Example: Full Stripe API Access

// Use stripeOptions for any Stripe Checkout parameter
const { url } = await subscrio.stripe.createCheckoutSession({
  customerKey: 'customer_123',
  billingCycleKey: 'pro-monthly',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel',
  stripeOptions: {
    consent_collection: {
      terms_of_service: 'required'
    },
    phone_number_collection: {
      enabled: true
    },
    custom_fields: [
      {
        key: 'company_name',
        label: { type: 'custom', custom: 'Company Name' },
        type: 'text'
      }
    ]
  }
});

// Use supported parameters: quantity, trialPeriodDays, metadata, allowPromotionCodes, etc.
// For custom Stripe Checkout options (e.g. consent_collection), use the Stripe .NET SDK directly.
var (url, _) = await subscrio.Stripe.CreateCheckoutSessionAsync(
    customerKey: "customer_123",
    billingCycleKey: "pro-monthly",
    successUrl: "https://yourapp.com/success",
    cancelUrl: "https://yourapp.com/cancel",
    quantity: 2,
    allowPromotionCodes: true,
    trialPeriodDays: 14
);
return Redirect(url);

Related Workflows

• Webhook verification – Your HTTP endpoint must verify Stripe signatures with stripe.webhooks.constructEvent (or equivalent) before calling processStripeEvent.
• Customer metadata – Attach subscrioCustomerKey (and optionally subscrioSubscriptionKey) to every Stripe customer and subscription you create so Subscrio can reconcile records automatically.
• Billing-cycle mapping – Store Stripe price IDs in BillingCycle.externalProductId to map subscriptions/billing cycles accurately.
• Reference guide – See docs/reference/how-to-integrate-with-stripe.md for an end-to-end walkthrough that covers setup, metadata, and webhook handling.