Create 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/form/

ℹ️

This call is required.
Request this call right after the calls:
After requesting this call, you must send the Start booking process request.

The call creates a booking process. The booking process includes several stages.

ℹ️

The limitations:

The booking form lifetime is 60 minutes.

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.

The 3D Secure check isn’t supported in the sandbox.

Request

language. Input value is ignored, the value is always en.

Response

Not supported fields:
- item_id.
- payment_type.type.
- payment_types.recommended_price.show_currency_code.
currency_code. For every object with this field, the value is always EUR.

Request example

curl --user '<KEY_ID>:<API_KEY>' 'https://api-sandbox.worldota.net/api/b2b/v3/hotel/order/booking/form/' \
--header 'Content-Type: application/json' \
--data '{
  "partner_order_id": "1c481611-6432-5157-03d6-6093g2b75gd1",
  "book_hash": "p-86ccba07-27ab-489b-b549-c956ea928811",
  "language": "en",
  "user_ip": "82.29.0.86"
}'

Request body

Expand this| Collapse this

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.

book_hash String required

The unique rate ID used to identify the selected rate.

ℹ️

Use the value of the book_hash field from one of the calls:
- Prebook rate from hotelpage step.
- Prebook rate from search step.
The value lifetime is 6 hours after you have prebooked the 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 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.

user_ip String required

The end user IP address.

Will be used for credit card processing if you use payment type now.

Response

Expand this| Collapse this

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:

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.

item_id Int

The order item ID.

is_gender_specification_required Boolean

Whether the guests’ gender is required by the hotel or not.

upsell_data [Object]

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.

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

data Object

The upsell time. The local time in the HH:MM:SS format.

payment_types [Object]

The order payment information.

amount String

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

⚠️

This parameter is currently under development and will be available later. It can be ignored at the moment.

The price below which the rate can’t be sold on B2C website.

amount String

The deposit amount.

currency_code String

The deposit amount currency code. Is the same as the charged (hotel) currency code.

show_amount String

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": {
    "is_gender_specification_required": false,
    "item_id": 89,
    "order_id": 89,
    "partner_order_id": "1c481611-6432-5157-03d6-6093g2b75gd1",
    "payment_types": [
      {
        "amount": "306.00",
        "currency_code": "USD",
        "is_need_credit_card_data": false,
        "is_need_cvc": false,
        "recommended_price": null,
        "type": "deposit"
      }
    ],
    "upsell_data": []
  },
  "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.

`insufficient_b2b_balance`

The credit limit is reached. Contact your account manager.

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

To book the real hotel, use the production environment.
To book the test hotel, use the test environment.

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

Create booking process

Sandbox limitations

Request

Response

Request example

Request body

Response

Response example

Errors

contract_mismatch

double_booking_form

insufficient_b2b_balance

duplicate_reservation

hotel_not_found

reservation_is_not_allowed

rate_not_found

sandbox_restriction

timeout, unknown, and 5xx

`contract_mismatch`

`double_booking_form`

`insufficient_b2b_balance`

`duplicate_reservation`

`hotel_not_found`

`reservation_is_not_allowed`

`rate_not_found`

`sandbox_restriction`

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