Payments

Handle deposits and card guarantees for bookings that come through Mozrest. Choose one of two approaches based on your payment infrastructure.

Payment Approaches

	Stripe (direct)	Payment Link (hosted by you)
How it works	Mozrest renders Stripe Elements, tokenizes card details, and sends you a token. You charge the guest on your backend.	You return a payment URL. Mozrest embeds it in an iframe. Your page sends PostMessage events to complete the flow.
Who charges	Your backend via Stripe API	Your payment page
Best for	RMS using Stripe or Stripe Connect	RMS with their own payment gateway or checkout

How the Guest Flow Works

1. Guest enters booking details in the Mozrest widget or channel UI.
2. Mozrest calls your Create Booking endpoint.
3. Your API returns status requires_payment if payment is needed.
4. Guest completes payment via Stripe Elements or your Payment Link.
5. Booking is confirmed.

Important

Your availability response defines at slot level whether a deposit or card guarantee is required and the amounts. Mozrest reads these rules when presenting options to the guest.

---

Stripe (Direct)

Venue Configuration

When creating or updating a venue, provide the paymentGateway object:

{
  "paymentGateway": {
    "gateway": "stripe",
    "publishKey": "pk_live_...",
    "merchantId": "acct_..."
  }
}

Field	Required	Description
gateway	Yes	Fixed: "stripe"
publishKey	Yes	Your Stripe Publishable Key
merchantId	Stripe Connect only	Connected account ID. Omit for single-account Stripe setups.

At Booking Time

1. Mozrest renders Stripe Elements and tokenizes the card details.
2. Mozrest calls your API with a paymentGatewayToken field (see Create Booking).
3. You use that token with Stripe to create or capture the charge.

Mozrest never charges the card — we only collect and tokenize. The token is a server-side input; do not log it.

Handling Payment Failures (Retry Flow)

When a charge fails, the guest may retry. To avoid duplicate reservations:

1. On failure: return status requires_payment and include externalId — the ID of the reservation you already created.
2. On retry: Mozrest re-sends the booking request with a new paymentGatewayToken and your externalId inside metadata.
3. Your responsibility: when metadata.externalId is present, retry the charge for that existing reservation instead of creating a new one.

---

Payment Link (Hosted by You)

What Your API Must Return

For any booking that requires payment:

1. Return status requires_payment.
2. Include a paymentURL property (camelCase, capital URL) with your payment page URL.

The payment URL must be:

• HTTPS
• Publicly reachable from the guest's browser
• Embeddable in an iframe — allow framing from the Mozrest origin(s) provided during onboarding

PostMessage Contract

Your payment page must send PostMessage events to its parent window so Mozrest can track the outcome and continue the flow.

Event format

{
  "event": "event-name",
  "data": {}
}

Terminal outcomes

Send exactly one when the flow completes:

Event	Type	Description
booking-created	Success	Payment successful, booking confirmed
booking-create-failed	Error	Booking could not be created
payment-failed	Error	Payment was declined
payment-3ds-failed	Error	3D Secure verification failed
booking-token-expired	Error	Booking token is no longer valid
payment-session-expired	Error	Payment session timed out
reservation-session-expired	Error	Reservation session timed out
reservation-session-mismatched	Error	Session mismatch detected
reservation-create-failed	Error	Reservation creation failed

Success example

{
  "event": "booking-created",
  "data": {
    "bookingId": "your-booking-id",
    "paymentMeta": {
      "type": "deposit",
      "cardType": "VISA",
      "lastFour": "4242",
      "amount": 6000,
      "currency": "GBP"
    }
  }
}

Error example

{
  "event": "payment-failed",
  "data": { "message": "The payment was declined." }
}

Height update (recommended)

Send payment-page-height-update whenever your page height changes so the iframe resizes correctly:

{
  "event": "payment-page-height-update",
  "data": { "height": 896 }
}

---

Implementation Checklist

Stripe:

• Configure paymentGateway on the venue with gateway, publishKey, and optionally merchantId
• Accept paymentGatewayToken in booking requests and charge via Stripe API
• Handle retries: return externalId on failure, check metadata.externalId on retry
• Ensure charges are idempotent — retries must not double-charge

Payment Link:

• Return status: "requires_payment" and paymentURL when payment is needed
• Ensure your payment page is HTTPS and iframe-embeddable
• Send PostMessage terminal outcome (booking-created or error event)
• Send payment-page-height-update for responsive iframe sizing
• Validate origin for any sensitive PostMessage logic