Authenticated user retrieves their current default payment method (card brand, last4, expiry) and billing email from Stripe. Requires a valid JWT access token.

• Data is fetched live from Stripe Customer.invoice_settings.default_payment_method — not cached in TalkIDE DB.
• If no default payment method is registered, the endpoint returns null for all card fields and the user’s account email as billingEmail.
• If stripe_customer_id is null (user has never performed any billing action), the endpoint returns the “no payment method” placeholder without creating a Stripe Customer.
• This endpoint is called on mount of BillingSection.vue to populate the payment method row.
• Related: UC-10001 — registration flow. UC-10003 — billing email update.

sequenceDiagram
    actor User

    User->>+FE: opens Profile → Billing & Usage section

    FE->>FE: onMounted — trigger billing data load

    FE->>+BE: GET /api/v1/users/me/billing/payment-method <br> Authorization: Bearer {accessToken}

    BE->>BE: validate JWT access token
    alt access token invalid or missing
        BE-->>FE: 401 Unauthorized <br> ErrorResponse
    end

    BE->>DB: SELECT stripe_customer_id FROM users WHERE id = userId

    alt stripe_customer_id is null
        BE-->>FE: 200 OK <br> PaymentMethodResponse (all card fields null)
    end

    BE->>Stripe: stripe.customers.retrieve(customerId, { expand: ["invoice_settings.default_payment_method"] })
    Stripe-->>BE: Customer { invoice_settings: { default_payment_method: PaymentMethod | null } }

    alt no default payment method on Customer
        BE-->>FE: 200 OK <br> PaymentMethodResponse (all card fields null)
    end

    BE->>-FE: 200 OK <br> PaymentMethodResponse

    FE->>-User: display card brand + last4 + expiry + billing email

GET /api/v1/users/me/billing/payment-method (no request body; authentication via JWT Bearer token)

200 OK PaymentMethodResponse (card registered):

{
  "brand": "visa",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2028,
  "billingEmail": "jane@example.com"
}

200 OK PaymentMethodResponse (no card registered):

{
  "brand": null,
  "last4": null,
  "expMonth": null,
  "expYear": null,
  "billingEmail": "jane@example.com"
}

401 Unauthorized ErrorResponse:

{
  "status": 401,
  "code": "AUTHENTICATION_FAILED",
  "message": "Access token is missing or invalid"
}

502 Bad Gateway (Stripe API unreachable) ErrorResponse:

{
  "status": 502,
  "code": "STRIPE_UNAVAILABLE",
  "message": "Payment provider is temporarily unavailable. Please try again."
}

Frontend

Validations

UX Guidelines

Payment method row states:

Brand icon mapping (FE-side, CSS class or SVG asset):

Backend

Validations

Test Cases