v2

latestOpenAPI 3.1.02026-08-05267431678.1 KB
billing

Setup Team Payment Method

Attach a payment method to a team's Stripe customer.

Requires: MANAGE_BILLING permission (owner, admin, or billing role)

This endpoint:

  1. Creates a Stripe customer for the team if one doesn't exist
  2. Attaches the payment method to the team's customer
  3. Sets it as the default payment method

Rate-limited to 5 attempts per user per hour. Each attempt captures a $1 PaymentIntent (real settled charge) for Stripe Radar fraud scoring, so unbounded retries from a single owner/admin let a bot incinerate the Stripe fee budget and burn Radar reputation. The cap leaves room for legitimate retries on declined cards or SCA hiccups while denying bots unlimited attempts on the same compromised owner account.

Args: request: FastAPI request (required by SlowAPI rate limiter). team_id: Team UUID. body: Payment method ID from Stripe.js. auth: Authenticated user context.

Returns: Success status and customer ID.

post/billing/team/{team_id}/setup-payment-method

Path parameters

team_idstring required

Request body

payment_method_idstring required

Stripe payment method ID from Stripe.js

payment_intent_idstring nullable

Set only on the post-3DS retry to finalize the existing verification PaymentIntent. Must match the payment_intent_id returned in the previous requires_action response.

Response

Successful Response

successboolean required
messagestring required
customer_idstring nullable
requires_actionboolean
client_secretstring nullable
payment_intent_idstring nullable