Integration Requirements

Integration Requirements

This section describes the key API integration requirements that partners must follow to ensure a stable and correct integration with ETG API.

These requirements are reviewed during certification and are intended to reduce booking issues, support workload, financial risks, and production incidents. If the integration does not comply with these requirements, ETG may request changes before granting production access.

⚠️
Use only field values, IDs, API keys, and any static content provided for a specific environment (sandbox, testing, or production) within that environment. For example, use sandbox data only in the sandbox environment. Do not use sandbox data in test or production environments, and do not mix data or configuration between different environments.

1. General

1.1 Products and Certifications

Our API can be integrated with different products and methods for reselling rates. The main focuses are on:

  • Website or Mobile app, where ETG rates are presented on a website or mobile application you developed.
  • API, where ETG rates are being sold via your API, which your end-users integrate into their product.

Each product requires its independent certification, which can occur simultaneously or sequentially. More information is available in Certification and Production access in the Certification section.

1.2 Payment Types

Depending on the partnership model, ETG provides different payment_type (B2B, Affiliate).

Affiliate

now - ETG charges the card provided during the booking process. Please integrate Create credit card token for this payment type, as ETG charges the end-user or your corporate card.

The now payment method is currently unavailable in the Sandbox environment.

hotel - payment at the hotel: some of the rates will require credit card data, some not. Refer to the API response below to identify such rates:

"is_need_credit_card_data": true,
    "is_need_cvc": true,
    "type": "hotel",

Please integrate Create credit card token (B2B, Affiliate) for this payment type.

For B2B API

deposit - the payment comes from your deposit. The partner is responsible for charging the end-user.

1.3 Workflow

Please find the recommended workflow with endpoints in the Integration Guide. Also, please refer to ETG API documentation for request and response sample as well as error descriptions.

Note that we expect the diagram of your workflow during the Certification with mentioned ETG endpoints integrated to our workflow.

1.4 IPs Whitelist

Justification: To ensure the security of system credentials and safeguard access, clients integrating the ETG APIv3 are required to provide their IP addresses for whitelisting

Please provide the list of the IP addresses that must be whitelisted on our end. In addition, please specify if you need our IP addresses to be whitelisted on your end so we can provide our list.

1.5 Hotels in sandbox and test environments

To help you familiarize yourself with the API and test your integration, ETG provides two non-production environments: Sandbox and Test.

Actual bookings are processed only in the Production environment.

Required hotel mapping for certification

Depending on the environment used for integration testing, ETG may ask you to map specific test hotels in your system.

Before starting certification, you must map the required ETG test hotel or hotels and make them available in your test search and booking flow.

ETG uses these hotels to verify the full integration flow, including search, hotel page, prebook, booking, booking status processing, and cancellation logic.

If the required test hotels are not mapped or cannot be found in your system, ETG may not be able to start or complete certification.

Sandbox environment

The Sandbox environment is intended for API familiarization and basic integration testing. Only a limited set of special demo hotels is available for booking in this environment.

For the full list of properties available in Sandbox, see Sandbox properties. For the list of demo hotels that can be booked in Sandbox, see Test hotels in Sandbox.

For Sandbox certification, ETG may ask you to map one or both of the following hotel IDs:

  • 10004834
  • 8819557

These hotels must be searchable in your system if certification is performed in the Sandbox environment.

Test Environment

The Test environment allows you to book rooms only in the ETG demo hotel:

  • 8473727

Test API keys cannot be used to book real hotels. If you try to book a real hotel with a test API key, the API will return the sandbox_restriction error.

When making bookings in the Test environment, use refundable rates with the following cancellation policy: free_cancellation_before: “2024-12-05T20:00:00”. If you use other rate types, the API may return the insufficient_b2b_balance error.

2. Hotel Static

2.1 Hotel Static Data upload and updates

We expect you to keep your hotel static data updated as frequently as possible, preferably daily. To achieve this, please use Content API, which provides flexible and incremental access to hotel descriptive content.

To synchronize hotel static data with your system, follow this recommended flow:

  1. Retrieve static parameter lists and translations:

Use the Retrieve hotel static data (B2B, Affiliate) endpoint to obtain possible values and translations for static hotel and room parameters.

  1. Retrieve available filter values:

Use the Retrieve filter values endpoint to get available filter values for efficient hotel selection.

  1. Retrieve hotel IDs by filters:

Use the Retrieve hotel IDs by filter endpoint to fetch applicable hotel IDs meeting your filter criteria.

  1. Retrieve full content by hotel IDs:

Use the Retrieve hotels content by IDs endpoint to download static hotel content, including descriptions, images, amenities, and more for the selected hotels.

Store this static content in your system and refresh it regularly (ideally daily, or as frequently as your business processes allow) to ensure your booking interface always operates with the most up-to-date information.

Do not request hotel content data from the Content API during live user search sessions.

The Content API is intended exclusively for offline content synchronization and must not be called simultaneously with search or booking requests. Download and update static data in advance, outside of active user operations.

Additional Information

  • If you need hotel review information, please refer to the Retrieve hotels review by IDs endpoint of the Content API.
  • Please note that initial data synchronization may require processing a significant amount of records. Supporting incremental updates using timestamps or specific filters is highly recommended.

By storing and regularly updating static hotel content via the Content API, you ensure that user-facing booking and search flows always operate on up-to-date, locally-cached information. Live API requests should be reserved for availability and pricing only.

2.2 Mapping logic and mapping updates

You are expected to map our hotels and hotel IDs to the corresponding hotels and identifiers in your system.

This is necessary because each supplier may provide slightly different information for the same hotel — such as pictures, descriptions, and contact details. For example, addresses may be formatted differently or contain subtle variations. Proper mapping allows you to merge these differences and select the most accurate and relevant hotel data, images, and amenities to show your customers.

Updating mapping data

  • Use the Content API to regularly retrieve and update hotel static content for your mapping logic.
  • We strongly recommend using the updated_since parameter in the Retrieve hotel IDs by filter method to identify hotels where information has changed since your last update. For example:
"updated_since": "2024-04-12 00:00:00"

This will return a list of hotels that have had changes after “2024-04-12 00:00:00”. On your next update, simply use the timestamp from your previous synchronization.

  • After obtaining the list of updated hotel IDs, use the Retrieve hotels content by IDs method to retrieve content only for those hotels.
  • Perform the mapping process as frequently as possible to ensure your system always operates on up-to-date data.
  • During certification, be prepared to explain your mapping logic and update frequency.

Do not request hotel content data from the Content API during live user search sessions.

The Content API is intended exclusively for scheduled, offline content synchronization and must not be used simultaneously with search or booking requests.

2.3 Hotel important information

In hotel static data Retrieve hotels content by IDs one can find parameters:

ℹ️
If you don’t have a similar structure and want to present information in a clear, user-friendly format, follow our implementation guidance and practical examples, see Metapolicy_struct.

We expect the information in these parameters to be parsed and displayed to the end-user since it contains essential data related to hotel rules, additional fees, or any other important information. For example, some hotels expect guests to provide their passport only and not their other IDs.

2.4 Room Static data

To use room static data like images and amenities, you must use rg_ext fields. The rg_ext is a group of parameters that are unique room identifiers in the hotel; it can be found in the search and hotel static responses.

Room images and descriptions can be obtained only by matching all rg_ext fields from the search with rg_ext from the hotel static.

3. Search Step

This section is related to the following methods: Search by region (B2B, Affiliate), Search by geo coordinates (B2B, Affiliate), Search by hotel IDs (B2B, Affiliate), Retrieve hotelpage (B2B, Affiliate), and Prebook rate from hotelpage step (B2B, Affiliate), Prebook rate from search step (B2B, Affiliate).

3.1 Prebook

Prebook confirms availability of a specific rate. If rate is no longer available, propose a substitute within defined price_increase_percent.

The price_increase_percent parameter can be from 0% to 100%. If you work with price_increase_percent, then it is mandatory to display that the price has changed to the end-user.

⚠️

The Prebook method recommended timeout is 60 seconds, with a minimum of 30 seconds (which may lead to a decrease in availability).

Please note that the Prebook method does not support incoming search timeouts. The timeout can only be adjusted on the ETG side.

Search logic depends on the partner’s product. There are two types of search logic possible:

Recommended Flow (Prebook from Hotelpage):

One of the Search by methods - Retrieve hotelpage (B2B, Affiliate) - Prebook rate from hotelpage step (B2B, Affiliate).

Prebook rate from hotelpage step should be implemented after Retrieve hotelpage (B2B, Affiliate), and must be excluded from the booking flow.

The logic of working with book hashes during the Prebook rate from hotelpage step is the following:

  1. You get the book hash that starts with “h-…” during Retrieve hotelpage.
  2. Use that book hash that starts with “h-…” in the Prebook rate from hotelpage step request. In return, the Prebook rate from hotelpage step will give you a book hash that starts with “p-….”.
  3. That book hash that starts from “p-….” should be used during Create booking process (B2B, Affiliate).

Alternative Flow (Prebook from Search)

One of the Search by methods - Prebook rate from search step (B2B, Affiliate), where due to the absence of the hotel page, the search_hash from the SERP calls is required to proceed with the booking when specified as the hash for the Prebook rate from search call.

Prebook rate from search step should be implemented after one of SERP calls and must be excluded from the booking flow.

The logic of working with book hashes during the Prebook rate from search step is the following:

  1. You get the search hash that starts with “sr-…” during one of SERP calls.
  2. Use that search hash that starts with “sr-…” in the Prebook rate from search step request. In return, the Prebook rate from search step will give you a book hash that starts with “p-….”.
  3. That book hash that starts from “p-….” should be used during Create booking process (B2B, Affiliate).

If you need this call, please contact us.

3.2 Cache

The caching recommendations depend on your product’s logic. We usually don’t recommend caching and encourage working with real, live data. The longer a rate is stored in the cache, the higher the possibility that it may no longer be available later.

If you provide approximate prices during the first search step (which refers to the SERP, using any of the three available methods) and then update the prices during the second search step (Hotelpage), then it doesn’t matter how long you cache the first step results.

If you match Search by methods and Retrieve hotelpage (B2B, Affiliate) by match_hash then we don’t recommend caching at all.

Caching the responses of Retrieve hotelpage (B2B, Affiliate) and Prebook rate from hotelpage step (B2B, Affiliate) is prohibited.

3.3 Children Logic

The child’s age should be specified in the Search by and Retrieve hotelpage (B2B, Affiliate) requests in brackets [15].

Moreover, our system supports stays of up to 30 nights, with up to 6 adults and 4 children in one room. Individuals aged 17 years and below are considered children. The check-in date must be less than or equal to 730 days from today.

3.4 Multiroom booking

ETG supports up to 9 rooms at one rate, but does not support different room types at one rate. To book multiple rooms, specify the desired configuration in the Search by and Retrieve hotelpage (B2B, Affiliate) requests using the guests parameter.

Example for searching 2 rooms

For example, to book 2 rooms:

  • Room 1: 2 adults.
  • Room 2: 2 adults and 1 child (7 years old).
"guests": [
  {
    "adults": 2,
    "children": []
  },
  {
    "adults": 2,
    "children": [7]
  },
]

Guest data in /booking/finish/ request.

When proceeding with booking, you need to provide detailed guest information for each room in the rooms parameter.

It is important to always provide genuine guest information as entered during the booking process.

If you do not have data for all guests, do not send fake or placeholder names, ages, or other details (e.g., avoid using Child One, or random ages).

You can submit guest information in the following ways:

Option 1: Specify real data for at least one adult per room

If you only have genuine information for one guest in each room, only include those guests in the request.

Do not send null or fake data for the remaining guests.

{
  "rooms": [
    {
      "guests": [
        {
          "age": null,
          "first_name": "Martin",
          "gender": null,
          "is_child": false,
          "last_name": "Smith"
        }
      ]
    },
    {
      "guests": [
        {
          "age": null,
          "first_name": "Olga",
          "gender": null,
          "is_child": false,
          "last_name": "Jordan"
        }
      ]
    }
  ]
}

Option 2: Specify real data for all guests (if available)

If you have authentic information about every guest, include complete details for each.

{
  "rooms": [
    {
      "guests": [
        {
          "first_name": "Martin",
          "last_name": "Smith"
        },
        {
          "first_name": "Eliot",
          "last_name": "Smith"
        }
      ]
    },
    {
      "guests": [
        {
          "first_name": "Olga",
          "last_name": "Jordan"
        },
        {
          "first_name": "Alexander",
          "last_name": "Jordan"
        },
        {
          "first_name": "Ben",
          "last_name": "Button",
          "age": 7,
          "is_child": true
        }
      ]
    }
  ]
}
ℹ️
  • Only provide genuine data for guests, as collected during the booking process.
  • Do not supply null, fake, or placeholder data for missing guests; simply omit those entries.

3.5 Taxes and fees

Taxes and fees must be excluded from the final price. ETG API sends both included and non-included taxes. Non-included taxes must be displayed to the end-user separately. To find non-included taxes, please refer to tax_data.taxes parameter and search for taxes with included_by_supplier: false data. For example,

"hid": 8473727,
"rates": [
  {
    "match_hash": "m-5ab93916-be48-5bc0-953f-69eba410b3af",
    "search_hash": null,
    "daily_prices": [
          "0.80"
    ],
    "meal": "nomeal",
    "meal_data": {
      "value": "nomeal",
      "has_breakfast": false,
      "no_child_meal": true
    },
    "payment_options": {
      "payment_types": [
        {
          "amount": "75.20",
          "show_amount": "0.80",
          "currency_code": "EUR",
          "show_currency_code": "EUR",
          "by": null,
          "is_need_credit_card_data": false,
          "is_need_cvc": false,
          "type": "deposit",
          "vat_data": {
            "included": false,
            "applied": false,
            "amount": "0.00",
            "currency_code": "USD",
            "value": "0.00"
          },
          "tax_data": {
            "taxes": [
              {
                "name": "city_tax",
                "included_by_supplier": false, // - this tax shouldn’t be added to the total price and should be excluded and shown separately
                "amount": "1130.10",
                "currency_code": "HNL"
              },
              {
                "name": "electricity_fee",
                "included_by_supplier": true, // - this price is included in the price sent in “amount”, “show_amount”, “commission_info.charge.amount_net”, and “commision_info.charge.amount_gross”
                "amount": "0.02",
                "currency_code": "EUR"
              },
              {
                "name": "service_fee",
                "included_by_supplier": false, // - this tax shouldn’t be added to the total price and should be excluded and shown separately
                "amount": "3.70",
                "currency_code": "HNL"
              },
              {
                "name": "vat",
                "included_by_supplier": false, // - this tax shouldn’t be added to the total price and should be excluded and shown separately
                "amount": "679.74",
                "currency_code": "HNL"
              }

If your local legislation requires the final price to include taxes, reach out to our API support team for guidance on how to present taxes to end users and calculate the final price correctly.

3.6 Search timeouts

Our system can work with dynamic timeouts during searches (Search by methods and Retrieve hotelpage (B2B, Affiliate). To do so, please send a timeout parameter with an integer value.

The logic of the dynamic timeout is below:

  • If you send us the desired timeout in the API requests, our system will follow that timeout and provide responses within the requested timeout.
  • If you don’t send us the desired timeout in the API requests, then our system will follow the timeout configured on your Production Key.

The recommended timeout for Search by methods and Retrieve hotelpage is 30s. We are open to discussing search timeouts during certification.

3.7 Cancellation policies

Please parse cancellation policies from the cancellation_penalties.policies parameter.

The cancellation policies might have three layers:

Cancellation policies can be retrieved from any API step where they are present in the response.

In most cases, you may receive them in the following API methods:

You should use the cancellation_penalties.policies parameter to parse the policies data. The cancellation policies might have three layers, for example:

"start_at": null,
"end_at": "2025-10-21T08:59:00" // from the moment of booking until this time, the booking is refundable without penalty 
    "amount_charge": "0.00",
    "amount_show": "0.00",
    "commission_info": {
      "show": {
        "amount_gross": "0.00",
        "amount_net": "0.00",
        "amount_commission": "0.00"
      },
      "charge": {
        "amount_gross": "0.00",
        "amount_net": "0.00",
        "amount_commission": "0.00"
      }
    }
  },
  {
"start_at": "2025-10-21T08:59:00" // - within this timeframe, the cancellation is possible with a partial penalty 
"end_at": "2025-10-21T08:59:00",
    "amount_charge": "116.80",
    "amount_show": "1.60",
    "commission_info": {
      "show": {
        "amount_gross": "2.00",
        "amount_net": "1.60",
        "amount_commission": "0.40"
      },
      "charge": {
        "amount_gross": "146.00",
        "amount_net": "116.80",
        "amount_commission": "29.20"
      }
    }
},
{
"start_at": "2025-10-21T08:59:00" // - from this moment, the cancellation is possible with a full penalty
"end_at": null,
  "amount_charge": "241.60",
  "amount_show": "2.40",
  "commission_info": {
    "show": {
      "amount_gross": "3.00",
      "amount_net": "2.40",
      "amount_commission": "0.60"
    },
    "charge": {
      "amount_gross": "302.00",
      "amount_net": "241.60",
      "amount_commission": "60.40"
    }
  }
}
],
"free_cancellation_before": "2025-10-21T08:59:00"
},

free_cancellation_before: “2025-10-21T08:59:00” - means that end-users are allowed to cancel the booking without penalties before 2025-10-21T08:59:00. After that, full or partial cancellation penalties will apply. The rate with free_cancellation_before": null means that there is no free cancellation. The penalties will apply immediately when the user decides to cancel.

It is important to note that we send the cancellation policies via API in the UTC+0 timezone.

3.8 Citizenship/residency

Justification: If the passport country is not sent in the API requests, and the hotel in a specific country has citizenship based price adjustments, then the customer will have to pay additionally at the front desk, which ultimately will result in bad customer experience or even a dispute.

We expect the residency parameter to be sent in the Search by and Retrieve hotelpage (B2B, Affiliate) requests. Please note that by residency, we mean passport country.

We require this information because prices may change for specific regions based on this residency parameter.

The rates in the search response are provided according to the citizenship of the first guest provided in the search request. Citizenship should be the same for each guest in every search request. Provide the real guests’ citizenship in the residency field.

3.9 Meal types

We expect our partners to match our meal types with those in their systems. Please don’t make the meal type better than the one we’ve sent. If you don’t find the corresponding meal type on your end, please create one and worsen the meal type in your system.

Please use meal_data.value to display meals specific to rates.

To get the full list of meals, please call the endpoint: Retrieve hotel static data (B2B, Affiliate)

All possible options will be listed under the meals parameter.

3.10 Final price / Commission

ETG v3 API works with both net and gross prices. Please parse the corresponding parameter depending on your type of prices.

Net Prices

ℹ️
Applicable only to B2B-API.

Please work with amount or show_amount. The difference between amount and show_amount is that amount stands for the price of your selected currency for our reconciliation, meanwhile show_amount is the currency requested in Search by (B2B, Affiliate) or Retrieve hotelpage (B2B, Affiliate) request.

Please note that if you work with net prices, then you are responsible for calculating your commission or markup.

Gross Prices

ℹ️
Applicable only to Affiliate-API.

Please work with amount or show_amount. The difference between amount and show_amount is that amount stands for the price of your selected currency for our reconciliation, meanwhile show_amount is the currency requested in the Search by (B2B, Affiliate) or Retrieve hotelpage (B2B, Affiliate) request.

Please note that if you work with gross prices, then ETG is responsible for calculating the commission, and our API sends prices with your commission included.

Fake Gross Prices

ℹ️
Applicable only to B2B-API.

With this commission model you display to the end-user commission_info.charge.amount_gross or commission_info.show.amount_gross but pay to ETG the price specified in commission_info.charge.amount_net in the currency specified in your contract.

Please note that if you work with fake gross prices, the ETG is responsible for calculating the agreed commission. Still ETG will charge a net price from you.

Please do not add excluded taxes to the final price; they should be displayed separately. If you need to change your commission model, please contact your Account Manager or Sales Manager.

3.11 Room name reflection

Please be informed to parse the room_name parameter and display it to your client.

3.12 Early check-in / Late check-out

The Early check-in / Late check-out is currently unavailable in the Sandbox environment.

ETG v3 API supports early check-in and late check-out. Guests can ask for early check-in and late check-out options, which allow checking in before the usual time and leaving after the regular check-out time, depending on agreement and availability, and often with an extra fee.

ℹ️
When working with upsells, ensure clarity for the end-user and avoid overwhelming them with options, follow our implementation guidance and practical examples, see Upsells.

3.13 Hotel chunk size

Our system supports up to 300 hotels in 1 request for Search by hotel IDs (B2B, Affiliate). The recommended amount of hotels in a chunk depends on the Search by hotel IDs timeout.

4 Card Payments

The Card Payments is currently unavailable in the Sandbox environment.

This information is applicable to affiliate contracts that are using card payments, where ETG charges end-users on partner’s behalf. To work with card payments, we expect you to provide the return_path URL.

4.1 Endpoints Logic

Create credit card token

Since ETG will be charging the end-user, we expect you to send us the credit card data using the Create credit card token (B2B) endpoint. The endpoint request sample body can be found in our Create credit card token (Affiliate).

We expect you to create pay_uuid and init_uuid independently.

Start booking process

Please ensure to include pay_uuid, init_uuid and return_path in your request for Start booking process (B2B, Affiliate). The sample request should look like this:

    "user": {
        "email": "[email protected]",
        "comment": "comment",
        "phone": "12312321"
    },
    "partner": {
        "partner_order_id": "asd123",
        "comment": "partner_comment",
        "amount_sell_b2b2c": "10"
    },
    "language": "en",
    "rooms": [
        {
            "guests": [
                {
                    "first_name": "Marty",
                    "last_name": "Quatro"
                },
                {
                    "first_name": "Marta",
                    "last_name": "Quatro"
                }
            ]
        }
    ],
    "upsell_data": [
        {
            "name": "early_checkin",
            "uid": "d7b56e81-b874-40ee-b195-e2f73d1ec714"
        },
        {
            "name": "late_checkout",
            "uid": "c4013ea8-3ffd-4eee-bbbc-37693670031e"
        }
    ],
    "payment_type": {
        "type": "now",
        "amount": "8",
        "currency_code": "EUR",
        "pay_uuid": "797870e3-e1f0-470a-87b3-38694f58bed1",
        "init_uuid": "c44ef1ba-595b-437f-ad14-74ce39a0f9ad"
    },
    "return_path": "https//api.hotel.com/return_path/v1/hotel-booking/3ds"
}

4.2 How to work with 3ds

We might send the address for completing 3ds authentication with GET or POST method during Check booking process (B2B, Affiliate). Please refer to the endpoint page for examples.

Please find the logic of working with them in our ETG API documentation.

Please note that you can encounter error: 3ds and status: 3ds. The difference is:

  • Error: 3ds is the error indicating that the authorization has failed
  • Status 3ds is the status indicating that the end-user needs to proceed with 3ds authentication

Please note that the validation process is mandatory. We will check how you work with card payment logic to ensure everything is correct.

4.3 Requirements on cards used for testing purposes

  1. Once you reach the Start booking process (B2B, Affiliate), kindly provide the actual first name and last name. Kindly do not place any unsupported symbols, special characters, or numbers within the name field.
  2. The guest’s email and phone number should be real (otherwise, our anti-fraud system may block such a booking attempt as suspicious). Do not provide any test email addresses such as ([email protected] or [email protected]).
  3. When using Affiliate API, please do not use your corporate email (e.g., @corporateemail.com) (because our system recognizes it as a b2b account email, and this may block the booking).
  4. Please don’t use different emails in combination with different bank cards. For example, if you used a specific card with a certain email for your initial booking, ensure that subsequent bookings are made using the same email and card combination.
  5. Please use a real bank card with a sufficient balance, and ensure to enter the card details without errors.

5. Booking Step

5.1 Receiving the final booking status

You can use the Check booking process (B2B, Affiliate) endpoint AND / OR Receive booking status webhook (B2B, Affiliate) to get the final booking status. One of these options is mandatory for the implementation.

Order can be shown as confirmed only after receiving ok status from the Check booking process response or confirmed from the Receive booking status webhook.

If you use the Check booking process (B2B, Affiliate) call, follow the recommendations Retry logic (B2B, Affiliate).

If you have any limitations for this step, contact the API support team.

5.2 Booking cut-off

The booking cut-off (also known as booking timeout) is a specific timeframe within which ETG must complete the booking. If the booking is not completed by the end of the cut-off period, the order will be automatically marked as failed.

This booking cut-off is configured manually after negotiating with the partner during certification. Please note that the ETG v3 API doesn’t support dynamic booking timeouts.

5.3 Errors and Statuses Processing Logic

Each booking endpoint has a unique logic of processing statuses and errors as it impacts the final booking status. The each logic for both front-end and backend is provided and elaborated in the table below. Please note that the logic for each endpoint should be integrated strictly as it’s presented.

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/booking/form/

Status or Error Logic on FE Logic on BE
Status ok In Progress or waiting for status Proceed to call the /order/booking/finish/ (B2B, Affiliate) endpoint
5xx status code In Progress or waiting for status Proceed to call the /order/booking/form/ (B2B, Affiliate) endpoint until you receive status ok. Allowed to make up to 10 repeated requests. If within these 10 requests you haven’t received the status ok, restart the search process.
Error timeout In Progress or waiting for status Proceed to call the /order/booking/form/ endpoint until you receive status ok. Allowed to make up to 10 repeated requests. If within these 10 requests you haven’t received the status ok, restart the search process.
Error unknown In Progress or waiting for status Proceed to call the /order/booking/form/ endpoint until you receive status ok. Allowed to make up to 10 repeated requests. If within these 10 requests you haven’t received the status ok, restart the search process.
Error contract_mismatch Failed Stop the booking process and show the user that the booking has failed. Refer to the documentation to learn what to do in this case.
Error double_booking_form In Progress or waiting for status Change the partner_order_id and retry the call again.
Error duplicate_reservation In Progress or waiting for status Change the partner_order_id and retry the call again.
Error hotel_not_found Failed Stop the booking process and show the user that the booking has failed. Refer to the documentation to learn what to do in this case.
Error insufficient_b2b_balance Failed Stop the booking process and show the user that the booking has failed. Refer to the documentation to learn what to do in this case.
Error reservation_is_not_allowed Failed Stop the booking process and show the user that the booking has failed. Refer to the documentation to learn what to do in this case.
Error rate_not_found Failed Stop the booking process and show the user that the booking has failed. Refer to the documentation to learn what to do in this case.
Error sandbox_restriction Failed Stop the booking process and show the user that the booking has failed. Refer to the documentation to learn what to do in this case.

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/booking/finish/

Status or Error Logic on FE Logic on BE
Status ok In Progress or waiting for status Proceed to call the “/order/booking/finish/status/” (B2B, Affiliate) endpoint.
5xx status code In Progress or waiting for status Proceed to call the “/order/booking/finish/status/” endpoint.
Error timeout In Progress or waiting for status Proceed to call the “/order/booking/finish/status/” endpoint.
Error unknown In Progress or waiting for status Proceed to call the “/order/booking/finish/status/” endpoint.
Error booking_form_expired Failed Stop the booking process and show the user that the booking has failed.
Error rate_not_found Failed Stop the booking process and show the user that the booking has failed.
Error return_path_required Failed Stop the booking process and show the user that the booking has failed.

Endpoint: https://api.worldota.net/api/b2b/v3/hotel/order/booking/finish/status/

Status or Error Logic on FE Logic on BE
Status ok Success Stop calling the /order/booking/finish/status/ (B2B, Affiliate) and show the user that the booking is successful.
Status processing In Progress or waiting for status Continue calling the /order/booking/finish/status/ at regular intervals within the booking timeout.
Error timeout In Progress or waiting for status Continue calling the /order/booking/finish/status/ at regular intervals within the booking timeout.
Error unknown In Progress or waiting for status Continue calling the /order/booking/finish/status/ at regular intervals within the booking timeout.
5xx status code In Progress or waiting for status Continue calling the /order/booking/finish/status/ at regular intervals within the booking timeout.
Error block Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error charge Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error 3ds Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error soldout Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error provider Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error book_limit Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error not_allowed Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.
Error booking_finish_did_not_succeed Failed Stop calling the /order/booking/finish/status/ and show the user that the booking has failed.

5.4 Known errors

Only applicable to the Check booking process

In Check booking process (B2B, Affiliate), if you encounter 3ds, block, book_limit, booking_finish_did_not_succeed, provider, or soldout errors, please consider the booking failed. These are the final failure errors.

5.5 Webhooks

Only applicable to Receive booking status webhook

If you choose to integrate the Receive booking status webhook (B2B, Affiliate) alone, please integrate the Create booking process and Start booking process methods. Handle our callbacks properly and respond with a 200 OK status when you receive them.

Errors such as timeout, unknown, and the 5хх status code do not indicate the booking failure. The logic of working with these errors is explained below:

Create booking process (B2B, Affiliate) Start booking process (B2B, Affiliate)
If you get errors such as timeout, unknown, or the 5хх status code, you should make another request with a new partner_order_id. The maximum number of calls is limited to 10. If you get errors such as timeout, unknown, or other 5хх status code, you should wait for the webhook notification within the predefined timeout period to confirm the booking status.

1. The failure booking status will come as failed in webhook notification.

2. If no webhook notification is received within this time, the booking should be treated as unsuccessful.

In case of doubt, please check the order status in Ratehawk Backoffice.

5.6 Booking statuses on the partner/platform side

Here is the list of ETG statuses: some are present during the booking step, and some are applicable during the post-booking step.

Please map the booking flow statuses according to the table below:

Booking Status Corresponding status or error Check booking process Corresponding status or error in webhooks
Success (required) Status Ok Confirmed
Failed (required) Errors 3ds, block, book_limit, booking_finish_did_not_succeed, charge, decoding_json, endpoint_exceeded_limit, endpoint_not_active, endpoint_not_found, incorrect_credentials, invalid_auth_header, invalid_params, lock, no_auth_header, not_allowed, not_allowed_host, order_not_found, overdue_debt, provider, soldout, unexpected_method Failed
In progress (required) Processing, timeout, unknown, and 5xx status code Not applicable as webhook informs confirmed and failed statuses only.
Cancelled (optional) Not present during the booking flow, can be seen in Order Information endpoint Not present during the booking flow, can be seen in Order Information endpoint
No-show (optional) Not present during the booking flow Not present during the booking flow

5.7 Confirmation e-mails

When calling Start booking process (B2B, Affiliate), please follow the below logic of emails:

For B2B API

      "user": {
      "email": "[email protected]", //- we expect to receive one fixed corporate email for B2B API with your domain
      "comment": "comment",
      "phone": "12312321" 
  },

For Affiliate

    "user": {
    "email": "[email protected]" // - we expect to receive the end-user email here 
    "comment": "comment",
    "phone": "12312321"
},

6. Post Booking Step

6.1 Retrieve bookings

The Retrieve bookings (B2B, Affiliate) endpoint shouldn’t be used for checking the booking final status and should be excluded from the booking flow.

If you are using the Retrieve bookings endpoint, please wait some time after receiving the successful response from Check booking process (B2B, Affiliate) or Receive booking status webhook (B2B, Affiliate) before calling Retrieve bookings. The order data might take some time to synchronize and appear in this endpoint API response.

Please be informed that we don’t change the rate details during the booking process, so there is no need to check that and reconfirm if the details have changed.

6.2 Cancel booking

If you received the timeout error when canceling the order, please call the Cancel booking (B2B, Affiliate) endpoint one more time.