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 hotel with “id” 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

The unique rate ID.

ℹ️
  • 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
The partner IP address.

Response

order_id Int

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

ℹ️
  • The minimum value is 1.
partner_order_id String

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

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
Whether the guests’ gender is required by the hotel or not.
upsell_data [Object]

Order upsell information.

charge_price Object

Price data of the upsell.

amount Float
Amount of the upsell.
currency_code String

The amount 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

Name of the upsell.

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

Order payment information.

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

The payment type.

ℹ️
  • The possible values:

    • now. Use it to allow the user to pay for the booking via the ETG payment system:

      1. Request the Order Booking Form call and get the card details.
      2. Request the Credit Card Data Tokenization call with the card details.

    • hotel. Use it to allow the user to pay for the booking upon check-in at the hotel. The user won’t be charged now.

    • deposit. Use it to allow you to charge the user bank card for the booking by yourself:

      1. You need to keep your ETG deposit sufficient. To increase funds, contact your account manager.
      2. The user makes a booking.
      3. You charge the user bank card.
      4. The ETG writes funds from your deposit by themselves during the reporting period.

      Every payment goes under a credit limit for the deposit.

recommended_price String

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 Float
Amount of the deposit (in the hotel’s currency - currency_code).
currency_code String
Amount’s currency. Is the same as the charged (hotel’s) currency.
show_amount Float
Rate price in the requested (show_currency_code) currency (not necessarily the sum in the charged/payment currency).
show_currency_code String
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.
  • The book_hash value lifetime expired.

Another search request is needed.

sandbox_restriction

You cannot book a hotel other than 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