Card payments

A room can accept on_site (pay at the studio), card (deposit now), or both — it is in room.paymentModes. The deposit is depositPercent of the price, computed by us, with a 0.50 minimum.

The browser never confirms a booking

A card booking becomes confirmed only when Stripe’s signed webhook reaches our server. A successful-looking return in the browser is not proof of payment; poll the booking instead.

Flow

1. Confirm with paymentMode: "card"

   POST /public/holds/{holdId}/confirm

   { "paymentMode": "card", "notes": "", "email": "marta@example.com" }

   response

   {
     "booking": { "reference": "MC-TGRMY5", "status": "pending_payment", "paymentStatus": "pending",
                  "depositCents": 2500, "currency": "EUR", "paymentDueAt": "2026-10-06T12:34:28Z" },
     "manageToken": "1000bb60…",
     "manageUrl": "https://…/r/1000bb60…",
     "clientSecret": "pi_3Q…_secret_…"
   }

2. Mount Stripe’s Payment Element with that clientSecret and the publishable key from the site payload (stripePublishableKey):

   const stripe = Stripe(site.stripePublishableKey);
   const elements = stripe.elements({ clientSecret });
   elements.create('payment').mount('#payment');
   
   const { error } = await stripe.confirmPayment({
     elements,
     confirmParams: { return_url: `${location.origin}/booking/${booking.reference}` },
     redirect: 'if_required',
   });

   Card data goes straight from the guest to Stripe. It never touches your servers or ours.

3. Wait for the webhook, by polling the booking

   for (let i = 0; i < 10; i++) {
     const b = await get(`/public/bookings/manage/${manageToken}`);
     if (b.status === 'confirmed') return b;          // webhook landed
     await new Promise((r) => setTimeout(r, 1500));
   }

   It is normally there within a second or two. Until then show “confirming your payment”, not “booked”.

The 20-minute window

A pending_payment booking holds the slot for 20 minutes (paymentDueAt). If payment does not arrive, the system cancels it and frees the slot. Tell the guest, and do not leave a half-paid screen open without a way back — the manage link works from the moment the booking exists.

States you will see

status	paymentStatus	Meaning
pending_payment	pending	Waiting for Stripe
confirmed	paid	Deposit received — the booking is real
cancelled	pending	The 20 minutes expired
confirmed	unpaid	on_site booking; the studio collects and marks it paid
confirmed	refunded	The studio refunded a cancelled booking

The rest of the price is settled at the studio. Mr Charles does not invoice the guest for it.

If the studio has no Stripe account

site.cardPayments is false and card will not appear in any paymentModes. Offer on_site only; everything else is identical.