v1.0.0 · Beta

EezyBookings SDK

A lightweight JavaScript widget that adds a full booking flow to any website in minutes. Drop it onto your existing page, point it at a form, and let EezyBookings handle availability, room selection, and payment inside a seamless iframe overlay.

Integration style:

Copy-paste into any HTML page

Introduction

The EezyBookings SDK is a single JavaScript file that you include on your lodge's website. It attaches to an HTML form you already have, collects guest and date details, and opens a hosted checkout inside an iframe modal — so your guests never leave your site.

Room selection, pricing, and payment are all handled inside the iframe by EezyBookings. You only need to provide the entry-point form.

Zero dependencies

Pure vanilla JS — no jQuery, no framework required.

Iframe checkout

Rooms, pricing, and payment stay hosted by EezyBookings.

One method

Call EezyBookings.init() once and the SDK does the rest.

Installation

<!-- Add before </body> on every page that has your booking form -->
<script src="https://cdn.eezybookings.com/sdk/v1/booking.js"></script>

The script is an IIFE — it attaches window.EezyBookings and has no other side effects until you call init().

Authentication

Generate an API key from Settings → API Keys. The key is passed in the apiKey option when you call init() and is included in the POST body sent to your lodge's booking endpoint.

<script>
  EezyBookings.init({
    formId: "booking-form",
    apiKey: "ek_live_xxxxxxxxxxxxxxxx",
    apiUrl: "https://YOUR_LODGE.eezybookings.com/api/book",
  });
</script>

This key is client-visible

The API key is embedded in the page source and sent from the browser. It is scoped to booking creation only — it cannot access private property data. Rotate it from the dashboard if it is ever misused.

Quickstart

A complete working integration — HTML form, script tag, and init call:

<!DOCTYPE html>
<html>
<body>

  <form id="booking-form">
    <input type="text"  name="first_name"    placeholder="First name"   required />
    <input type="text"  name="last_name"     placeholder="Last name"    required />
    <input type="email" name="email"         placeholder="Email"        required />
    <input type="tel"   name="phone"         placeholder="Phone"        required />
    <input type="date"  name="check_in_date"                            required />
    <input type="date"  name="check_out_date"                           required />
    <input type="number" name="guests" value="2" min="1"                required />
    <button type="submit">Check availability</button>
  </form>

  <script src="https://cdn.eezybookings.com/sdk/v1/booking.js"></script>
  <script>
    EezyBookings.init({
      formId: "booking-form",
      apiKey: "ek_live_xxxxxxxxxxxxxxxx",
      apiUrl: "https://YOUR_LODGE.eezybookings.com/api/book",
    });
  </script>

</body>
</html>

Bookings widget

EezyBookings.init(options) is the only method you need to call. It must run after the DOM is ready and the target form exists.

Init options

Option	Type	Required	Description
formId	string	Yes	The id attribute of the HTML form to attach to.
apiKey	string	Yes	Your publishable API key from Settings → API Keys.
apiUrl	string	Yes	The booking session endpoint for your lodge.

Required form fields

Your form must contain inputs with the following name attributes. The SDK reads them via FormData on submit.

Field name	Expected value
first_name	Guest's first name
last_name	Guest's last name
email	Guest's email address
phone	Guest's phone number
check_in_date	Arrival date — YYYY-MM-DD
check_out_date	Departure date — YYYY-MM-DD
guests	Number of guests (integer)

What happens on submit

The SDK intercepts the form's submit event and prevents the default browser action.
It disables the submit button and shows a Loading… label.
A POST request is sent to apiUrl with the form data and api_key as JSON.
On success the server returns { iframe_url } and the SDK opens a modal with that URL loaded in an iframe.
The guest completes room selection and payment inside the iframe without leaving your site.

POST request body

{
  "api_key":        "ek_live_xxxxxxxxxxxxxxxx",
  "first_name":     "Amara",
  "last_name":      "Okonkwo",
  "email":          "amara@example.com",
  "phone":          "+27 82 555 0123",
  "check_in_date":  "2026-05-12",
  "check_out_date": "2026-05-15",
  "guests":         "2"
}

Expected API response

{
  "iframe_url": "https://YOUR_LODGE.eezybookings.com/checkout/sess_xxxxxxxx"
}

Rooms

Room selection is handled entirely inside the iframe checkout. Your guests see live availability, pricing, and room descriptions without any additional code on your side.

To manage your room inventory — add rooms, set rates, block dates — log in to the dashboard.

No SDK methods for rooms

The booking widget does not expose a rooms API. All room data flows through the hosted checkout iframe. Use the dashboard to configure room types, nightly rates, and availability windows.

Payments

Payment is collected inside the hosted iframe using the payment gateway configured for your lodge (Yoco or Paystack). No payment credentials or card data ever pass through your website.

After a successful payment the iframe redirects to your lodge's thank-you page and the booking is confirmed. Your guest will receive a confirmation email automatically.

Yoco

Card payments for South African lodges. Enable in Settings → Payments → Yoco.

Paystack

Card and bank transfer support. Enable in Settings → Payments → Paystack.

Webhooks

EezyBookings sends signed POST requests to your server when key events occur — payment succeeded, payment failed, booking confirmed. Configure your endpoint in Settings → Webhooks.

Each request includes an x-eezy-signature header. Verify it using your webhook secret before processing the payload.

Verifying the signature

// Laravel example
Route::post('/webhooks/eezy', function (Request $request) {
    $secret    = config('services.eezybookings.webhook_secret');
    $signature = $request->header('x-eezy-signature');
    $expected  = hash_hmac('sha256', $request->getContent(), $secret);

    if (!hash_equals($expected, $signature)) {
        abort(401, 'Invalid signature');
    }

    $event = $request->json('event');

    match ($event) {
        'payment.succeeded' => handlePaymentSucceeded($request->json()),
        'payment.failed'    => handlePaymentFailed($request->json()),
        default             => null,
    };

    return response()->noContent();
});

Event types

Event	Fired when
payment.succeeded	Guest completes payment in the iframe checkout.
payment.failed	A payment attempt is declined or times out.
booking.confirmed	A booking is fully confirmed after successful payment.
booking.cancelled	A booking is cancelled from the dashboard or by the guest.

Error handling

By default the SDK shows a browser alert() when the booking session request fails. You can intercept this by wrapping the network call or by showing your own UI before calling init.

The most common failure modes are:

Scenario	Cause
Form not found	formId does not match any element in the DOM at the time init() is called.
Invalid response	The apiUrl responded but did not return an iframe_url field.
Network error	The apiUrl is unreachable or returned a non-2xx status.
Modal not opening	createModal() was not called — usually because init() threw before reaching it.

Checking that init succeeded

<script>
  // Check that the form exists before calling init
  if (!document.getElementById("booking-form")) {
    console.error("EezyBookings: #booking-form not found — skipping init");
  } else {
    EezyBookings.init({
      formId: "booking-form",
      apiKey: "ek_live_xxxxxxxxxxxxxxxx",
      apiUrl: "https://YOUR_LODGE.eezybookings.com/api/book",
    });
  }
</script>

Need a hand?

Our engineering team is happy to help with integration questions.