---
title: "Finalize the flow after returning from hosted Stripe Checkout"
method: POST
path: "/onboarding/v3/checkout-session/complete"
tags: ["Onboarding"]
---

# Finalize the flow after returning from hosted Stripe Checkout

`POST /onboarding/v3/checkout-session/complete`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/onboarding/v3/checkout-session/complete`
- Auth: HTTP bearer

Validates the returned session against the flow's durable billing authority, stamps the provisioned company onto the Checkout-created subscription, and completes the flow like subscribe. Replaying the return on a paid flow is an idempotent 200. A session from another signup, or one that expired, answers 409 ONBOARDING_CHECKOUT_SESSION_STALE with nothing adopted; the client drops its return marker and offers checkout again. 503 is reserved for Stripe being unavailable or returning state that fails provider authority checks.

## Headers

- `X-Median-App-Surface` 'qa'

## Request body

- OnboardingV3CheckoutComplete
  - `sessionId` string, required

## Response `200`

Completed flow

- OnboardingV3SubscribeApiResponse
  - `success` true, required
  - `data` union, required
    - object
      - `flow` OnboardingV3Flow, required
        - `id` string, uuid, required
        - `companyId` string, uuid, nullable, required
        - `stage` 'auth' | 'price' | 'sales' | 'subscribe' | 'setup' | 'books', required
        - `revenueBand` string, nullable, required
        - `expensesBand` string, nullable, required
        - `accountCount` integer, nullable, required
        - `priceTier` '200' | '500' | 'custom' | 'sales' | 'null', nullable, required
        - `priceMonthlyCents` integer, nullable, required
        - `pricePlanId` 'essential' | 'growth' | 'custom' | 'null', nullable, required
        - `trialDays` integer, required
        - `billingInterval` 'year': Present only when the customer chose annual billing on a custom offer (absent = monthly).
        - `welcomeCall` object, nullable, required
        - `accountName` string, required
        - `accountEmail` string, email, required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
    - object
      - `actionRequired` object, required
        - `clientSecret` string, required

## Other responses

- `400`: Onboarding request body is not valid JSON
- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `404`: Resource not found
- `409`: Request conflicts with the durable onboarding state
- `413`: Onboarding pricing request exceeds the 4096-byte route limit
- `415`: Onboarding request charset or content encoding is unsupported
- `422`: Validation error
- `503`: Required sandbox provider configuration or service is unavailable

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)