checkout_create_payment_session

Tool of ComOS Federation Gateway

Create a secure Stripe Checkout Session for payment collection. Returns a payment URL where the customer enters card details. **IMPORTANT: Use this for REAL payments instead of checkout_start with paymentMethodId.** **Recommended Flow:** 1. Collect shipping address from user via conversation 2. Start checkout with `checkout_start` (without paymentMethodId) → creates pending checkout 3. Optionally: `checkout_shipping_options` → `checkout_select_shipping` for shipping choice 4. Call this tool → returns Stripe payment URL 5. Present URL to user (redirect, link, or embed) 6. After payment, verify with `checkout_status` **Why this flow?** - Customer enters card on Stripe's PCI-compliant hosted page - Card numbers never touch your servers - Supports all Stripe methods (cards, Apple Pay, Google Pay, etc.) - Handles 3D Secure authentication automatically **Webhook Behavior:** - Order completes automatically when Stripe confirms payment via webhook - If webhook is delayed: poll `checkout_status` to verify (Stripe eventually delivers) - If webhook fails: saga remains `payment_pending`; manual intervention may be needed **Session Notes:** - URL is single-use; once customer starts, it cannot be reused - Sessions expire after ~24 hours; create new session if expired - Returns `payment_pending` status after successful creation (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.)