Appointment checkout

Appointment listings need a time slot before payment can complete. You can choose who owns the calendar UI:

Flow	Who picks the time	Best for
A — Your app owns the calendar	Your UI → pass `appointmentSlot` at create	Full control over booking UX
B — Onflay owns the calendar	Omit slots → buyer picks on hosted page or overlay (incl. packs)	Fastest integrate

Both sit on Tier 1 with the same Tier 2 receipt confirmation path.

Prerequisites

The listing must be ready to book:

Requirement	Notes
`type`	`APPOINTMENT`
`status`	`ACTIVE`
Variant `durationMinutes`	At least `5`
Creator availability	Weekly hours configured in the dashboard
Meeting / delivery config	Virtual meeting link provider and/or in-person address, matching the listing delivery method

Configure availability and meeting settings in the Onflay dashboard under Scheduling. Without availability, the public slots endpoints return empty days.

Flow B — Onflay calendar (simplest)

Create a checkout session without appointmentSlot. Onflay shows the availability calendar, then payment — either full-page or overlay.

Full-page hosted

POST /v1/checkout-sessions
Authorization: Bearer sk_test_...
Content-Type: application/json
Idempotency-Key: checkout:user_123:appt:open

{
  "listingId": "listing_...",
  "variantId": "variant_...",
  "email": "buyer@example.com",
  "successUrl": "https://app.example.com/booking/success",
  "cancelUrl": "https://app.example.com/booking"
}

Redirect to checkoutUrl.

Overlay (`onflay.js`)

Same create call with uiMode: "embedded", then open embedUrl in the overlay (see Overlay checkout):

POST /v1/checkout-sessions
Authorization: Bearer sk_test_...
Content-Type: application/json

{
  "listingId": "listing_...",
  "variantId": "variant_...",
  "email": "buyer@example.com",
  "successUrl": "https://app.example.com/booking/success",
  "cancelUrl": "https://app.example.com/booking",
  "uiMode": "embedded"
}

OnflayCheckout.open({ url: session.embedUrl, onComplete: async ({ checkoutId }) => { /* confirm receipt */ } });

Notes:

Works for single-session and session packs. Packs collect all N times inside hosted/overlay checkout before payment.
No Stripe PaymentIntent is created until the buyer confirms their time(s).
Hybrid listings show a Virtual / In person choice before times.
Sessions still expire after 30 minutes if unpaid.

Flow A — Your app owns the calendar

Step 1 — Fetch availability

Public (no API key) endpoints:

GET /v1/listings/{listingId}/available-dates?from=2026-08-01&to=2026-08-31&variantId={variantId}

GET /v1/listings/{listingId}/slots?date=2026-08-20&variantId={variantId}

Optional query params:

variantId — defaults to the listing’s default variant when omitted
durationMinutes — override session length (defaults to the variant duration)

Use available-dates to highlight days on a month calendar, then slots for the chosen day’s open start times. Each slot includes an ISO startsAt you can pass straight into checkout. There is also a range helper when you want several days at once:

GET /v1/listings/{listingId}/slots/range?from=2026-08-20&to=2026-08-27&variantId={variantId}

Step 2 — Buyer selects a slot

Collect in your UI:

Field	Required	Notes
`startsAt`	Yes	ISO 8601 from the slots response
`timezone`	Yes	IANA timezone for the buyer’s view (e.g. `America/Santo_Domingo`)
`deliveryMode`	Sometimes	`virtual` or `in_person`. Required for hybrid listings; inferred when the listing is online-only or in-person-only

For pack variants (sessionCount > 1), the buyer must pick exactly N distinct, non-overlapping times.

Step 3 — Create a checkout session with the slot

POST /v1/checkout-sessions
Authorization: Bearer sk_test_...
Content-Type: application/json
Idempotency-Key: checkout:user_123:appt:2026-08-20T15:00:00Z

{
  "listingId": "listing_...",
  "variantId": "variant_...",
  "email": "buyer@example.com",
  "successUrl": "https://app.example.com/booking/success",
  "cancelUrl": "https://app.example.com/booking",
  "appointmentSlot": {
    "startsAt": "2026-08-20T19:00:00.000Z",
    "timezone": "America/Santo_Domingo",
    "deliveryMode": "virtual"
  }
}

For packs, send appointmentSlots (array) instead of appointmentSlot, with exactly sessionCount entries. Onflay validates that each slot is still free, stores the selection on the session, and returns a hosted checkout URL (checkoutUrl). Appointment sessions expire after 30 minutes if unpaid. Always set cancelUrl so the buyer can return to your booking UI if the slot becomes unavailable while they are on the payment page.

Step 4 — Redirect to hosted checkout

Send the buyer to checkoutUrl. They enter payment details; the pending page shows the selected session time(s). If the slot was taken between create and page load, hosted checkout shows a SLOT_UNAVAILABLE state. Prefer linking back via your cancelUrl.

Confirm payment (both flows)

Do not grant access from successUrl alone. Use Tier 2 confirmation:

GET /v1/checkout-sessions/{checkoutId}/receipt?returnToken=...
Authorization: Bearer sk_test_...

Or headless: ?headless=true with the secret key (no return token). Poll until paid | failed | expired. After payment succeeds, Onflay creates the appointment row (meeting link / location as configured).

Error contract

Situation	HTTP	Notes
Pack with wrong slot count / overlap	`400`	On create (Flow A) or attach (Flow B)
Wrong pack length / overlapping slots	`400`	See pack helper messages
Slot in the past	`400`	Choose a future time
Slot no longer free at create / attach	`400`	Re-fetch slots and pick again
Slot taken while pending checkout is open	`409`	`code: "SLOT_UNAVAILABLE"`; recovery via `listingUrl` / `cancelUrl`
Session expired	`410`	Create a new checkout session

Integration ladder
Quickstart
Customer access (Tier 2 / 3 provisioning)
OpenAPI reference

Empezar

Para creadores

Desarrolladores

Conceptos operativos

Prerequisites

Flow B — Onflay calendar (simplest)

Full-page hosted

Overlay (`onflay.js`)

Flow A — Your app owns the calendar

Step 1 — Fetch availability

Step 2 — Buyer selects a slot

Step 3 — Create a checkout session with the slot

Step 4 — Redirect to hosted checkout

Confirm payment (both flows)

Error contract

​Prerequisites

​Flow B — Onflay calendar (simplest)

​Full-page hosted

​Overlay (onflay.js)

​Flow A — Your app owns the calendar

​Step 1 — Fetch availability

​Step 2 — Buyer selects a slot

​Step 3 — Create a checkout session with the slot

​Step 4 — Redirect to hosted checkout

​Confirm payment (both flows)

​Error contract

​Related

Prerequisites

Flow B — Onflay calendar (simplest)

Full-page hosted

Overlay (`onflay.js`)

Flow A — Your app owns the calendar

Step 1 — Fetch availability

Step 2 — Buyer selects a slot

Step 3 — Create a checkout session with the slot

Step 4 — Redirect to hosted checkout

Confirm payment (both flows)

Error contract

Related