For the complete documentation index, see llms.txt. This page is also available as Markdown.

Start a Sphere-hosted checkout

Start a Sphere-hosted embedded Stripe Checkout flow.

Start a Sphere-hosted embedded checkout

post
/stripe/checkout/hosted_sessions

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.

Authorizations
X-API-KEYstringRequired
Body

checkout_session takes your own checkout.sessions.create params and forwards them to Stripe, except the ones Sphere sets itself. The other fields have no Stripe equivalent: publishable_key mounts the session in the browser (it is not a secret) and may be omitted on a direct-install connection, where Sphere uses the connected account's own key. success_url becomes the session's return_url. allow_promotion_codes is set at the top level, not inside checkout_session.

publishable_keystring · nullableOptionalDefault: nullPattern: ^pk_
stripe_account_idstring · nullableOptionalDefault: nullPattern: ^acct_
success_urlstring · min: 1Required
allow_promotion_codesbooleanOptionalDefault: false
Responses
201Success
application/json

Redirect the buyer here instead of to Stripe. Opaque — do not parse it.

urlstringRequired
post/stripe/checkout/hosted_sessions
POST /v1/stripe/checkout/hosted_sessions HTTP/1.1
Host: api.getsphere.com
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 220

{
  "publishable_key": "text",
  "stripe_account_id": "text",
  "success_url": "text",
  "allow_promotion_codes": false,
  "prefill": {
    "country": "text",
    "email": "text",
    "name": "text"
  },
  "checkout_session": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{
  "url": "text"
}

Last updated

Was this helpful?