> For the complete documentation index, see [llms.txt](https://docs.getsphere.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getsphere.com/features/integrations/api/stripe-integration-api/start-a-sphere-hosted-checkout.md).

# Start a Sphere-hosted checkout

Start a Sphere-hosted embedded Stripe Checkout flow.

## Start a Sphere-hosted embedded checkout

> Send the cart, currency, and a success\_url (plus your publishable key, unless it is a direct-install connection whose key Sphere already holds). Sphere creates an embedded Stripe Checkout Session (no tax yet) and returns a url. Redirect the buyer to it instead of to Stripe; they enter their address on the Sphere-hosted page, tax is attached to the session, and they pay there via Stripe's embedded Checkout.

```json
{"openapi":"3.1.0","info":{"title":"Sphere API","version":"1.0.0"},"servers":[{"url":"https://api.getsphere.com/v1"},{"url":"https://server.getsphere.com/tax_api/v1"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}},"schemas":{"StartEmbeddedCheckoutRequest":{"additionalProperties":false,"description":"``checkout_session`` takes your own checkout.sessions.create params and\nforwards them to Stripe, except the ones Sphere sets itself. The other fields\nhave no Stripe equivalent: ``publishable_key`` mounts the session in the\nbrowser (it is not a secret) and may be omitted on a direct-install\nconnection, where Sphere uses the connected account's own key.\n``success_url`` becomes the session's return_url. ``allow_promotion_codes``\nis set at the top level, not inside ``checkout_session``.","properties":{"publishable_key":{"anyOf":[{"pattern":"^pk_","type":"string"},{"type":"null"}],"default":null,"title":"Publishable Key"},"stripe_account_id":{"anyOf":[{"pattern":"^acct_","type":"string"},{"type":"null"}],"default":null,"title":"Stripe Account Id"},"success_url":{"minLength":1,"title":"Success Url","type":"string"},"allow_promotion_codes":{"default":false,"title":"Allow Promotion Codes","type":"boolean"},"prefill":{"anyOf":[{"$ref":"#/components/schemas/EmbeddedCheckoutPrefill"},{"type":"null"}],"default":null},"checkout_session":{"additionalProperties":true,"title":"Checkout Session","type":"object"}},"required":["success_url"],"title":"StartEmbeddedCheckoutRequest","type":"object"},"EmbeddedCheckoutPrefill":{"additionalProperties":false,"description":"Buyer details you already have, used to prefill the checkout form.","properties":{"country":{"anyOf":[{"maxLength":2,"minLength":2,"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"}},"title":"EmbeddedCheckoutPrefill","type":"object"},"StartEmbeddedCheckoutResponse":{"description":"Redirect the buyer here instead of to Stripe. Opaque — do not parse it.","properties":{"url":{"title":"Url","type":"string"}},"required":["url"],"title":"StartEmbeddedCheckoutResponse","type":"object"}}},"paths":{"/stripe/checkout/hosted_sessions":{"post":{"operationId":"stripe_checkout_hosted_sessions_create","description":"Send the cart, currency, and a success_url (plus your publishable key, unless it is a direct-install connection whose key Sphere already holds). Sphere creates an embedded Stripe Checkout Session (no tax yet) and returns a url. Redirect the buyer to it instead of to Stripe; they enter their address on the Sphere-hosted page, tax is attached to the session, and they pay there via Stripe's embedded Checkout.","summary":"Start a Sphere-hosted embedded checkout","tags":["Stripe"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartEmbeddedCheckoutRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/StartEmbeddedCheckoutRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/StartEmbeddedCheckoutRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartEmbeddedCheckoutResponse"}}},"description":""},"400":{"description":"Validation error."},"403":{"description":"Missing/invalid API key, or Stripe account not enabled for Sphere tax."},"404":{"description":"No such connected Stripe account."},"502":{"description":"Stripe refused the Checkout Session."}}}}}}
```
