# Create booking process

URL: https://docs.emergingtravel.com/docs/affiliate-api/booking/create-booking-process/

Tags: affiliate

---



**Sandbox**

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

**Production**

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




> [!NOTE]
> * <strong>This call is required</strong>.
> * Request this call right after the calls:
>   * [Retrieve hotelpage](/docs/affiliate-api/hotel-search/retrieve-hotelpage/).
>   * [Prebook rate from hotelpage step](/docs/affiliate-api/hotel-search/prebook-rate-from-hotelpage-step/).
>   * [Prebook rate from search step](/docs/affiliate-api/hotel-search/prebook-rate-from-search-step/).
> * After requesting this call, you must send the [Start booking process](/docs/affiliate-api/booking/start-booking-process/) request.



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

> [!NOTE]
> The limitations:
> * The booking form lifetime is 60 minutes.



> [!WARNING]
> The following applies only when using a test API key:
> 
> * All bookings for the test hotel (use `hid` = `8473727`or `id` = `test_hotel_do_not_book`) will be real with all financial responsibilities. Nevertheless, giveaway prices are available within their rates for testing purposes.
> * All test bookings must be canceled.



## Sandbox limitations { #limitations }

> [!WARNING]
> Use only field values, IDs, API keys, and any static content from the sandbox environment within the sandbox. <strong>Do not use sandbox data in test or production environments, and do not mix data or configuration between different environments.</strong>




* The 3D Secure check is not supported in the sandbox.
* The input value for the `language` field is ignored and is always set to `en`.
* The following fields are not supported: `item_id`, `payment_type.type`, and `payment_types.recommended_price.show_currency_code`.
* For all objects with the `currency_code` field, the value is always `EUR`.

## Request example


**Sandbox**

```shell
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": "asd12399235",
    "book_hash": "h-372e7fa4-3a85-5a09-9f14-867766abf26c",
    "language": "en",
    "user_ip": "82.29.0.86"
}'
```

**Production**

```shell
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": "asd12399235",
    "book_hash": "h-372e7fa4-3a85-5a09-9f14-867766abf26c",
    "language": "en",
    "user_ip": "82.29.0.86"
}'
```




## Request body



- **partner_order_id** *(String, required)*

  <p>The external booking ID in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)
   format.</p>
  <p>The ID remains the same if you cancel a booking that:</p>
  <ul>
  <li>Is successful.</li>
  <li>Is failed.</li>
  <li>Has the fail status response from the [Check booking process](/docs/affiliate-api/booking/check-booking-process/)
   call.</li>
  </ul>
  <p>Use this field value for the rest of the booking calls.</p>
  > [!NOTE]
  > * 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)*

  <p>The unique rate ID used to identify the selected rate.</p>
  > [!NOTE]
  > Use the value of the `book_hash` field from one of the calls:
  >   * [Prebook rate from hotelpage step](/docs/affiliate-api/hotel-search/prebook-rate-from-hotelpage-step/).
  >   * [Prebook rate from search step](/docs/affiliate-api/hotel-search/prebook-rate-from-search-step/).


- **language** *(String, required)*

  <p>The language.</p>
  > [!NOTE]
  > 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)*

  <p>The end user IP address.</p>
  <p>Will be used for credit card processing if you use payment type <code>now</code>.</p>





## Response



[//]: # (order_id)
- **order_id** *(Int)*

  <p>The order ID created by the ETG.</p>
  > [!NOTE]
  > * The minimum value is `1`.


[//]: # (partner_order_id)
- **partner_order_id** *(String)*

  <p>The external booking ID in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)
   format.</p>
  <p>The ID remains the same if you cancel a booking that:</p>
  <ul>
  <li>Is successful.</li>
  <li>Is failed.</li>
  <li>Has the fail status response from the [Check booking process](/docs/affiliate-api/booking/check-booking-process/)
   call.</li>
  </ul>
  <p>Use this field value for the rest of the booking calls.</p>
  > [!NOTE]
  > * 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)
- **item_id** *(Int)*

  <p>The order item ID.</p>
  <p>Use this field value in the [Create credit card token](/docs/affiliate-api/booking/create-credit-card-token/)
   call to allow the user pay with a bank card.</p>


[//]: # (is_gender_specification_required)
- **is_gender_specification_required** *(Boolean)*

  <p>Whether the guests’ gender is required by the hotel or not.</p>


[//]: # (upsell_data)
- **upsell_data** *([Object])*

  <p>The order upsell information.</p>
  <blockquote>
  <p>[!WARNING]</p>
  <ul>
  <li>Set these parameters only when the user really needs additional services.</li>
  <li>Only one early check-in and one late check-out should be requested and selected.</li>
  </ul></blockquote>
  <ul>
  <li>
  <p><strong>charge_price</strong> <em>(Object)</em></p>
  <p>The upsell price information.</p>
  <ul>
  <li>
  <p><strong>amount</strong> <em>(String)</em></p>
  <p>The upsell amount in the currency specified by the <code>currency_code</code> field.</p>
  </li>
  <li>
  <p><strong>currency_code</strong> <em>(String)</em></p>
  <p>The amount currency code in the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
   format.</p>
  <blockquote>
  <p>[!NOTE]</p>
  <ul>
  <li>The length is <code>3</code> characters.</li>
  <li>The possible values:
  <ul>
  <li><code>AED</code>.</li>
  <li><code>AFN</code>.</li>
  <li><code>ALL</code>.</li>
  <li><code>AMD</code>.</li>
  <li><code>ANG</code>.</li>
  <li><code>AOA</code>.</li>
  <li><code>ARS</code>.</li>
  <li><code>AUD</code>.</li>
  <li><code>AWG</code>.</li>
  <li><code>AZN</code>.</li>
  <li><code>BAM</code>.</li>
  <li><code>BBD</code>.</li>
  <li><code>BDT</code>.</li>
  <li><code>BGN</code>.</li>
  <li><code>BHD</code>.</li>
  <li><code>BIF</code>.</li>
  <li><code>BMD</code>.</li>
  <li><code>BND</code>.</li>
  <li><code>BOB</code>.</li>
  <li><code>BOV</code>.</li>
  <li><code>BRL</code>.</li>
  <li><code>BSD</code>.</li>
  <li><code>BTN</code>.</li>
  <li><code>BWP</code>.</li>
  <li><code>BYR</code>.</li>
  <li><code>BYN</code>.</li>
  <li><code>BZD</code>.</li>
  <li><code>CAD</code>.</li>
  <li><code>CDF</code>.</li>
  <li><code>CHE</code>.</li>
  <li><code>CHF</code>.</li>
  <li><code>CHW</code>.</li>
  <li><code>CLF</code>.</li>
  <li><code>CLP</code>.</li>
  <li><code>CNY</code>.</li>
  <li><code>COP</code>.</li>
  <li><code>COU</code>.</li>
  <li><code>CRC</code>.</li>
  <li><code>CUC</code>.</li>
  <li><code>CUP</code>.</li>
  <li><code>CVE</code>.</li>
  <li><code>CZK</code>.</li>
  <li><code>DJF</code>.</li>
  <li><code>DKK</code>.</li>
  <li><code>DOP</code>.</li>
  <li><code>DZD</code>.</li>
  <li><code>EGP</code>.</li>
  <li><code>ERN</code>.</li>
  <li><code>ETB</code>.</li>
  <li><code>EUR</code>.</li>
  <li><code>FJD</code>.</li>
  <li><code>FKP</code>.</li>
  <li><code>GBP</code>.</li>
  <li><code>GEL</code>.</li>
  <li><code>GHS</code>.</li>
  <li><code>GIP</code>.</li>
  <li><code>GMD</code>.</li>
  <li><code>GNF</code>.</li>
  <li><code>GTQ</code>.</li>
  <li><code>GYD</code>.</li>
  <li><code>HKD</code>.</li>
  <li><code>HNL</code>.</li>
  <li><code>HRK</code>.</li>
  <li><code>HTG</code>.</li>
  <li><code>HUF</code>.</li>
  <li><code>IDR</code>.</li>
  <li><code>ILS</code>.</li>
  <li><code>INR</code>.</li>
  <li><code>IQD</code>.</li>
  <li><code>IRR</code>.</li>
  <li><code>ISK</code>.</li>
  <li><code>JMD</code>.</li>
  <li><code>JOD</code>.</li>
  <li><code>JPY</code>.</li>
  <li><code>KES</code>.</li>
  <li><code>KGS</code>.</li>
  <li><code>KHR</code>.</li>
  <li><code>KMF</code>.</li>
  <li><code>KPW</code>.</li>
  <li><code>KRW</code>.</li>
  <li><code>KWD</code>.</li>
  <li><code>KYD</code>.</li>
  <li><code>KZT</code>.</li>
  <li><code>LAK</code>.</li>
  <li><code>LBP</code>.</li>
  <li><code>LKR</code>.</li>
  <li><code>LRD</code>.</li>
  <li><code>LSL</code>.</li>
  <li><code>LTL</code>.</li>
  <li><code>LVL</code>.</li>
  <li><code>LYD</code>.</li>
  <li><code>MAD</code>.</li>
  <li><code>MDL</code>.</li>
  <li><code>MGA</code>.</li>
  <li><code>MKD</code>.</li>
  <li><code>MMK</code>.</li>
  <li><code>MNT</code>.</li>
  <li><code>MOP</code>.</li>
  <li><code>MRO</code>.</li>
  <li><code>MUR</code>.</li>
  <li><code>MVR</code>.</li>
  <li><code>MWK</code>.</li>
  <li><code>MXN</code>.</li>
  <li><code>MXV</code>.</li>
  <li><code>MYR</code>.</li>
  <li><code>MZN</code>.</li>
  <li><code>NAD</code>.</li>
  <li><code>NGN</code>.</li>
  <li><code>NIO</code>.</li>
  <li><code>NOK</code>.</li>
  <li><code>NPR</code>.</li>
  <li><code>NZD</code>.</li>
  <li><code>OMR</code>.</li>
  <li><code>PAB</code>.</li>
  <li><code>PEN</code>.</li>
  <li><code>PGK</code>.</li>
  <li><code>PHP</code>.</li>
  <li><code>PKR</code>.</li>
  <li><code>PLN</code>.</li>
  <li><code>PYG</code>.</li>
  <li><code>QAR</code>.</li>
  <li><code>RON</code>.</li>
  <li><code>RSD</code>.</li>
  <li><code>RUB</code>.</li>
  <li><code>RWF</code>.</li>
  <li><code>SAR</code>.</li>
  <li><code>SBD</code>.</li>
  <li><code>SCR</code>.</li>
  <li><code>SDG</code>.</li>
  <li><code>SEK</code>.</li>
  <li><code>SGD</code>.</li>
  <li><code>SHP</code>.</li>
  <li><code>SLL</code>.</li>
  <li><code>SOS</code>.</li>
  <li><code>SRD</code>.</li>
  <li><code>SSP</code>.</li>
  <li><code>STD</code>.</li>
  <li><code>SVC</code>.</li>
  <li><code>SYP</code>.</li>
  <li><code>SZL</code>.</li>
  <li><code>THB</code>.</li>
  <li><code>TJS</code>.</li>
  <li><code>TMT</code>.</li>
  <li><code>TND</code>.</li>
  <li><code>TOP</code>.</li>
  <li><code>TRY</code>.</li>
  <li><code>TTD</code>.</li>
  <li><code>TWD</code>.</li>
  <li><code>TZS</code>.</li>
  <li><code>UAH</code>.</li>
  <li><code>UGX</code>.</li>
  <li><code>USD</code>.</li>
  <li><code>USN</code>.</li>
  <li><code>USS</code>.</li>
  <li><code>UYI</code>.</li>
  <li><code>UYU</code>.</li>
  <li><code>UZS</code>.</li>
  <li><code>VEF</code>.</li>
  <li><code>VND</code>.</li>
  <li><code>VUV</code>.</li>
  <li><code>WST</code>.</li>
  <li><code>XAF</code>.</li>
  <li><code>XAG</code>.</li>
  <li><code>XAU</code>.</li>
  <li><code>XBA</code>.</li>
  <li><code>XBB</code>.</li>
  <li><code>XBC</code>.</li>
  <li><code>XBD</code>.</li>
  <li><code>XCD</code>.</li>
  <li><code>XDR</code>.</li>
  <li><code>XFU</code>.</li>
  <li><code>XOF</code>.</li>
  <li><code>XPD</code>.</li>
  <li><code>XPF</code>.</li>
  <li><code>XPT</code>.</li>
  <li><code>XSU</code>.</li>
  <li><code>XTS</code>.</li>
  <li><code>XUA</code>.</li>
  <li><code>YER</code>.</li>
  <li><code>ZAR</code>.</li>
  <li><code>ZMW</code>.</li>
  <li><code>ZWL</code>.</li>
  </ul>
  </li>
  </ul></blockquote>
  </li>
  </ul>
  </li>
  <li>
  <p><strong>name</strong> <em>(String)</em></p>
  <p>The upsell name.</p>
  > [!NOTE]
  > * The possible values:
  >   * `early_checkin`.
  >   * `late_checkout`.
  </li>
  <li>
  <p><strong>rule_id</strong> <em>(Int)</em></p>
  <p>The upsell rule ID.</p>
  </li>
  <li>
  <p><strong>uid</strong> <em>(String)</em></p>
  <p>The upsell ID.</p>
  </li>
  <li>
  <p><strong>data</strong> <em>(Object)</em></p>
  <p>The upsell time. The local time in the <code>HH:MM:SS</code> format.</p>
  </li>
  </ul>


[//]: # (payment_types)
- **payment_types** *([Object])*

  <p>The order payment information.</p>
  <ul>
  <li>
  <p><strong>amount</strong> <em>(String)</em></p>
  <p>The booking amount in the currency specified by the <code>currency_code</code> field.</p>
  </li>
  <li>
  <p><strong>currency_code</strong> <em>(String)</em></p>
  <p>The amount currency code. Is the same as the charged (contract) currency code.</p>
  > [!NOTE]
  > If the `payment_types` is `hotel`, the hotel `currency_code` will be used here.
  </li>
  <li>
  <p><strong>is_need_credit_card_data</strong> <em>(Boolean)</em></p>
  <p>Whether the credit card information is needed or not.</p>
  </li>
  <li>
  <p><strong>is_need_cvc</strong> <em>(Boolean)</em></p>
  <p>Whether the CVC is needed or not.</p>
  </li>
  <li>
  <p><strong>recommended_price</strong> <em>(String)</em></p>
  <blockquote>
  <p>[!WARNING]
  This parameter is currently under development and will be available later. It can be ignored at the moment.</p></blockquote>
  <p>The price below which the rate can’t be sold on B2C website.</p> 
  <ul>
  <li>
  <p><strong>amount</strong> <em>(String)</em></p>
  <p>The deposit amount in the currency specified by the <code>currency_code</code> field.</p>
  </li>
  <li>
  <p><strong>currency_code</strong> <em>(String)</em></p>
  <p>The deposit amount currency code. Is the same as the charged (hotel) currency code.</p>
  </li>
  <li>
  <p><strong>show_amount</strong> <em>(String)</em></p>
  <p>The rate price in the request currency code of this object <code>show_currency_code</code> field value.</p>
  <p>Isn’t necessarily the sum in the charged or payment currency code.</p>
  </li>
  <li>
  <p><strong>show_currency_code</strong> <em>(String)</em></p>
  <p>The request currency code.</p>
  <p>Isn’t necessarily in the charged or payment currency code.</p>
  </li>
  </ul>
  </li>
  <li>
  <p><strong>type</strong> <em>(String)</em></p>
  <p>The payment type.</p>
  > [!NOTE]
  > * 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](/docs/affiliate-api/booking/create-booking-process/) call and get the card details.
  >     1. Request the [Create credit card token](/docs/affiliate-api/booking/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.
  >     1. The user makes a booking.
  >     1. You charge the user bank card.
  >     1. The ETG writes funds from your deposit by themselves during the reporting period.
  </li>
  </ul>





## Response example

```json
{
    "data": {
        "order_id": 559350847,
        "partner_order_id": "asd12399235",
        "item_id": 128903852,
        "payment_types": [
            {
                "amount": "2000.00",
                "currency_code": "INR",
                "is_need_credit_card_data": false,
                "is_need_cvc": false,
                "type": "hotel",
                "recommended_price": null
            }
        ],
        "is_gender_specification_required": false,
        "upsell_data": []
    },
    "debug": {
        "api_endpoint": {
            "endpoint": "api/b2b/v3/hotel/order/booking/form",
            "is_active": true,
            "is_limited": true,
            "remaining": 29,
            "requests_number": 30,
            "reset": "2025-10-21T12:22:00",
            "seconds_number": 60
        },
        "request": {
            "partner_order_id": "asd12399235",
            "book_hash": "h-372e7fa4-3a85-5a09-9f14-867766abf26c",
            "language": "en",
            "user_ip": "82.29.0.86"
        },
        "method": "POST",
        "real_ip": "104.30.161.77",
        "request_id": "26f502336760ea6e5a71ed6beae781f5",
        "key_id": 1234,
        "api_key_id": 1234,
        "utcnow": "2025-10-21T12:21:01.572537"
    },
    "status": "ok",
    "error": null
}
```

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

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

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](/docs/glossary/#test-environment).

* To book the real hotel, use the [production environment](/docs/glossary/#production-environment).
* To book the test hotel, use the [test environment](/docs/glossary/#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.

## Error Handling Diagram

Below is a sequence diagram describing how to handle errors during the booking creation process:

> [!NOTE]
> The number of retries should be limited to 10.



```mermaid
sequenceDiagram
    participant User
    participant API

   User->>API: Create booking process request
alt status == "ok"
    API-->>User: Response: "ok"
    User->>User: Go to Start booking process
    else error in (duplicate_reservation, double_booking_form, unknown, timeout) or HTTP status code 5xx
    loop Retry with new partner_order_id (until status == "ok" or other error)
        User->>API: Retry Create booking process with new partner_order_id
        API-->>User: Response
        alt status == "ok"
            User->>User: Go to Start booking process
          else error in retryable set
            User->>User: Continue retry
        else other error
            User->>User: Show error and stop
        end
    end
else other error
    API-->>User: Response error
    User->>User: Show error and stop
end
```