@misterhomer1992/miit-bot-payment 1.1.7 → 2.0.4

package/src/modules/payments/webhook.service.ts

@@ -0,0 +1,812 @@
+import moment from 'moment';
+import type { ResponseTransactionStatus } from '@misterhomer1992/wayforpay-api';
+import { Logger } from '../logger/types';
+
+const APPROVED_STATUS: ResponseTransactionStatus = 'Approved';
+const DECLINED_STATUS: ResponseTransactionStatus = 'Declined';
+const EXPIRED_STATUS: ResponseTransactionStatus = 'Expired';
+import { WayForPayService } from './wayforpay.service';
+import { PaymentService } from './service';
+import { InvoiceService } from '../invoice/service';
+import { SubscriptionService } from '../subscription/service';
+import { SubscriptionPlanService } from '../subscriptionPlan/service';
+import { TokenPackService } from '../tokenPack/service';
+import {
+    parseOrderReference,
+    isSubscriptionOrderReference,
+    isTokenPackOrderReference,
+    isUpgradeOrderReference,
+    getOrderReferenceUserId,
+    getOrderReferenceItemId,
+    parseUpgradeOrderReference,
+} from './utils';
+import type { WayForPayCallbackData, IWayForPayService } from './wayforpay.types';
+import type { IPaymentService } from './types';
+import type { IInvoiceService } from '../invoice/types';
+import type { ISubscriptionService, SubscriptionEntity } from '../subscription/types';
+import type { ISubscriptionPlanService } from '../subscriptionPlan/types';
+import type { ITokenPackService } from '../tokenPack/types';
+import type { WebhookProcessingResult, IWebhookHandlerService } from './webhook.types';
+import { DEFAULT_TOKEN_PACK_PLANS } from '../token/const';
+import type { TokenPackPlan } from '../token/types';
+import { ConfigurationManager, GracePeriodConfig, DEFAULT_GRACE_PERIOD_CONFIG } from '../../config';
+
+/**
+ * WebhookHandlerService processes payment confirmation webhooks from WayForPay.
+ * It handles signature verification, payment status updates, subscription activation,
+ * and user token balance initialization.
+ */
+export class WebhookHandlerService implements IWebhookHandlerService {
+    private readonly logger: Logger;
+    private readonly wayForPayService: IWayForPayService;
+    private readonly paymentService: IPaymentService;
+    private readonly invoiceService: IInvoiceService;
+    private readonly subscriptionService: ISubscriptionService;
+    private readonly subscriptionPlanService: ISubscriptionPlanService;
+    private readonly tokenPackService: ITokenPackService;
+    private readonly tokenPackPlans: TokenPackPlan[];
+    private readonly gracePeriodConfig: GracePeriodConfig;
+
+    constructor({
+        logger,
+        wayForPayService,
+        paymentService,
+        invoiceService,
+        subscriptionService,
+        subscriptionPlanService,
+        tokenPackService,
+        tokenPackPlans,
+        gracePeriodConfig,
+    }: {
+        logger: Logger;
+        wayForPayService?: IWayForPayService;
+        paymentService?: IPaymentService;
+        invoiceService?: IInvoiceService;
+        subscriptionService?: ISubscriptionService;
+        subscriptionPlanService?: ISubscriptionPlanService;
+        tokenPackService?: ITokenPackService;
+        tokenPackPlans?: TokenPackPlan[];
+        gracePeriodConfig?: GracePeriodConfig;
+    }) {
+        this.logger = logger;
+        this.wayForPayService = wayForPayService || new WayForPayService({ logger });
+        this.paymentService = paymentService || new PaymentService({ logger });
+        this.invoiceService = invoiceService || new InvoiceService({ logger });
+        this.subscriptionService = subscriptionService || new SubscriptionService({ logger });
+        this.subscriptionPlanService = subscriptionPlanService || new SubscriptionPlanService({ logger });
+        this.tokenPackService = tokenPackService || new TokenPackService({ logger });
+        this.tokenPackPlans = tokenPackPlans || DEFAULT_TOKEN_PACK_PLANS;
+        this.gracePeriodConfig = gracePeriodConfig || this.loadGracePeriodConfig();
+    }
+
+    private loadGracePeriodConfig(): GracePeriodConfig {
+        try {
+            const configManager = ConfigurationManager.getInstance();
+            return configManager.getGracePeriodConfig();
+        } catch {
+            return DEFAULT_GRACE_PERIOD_CONFIG;
+        }
+    }
+
+    /**
+     * Processes a payment confirmation webhook from WayForPay.
+     * This method handles the complete webhook flow:
+     * 1. Verifies the signature to validate request authenticity
+     * 2. Creates an invoice record
+     * 3. Updates payment status
+     * 4. Activates subscription or renews existing one
+     * 5. Initializes user token balance based on plan
+     *
+     * @param callbackData - The callback data from WayForPay
+     * @returns Processing result with response to send back to WayForPay
+     */
+    public async processPaymentWebhook(callbackData: WayForPayCallbackData): Promise<WebhookProcessingResult> {
+        const { orderReference, transactionStatus } = callbackData;
+
+        this.logger.info({
+            message: 'Processing WayForPay webhook',
+            payload: {
+                orderReference,
+                transactionStatus,
+            },
+        });
+
+        try {
+            // Step 1: Verify signature to validate request authenticity
+            const signatureResult = this.wayForPayService.verifyCallbackSignature(callbackData);
+
+            if (!signatureResult.isValid) {
+                this.logger.warning({
+                    message: 'Invalid webhook signature',
+                    payload: {
+                        orderReference,
+                        error: signatureResult.error,
+                    },
+                });
+
+                return {
+                    success: false,
+                    response: this.wayForPayService.buildWebhookResponse(orderReference, 'decline'),
+                    error: signatureResult.error || 'Invalid signature',
+                };
+            }
+
+            // Step 2: Check if this is an approved transaction
+            if (transactionStatus !== APPROVED_STATUS) {
+                this.logger.info({
+                    message: 'Webhook received for non-approved transaction',
+                    payload: {
+                        orderReference,
+                        transactionStatus,
+                    },
+                });
+
+                // Handle declined or other statuses
+                if (transactionStatus === DECLINED_STATUS || transactionStatus === EXPIRED_STATUS) {
+                    await this.handleFailedPayment(callbackData);
+                }
+
+                return {
+                    success: true,
+                    response: this.wayForPayService.buildWebhookResponse(orderReference, 'accept'),
+                };
+            }
+
+            // Step 3: Process based on payment type
+            if (isUpgradeOrderReference(orderReference)) {
+                // Process upgrade payment
+                await this.processApprovedUpgradePayment(callbackData);
+            } else if (isSubscriptionOrderReference(orderReference)) {
+                // Process subscription payment
+                await this.processApprovedSubscriptionPayment(callbackData);
+            } else if (isTokenPackOrderReference(orderReference)) {
+                // Process token pack payment
+                await this.processApprovedTokenPackPayment(callbackData);
+            } else {
+                this.logger.info({
+                    message: 'Webhook received for unknown payment type',
+                    payload: { orderReference },
+                });
+            }
+
+            return {
+                success: true,
+                response: this.wayForPayService.buildWebhookResponse(orderReference, 'accept'),
+            };
+        } catch (error) {
+            this.logger.error({
+                message: 'Error processing webhook',
+                payload: {
+                    orderReference,
+                    error: JSON.stringify(error),
+                },
+            });
+
+            return {
+                success: false,
+                response: this.wayForPayService.buildWebhookResponse(orderReference, 'decline'),
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+
+    /**
+     * Processes an approved subscription payment.
+     * Creates invoice, updates payment status, activates subscription,
+     * and initializes token balance.
+     */
+    private async processApprovedSubscriptionPayment(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference, merchantAccount, merchantSignature, reasonCode, reason, amount, currency } =
+            callbackData;
+
+        // Parse order reference to extract user and plan info
+        const parsedReference = parseOrderReference(orderReference);
+        if (!parsedReference) {
+            throw new Error(`Invalid order reference format: ${orderReference}`);
+        }
+
+        const userId = getOrderReferenceUserId(orderReference);
+        const planId = getOrderReferenceItemId(orderReference);
+        const { platform } = parsedReference;
+
+        if (!userId || !planId) {
+            throw new Error(`Could not extract userId or planId from order reference: ${orderReference}`);
+        }
+
+        // Check for duplicate webhook (idempotency)
+        const existingInvoice = await this.invoiceService.getByOrderReference(orderReference);
+        if (existingInvoice) {
+            this.logger.info({
+                message: 'Duplicate webhook received, already processed',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        // Create invoice record
+        // reasonCode from WayForPay is a string like '1100', convert to number for storage
+        const reasonCodeNumber = typeof reasonCode === 'string' ? parseInt(reasonCode, 10) : Number(reasonCode);
+        const invoice = await this.invoiceService.create({
+            merchantAccount,
+            orderReference,
+            merchantSignature,
+            reasonCode: reasonCodeNumber,
+            reason,
+            createdDate: moment.unix(callbackData.createdDate).toISOString(),
+            processingDate: moment.unix(callbackData.processingDate).toISOString(),
+            currency,
+            amount,
+        });
+
+        this.logger.info({
+            message: 'Invoice created',
+            payload: { invoiceId: invoice.id, orderReference },
+        });
+
+        // Update payment status to completed
+        const payment = await this.paymentService.getByOrderReference(orderReference);
+        if (payment && payment.id) {
+            await this.paymentService.changeStatus({
+                id: payment.id,
+                status: 'completed',
+            });
+
+            this.logger.info({
+                message: 'Payment status updated to completed',
+                payload: { paymentId: payment.id, orderReference },
+            });
+        }
+
+        // Get subscription plan to calculate expiration and tokens
+        const subscriptionPlan = await this.subscriptionPlanService.getById(planId);
+        if (!subscriptionPlan) {
+            throw new Error(`Subscription plan not found: ${planId}`);
+        }
+
+        // Calculate subscription expiration date
+        const startedAt = moment.utc().toISOString();
+        const expiresAt = this.calculateExpirationDate(subscriptionPlan.regularMode, subscriptionPlan.count);
+
+        // Check for existing active subscription
+        const existingSubscription = await this.subscriptionService.getByUser({
+            userId,
+            platform,
+            status: 'active',
+        });
+
+        if (existingSubscription) {
+            // Renew existing subscription
+            await this.renewSubscription(existingSubscription, expiresAt);
+        } else {
+            // Activate new subscription
+            await this.activateNewSubscription({
+                userId,
+                platform,
+                planId,
+                startedAt,
+                expiresAt,
+            });
+        }
+
+        // Initialize user token balance based on plan credits
+        await this.initializeTokenBalance({
+            userId,
+            platform,
+            planId,
+            tokens: subscriptionPlan.credits,
+        });
+
+        this.logger.info({
+            message: 'Subscription activated successfully',
+            payload: {
+                userId,
+                platform,
+                planId,
+                expiresAt,
+                tokens: subscriptionPlan.credits,
+            },
+        });
+    }
+
+    /**
+     * Processes an approved token pack payment.
+     * Creates invoice, updates payment status, and adds tokens to user balance.
+     */
+    private async processApprovedTokenPackPayment(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference, merchantAccount, merchantSignature, reasonCode, reason, amount, currency } =
+            callbackData;
+
+        // Parse order reference to extract user and pack info
+        const parsedReference = parseOrderReference(orderReference);
+        if (!parsedReference) {
+            throw new Error(`Invalid order reference format: ${orderReference}`);
+        }
+
+        const userId = getOrderReferenceUserId(orderReference);
+        const packId = getOrderReferenceItemId(orderReference);
+        const { platform } = parsedReference;
+
+        if (!userId || !packId) {
+            throw new Error(`Could not extract userId or packId from order reference: ${orderReference}`);
+        }
+
+        // Check for duplicate webhook (idempotency)
+        const existingInvoice = await this.invoiceService.getByOrderReference(orderReference);
+        if (existingInvoice) {
+            this.logger.info({
+                message: 'Duplicate webhook received for token pack, already processed',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        // Create invoice record
+        const reasonCodeNumber = typeof reasonCode === 'string' ? parseInt(reasonCode, 10) : Number(reasonCode);
+        const invoice = await this.invoiceService.create({
+            merchantAccount,
+            orderReference,
+            merchantSignature,
+            reasonCode: reasonCodeNumber,
+            reason,
+            createdDate: moment.unix(callbackData.createdDate).toISOString(),
+            processingDate: moment.unix(callbackData.processingDate).toISOString(),
+            currency,
+            amount,
+        });
+
+        this.logger.info({
+            message: 'Invoice created for token pack',
+            payload: { invoiceId: invoice.id, orderReference },
+        });
+
+        // Update payment status to completed
+        const payment = await this.paymentService.getByOrderReference(orderReference);
+        if (payment && payment.id) {
+            await this.paymentService.changeStatus({
+                id: payment.id,
+                status: 'completed',
+            });
+
+            this.logger.info({
+                message: 'Token pack payment status updated to completed',
+                payload: { paymentId: payment.id, orderReference },
+            });
+        }
+
+        // Get token pack plan to determine token count
+        const tokenPackPlan = this.tokenPackPlans.find((p) => p.id === packId);
+        if (!tokenPackPlan) {
+            throw new Error(`Token pack plan not found: ${packId}`);
+        }
+
+        // Create token pack for user
+        await this.tokenPackService.create({
+            userId,
+            platform,
+            packId,
+            tokens: tokenPackPlan.tokens,
+            purchasedAt: moment.utc().toISOString(),
+            provider: 'wayforpay',
+        });
+
+        this.logger.info({
+            message: 'Token pack activated successfully',
+            payload: {
+                userId,
+                platform,
+                packId,
+                tokens: tokenPackPlan.tokens,
+            },
+        });
+    }
+
+    /**
+     * Processes an approved subscription upgrade payment.
+     * Updates subscription's planId, resets expiresAt, and adds new plan's tokens to existing balance.
+     */
+    private async processApprovedUpgradePayment(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference, merchantAccount, merchantSignature, reasonCode, reason, amount, currency } =
+            callbackData;
+
+        // Parse upgrade order reference to extract both plan IDs
+        const upgradeParsed = parseUpgradeOrderReference(orderReference);
+        if (!upgradeParsed) {
+            throw new Error(`Invalid upgrade order reference format: ${orderReference}`);
+        }
+
+        const { userId, platform, currentPlanId, newPlanId } = upgradeParsed;
+
+        if (!userId || !currentPlanId || !newPlanId) {
+            throw new Error(`Could not extract userId or plan IDs from upgrade order reference: ${orderReference}`);
+        }
+
+        // Check for duplicate webhook (idempotency)
+        const existingInvoice = await this.invoiceService.getByOrderReference(orderReference);
+        if (existingInvoice) {
+            this.logger.info({
+                message: 'Duplicate webhook received for upgrade, already processed',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        // Create invoice record
+        const reasonCodeNumber = typeof reasonCode === 'string' ? parseInt(reasonCode, 10) : Number(reasonCode);
+        const invoice = await this.invoiceService.create({
+            merchantAccount,
+            orderReference,
+            merchantSignature,
+            reasonCode: reasonCodeNumber,
+            reason,
+            createdDate: moment.unix(callbackData.createdDate).toISOString(),
+            processingDate: moment.unix(callbackData.processingDate).toISOString(),
+            currency,
+            amount,
+        });
+
+        this.logger.info({
+            message: 'Invoice created for upgrade',
+            payload: { invoiceId: invoice.id, orderReference },
+        });
+
+        // Update payment status to completed
+        const payment = await this.paymentService.getByOrderReference(orderReference);
+        if (payment && payment.id) {
+            await this.paymentService.changeStatus({
+                id: payment.id,
+                status: 'completed',
+            });
+
+            this.logger.info({
+                message: 'Upgrade payment status updated to completed',
+                payload: { paymentId: payment.id, orderReference },
+            });
+        }
+
+        // Get the new subscription plan
+        const newPlan = await this.subscriptionPlanService.getById(newPlanId);
+        if (!newPlan) {
+            throw new Error(`New subscription plan not found: ${newPlanId}`);
+        }
+
+        // Get existing active subscription
+        const existingSubscription = await this.subscriptionService.getByUser({
+            userId,
+            platform,
+            status: 'active',
+        });
+
+        if (!existingSubscription) {
+            this.logger.warning({
+                message: 'No active subscription found for upgrade, treating as new subscription',
+                payload: { userId, platform, orderReference },
+            });
+
+            // Fall back to creating a new subscription
+            const startedAt = moment.utc().toISOString();
+            const expiresAt = this.calculateExpirationDate(newPlan.regularMode, newPlan.count);
+
+            await this.activateNewSubscription({
+                userId,
+                platform,
+                planId: newPlanId,
+                startedAt,
+                expiresAt,
+            });
+
+            // Initialize token balance with new plan's credits
+            await this.initializeTokenBalance({
+                userId,
+                platform,
+                planId: newPlanId,
+                tokens: newPlan.credits,
+            });
+
+            return;
+        }
+
+        // Calculate new expiration date (full new period from now)
+        const startedAt = moment.utc().toISOString();
+        const expiresAt = this.calculateExpirationDate(newPlan.regularMode, newPlan.count);
+
+        // Update subscription: change planId, reset expiresAt and startedAt, ensure active status
+        await this.subscriptionService.updateFieldsById({
+            subscriptionId: existingSubscription.id,
+            fields: [
+                ['planId', newPlanId],
+                ['expiresAt', expiresAt],
+                ['startedAt', startedAt],
+                ['status', 'active'],
+            ],
+        });
+
+        this.logger.info({
+            message: 'Subscription upgraded',
+            payload: {
+                subscriptionId: existingSubscription.id,
+                previousPlanId: existingSubscription.planId,
+                newPlanId,
+                previousExpiresAt: existingSubscription.expiresAt,
+                newExpiresAt: expiresAt,
+            },
+        });
+
+        // Add new plan's tokens to existing balance (keep existing + add new)
+        await this.initializeTokenBalance({
+            userId,
+            platform,
+            planId: newPlanId,
+            tokens: newPlan.credits,
+        });
+
+        this.logger.info({
+            message: 'Subscription upgrade completed successfully',
+            payload: {
+                userId,
+                platform,
+                previousPlanId: currentPlanId,
+                newPlanId,
+                expiresAt,
+                tokensAdded: newPlan.credits,
+            },
+        });
+    }
+
+    /**
+     * Activates a new subscription for the user.
+     */
+    private async activateNewSubscription(params: {
+        userId: string;
+        platform: string;
+        planId: string;
+        startedAt: string;
+        expiresAt: string;
+    }): Promise<void> {
+        const subscriptionData: Omit<SubscriptionEntity, 'id' | 'status'> = {
+            userId: params.userId,
+            platform: params.platform,
+            planId: params.planId,
+            startedAt: params.startedAt,
+            expiresAt: params.expiresAt,
+            provider: 'wayforpay',
+        };
+
+        await this.subscriptionService.activateSubscription(subscriptionData);
+
+        this.logger.info({
+            message: 'New subscription activated',
+            payload: {
+                userId: params.userId,
+                platform: params.platform,
+                planId: params.planId,
+            },
+        });
+    }
+
+    /**
+     * Renews an existing subscription by extending its expiration date.
+     */
+    private async renewSubscription(
+        existingSubscription: SubscriptionEntity,
+        newExpiresAt: string,
+    ): Promise<void> {
+        // If the subscription hasn't expired yet, extend from current expiration
+        const currentExpiration = moment.utc(existingSubscription.expiresAt);
+        const now = moment.utc();
+
+        let extendedExpiresAt: string;
+        if (currentExpiration.isAfter(now)) {
+            // Extend from current expiration date
+            const durationToAdd = moment.utc(newExpiresAt).diff(moment.utc(), 'milliseconds');
+            extendedExpiresAt = currentExpiration.add(durationToAdd, 'milliseconds').toISOString();
+        } else {
+            // Subscription has expired, use the new expiration date
+            extendedExpiresAt = newExpiresAt;
+        }
+
+        await this.subscriptionService.renewSubscription({
+            userId: existingSubscription.userId,
+            platform: existingSubscription.platform,
+            expiresAt: extendedExpiresAt,
+        });
+
+        this.logger.info({
+            message: 'Subscription renewed',
+            payload: {
+                subscriptionId: existingSubscription.id,
+                previousExpiresAt: existingSubscription.expiresAt,
+                newExpiresAt: extendedExpiresAt,
+            },
+        });
+    }
+
+    /**
+     * Initializes user token balance by creating a token pack.
+     */
+    private async initializeTokenBalance(params: {
+        userId: string;
+        platform: string;
+        planId: string;
+        tokens: number;
+    }): Promise<void> {
+        const { userId, platform, planId, tokens } = params;
+
+        await this.tokenPackService.create({
+            userId,
+            platform,
+            packId: planId,
+            tokens,
+            purchasedAt: moment.utc().toISOString(),
+            provider: 'wayforpay',
+        });
+
+        this.logger.info({
+            message: 'Token balance initialized',
+            payload: {
+                userId,
+                platform,
+                packId: planId,
+                tokens,
+            },
+        });
+    }
+
+    /**
+     * Calculates the subscription expiration date based on the regular mode.
+     */
+    private calculateExpirationDate(
+        regularMode: 'daily' | 'monthly' | 'yearly',
+        count: number,
+    ): string {
+        const now = moment.utc();
+
+        switch (regularMode) {
+            case 'daily':
+                return now.add(count, 'days').toISOString();
+            case 'monthly':
+                return now.add(count, 'months').toISOString();
+            case 'yearly':
+                return now.add(count, 'years').toISOString();
+            default:
+                return now.add(count, 'months').toISOString();
+        }
+    }
+
+    /**
+     * Handles failed or declined payments.
+     * For recurring subscription renewals, this triggers deactivation of the subscription.
+     */
+    private async handleFailedPayment(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference } = callbackData;
+
+        const payment = await this.paymentService.getByOrderReference(orderReference);
+        if (payment && payment.id) {
+            await this.paymentService.changeStatus({
+                id: payment.id,
+                status: 'failed',
+            });
+
+            this.logger.info({
+                message: 'Payment status updated to failed',
+                payload: {
+                    paymentId: payment.id,
+                    orderReference,
+                    reason: callbackData.reason,
+                },
+            });
+        }
+
+        // Handle failed recurring renewal - deactivate subscription
+        if (this.isRecurringRenewal(callbackData) && isSubscriptionOrderReference(orderReference)) {
+            await this.handleFailedRenewal(callbackData);
+        }
+    }
+
+    /**
+     * Checks if the payment callback is for a recurring renewal payment.
+     * WayForPay sets regularOn field for recurring payments.
+     */
+    private isRecurringRenewal(callbackData: WayForPayCallbackData): boolean {
+        // regularOn is set by WayForPay for recurring payment callbacks
+        return !!callbackData.regularOn;
+    }
+
+    /**
+     * Handles a failed recurring renewal by cancelling or deactivating the subscription.
+     * Respects grace period configuration before full deactivation.
+     */
+    private async handleFailedRenewal(callbackData: WayForPayCallbackData): Promise<void> {
+        const { orderReference, reason, reasonCode } = callbackData;
+
+        const parsedReference = parseOrderReference(orderReference);
+        if (!parsedReference) {
+            this.logger.warning({
+                message: 'Could not parse order reference for failed renewal',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        const userId = getOrderReferenceUserId(orderReference);
+        const { platform } = parsedReference;
+
+        if (!userId) {
+            this.logger.warning({
+                message: 'Could not extract userId from order reference for failed renewal',
+                payload: { orderReference },
+            });
+            return;
+        }
+
+        // Find active subscription for user
+        const existingSubscription = await this.subscriptionService.getByUser({
+            userId,
+            platform,
+            status: 'active',
+        });
+
+        if (!existingSubscription) {
+            this.logger.info({
+                message: 'No active subscription found for failed renewal',
+                payload: { userId, platform, orderReference },
+            });
+            return;
+        }
+
+        // Check if subscription has expired past the grace period
+        const now = moment.utc();
+        const expiresAt = moment.utc(existingSubscription.expiresAt);
+        const gracePeriodMs = this.gracePeriodConfig.enabled ? this.gracePeriodConfig.durationMs : 0;
+        const gracePeriodEnd = expiresAt.clone().add(gracePeriodMs, 'milliseconds');
+
+        if (now.isAfter(gracePeriodEnd)) {
+            // Subscription has expired past grace period - deactivate it
+            await this.subscriptionService.deactivateSubscription({ id: existingSubscription.id });
+
+            this.logger.info({
+                message: 'Subscription deactivated due to failed renewal (past grace period)',
+                payload: {
+                    subscriptionId: existingSubscription.id,
+                    userId,
+                    platform,
+                    orderReference,
+                    reason,
+                    reasonCode,
+                    expiresAt: existingSubscription.expiresAt,
+                    gracePeriodMs,
+                    gracePeriodEnd: gracePeriodEnd.toISOString(),
+                },
+            });
+        } else if (expiresAt.isBefore(now)) {
+            // Subscription has expired but within grace period - cancel (mark for future deactivation)
+            await this.subscriptionService.cancelSubscription({ id: existingSubscription.id });
+
+            this.logger.info({
+                message: 'Subscription cancelled due to failed renewal (within grace period)',
+                payload: {
+                    subscriptionId: existingSubscription.id,
+                    userId,
+                    platform,
+                    orderReference,
+                    expiresAt: existingSubscription.expiresAt,
+                    gracePeriodEnd: gracePeriodEnd.toISOString(),
+                    reason,
+                    reasonCode,
+                },
+            });
+        } else {
+            this.logger.info({
+                message: 'Failed renewal for subscription that has not yet expired',
+                payload: {
+                    subscriptionId: existingSubscription.id,
+                    userId,
+                    platform,
+                    orderReference,
+                    expiresAt: existingSubscription.expiresAt,
+                    reason,
+                    reasonCode,
+                },
+            });
+        }
+    }
+}