Checkout Sessions

Status: contracted_test. The six canonical Checkout Session operations are in the generated API Reference. Only sk_test_* mode is promised. See API coverage.

A Checkout Session represents one customer’s journey through the Fluveo-hosted payment page. You create it server-side, redirect the customer to its url, and retrieve it on return to confirm the outcome. For the end-to-end flow, see the Checkout overview.

Create

POST /v1/checkout/sessions

curl -s -X POST https://api.devfluveo.com/v1/checkout/sessions \
  -u "$FLUVEO_API_KEY:" -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "success_url": "https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url":  "https://example.com/cart",
    "line_items":  [{ "price_data": { "currency": "usd", "unit_amount": 4242, "product_data": { "name": "Demo Plan" } }, "quantity": 1 }]
  }'

PaymentIntent metadata

Session metadata stays on the session. If you want metadata on the PaymentIntent too, send it in payment_intent_data[metadata]. Each rule below that fails is a 400 invalid_request_error, and nothing is created:

• At most 31 keys: Stripe allows 50, and Fluveo and the payment processor reserve up to 19 keys on the PaymentIntent. Later PaymentIntent updates keep the same limit. A PaymentIntent that already has more than 31 keys can change or remove keys, but an update can never leave it with more keys than it had.
• No order_id key, in any letter case: the payment processor uses it to match the payment.
• No invoice key: it marks a hosted invoice payment, and only Fluveo’s own hosted invoice page sets it.
• No empty key, and no key with [ or ]. The usual metadata rules apply too: no fluveo_ prefix, keys up to 40 and values up to 500 characters.
• Session metadata[order_id] and metadata[invoice] are still fine, because they stay on the session.

The session object

{
  "id":             "cs_R9k8AzB2xQRH9Jf",
  "object":         "checkout.session",
  "mode":           "payment",
  "url":            "https://pay.fluveo.com/c/cs_R9k8AzB2xQRH9Jf",
  "status":         "open",
  "payment_status": "unpaid",
  "amount_total":   4242,
  "currency":       "usd",
  "success_url":    "https://example.com/thanks",
  "cancel_url":     "https://example.com/cart",
  "expires_at":     1769498745,
  "created":        1769412345,
  "livemode":       false
}

• status: open → complete (or expired).
• payment_status: unpaid → paid.

Retrieve (confirm the outcome)

GET /v1/checkout/sessions/{id} — call this when the customer returns to your success_url. Fulfill only when payment_status is paid — don’t trust the redirect by itself. Merchant-public Events and WebhookEndpoints are currently unavailable, so re-retrieve the session from your server until it reaches a terminal state; do not make fulfillment depend on a public webhook.

curl -s https://api.devfluveo.com/v1/checkout/sessions/cs_… -u "$FLUVEO_API_KEY:"

Hidden from the public API

Each item below is hidden because it does not follow the Stripe parity ADR (ADR 0004 as amended). The hidden public /v1 registry lists every hidden item. Public /v1 answers a hidden operation as an unknown URL, refuses a hidden request parameter or value with Stripe’s invalid_request_error, and omits a hidden response key.

• the value square of branding_settings[border_style] on POST /v1/checkout/sessions (HIDE0-014)
• the value hosted of ui_mode on POST /v1/checkout/sessions (HIDE0-015)
• the request parameter customer_email of POST /v1/checkout/sessions/{session} (HIDE0-074)
• the request parameter shipping_details of POST /v1/checkout/sessions/{session} (HIDE0-075)