Purchase Token Grants

Create a token purchase for the client with comprehensive validation and error handling.

This endpoint provides a production-ready token purchase flow supporting:

• Credit card payments via Stripe PaymentIntent
• ACH payments via Stripe PaymentIntent
• Invoice payments for eligible plans

The endpoint implements proper:

• Input validation and sanitization
• User permission checks
• Business rule enforcement
• Comprehensive error handling
• Audit logging

Args: request: Purchase request with token_amount, payment_method, and optional fields user: Authenticated user making the request token_purchase_service: Service handling the token purchase logic

Returns: Dict containing purchase details: - payment_method: The payment method used - payment_id: Internal payment tracking ID - token_amount: Number of tokens purchased - total_amount: Total cost in USD - For Card/ACH: PaymentIntent with client_secret for frontend processing - For Invoice: Invoice details with hosted_invoice_url

Raises: 400: Invalid input parameters or business rule violations 401: User not authenticated 403: User lacks permission for this client, or the client is a wholesale client (their allowance comes from the contract tier) 404: Client plan or tokens not found 422: Business logic violations 500: System errors 502: External service (Stripe) errors