[PM-32480] Add endpoint for Stripe billing portal session

src/Api/Billing/Controllers/VNext/AccountBillingVNextController.cs

@@ -2,14 +2,18 @@
 using Bit.Api.Billing.Models.Requests.Payment;
 using Bit.Api.Billing.Models.Requests.Premium;
 using Bit.Api.Billing.Models.Requests.Storage;
+using Bit.Api.Billing.Models.Responses.Portal;
 using Bit.Core;
 using Bit.Core.Billing.Licenses.Queries;
 using Bit.Core.Billing.Payment.Commands;
 using Bit.Core.Billing.Payment.Queries;
+using Bit.Core.Billing.Portal.Commands;
 using Bit.Core.Billing.Premium.Commands;
 using Bit.Core.Billing.Subscriptions.Commands;
 using Bit.Core.Billing.Subscriptions.Queries;
+using Bit.Core.Context;
 using Bit.Core.Entities;
+using Bit.Core.Enums;
 using Bit.Core.Utilities;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
@@ -21,17 +25,19 @@ namespace Bit.Api.Billing.Controllers.VNext;
 [Route("account/billing/vnext")]
 [SelfHosted(NotSelfHostedOnly = true)]
 public class AccountBillingVNextController(
+    ICreateBillingPortalSessionCommand createBillingPortalSessionCommand,
     ICreateBitPayInvoiceForCreditCommand createBitPayInvoiceForCreditCommand,
     ICreatePremiumCloudHostedSubscriptionCommand createPremiumCloudHostedSubscriptionCommand,
+    ICurrentContext currentContext,
+    IGetApplicableDiscountsQuery getApplicableDiscountsQuery,
     IGetBitwardenSubscriptionQuery getBitwardenSubscriptionQuery,
     IGetCreditQuery getCreditQuery,
     IGetPaymentMethodQuery getPaymentMethodQuery,
     IGetUserLicenseQuery getUserLicenseQuery,
     IReinstateSubscriptionCommand reinstateSubscriptionCommand,
     IUpdatePaymentMethodCommand updatePaymentMethodCommand,
     IUpdatePremiumStorageCommand updatePremiumStorageCommand,
-    IUpgradePremiumToOrganizationCommand upgradePremiumToOrganizationCommand,
-    IGetApplicableDiscountsQuery getApplicableDiscountsQuery) : BaseBillingController
+    IUpgradePremiumToOrganizationCommand upgradePremiumToOrganizationCommand) : BaseBillingController
 {
     [HttpGet("credit")]
     [InjectUser]
@@ -147,4 +153,19 @@ public async Task<IResult> GetApplicableDiscountsAsync(
         return Handle(result);
     }
 
+    [HttpPost("portal-session")]
+    [InjectUser]
+    public async Task<IResult> CreatePortalSessionAsync([BindNever] User user)
+    {
+        if (DeviceTypes.ToClientType(currentContext.DeviceType) != ClientType.Mobile)
+        {
+            return TypedResults.NotFound();
+        }
+
+        var returnUrl = "bitwarden://premium-upgrade-callback";
+
+        var result = await createBillingPortalSessionCommand.Run(user, returnUrl);
+        return Handle(result.Map(url => new PortalSessionResponse { Url = url }));
+    }
+
 }

src/Api/Billing/Models/Responses/Portal/PortalSessionResponse.cs

@@ -0,0 +1,12 @@
+namespace Bit.Api.Billing.Models.Responses.Portal;
+
+/// <summary>
+/// Response model containing the Stripe billing portal session URL.
+/// </summary>
+public class PortalSessionResponse
+{
+    /// <summary>
+    /// The URL to redirect the user to for accessing the Stripe billing portal.
+    /// </summary>
+    public required string Url { get; init; }
+}

src/Core/Billing/Extensions/ServiceCollectionExtensions.cs

@@ -4,6 +4,7 @@
 using Bit.Core.Billing.Organizations.Queries;
 using Bit.Core.Billing.Organizations.Services;
 using Bit.Core.Billing.Payment;
+using Bit.Core.Billing.Portal.Commands;
 using Bit.Core.Billing.Premium.Commands;
 using Bit.Core.Billing.Premium.Queries;
 using Bit.Core.Billing.Pricing;
@@ -44,6 +45,7 @@ public static void AddBillingOperations(this IServiceCollection services)
         services.AddTransient<IBraintreeService, BraintreeService>();
         services.AddTransient<IUpdateOrganizationSubscriptionCommand, UpdateOrganizationSubscriptionCommand>();
         services.AddTransient<IUpgradeOrganizationPlanVNextCommand, UpgradeOrganizationPlanVNextCommand>();
+        services.AddTransient<ICreateBillingPortalSessionCommand, CreateBillingPortalSessionCommand>();
     }
 
     private static void AddOrganizationLicenseCommandsQueries(this IServiceCollection services)

src/Core/Billing/Portal/Commands/CreateBillingPortalSessionCommand.cs

@@ -0,0 +1,78 @@
+using Bit.Core.Billing.Commands;
+using Bit.Core.Billing.Constants;
+using Bit.Core.Billing.Services;
+using Bit.Core.Entities;
+using Microsoft.Extensions.Logging;
+using Stripe;
+using Stripe.BillingPortal;
+
+namespace Bit.Core.Billing.Portal.Commands;
+
+using static StripeConstants;
+
+public interface ICreateBillingPortalSessionCommand
+{
+    Task<BillingCommandResult<string>> Run(User user, string returnUrl);
+}
+
+public class CreateBillingPortalSessionCommand(
+    ILogger<CreateBillingPortalSessionCommand> logger,
+    IStripeAdapter stripeAdapter)
+    : BaseBillingCommand<CreateBillingPortalSessionCommand>(logger), ICreateBillingPortalSessionCommand
+{
+    private readonly ILogger<CreateBillingPortalSessionCommand> _logger = logger;
+
+    protected override Conflict DefaultConflict =>
+        new("Unable to create billing portal session. Please contact support for assistance.");
+
+    public Task<BillingCommandResult<string>> Run(User user, string returnUrl) =>
+        HandleAsync<string>(async () =>
+        {
+            if (string.IsNullOrEmpty(user.GatewayCustomerId))
+            {
+                _logger.LogWarning("{Command}: User ({UserId}) does not have a Stripe customer ID",
+                    CommandName, user.Id);
+                return DefaultConflict;
+            }
+
+            if (string.IsNullOrEmpty(user.GatewaySubscriptionId))
+            {
+                _logger.LogWarning("{Command}: User ({UserId}) does not have a subscription",
+                    CommandName, user.Id);
+                return DefaultConflict;
+            }
+
+            // Fetch the subscription to validate its status
+            Subscription subscription;
+            try
+            {
+                subscription = await stripeAdapter.GetSubscriptionAsync(user.GatewaySubscriptionId);
+            }
+            catch (StripeException stripeException)
+            {
+                _logger.LogError(stripeException,
+                    "{Command}: Failed to fetch subscription ({SubscriptionId}) for user ({UserId})",
+                    CommandName, user.GatewaySubscriptionId, user.Id);
+                return DefaultConflict;
+            }
+
+            // Only allow portal access for active or past_due subscriptions
+            if (subscription.Status != SubscriptionStatus.Active && subscription.Status != SubscriptionStatus.PastDue)
+            {
+                _logger.LogWarning(
+                    "{Command}: User ({UserId}) subscription ({SubscriptionId}) has status '{Status}' which is not eligible for portal access",
+                    CommandName, user.Id, user.GatewaySubscriptionId, subscription.Status);
+                return new BadRequest("Your subscription cannot be managed in its current status.");
+            }
+
+            var options = new SessionCreateOptions
+            {
+                Customer = user.GatewayCustomerId,
+                ReturnUrl = returnUrl
+            };
+
+            var session = await stripeAdapter.CreateBillingPortalSessionAsync(options);
+
+            return session.Url;
+        });
+}

src/Core/Billing/Services/IStripeAdapter.cs

@@ -3,6 +3,7 @@
 
 using Bit.Core.Models.BitStripe;
 using Stripe;
+using Stripe.BillingPortal;
 using Stripe.Tax;
 
 namespace Bit.Core.Billing.Services;
@@ -52,4 +53,5 @@ Task<CustomerBalanceTransaction> CreateCustomerBalanceTransactionAsync(string cu
     Task<Coupon> GetCouponAsync(string couponId, CouponGetOptions options = null);
     Task<List<Product>> ListProductsAsync(ProductListOptions options = null);
     Task<StripeList<Subscription>> ListSubscriptionsAsync(SubscriptionListOptions options = null);
+    Task<Session> CreateBillingPortalSessionAsync(SessionCreateOptions options);
 }

src/Core/Billing/Services/Implementations/StripeAdapter.cs

@@ -4,6 +4,7 @@
 
 using Bit.Core.Models.BitStripe;
 using Stripe;
+using Stripe.BillingPortal;
 using Stripe.Tax;
 using Stripe.TestHelpers;
 using CustomerService = Stripe.CustomerService;
@@ -29,6 +30,7 @@ public class StripeAdapter : IStripeAdapter
     private readonly RegistrationService _taxRegistrationService;
     private readonly CouponService _couponService;
     private readonly ProductService _productService;
+    private readonly SessionService _billingPortalSessionService;
 
     public StripeAdapter()
     {
@@ -48,6 +50,7 @@ public StripeAdapter()
         _taxRegistrationService = new RegistrationService();
         _couponService = new CouponService();
         _productService = new ProductService();
+        _billingPortalSessionService = new SessionService();
     }
 
     /**************
@@ -234,4 +237,10 @@ public async Task<List<Product>> ListProductsAsync(ProductListOptions options =
      ****************/
     public Task<StripeList<Subscription>> ListSubscriptionsAsync(SubscriptionListOptions options = null) =>
         _subscriptionService.ListAsync(options);
+
+    /**********************
+     ** BILLING PORTAL **
+     **********************/
+    public Task<Session> CreateBillingPortalSessionAsync(SessionCreateOptions options) =>
+        _billingPortalSessionService.CreateAsync(options);
 }