ETG API V3
B2B API
Booking
Create booking process

Create booking process

#b2b

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

The call creates a booking process. The booking process includes several stages. Their number depends on whether there are 3D Secure and fraud checks.

ℹ️

The limitations:

  • The booking form lifetime is 60 minutes.
⚠️
  • All bookings for the hotel with the test_hotel_do_not_book ID will be real with all financial responsibilities. Nevertheless, giveaway prices are available within their rates for testing purposes.
  • All test bookings must be canceled.

Request example 

curl --user '<KEY_ID>:<API_KEY>' 'https://api.worldota.net/api/b2b/v3/hotel/order/booking/form/' \
--header 'Content-Type: application/json' \
--data '{
  "partner_order_id": "0b370500-5321-4046-92c5-5982f1a64fc6",
  "book_hash": "h-b91ec066-8cb4-57bd-9a0f-2bf9cb87c773",
  "language": "en",
  "user_ip": "82.29.0.86"
}'

Request body

partner_order_id String required

The external booking ID in the UUID format.

The ID remains the same if you cancel a booking that:

Use this field for the rest of the booking calls.

ℹ️
  • The value should be unique for the order within the same contact.
  • The minimum length is 3 character.
  • The maximum length is 256 characters.
book_hash String required

The unique rate ID used to identify the selected rate.

ℹ️
language String required

The language.

ℹ️

The possible values:

  • ar — Arabic.
  • bg — Bulgarian.
  • cs — Czech.
  • da — Danish.
  • de — German.
  • el — Greek.
  • en — English.
  • es — Spanish.
  • fi — Finnish.
  • fr — French.
  • he — Hebrew.
  • hu — Hungarian.
  • it — Italian.
  • ja — Japanese.
  • kk — Kazakh.
  • ko — Korean.
  • nl — Dutch.
  • no — Norwegian.
  • pl — Polish.
  • pt — Portuguese.
  • pt_PT — Portuguese (Portugal).
  • ro — Romanian.
  • ru — Russian.
  • sq — Albanian.
  • sr — Serbian.
  • sv — Swedish.
  • th — Thai.
  • tr — Turkish.
  • uk — Ukrainian.
  • vi — Vietnamese.
  • zh_CN — Simplified Chinese.
  • zh_TW — Traditional Chinese.
user_ip String required
The partner IP address.

Response

order_id Int

The order ID created by the ETG.

ℹ️
  • The minimum value is 1.
partner_order_id String

The external booking ID in the UUID format.

The ID remains the same if you cancel a booking that:

Use this field for the rest of the booking calls.

ℹ️
  • The value should be unique for the order within the same contact.
  • The minimum length is 3 character.
  • The maximum length is 256 characters.
item_id Int

The order item ID.

Use this field value in the Create credit card token call to allow the user to pay with a bank card.

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

The order upsell information.

charge_price Object

The upsell price information.

amount String
The upsell amount.
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

The upsell name.

ℹ️
  • The possible values:
    • early_checkin.
    • late_checkout.
rule_id Int
The upsell rule ID.
uid String
The upsell ID.
data Object
The upsell time. The local time in the HH:MM:SS format.
payment_types [Object]

The order payment information.

amount String
The order amount.
currency_code String required
The amount currency code. Is the same as the charged (contract) currency code.
is_need_credit_card_data Boolean
Whether the credit card information is needed or not.
is_need_cvc Boolean
Whether the CVC is needed or not.
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 Create booking process call and get the card details.
      2. Request the Create credit card token 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 can’t be sold on B2C website.

To get this value, you have to sign an additional agreement with the ETG. Has the null value, ff the agreement isn’t signed. For more details, contact your account manager.

amount String
The deposit amount.
currency_code String
The deposit amount currency code. Is the same as the charged (hotel) currency code.
show_amount Float

The rate price in the request currency code of this object show_currency_code field value.

Isn’t necessarily the sum in the charged or payment currency code.

show_currency_code String

The request currency code.

Isn’t necessarily in the charged or payment currency code.

Response example 

{
  "data": {
    "item_id": 32165487,
    "order_id": 123456789,
    "partner_order_id": "0b370500-5321-4046-92c5-5982f1a64fc6",
    "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": "0.40",
        "currency_code": "EUR",
        "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

The error field has the value specified in the headers below.

contract_mismatch

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

double_booking_form

An attempt to make a new booking with the partner_order_id that is already used for the API key contract and isn’t completed yet.

Make another request with a new partner_order_id.

duplicate_reservation

An attempt to make a new booking with the partner_order_id that is already used for the API key contract and is already completed with a successful or error status.

Make another request with a new partner_order_id.

hotel_not_found

The hotel isn’t found.

reservation_is_not_allowed

There is no permission to use this call for this contract. Contact your account manager.

rate_not_found

  • The rate with the book_hash field value isn’t found.
  • The book_hash field value has expired.

Send another search request and change the book_hash field value.

sandbox_restriction

An attempt to book the real hotel in the test environment.

timeout, unknown, and 5xx

If you get errors timeout, unknown, or the 5xx 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.