Online payment
How the hosted checkout works when a workspace collects payment before confirming a booking.
When your workspace collects payment online, the widget adds a checkout step before the booking is confirmed. The patient pays on a hosted checkout page, and the widget waits for confirmation before finishing.
This is enabled from your Medos dashboard. There's no widget config for it — if the workspace has online payment turned on and the doctor charges a fee, the step appears automatically.
What the patient sees
Reviews the booking on the summary screen and confirms.
A checkout window opens with the hosted payment page.
The widget shows a waiting screen while the payment completes. It polls in the background, so the patient can finish paying at their own pace.
The booking confirms once payment succeeds.
The waiting screen
Because checkout happens in a separate window, the widget can't rely on the patient coming back on their own. The waiting screen handles every outcome:
| Outcome | What the patient can do |
|---|---|
| Payment succeeded | Continues automatically to confirmation |
| Checkout window was closed or lost | Reopen checkout — returns to the same payment session |
| Payment failed | Retry — resumes the same session rather than double-charging |
| Nothing happened for a while | The wait times out and offers a retry |
| Patient changed their mind | Cancel — returns to the summary step |
Retry resumes, it doesn't restart
Retrying reopens the same checkout session instead of creating a new one, so a patient can't accidentally pay twice for one booking.
Popup blockers
The checkout opens in a new window, which some browsers block. When that happens the patient stays on the waiting screen and can use Reopen checkout — that action is a direct response to their click, so it isn't blocked.
Nothing to handle in your integration, but it's worth knowing if a patient reports "nothing happened after I confirmed".
Timing
The widget polls for payment confirmation every few seconds and keeps waiting for up to five minutes. After that it stops polling and offers a retry — the payment session itself isn't cancelled, so a patient who completes payment late can still reopen and finish.
What your callbacks see
onSuccess is intended to fire only after payment is confirmed and the
booking exists — though
it doesn't fire yet.
You never get a success callback for an unpaid booking, so you can treat it as
final:
MedosBooking.init({
apiKey: "mk_your_publishable_key",
mode: "inline",
containerId: "medos-booking",
onSuccess: (data) => {
// Payment confirmed and booking created
window.location.href = `/booked?id=${data.appointmentId}`;
},
});A patient who abandons checkout produces no onSuccess. Payment failures are
surfaced in the widget's own UI; onError is reserved for errors that break
the flow rather than a declined card.
Free bookings skip it
If the doctor's fee is zero, or the patient redeems a session pack, there's nothing to charge and the checkout step is skipped entirely.