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

[cyprain-okeke]

🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-32480

📔 Objective

• Adds new POST /account/billing/vnext/portal-session endpoint that returns a Stripe Customer Portal URL
• Enables Premium users with active or past_due subscriptions to manage or cancel their subscriptions via Stripe's hosted portal
• Implements security validations to ensure only eligible users can access the portal

Changes

API Layer

• Added CreatePortalSessionAsync endpoint to AccountBillingVNextController
• Created PortalSessionRequest model with URL validation and XSS prevention
• Created PortalSessionResponse model for returning the portal URL

Core Layer

• Implemented ICreateBillingPortalSessionCommand with comprehensive business logic validation:
• Verifies user has Stripe customer ID
• Verifies user has active subscription
• Validates subscription status (only active or past_due allowed)
• Creates Stripe billing portal session with custom return URL
• Added CreateBillingPortalSessionAsync to IStripeAdapter and StripeAdapter
• Registered command in dependency injection container

Test Plan

1. **Success Case**: Call endpoint with authenticated Premium user (active subscription)                                        
   - Verify portal URL is returned                                                                                              
   - Verify URL can be opened and displays subscription management options                                                      
                                                                                                                              
2. **Past Due Case**: Test with Premium user in past_due status                                                                 
    - Verify portal URL is returned                                                                                                                                                                                                                                │
3. **Error Cases**: Test with users who:                                                                                        
   - Have no Stripe customer ID → Returns 400 BadRequest                                                                        
   - Have no subscription → Returns 400 BadRequest                                                                              
   - Have canceled/incomplete subscription → Returns 400 BadRequest                                                             
   - Subscription not found in Stripe → Returns 400 BadRequest                                                                  
                                                                                                                              
4. **Validation**: Test request validation                                                                                      
   - Missing return URL → Returns 400                                                                                           
   - Invalid URL format → Returns 400                                                                                           
   - Non-HTTP(S) scheme (javascript:, data:, etc.) → Returns 400             

📸 Screenshots

[github-actions]

Checkmarx One – Scan Summary & Details – 5fbb4583-dbb1-4ad6-9e17-b73f99b5c383

Great job! No new security vulnerabilities introduced in this pull request

[codecov]

Codecov Report

❌ Patch coverage is 98.52941% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 57.73%. Comparing base (2efacd5) to head (6993e89).

Files with missing lines	Patch %	Lines
.../Billing/Services/Implementations/StripeAdapter.cs	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7227      +/-   ##
==========================================
+ Coverage   57.69%   57.73%   +0.03%     
==========================================
  Files        2035     2037       +2     
  Lines       89672    89738      +66     
  Branches     7993     7994       +1     
==========================================
+ Hits        51738    51809      +71     
+ Misses      36074    36070       -4     
+ Partials     1860     1859       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[SaintPatrck]

❓ I don't see this mentioned as a request property in the linked JIRA ticket, or in the tech breakdown. When the mobile client calls this endpoint, what value should this be and where does it come from?

[cyprain-okeke]

The ReturnUrl is required by Stripe's billing portal session API (see
https://docs.stripe.com/api/customer_portal/sessions/create). When users finish managing their subscription in the Stripe
portal, they click a "Return to Bitwarden" link that redirects to this URL.

For mobile clients, this should be a deep link (e.g., bitwarden://billing-return or similar app-specific URL scheme) that opens
the app. The mobile client would:

1. Open the portal URL in an in-app browser/web view
2. After the user completes their session, Stripe redirects to the ReturnUrl
3. The deep link triggers the mobile app to close the web view and return to the billing screen

This is standard practice for Stripe portal integration on mobile - the same pattern is used across other platforms (see
https://docs.stripe.com/customer-management/integrate-customer-portal).

[SaintPatrck]

If ReturnUrl is a deeplink like bitwarden://foo, this validation will trigger an error response. Is that intentional?

[cyprain-okeke]

remove the returnurl from the request, instead pass it from the server base on client

[github-actions]

Overall Assessment: APPROVE

Reviewed the new POST /account/billing/vnext/portal-session endpoint including the controller action, CreateBillingPortalSessionCommand, StripeAdapter extension, DI registration, and associated tests. The return URL is correctly hardcoded server-side (eliminating the open redirect risk from the earlier iteration), the endpoint is properly gated to mobile clients via DeviceTypes.ToClientType, and the command follows the established BaseBillingCommand pattern with appropriate Stripe error handling. Test coverage is thorough at the command level with well-structured edge case scenarios.

Code Review Details

No findings. The implementation is well-aligned with existing billing command patterns and addresses feedback from prior review iterations.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud