[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 – 3fc65c01-822d-4ec4-958a-e5af1ab6cc96

---

New Issues (1)

Checkmarx found the following issues in this Pull Request

#	Severity	Issue	Source File / Package	Checkmarx Insight
1		CSRF	/src/Api/Billing/Controllers/VNext/AccountBillingVNextController.cs: 131	details Method at line 131 of /src/Api/Billing/Controllers/VNext/AccountBillingVNextController.cs gets a parameter from a user request from request. Thi... Attack Vector

[codecov]

Codecov Report

❌ Patch coverage is 98.79518% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 57.55%. Comparing base (11af4dc) to head (3ed84b8).

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.50%   57.55%   +0.04%     
==========================================
  Files        2032     2034       +2     
  Lines       89544    89625      +81     
  Branches     7960     7961       +1     
==========================================
+ Hits        51496    51582      +86     
+ Misses      36202    36198       -4     
+ Partials     1846     1845       -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

[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