ETG API V3
B2B API
Booking
Order Booking Form

Order Booking Form

https://api.worldota.net/api/b2b/v3/hotel/order/booking/form/
ℹ️
The call is required.

Creating a new reservation.

The process of reserving a rate includes several stages. Their number depends on whether there are 3D-secure checks and fraud checks (one or both of these checks can appear).

Important

Please note that booking hotels with “id” test_hotel and test_hotel_do_not_book will be a real booking with all of the financial responsibilities being the same as with real hotels, although the hotels themselves don’t exist. Nevertheless, giveaway prices are available within their rates for testing purposes.

All of the test reservations must be cancelled.

Request example 

curl --location 'https://api.worldota.net/api/b2b/v3/hotel/order/booking/form/' \
--header 'Content-Type: application/json' \
--data '{
    "partner_order_id": "asd123",
    "book_hash": "h-b91ec066-8cb4-57bd-9a0f-2bf9cb87c773",
    "language": "en",
    "user_ip": "82.29.0.86"
}'

Request body

partner_order_id String required

Identifier of the booking (at the partner) made by the partner. Shall be unique for the order within the same contact, otherwise an error will be returned. If a successful reservation is cancelled, the identifier remains the same. It is also assigned to reservations which were not completed successfully (after /hotel/order/booking/finish/status/ requests).

We highly recommend that you use the universally unique identifier (UUID).

All actions with the reservation are made with the partner_order_id.

ℹ️
  • The minimum length is 3 character.
  • The maximum length is 256 characters.
book_hash String required

Unique identifier of the rate (from the hotel page request). The book_hash key’s value can be transferred in the value of this parameter within 6 hours after the relevant rate is returned in the search results. Exceeding this limit will return an error with a “rate_not_found” value.

ℹ️
  • The minimum length is 3 character.
  • The maximum length is 256 characters.
language String required

The language.

ℹ️

The possible values:

  • ar—Arabic.
  • bg–Bulgarian.
  • cs–Czech.
  • de–German.
  • el–Greek.
  • en–English.
  • es–Spanish.
  • fr–French.
  • he–Hebrew.
  • hu–Hungarian.
  • it–Italian.
  • ja–Japanese.
  • kk–Kazakh.
  • ko–Korean.
  • nl–Dutch.
  • pl–Polish.
  • pt–Portuguese.
  • pt_PT–Portuguese (Portugal).
  • ro–Romanian.
  • ru–Russian.
  • sq–Albanian.
  • sr–Serbian.
  • th–Thai.
  • tr–Turkish.
  • uk–Ukrainian.
  • vi–Vietnamese.
  • zh_CN–Simplified Chinese.
user_ip String required
IP of the user.

Response

order_id Int required

Identifier of the booking made by the partner (identifier created at Emerging Travel Group).

ℹ️
  • The minimum value is 1.
partner_order_id String required

Identifier of the booking (at the partner) made by the partner.

ℹ️
  • The minimum length is 1 character.
  • The maximum length is 256 characters.
item_id Int required

Identifier of the booking order item made by the partner (identifier created at Emerging Travel Group).

It is only used for credit card data tokenization (in case of payment with card details).

is_gender_specification_required Boolean required
Whether the guests’ gender is required by the hotel or not.
upsell_data Array[Object] required

Order upsell information.

charge_price Object required

Price data of the upsell.

amount Number required
Amount of the upsell.
currency_code String required

The currency code in the ISO 4217 format.

ℹ️
  • The length is 3 characters.
  • The possible values:
    • AED.
    • AFN.
    • ALL.
    • AMD.
    • ANG.
    • AOA.
    • ARS.
    • AUD.
    • AWG.
    • AZN.
    • BAM.
    • BBD.
    • BDT.
    • BGN.
    • BHD.
    • BIF.
    • BMD.
    • BND.
    • BOB.
    • BOV.
    • BRL.
    • BSD.
    • BTN.
    • BWP.
    • BYR.
    • BYN.
    • BZD.
    • CAD.
    • CDF.
    • CHE.
    • CHF.
    • CHW.
    • CLF.
    • CLP.
    • CNY.
    • COP.
    • COU.
    • CRC.
    • CUC.
    • CUP.
    • CVE.
    • CZK.
    • DJF.
    • DKK.
    • DOP.
    • DZD.
    • EGP.
    • ERN.
    • ETB.
    • EUR.
    • FJD.
    • FKP.
    • GBP.
    • GEL.
    • GHS.
    • GIP.
    • GMD.
    • GNF.
    • GTQ.
    • GYD.
    • HKD.
    • HNL.
    • HRK.
    • HTG.
    • HUF.
    • IDR.
    • ILS.
    • INR.
    • IQD.
    • IRR.
    • ISK.
    • JMD.
    • JOD.
    • JPY.
    • KES.
    • KGS.
    • KHR.
    • KMF.
    • KPW.
    • KRW.
    • KWD.
    • KYD.
    • KZT.
    • LAK.
    • LBP.
    • LKR.
    • LRD.
    • LSL.
    • LTL.
    • LVL.
    • LYD.
    • MAD.
    • MDL.
    • MGA.
    • MKD.
    • MMK.
    • MNT.
    • MOP.
    • MRO.
    • MUR.
    • MVR.
    • MWK.
    • MXN.
    • MXV.
    • MYR.
    • MZN.
    • NAD.
    • NGN.
    • NIO.
    • NOK.
    • NPR.
    • NZD.
    • OMR.
    • PAB.
    • PEN.
    • PGK.
    • PHP.
    • PKR.
    • PLN.
    • PYG.
    • QAR.
    • RON.
    • RSD.
    • RUB.
    • RWF.
    • SAR.
    • SBD.
    • SCR.
    • SDG.
    • SEK.
    • SGD.
    • SHP.
    • SLL.
    • SOS.
    • SRD.
    • SSP.
    • STD.
    • SVC.
    • SYP.
    • SZL.
    • THB.
    • TJS.
    • TMT.
    • TND.
    • TOP.
    • TRY.
    • TTD.
    • TWD.
    • TZS.
    • UAH.
    • UGX.
    • USD.
    • USN.
    • USS.
    • UYI.
    • UYU.
    • UZS.
    • VEF.
    • VND.
    • VUV.
    • WST.
    • XAF.
    • XAG.
    • XAU.
    • XBA.
    • XBB.
    • XBC.
    • XBD.
    • XCD.
    • XDR.
    • XFU.
    • XOF.
    • XPD.
    • XPF.
    • XPT.
    • XSU.
    • XTS.
    • XUA.
    • YER.
    • ZAR.
    • ZMW.
    • ZWL.
name String required

Name of the upsell.

ℹ️
  • The possible values:
    • early_checkin.
    • late_checkout.
rule_id Int required
Rule ID.
uid String optional
Identifier of the upsell.
data Object optional
Time of the upsell.
payment_types Array[Object] required

Order payment information.

amount Number required
Amount of the order.
is_need_credit_card_data Boolean required
Whether or not credit card information is needed.
is_need_cvc Boolean required
Whether or not a CVC code is needed.
type String required

Payment type option.

ℹ️
  • The possible values:
    • now.
    • hotel.
    • deposit.
recommended_price String optional

The price below which the rate cannot be sold on b2c website. This price will be transferred only if you have signed an additional agreement with ETG, for details, you can contact your account manager. If the agreement is not signed, a null will be transferred.

amount Number required
Amount of the deposit (in the hotel’s currency - currency_code).
currency_code String required
Amount’s currency. Is the same as the charged (hotel’s) currency.
show_amount Number required
Rate price in the requested (show_currency_code) currency (not necessarily the sum in the charged/payment currency).
show_currency_code String optional
Requested currency (not necessarily the charged/payment currency).

Response example 

{
  "data": {
    "item_id": 32165487,
    "order_id": 123456789,
    "partner_order_id": "asd123",
    "payment_types": [
      {
        "amount": "0.93",
        "currency_code": "EUR",
        "is_need_credit_card_data": false,
        "is_need_cvc": false,
        "recommended_price": {
          "amount": "1.10",
          "currency_code": "EUR",
          "show_amount": "1.10",
          "show_currency_code": "EUR"
        },
        "type": "deposit"
      },
      {
        "amount": "40.85",
        "currency_code": "RUB",
        "is_need_credit_card_data": true,
        "is_need_cvc": true,
        "type": "now"
      },
      {
        "amount": "0.95",
        "currency_code": "USD",
        "is_need_credit_card_data": true,
        "is_need_cvc": true,
        "type": "now"
      },
      {
        "amount": "0.95",
        "currency_code": "EUR",
        "is_need_credit_card_data": true,
        "is_need_cvc": true,
        "type": "now"
      },
      {
        "amount": "0.95",
        "currency_code": "GBP",
        "is_need_credit_card_data": true,
        "is_need_cvc": true,
        "type": "now"
      }
    ],
    "upsell_data": [
      {
        "charge_price": {
          "amount": "4.6",
          "currency_code": "EUR"
        },
        "data": {
          "checkout_time": "19:00:00"
        },
        "name": "late_checkout",
        "rule_id": 473,
        "uid": "a3f405af-14ea-4cf0-923d-a2e6047c1ba7"
      },
      {
        "charge_price": {
          "amount": "3.2",
          "currency_code": "EUR"
        },
        "data": {
          "checkout_time": "18:00:00"
        },
        "name": "late_checkout",
        "rule_id": 473,
        "uid": "3350a400-7262-44c9-8c96-3e92959a7344"
      },
      {
        "charge_price": {
          "amount": "2.8",
          "currency_code": "EUR"
        },
        "data": {
          "checkin_time": "11:00:00"
        },
        "name": "early_checkin",
        "rule_id": 493,
        "uid": "5e5e5839-874b-4f12-b43e-02543a1a478b"
      },
      {
        "charge_price": {
          "amount": "3.9",
          "currency_code": "EUR"
        },
        "data": {
          "checkin_time": "09:00:00"
        },
        "name": "early_checkin",
        "rule_id": 493,
        "uid": "b29b5a49-1b81-429f-8bbf-644e9d585481"
      },
      {
        "charge_price": {
          "amount": "3.9",
          "currency_code": "EUR"
        },
        "data": {
          "checkin_time": "08:00:00"
        },
        "name": "early_checkin",
        "rule_id": 493,
        "uid": "f43dd8af-d86f-421c-b2ec-5feddf86e879"
      },
      {
        "charge_price": {
          "amount": "2.8",
          "currency_code": "EUR"
        },
        "data": {
          "checkin_time": "10:00:00"
        },
        "name": "early_checkin",
        "rule_id": 493,
        "uid": "f46a2e15-922c-4bc8-80fb-4c85705dcd8f"
      },
      {
        "charge_price": {
          "amount": "3.2",
          "currency_code": "EUR"
        },
        "data": {
          "checkout_time": "17:00:00"
        },
        "name": "late_checkout",
        "rule_id": 473,
        "uid": "a114bb6b-537a-4a6f-816c-4f5f3c43e465"
      },
      {
        "charge_price": {
          "amount": "4.6",
          "currency_code": "EUR"
        },
        "data": {
          "checkout_time": "20:00:00"
        },
        "name": "late_checkout",
        "rule_id": 473,
        "uid": "796d4761-8a69-4925-ad04-d0772a44050f"
      }
    ]
  },
  "debug": null,
  "error": null,
  "status": "ok"
}

Errors’ description

contract_mismatch

An attempt to make a booking with a rate found with a different contract.

double_booking_form

An attempt to make a booking with a partner_order_id already used for the API key’s contract that wasn’t completed yet. In any case, for any further /hotel/order/booking/form/ request, a new unique partner_order_id needs to be used.

duplicate_reservation

An attempt to make a booking with a partner_order_id already used for API key’s contract that was already completed or failed. In any case, for further /hotel/order/booking/form/ request, a new unique partner_order_id needs to be used.

hotel_not_found

In case there is no available hotel in the database.

insufficient_b2b_balance

In case the credit limit is not sufficient for the reservation.

To discuss changes to this limit please contact your account manager.

reservation_is_not_allowed

Booking functionality is not activated on your API-key.

rate_not_found

Rate wasn’t found. Probably too much time has passed since the search request. Another search request is needed.

sandbox_restriction

You cannot book a hotel other than test_hotel or test_hotel_do_not_book with a sandbox API-key.

timeout, unknown, and 5xx

If you get errors timeout, unknown, or the 5хх status code from this call:

  • Make another request with a new partner_order_id.
  • The number of calls should be limited to 10.
  • If you get this error more than 10 times in a row, the issue is probably in automatically changed settings of your contract. Contact your account manager to resolve the issue. Otherwise, the ETG has temporary technical issues.
Credit Card Data Tokenization