[BE/Platform] Allow Payment Method Selection During Plan Change

Problem Statement

During a subscription change, the system currently charges the same card linked to the active subscription, without giving users a chance to choose a different one.

If that card has insufficient funds, the upgrade still proceeds, often resulting in a past-due subscription and poor customer experience.

User Story

As a subscriber changing my plan, I want to select an existing saved payment method or add a new one before confirming the change, so that my payment succeeds and I can control which card is charged.

Definition of Done (DoD)

1. Modify Change Subscription API (reference) to accept an optional payment_method_id parameter.

2. Validate that:

3. If payment_method_id is provided, charge that method instead of the default subscription card.

4. If none is provided, fallback to the current default.

5. UI / SDK

6. Within Change Plan flow, display the Payment Method modal:

7. Similar to normal checkout flow,

8. Allow selection from existing saved cards.

9. “Add new card” should be available.

10. If user adds a new card, set it as the payment_method_id for the API request.

1. Unit tests to verify:

2. Successful charge using alternate saved card

3. Successful charge using new card

4. Graceful fallback to default card

5. Include proper error handling for declined payments before plan activation.

Affected Components

API / SDK / Integrations