Start booking process

ETG API V3

Booking

🆕

The Sandbox environment is available exclusively to new partners who begin their integration in Q4 2025.

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

ℹ️

This call is required.
Request this call right after the Create booking process call.
As the booking process is made asynchronously, repeatedly request the Check booking process call to know the status.

The call starts the booking process.

⚠️

If invalid user data is used, the data may be added to the stop list.

Sandbox limitations

⚠️

Use all field values and API keys obtained from the sandbox environment only within the sandbox. Don’t mix them with test or production environments.

Request

payment_type.type. The possible field values:
- hotel.
- deposit.
payment_type.currency_code. The field value is always USD.
Not supported fields:
- payment_type.init_uuid.
- payment_type.pay_uuid.
- upsell_data.
- return_path.

Response

currency_code. For every object with this field, the value is always EUR.

Errors

Not supported errors:
- book_hash_not_found.
- rate_not_found.
- return_path_required.
- not_enough_credit_card_data.
- incorrect_init_uuid_format.
- incorrect_pay_uuid_format.

Request example

curl --user '<KEY_ID>:<API_KEY>' 'https://api-sandbox.worldota.net/api/b2b/v3/hotel/order/booking/finish/' \
--header 'Content-Type: application/json' \
--data '{
  "user": {
    "email": "[email protected]",
    "comment": "The user comment.",
    "phone": "12124567899"
  },
  "supplier_data": {
    "first_name_original": "Peter",
    "last_name_original": "Collins",
    "phone": "12124567880",
    "email": "[email protected]"
  },
  "partner": {
    "partner_order_id": "1c481611-6432-5157-03d6-6093g2b75gd1",
    "comment": "The partner comment.",
    "amount_sell_b2b2c": "10"
  },
  "language": "en",
  "rooms": [
    {
      "guests": [
        {
          "first_name": "Martin",
          "last_name": "Smith"
        },
        {
          "first_name": "Eliot",
          "last_name": "Smith"
        }
      ]
    }
  ],
  "payment_type": {
    "type": "deposit",
    "amount": "306.00",
    "currency_code": "USD"
  }
}'

Request body

Expand this| Collapse this

arrival_datetime DateTime optional

The estimated arrival time to the hotel.

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 Bokmål.
pl — Polish.
pt — Portuguese.
pt_PT — European Portuguese.
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.

partner Object required

The partner information.

partner_order_id String required

The external booking ID in the UUID format.

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

Is successful.
Is failed.
Has the fail status response from the Check booking process call.

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.

comment String optional

The partner booking internal comment.

The comment isn’t sent to the hotel and not processed by the ETG API support team. It is visible only to the partner itself.

ℹ️

The minimum length is 1 character.
The maximum length is 256 character.

amount_sell_b2b2c String optional

The resale price for the user in the contract currency.

The value is accepted if transferred (even if automatic completion of the resale price value is activated) and is displayed in the confirmatory accounting documents for the partners.

ℹ️

The minimum value is 1.

payment_type Object required

The order payment information.

type String required

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.
- 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.

amount String required

The booking amount.

currency_code String required

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.

init_uuid String optional

The external booking token ID in the UUID format.

ℹ️

The length is 36 characters.
Must be unique for every payment. Otherwise, the ETG will return an error.
The value matches the pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$.
Is required for bookings where the is_need_credit_card_data field was passed with the true value.

pay_uuid String optional

The external booking payment ID in the UUID format.

ℹ️

The length is 36 characters.
Must be unique for every payment. Otherwise, the ETG will return an error.
The value matches the pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$.
Is required for bookings where the is_need_credit_card_data field was passed with the true value.

upsell_data Object optional

The order upsell information.

⚠️

Set these parameters only when the user really needs additional services.
Only one early check-in and one late check-out should be requested and selected.

attributes String optional

The upsell check-in and check-out dates.

checkin_datetime Datetime optional

The upsell check-in date and time.

checkout_datetime Datetime optional

The upsell check-out date and time.

name String optional

The upsell name.

ℹ️

The possible values:
- early_checkin.
- late_checkout.

rule_id Int optional

The upsell rule ID.

uid String optional

The upsell ID.

ℹ️

Use the value of the uid field from the Create booking process call.

return_path String optional

The URL at your side to redirect the user to. It is done by the payment gateway after 3D Secure check. The reason the ETG needs it.

This field is required if the rate you are booking has the payment_types field with the now value.

The field data_3ds of the Check booking process call will have the null value if:

You don’t pass this field.
The issuing bank requires 3D Secure check.

ℹ️

Must have the HTTPS scheme.
Might have GET parameters.
The minimum length is 1 character.
The maximum length is 256 character.

rooms [Object] required

The guests’ information for the rooms.

guests Object required

The guests’ information.

first_name String required or optional

The guest first name.

ℹ️

It is mandatory to provide the first name for at least one guest in each booked room.
The minimum length is 1 character.
The maximum length is 50 characters.
Digits and non-word symbols are prohibited, field should contain only unicode letters (Latin, Cyrillic, Hebrew, Hindi, Bengali, Thai etc.), spaces or following special characters: '-,.’.

last_name String required or optional

The guest last name. For test purposes use the Ratehawk value.

ℹ️

It is mandatory to provide the last name for at least one guest in each booked room.
The minimum length is 1 character.
The maximum length is 50 characters.
Digits and non-word symbols are prohibited, field should contain only unicode letters (Latin, Cyrillic, Hebrew, Hindi, Bengali, Thai etc.), spaces or following special characters: '-,.’.

is_child Boolean optional

Whether the guest is a child or not.

age Int required or optional

The child age in years.

ℹ️

Specify the child’s age if there are children in the booking request.
The minimum value is 0.
The maximum value is 17.

gender String optional

The guest gender.

ℹ️

Is required if the hotel you intend to book has the is_gender_specification_required field with the true value. The field appears only in the Retrieve hotel content call response.
The possible values:
- male.
- female.
- unknown.

user Object required

comment String optional

email String required

phone String required

supplier_data Object required or optional

The contact details of the user who initiated the booking.

ℹ️

To know if the field is required for you, contact your account manager.

first_name_original String required

The first name of the user who initiated the booking.

ℹ️

To know if the field is required for you, contact your account manager.

last_name_original String required

The last name of the user who initiated the booking.

ℹ️

To know if the field is required for you, contact your account manager.

email String required

The email address of the user who initiated the booking.

ℹ️

To know if the field is required for you, contact your account manager.

phone String required

The phone number of the user who initiated the booking.

ℹ️

To know if the field is required for you, contact your account manager.
The minimum length is 5 characters.
The maximum length is 35 characters.

Response example

{
  "data": null,
  "debug": null,
  "error": null,
  "status": "ok"
}

Errors

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

`book_hash_not_found`

⚠️

The error isn’t supported yet.

A rare internal error when the ETG couldn’t recognize the book_hash used in the booking.

After getting the error, the only option is to find another rate and continue with it.

`booking_form_expired`

In case Create booking process has been expired.

Request a new Create booking process with a different partner_order_id.

`chosen_payment_type_was_not_available_on_booking_form`

The payment_type field values don’t match any of the payment_types field values in the response of the Create booking process call.

Try to change the payment_type field value according to the payment_types field values in the response.

`credit_card_required`

N/A (cc payments not supported yet)

`double_booking_finish`

An attempt to finish the booking for the second time while the status of the first attempt isn’t an error.

`email`

The provided email address isn’t valid.

`incorrect_chosen_payment_type`

The type field value is incorrect.

`incorrect_guests_number`

The adult guest number doesn’t match the adult guest number in the request of the Retrieve hotelpage call.

Try to change the rooms field item number according to the guests field values in the request.

`incorrect_children_data`

The children guest number doesn’t match the children guest number in the request of the Retrieve hotelpage call.
The children age is incorrect.

Try to change:

The rooms field item number according to the guests field values in the request.
The age field value.

`incorrect_rooms_number`

The room number doesn’t match the room number in the request of the Retrieve hotelpage call.

Try to change the rooms field item number according to the guests field values in the request.

`insufficient_b2b_balance`

The credit limit is reached. Contact your account manager.

`order_not_found`

The order with the partner_order_id field value isn’t found.

Send another booking creation request and change the partner_order_id field value.

`rate_not_found`

⚠️

The error isn’t supported yet.

The rate isn’t found. Send another search request.

`return_path_required`

⚠️

The error isn’t supported yet.

The return_path field is required if the rate you are booking has the payment_types field with the now value.

`unauthorized_group_booking`

An attempt to make a request with the conditions:

More than 9 bookings in the same hotel.
More than 9 bookings for the same dates.
In one request.

To make a group booking:

Contact the API support team.
Fill in the group booking form on the site.

`invalid_upsell_attributes`

Invalid name and attributes combination in upsell_data field.

`invalid_upsell_uid`

Invalid upsell uid in upsell_data field.

`arrival_date_differs_from_checkin_date`

The check-in date should be equal to or the day after the check-in date in the request of the Retrieve hotelpage call.

Try to change the checkin_datetime field value according to the checkin field value in the request.

`not_enough_credit_card_data`

⚠️

The error isn’t supported yet.

The init_uuid and pay_uuid fields are required if the rate you are booking has the is_need_credit_card_data field with the true value.

`incorrect_init_uuid_format`

⚠️

The error isn’t supported yet.

The init_uuid field values don’t match the regular expression.

`incorrect_pay_uuid_format`

⚠️

The error isn’t supported yet.

The pay_uuid field values don’t match the regular expression.

`sandbox_restriction`

An attempt to book the test hotel with the hid = 6291619 or id = test_hotel_do_not_book in the production environment.

To book the test hotel, use the test environment.

`supplier_data_required`

The supplier_data field is required for your integration. Contact your account manager.

`timeout`, `unknown`, and `5xx`

If you get the error, it doesn’t necessarily mean the booking isn’t created. These errors may occur because of the ETG services’ timeout. To check the booking creation, send the Check booking process request.

Start booking process

Sandbox limitations

Request

Response

Errors

Request example

Request body

Response example

Errors

book_hash_not_found

booking_form_expired

chosen_payment_type_was_not_available_on_booking_form

credit_card_required

double_booking_finish

email

incorrect_chosen_payment_type

incorrect_guests_number

incorrect_children_data

incorrect_rooms_number

insufficient_b2b_balance

order_not_found

rate_not_found

return_path_required

unauthorized_group_booking

invalid_upsell_attributes

invalid_upsell_uid

arrival_date_differs_from_checkin_date

not_enough_credit_card_data

incorrect_init_uuid_format

incorrect_pay_uuid_format

sandbox_restriction

supplier_data_required

timeout, unknown, and 5xx

`book_hash_not_found`

`booking_form_expired`

`chosen_payment_type_was_not_available_on_booking_form`

`credit_card_required`

`double_booking_finish`

`email`

`incorrect_chosen_payment_type`

`incorrect_guests_number`

`incorrect_children_data`

`incorrect_rooms_number`

`insufficient_b2b_balance`

`order_not_found`

`rate_not_found`

`return_path_required`

`unauthorized_group_booking`

`invalid_upsell_attributes`

`invalid_upsell_uid`

`arrival_date_differs_from_checkin_date`

`not_enough_credit_card_data`

`incorrect_init_uuid_format`

`incorrect_pay_uuid_format`

`sandbox_restriction`

`supplier_data_required`

`timeout`, `unknown`, and `5xx`