---
title: "Prepare or complete consumer umbrella payment collection in chat."
method: POST
path: "/api/intake/{uid}/payment"
---

# Prepare or complete consumer umbrella payment collection in chat.

`POST /api/intake/{uid}/payment`

## Request

- Base URL: `https://api.coveragecat.com`
- URL: `https://api.coveragecat.com/api/intake/{uid}/payment`
- Auth: HTTP bearer

Use this only after the consumer umbrella follow-up reports `payment_needed`. Authenticate with `Authorization: Bearer <intake_access_token>` from the latest consumer-prefill follow-up response. First call this endpoint with `payment_collection_requested: true` to request a secure Stripe SetupIntent session; this native step comes before handing the shopper to `payment_url`. If your runtime can render the registered secure payment UI, display it and wait for completion; do not collect card details through conversational text. Then call this same endpoint again with `setup_intent_id` and `payment_method_id` so Coverage Cat can place the reusable payment method on file. If the secure UI is unavailable or setup fails in chat, use the returned `payment_url` browser fallback and preserve the specific fallback reason. When `payment_needed` appears, the current checkout price shown came directly from the insurer while Coverage Cat is down to final declarations verification before charging the card. Never describe successful payment-method setup as premium collected or active insurance.

## Path parameters

- `uid` string, required

## Headers

- `Coverage-Cat-API-Version` 'v1'
- `Idempotency-Key` string

## Request body

- union
  - object
    - `payment_collection_requested` true, required: Use true on the first payment call to request a secure Stripe SetupIntent session for hosted card collection.
  - object
    - `payment_method_id` string, required: Reusable Stripe PaymentMethod id produced by the secure client-side setup confirmation.
    - `setup_intent_id` string, required: SetupIntent id returned by the earlier payment_collection_ready response.

## Response `200`

Payment collection is ready or the payment method is now on file.

- IntakeAssistantResponse: REST consumer follow-up payload for the `/api/intake/{uid}` surface.
  - `poll_after_seconds` integer
  - `documents` object[]
    - `content_type` string
    - `download_url` string, uri: Short-lived browser continuation for this policy document.
    - `label` string
    - `name` string
    - `type` string
  - `payment_setup` object
    - `environment` 'test' | 'live'
    - `payment_method_types` string[]
    - `provider` string
    - `setup_intent_id` string
    - `usage` string
  - `detail_status` 'abandoned' | 'blocked' | 'bound' | 'cancelled' | 'chosen' | 'credit_consent_pending' | 'credit_consent_required' | 'dev_success' | 'documents_needed' | 'documents_pending_review' | 'email_sent' | 'in_review' | 'ineligible' | 'info_requested' | 'needs_more_info' | 'needs_more_info_to_bind' | 'no_policy' | 'no_chosen_offer' | 'no_quotes' | 'no_selection' | 'ok' | 'payment_collection_ready' | 'payment_needed' | 'pending' | 'pending_quotes' | 'queued' | 'quote_rate_limited' | 'quoted' | 'ready_for_review' | 'ready_for_submission' | 'ready_to_finalize' | 'review_pending' | 'service_preview' | 'service_requested' | 'sandbox_unsupported' | 'stale_selection' | 'verifying_documents' | 'waiting_on_carrier' | 'waiting_on_documents' | 'waiting_on_payment'
  - `required_upload_types` string[]
  - `payment_ui` object
    - `availability` 'ready' | 'unknown' | 'unsupported'
    - `fallback_reason` string
    - `mode` string
  - `uid` string, required: Coverage Cat intake uid for the current handoff.
  - `payment_url` string, uri: Coverage Cat browser URL for secure payment fallback.
  - `known_summary` object: Structured facts Coverage Cat can safely summarize at this stage.
  - `compare_details_url` string, uri: Coverage Cat browser URL for compare-details follow-up.
  - `uploaded_count` integer
  - `response_summary` string
  - `schema` object: Supplemental schema hints for homeowners review payloads.
  - `user_action_required` string
  - `expires_at` string, date-time: When the current consumer handoff expires.
  - `agent_instructions` string[]
  - `review_token` string: Opaque review token for delegated review-style submit paths.
  - `status` 'abandoned' | 'blocked' | 'bound' | 'cancelled' | 'chosen' | 'credit_consent_pending' | 'credit_consent_required' | 'dev_success' | 'documents_needed' | 'documents_pending_review' | 'email_sent' | 'in_review' | 'ineligible' | 'info_requested' | 'needs_more_info' | 'needs_more_info_to_bind' | 'no_policy' | 'no_chosen_offer' | 'no_quotes' | 'no_selection' | 'ok' | 'payment_collection_ready' | 'payment_needed' | 'pending' | 'pending_quotes' | 'queued' | 'quote_rate_limited' | 'quoted' | 'ready_for_review' | 'ready_for_submission' | 'ready_to_finalize' | 'review_pending' | 'service_preview' | 'service_requested' | 'sandbox_unsupported' | 'stale_selection' | 'verifying_documents' | 'waiting_on_carrier' | 'waiting_on_documents' | 'waiting_on_payment', required
  - `intake_access_token` string: Short-lived follow-up bearer. On REST, send it back as Authorization for the next `/api/intake/{uid}` call. On MCP, retry the same follow-up tool with this token only when your host cannot preserve Coverage Cat's hidden shopper session. Never display it to the shopper.
  - `selected_offer` object
    - `address` object
      - `city` string
      - `state` string
      - `street` string
      - `zip` string
    - `annual_price` number
    - `carrier` string
    - `coverage_limit` string
    - `coverage_summary` object: Homeowners or umbrella coverage details Coverage Cat can safely summarize.
    - `deductible` number
    - `dwelling_coverage` number
    - `is_estimate` boolean
    - `minimum_auto_limits` object: Underlying auto-limit requirements for this offer.
    - `personal_liability` number
    - `policy_subtype` string
    - `policy_subtype_display` string
    - `price_range` object
      - `high` number
      - `low` number
    - `quote_number` string
    - `recommended` boolean
    - `sample_policy_url` string, uri
    - `selection_guidance` object: Offer-specific same-reply requirements and guidance.
    - `selection_token` string
    - `um_uim_selection` object: Optional excess UM/UIM election details for this offer.
  - `line` 'umbrella' | 'homeowners'
  - `support` object
    - `contact_url` string, uri: Coverage Cat support route for billing, cancellations, and quote follow-up.
    - `email` string
    - `phone` string
  - `purchase_preview` object
    - `action_summary` string
    - `approval_required` boolean
    - `carrier_conditions` string[]
    - `coverage_summary` object: Coverage details tied to the current previewed offer.
    - `effective_date` string, date
    - `effective_period` object
      - `ends_on` string, date
      - `starts_on` string, date
    - `payment_timing` string
    - `price` object
      - `annual_premium` number
      - `currency` string
      - `payment_method` string
    - `status` string
    - `uncertainty` string
  - `service_request` object
    - `action_summary` string
    - `billing_effect` string
    - `carrier_conditions` string[]
    - `coverage_effect` string
    - `details` string
    - `estimated_refund_status` 'not_applicable' | 'unknown_pending_review'
    - `final_outcome` object: Final carrier or billing outcome once Coverage Cat can confirm it.
    - `reason` string
    - `request_id` string
    - `request_type` 'policy_cancellation' | 'refund_request' | 'support_case'
    - `requested_at` string, date-time
    - `requested_effective_date` string, date
    - `status` 'pending_review' | 'completed'
    - `uncertainty` string
  - `conversation` object
    - `messages` object[]
      - `author_label` string
      - `delivery_state` 'received' | 'queued' | 'sent'
      - `direction` 'incoming' | 'outgoing'
      - `medium` 'email' | 'app' | 'sms'
      - `message_id` integer
      - `subject` string
      - `text` string
      - `timestamp` string, date-time
    - `reply_pending` boolean
    - `reply_supported` boolean
    - `reply_to_message_id` integer
    - `reply_via` string
  - `offers_url` string, uri: Coverage Cat browser URL for the selected offer or offer-tracking page.
  - `service_requests` object[]
    - `action_summary` string
    - `billing_effect` string
    - `carrier_conditions` string[]
    - `coverage_effect` string
    - `details` string
    - `estimated_refund_status` 'not_applicable' | 'unknown_pending_review'
    - `final_outcome` object: Final carrier or billing outcome once Coverage Cat can confirm it.
    - `reason` string
    - `request_id` string
    - `request_type` 'policy_cancellation' | 'refund_request' | 'support_case'
    - `requested_at` string, date-time
    - `requested_effective_date` string, date
    - `status` 'pending_review' | 'completed'
    - `uncertainty` string
  - `payment_collection_supported` boolean
  - `review_estimates` object[]
  - `notification_channel` object
    - `customer_owned_inbox_required` boolean
    - `destination_hint` string
    - `events` string[]
    - `registered` boolean
    - `role` string
    - `type` string
  - `credit_consent_question` string
  - `next_action` object: A structured hint for the next allowed tool or endpoint action.
  - `application_submitted` boolean
  - `uploaded` object[]
    - `filename` string
    - `type` string
  - `review` object: Structured review card or selected-offer review block.
  - `missing_fields` object[]: Structured missing-value hints for homeowners pre-submit review.
  - `next_question` object: The current shopper-owned question bundle or bind-stage question.
  - `sandbox` boolean: True when Coverage Cat is returning consumer sandbox test data rather than a live shopper workflow.
  - `selection_guidance` object: Guidance for completing an offer choice in one shopper-facing reply.
  - `review_items` object[]
    - `description` string
    - `display_value` string
    - `enum` string[]
    - `label` string
    - `number` integer
    - `path` union[]
      - union
        - string
        - integer
    - `suggested_value` unknown
  - `payment_status` object
    - `channel` string
    - `customer_owned_inbox_required` boolean
    - `destination_hint` string
    - `payment_intent_id` string
    - `payment_method_saved_at` string, date-time
    - `provider` string
    - `state` string
    - `timing` string
  - `preview_token` string: Opaque bind-preview token for the next homeowners bind confirmation.
  - `offers` object[]
    - `address` object
      - `city` string
      - `state` string
      - `street` string
      - `zip` string
    - `annual_price` number
    - `carrier` string
    - `coverage_limit` string
    - `coverage_summary` object: Homeowners or umbrella coverage details Coverage Cat can safely summarize.
    - `deductible` number
    - `dwelling_coverage` number
    - `is_estimate` boolean
    - `minimum_auto_limits` object: Underlying auto-limit requirements for this offer.
    - `personal_liability` number
    - `policy_subtype` string
    - `policy_subtype_display` string
    - `price_range` object
      - `high` number
      - `low` number
    - `quote_number` string
    - `recommended` boolean
    - `sample_policy_url` string, uri
    - `selection_guidance` object: Offer-specific same-reply requirements and guidance.
    - `selection_token` string
    - `um_uim_selection` object: Optional excess UM/UIM election details for this offer.
  - `service_preview` object
    - `action_summary` string
    - `approval_required` boolean
    - `billing_effect` string
    - `carrier_conditions` string[]
    - `coverage_effect` string
    - `details` string
    - `estimated_refund_status` 'not_applicable' | 'unknown_pending_review'
    - `reason` string
    - `request_type` 'policy_cancellation' | 'refund_request' | 'support_case'
    - `requested_effective_date` string, date
    - `status` 'preview'
    - `uncertainty` string
  - `post_choose` object: Structured post-choose state after a quoted umbrella offer is selected.
  - `pending_fields` object[]: Structured missing-value hints for umbrella pre-submit review.
  - `offer_summary` object
    - `cheapest_annual_premium` number
    - `cheapest_carrier` string
    - `quote_count` integer
    - `recommended_annual_premium` number
    - `recommended_carrier` string
  - `policy` object
    - `cancellation_note` string
    - `cancelled_at` string, date
    - `carrier` string
    - `confirmation_timestamp` string, date-time
    - `coverage_summary` object: Carrier-confirmed policy coverage details Coverage Cat can safely return.
    - `effective_date` string, date
    - `effective_period` object
      - `ends_on` string, date
      - `starts_on` string, date
    - `policy_number` string
    - `state` 'bound' | 'cancelled'
  - `field_estimates` object[]

## Other responses

- `400`: Invalid payment request.
- `401`: Invalid, missing, or stale intake access token.
- `404`: No intake exists for that uid.
- `409`: The intake is not currently ready for payment collection or the submitted payment state is stale.
- `429`: Too many consumer intake follow-up requests. Honor the Retry-After header before retrying, and always retry with the newest intake access token.

---

[API](https://skmtc.dev/coveragecat/apis/coverage-cat-delegated-insurance-purchase-apis.md) · [All operations](https://skmtc.dev/coveragecat/apis/coverage-cat-delegated-insurance-purchase-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/coveragecat/apis/coverage-cat-delegated-insurance-purchase-apis/revisions/b80fe29790dc?raw)