Start booking process

ETG API V3

Affiliate API

Booking

Start booking process

https://api.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.

Request example

curl --user '<KEY_ID>:<API_KEY>' 'https://api.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": "0b370500-5321-4046-92c5-5982f1a64fc6",
    "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": "9",
    "currency_code": "EUR"
  },
  "return_path": "https://example.com"
}'

Request body

Expand this| Collapse this

arrival_datetime DateTime optional

The estimated arrival time to the hotel.

book_timeout Int optional

The booking timeout in seconds.

ℹ️

The minimum value is 10.
The maximum value is 600.

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.

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

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.
Should be the same with the init_uuid field value from the Create credit card token) call.

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.
Should be the same with the pay_uuid field value from the Create credit card token) 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 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.
The match pattern:
- ^[^\W\d_]+([^\W\d_]*[\u0590-\u05FF\u0900-\u097F\u0980-\u09FF\u0E00-\u0E7F'\-,.’\s]*)*$.

last_name String 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.
The match pattern:
- ^[^\W\d_]+([^\W\d_]*[\u0590-\u05FF\u0900-\u097F\u0980-\u09FF\u0E00-\u0E7F'\-,.’\s]*)*$.

is_child Boolean optional

Whether the guest is a child or not.

age Int 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

The guest additional information.

comment String optional

The guest comments sent to the hotel.

email String required

The guest email address for contacting purposes. The email address must be valid.

phone String required

The guest phone number for contacting purposes. The phone number must be valid.

ℹ️

The minimum length is 5 characters.
The maximum length is 35 characters.

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.

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

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`

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.

`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 rate isn’t found. Send another search request.

`return_path_required`

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 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 init_uuid field values don’t match the regular expression.

`incorrect_pay_uuid_format`

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 finishing, send the Check booking process request.

Start booking process

Request example

Request body

Response example

Errors

book_hash_not_found

booking_form_expired

chosen_payment_type_was_not_available_on_booking_form

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`

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