# How VibeBooking works with your system

> **Plans**
>
> Everything on this page is available on every plan.

VibeBooking reads a hotel's rooms, rates and availability from your system, and writes the bookings AI assistants make back into it. We build the adapter for your API ourselves.

## What we need from your system

| Function | What we need |
| --- | --- |
| Read rooms, rates and availability | Rate plans, rates and availability by date, minimum stay, closed to arrival or departure |
| Create a booking | One booking per stay, answered with your id. Store our reference on it |
| Tell a refusal from no answer | A clear error when you cannot take the booking |
| Find by our reference | Look up a booking by our reference |
| Read by your id | Whether it exists, whether it is cancelled, and our reference |
| Cancel | Cancel by your id. Cancelling a cancelled booking succeeds |
| Room back on cancel or change | Tell us whether the room goes back. If not, we take no bookings there |
| Record how it is paid | Paid now or pay at the property, and the amount paid |

A timeout or a server error means the booking may have landed, and we treat it that way.

### How a booking goes through

```mermaid
sequenceDiagram
    autonumber
    participant G as Guest or AI assistant
    participant V as VibeBooking
    participant S as Stripe (the hotel's account)
    participant P as Your system
    G->>V: Asks to book
    V->>P: Re-checks rate and availability
    V->>S: Authorises the card
    V->>P: Creates the booking, with our reference
    P-->>V: Your id
    V->>S: Captures the payment
    V-->>G: Confirmation email
```

### Payment

The hotel is the merchant of record and is paid through its own Stripe account. VibeBooking never holds the money and takes no fee. A booking that cannot be written is never charged.

## What we promise

- Every call is idempotent: a retry gives the same result.
- A booking is never created twice.
- If the payment fails, we cancel the booking in your system too.
- We reconcile regularly and flag any difference.
- Guest details live only in the booking service's database, and we send only what is needed.

When your system does not answer:

```mermaid
sequenceDiagram
    participant V as VibeBooking
    participant P as Your system
    participant S as Stripe
    V-xP: Creates the booking
    Note over V,P: Timeout. Not sent again
    V->>P: Looks it up by our reference
    alt Found
        V->>S: Captures the payment
    else Not found
        V->>S: Releases the authorisation
    end
```

## What we send with each booking

| Field | What it holds |
| --- | --- |
| Our booking reference | For example `VB-ABC123`. Also how we search for, read and cancel the booking |
| Room type, rate plan | Your system's ids |
| Check-in, check-out |  |
| Guests | Adults and children |
| Price per night, currency | The total divided by the nights, including any accommodation tax paid at the property |
| Payment | Paid now: the amount paid online and the Stripe payment id; the rest of the total is collected at the property. Pay at the property: all of it is collected there |
| Lead guest's name, email, phone |  |
| Furigana | A name written in kanji |
| Lives abroad | A guest living outside Japan, and whether they are a Japanese national |
| Nationality, passport number | A foreign national with no address in Japan: fields of Japan's guest register |
| Source id | Our id for which AI assistant the booking came through |

Where your system has no field for one of these, we write it in the booking's notes, one per line. The passport is checked at check-in, face to face. Card details never reach your system.

## API styles

Whatever style your API uses, we build an adapter for it if we need to. Our booking side stays the same; each system gets its own adapter.

| Style | Support |
| --- | --- |
| REST (JSON) | In use (Channex, Beds24) |
| SOAP or XML over HTTPS | Built to your specification |
| TravelXML | Built to your specification |
| Authentication | API keys, refresh tokens |
| Transport | HTTPS only |

### OpenTravel mapping

We do not speak OpenTravel (OTA) messages as standard. If your API takes OTA XML (`http://www.opentravel.org/OTA/2003/05`), we send each booking as an `OTA_HotelResNotifRQ`, as below. Element names and codes follow OpenTravel 2017B.

| What we send | OpenTravel element |
| --- | --- |
| Our booking reference | `UniqueID` (`Type="14"`) |
| Room type, rate plan | `RoomType@RoomTypeCode`, `RatePlan@RatePlanCode` |
| Check-in and check-out dates | `TimeSpan@Start`, `TimeSpan@End` |
| Guests | `GuestCount@AgeQualifyingCode` (adults `10`, children `8`) |
| Price per night, currency | `Rate/Base@AmountAfterTax`, `@CurrencyCode` |
| Payment | `Guarantee@GuaranteeType` (`PrePay` when paid online, `None` when paid at the property); the amount paid in `DepositPayments` |
| Lead guest's name, email, phone | `PersonName`, `Email` and `Telephone` under `Customer` |
| Nationality, passport number | `CitizenCountryName`, `Document` (`DocType="2"`) |
| Furigana, lives overseas | No element for these, so they go in `ResGlobalInfo/Comments` |
| Source ID | `POS/Source/BookingChannel` |
| Cancellation | `ResStatus="Cancel"` |

We never send card details (`PaymentCard`).

## Systems we work with

### Channex

| Function | In Channex |
| --- | --- |
| Read | Room types, rate plans, availability, restrictions |
| Create a booking | Booking CRS `POST /bookings` (status `new`, `ota_name` `Offline`) |
| Our reference | `ota_reservation_code` and `meta` |
| Find by our reference | The bookings list, matched on our reference |
| Read by your id | `GET /bookings/:id` |
| Cancel | `PUT /bookings/:id` (status `cancelled`) |
| Room back | `allow_availability_autoupdate_on_cancellation` and `allow_availability_autoupdate_on_modification` both on |
| Paid now | `payment_collect` `ota`, amount as a deposit |
| Pay at the property | `payment_collect` `property` |

Furigana and the guest register items go in the booking notes, one line each, in Japanese for the front desk.

| Guest data | In Channex |
| --- | --- |
| Name | `customer` surname and name, and the room's guest |
| Email, phone | `customer` `mail`, `phone` |
| Furigana | Notes `ふりがな: …` |
| Lives abroad | Notes `居住: 海外`, or `居住: 海外（日本国籍）` for a Japanese national |
| Nationality | Notes `国籍: …` |
| Passport number | Notes `旅券番号: …` |
| A test booking | Notes start with `[TEST]` |

- The Booking CRS application must be installed.
- The room-back settings are off by default; the hotel switches them on in Channex.
- The API is asynchronous: a read right after a create can answer 404. We never take that as no booking.

### How a hotel connects

The hotel pastes a Channex API key into the VibeBooking console. Once connected, Channex appears under **Properties** › **Integrations**.

![The Connect Channex screen, with a field to paste the API key and a Connect button.](https://docs.vibebooking.ai/screenshots/en/channex-key-desktop.webp)
*Pasting the API key to connect.*

![The Connections tab, showing Channex connected.](https://docs.vibebooking.ai/screenshots/en/channex-connected-desktop.webp)
*Integrations, once connected.*

## Adding your system

Email hello@vibebooking.ai.