> For the complete documentation index, see [llms.txt](https://developer.gotadi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.gotadi.com/english/b2b2c-partner/api-method/hotel/cancellation-api.md).

# Cancellation API

Document Hotel API Cancellation

![Luồng huỷ phòng khách sạn](https://developer.gotadi.com/img/cancellation-process.png)

## Description of penalties for cancellation

If you do not check in, or if you cancel or modify this reservation after the check-in time, you may be subject to a penalty fee of up to 100% of the booking value.

### Penalties <a href="#cac-hinh-thuc-phat" id="cac-hinh-thuc-phat"></a>

#### **Example 1: Cancellation fee per night**

```json
[{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "NIGHTS",
    "currency": "VND",  
    "percent": "",  
    "nights": "1.0",
    "amount": "",
    "description": ""
}]
```

* Free cancellation before `2021-05-12T18:00:00.000+07:00`
* 1 night fee for cancellation from `2021-05-12T18:00:00.000+07:00` to `2021-05-13T18:00:00.000+07:00`

**Example 2: Cancellation fee by price**

```json
[{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "AMOUNT",
    "currency": "VND",
    "percent": "",
    "nights": "",
    "amount": "200000",
    "description": ""
}]
```

* Free cancellation before `2021-05-12T18:00:00.000+07:00`
* Cancellation fee of 200,000 VND from May 12, 2021, 18:00 (GMT+7) to May 13, 2021, 18:00 (GMT+7).

**Example 3: Cancellation fee by percentage**

```json
[{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "70%",
    "nights": "",
    "amount": "",
    "description": ""
}]
```

* Free cancellation before `2021-05-12T18:00:00.000+07:00`
* Cancellation fee 70% of room value from `2021-05-12T18:00:00.000+07:00` to `2021-05-13T18:00:00.000+07:00`

**Example 4: Various types of cancellation fees**

```json
[{
    "startDate": "2021-05-10T18:00:00.000+07:00",
    "endDate": "2021-05-12T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "50%",
    "nights": "",
    "amount": "",
    "description": ""
},
{
    "startDate": "2021-05-12T18:00:00.000+07:00",
    "endDate": "2021-05-13T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "70%",
    "nights": "",
    "amount": "",
    "description": ""
}]
```

* Free cancellation before `2021-05-10T18:00:00.000+07:00`
* Cancellation fee 50% of room value from `2021-05-10T18:00:00.000+07:00` to `2021-05-12T18:00:00.000+07:00`
* Cancellation fee 70% of room value from `2021-05-12T18:00:00.000+07:00` to `2021-05-13T18:00:00.000+07:00`

**Example 5: Cancellation fee with various fee**

```json
[{
    "startDate": "2021-05-10T18:00:00.000+07:00",
    "endDate": "2021-05-12T18:00:00.000+07:00",
    "type": "PERCENT",
    "currency": "VND",
    "percent": "50%",
    "nights": "",
    "amount": "25000",
    "description": ""
}]
```

* Free cancellation before `2021-05-10T18:00:00.000+07:00`
* Cancellation fee 50% of room value from `2021-05-10T18:00:00.000+07:00` to `2021-05-12T18:00:00.000+07:00` with various fee.
* Cancellation fee of 25,000 VND from `2021-05-10T18:00:00.000+07:00` to `2021-05-12T18:00:00.000+07:00`

**Example 6: Free cancellation**

```json
[{
    "startDate": "2021-05-01T18:00:00.000+07:00",
    "endDate": "2021-05-12T18:00:00.000+07:00",
    "type": "NIGHTS",
    "currency": "VND",
    "percent": "",
    "nights": "0",
    "amount": "",
    "description": ""
}]
```

* Free cancellation before `2021-05-12T18:00:00.000+07:00`

***

## 1. API to Check Cancellation Eligibility and Fees <a href="#id-1-api-kiem-tra-kha-nang-huy-phong-va-phi-phat" id="id-1-api-kiem-tra-kha-nang-huy-phong-va-phi-phat"></a>

POST: /api/v3/hotel/check-cancel-penalty

Returns room cancelability status information, and cancellation penalty information.

#### Request Body <a href="#request-body" id="request-body"></a>

Model

<details>

<summary>Request Body</summary>

* bookingNumber (String, Required)

  Reference code (Unique)

</details>

Example

#### Response <a href="#response" id="response"></a>

**Code 200**

> OK

<details>

<summary>Model</summary>

* result (CheckCancelPenaltyResult, Optional)

  Returned result information

  * status (string, optional) = \[‘ALLOW\_CANCELLATION’, ‘NOT\_ALLOW\_CANCELLATION’, ‘UNKNOWN’]

    Information to determine cancellation status

    * `ALLOW_CANCELLATION`: Chấp nhận huỷ phòng
    * `NOT_ALLOW_CANCELLATION`: Không chấp nhận huỷ phòng
    * `UNKNOWN`: Unable to determine status, needs to be rechecked.
  * cancelPenalties (Array\[CancelPenalty], optional),
  * cancelPenaltyTotal (number, optional),
* duration (Integer, Optional)
* success (Integer, Bool)
* infos (Array\[InfosDTO], Optional)
* errors (Array\[ErrorsDTO], Optional)
* textMessage (String, Optional)

</details>

***

## 2. API request to cancel hotel booking <a href="#id-2-api-yeu-cau-huy-booking-hotel" id="id-2-api-yeu-cau-huy-booking-hotel"></a>

POST: /api/partner/cancellation

**API sends a cancellation request for a hotel booking and waits for a response from the provider**

**Notice:**

* **Security Requirements:** Data must be encrypted and include a digital signature.
* **Request:** Encryption and digital signature are **not required**.
* **Response:** Certain parts of the response **must be encrypted** and include a digital signature.

#### Request Body <a href="#request-body_1" id="request-body_1"></a>

<details>

<summary>Model</summary>

#### **Key (string, required)**

* Decryption key for the encrypted data.

**Data (string, required)**

* Encrypted data containing a digital signature.

**Signature Data Schema:**

```
<access_code>|<booking_number>|<cancel_penalty_amount>
```

#### **Original Data Schema:**

```
<access_code>|<booking_number>|<cancel_penalty_amount>|<signature>
```

* **access\_code (String, required)** – Access code provided by Gotadi to the Partner.
* **bookingNumber (String, required)** – Reference code for the booking.
* **cancel\_penalty\_amount (String, optional)** – Cancellation penalty fee, formatted to two decimal places (0.00).

</details>

#### Response <a href="#response_1" id="response_1"></a>

**Code 200**

> OK

<details>

<summary>Model</summary>

* **key (String, required)** – Decryption key for the encrypted data.
* **data (String, required)** – Encrypted data containing a digital signature.

*Signature data schema:*

```
<access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>
```

*Original data schema:*

```
<access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>|<signature>
```

* **access\_code (String, required)** – Access code provided by Gotadi to the Partner.
* **booking\_number (String, required)** – Reference code for the booking.
* **error\_code (String, required)** – Error code.
* **product\_type (String, optional)** – Product type, with possible values: `AIR` (flight) or `HOTEL` (hotel), corresponding to the purchased product.
* **cancellation\_status (String, optional)** – Cancellation status information:
  * **CANCEL\_UNKNOWN** – Status is unknown and requires rechecking.
  * **CANCEL\_PENALTY\_MISMATCH** – The cancellation penalty fee does not match. The API for checking cancellation eligibility and penalty fees should be called again before resubmitting the cancellation request.
  * **CANCEL\_WAITING\_CONFIRM** – Cancellation request sent successfully, waiting for confirmation from the provider.
  * **CANCEL\_CONFIRMED** – Cancellation confirmed successfully.
  * **CANCEL\_EXPIRED** – Cancellation request has expired.

</details>

## 3. **API to Check Room Cancellation Status** <a href="#id-3-api-kiem-tra-trang-thai-huy-phong" id="id-3-api-kiem-tra-trang-thai-huy-phong"></a>

POST: /api/partner/cancellation-check

API to check room cancellation status

Note

**Security Requirements:** Encryption and Digital Signature Required

* **Request:** Encryption and digital signature are **not required**.
* **Response:** Certain parts of the response **must be encrypted** and include a digital signature.

#### Request Body <a href="#request-body_2" id="request-body_2"></a>

<details>

<summary>Model</summary>

* key (string, required),
* data (string, required),

  *Signature data schema:*

  ```
  <access_code>|<booking_number>>
  ```

  *Original data schema:*

  ```
  <access_code>|<booking_number>|<signature>
  ```

  * access\_code (String, required)

    Gotadi provide
  * bookingNumber (String, required)

    Reference code

</details>

#### Response <a href="#response_2" id="response_2"></a>

**Code 200**

> OK

<details>

<summary>Model</summary>

* key (String, required)
* data (String, required)

  *Signature data schema:*

  ```
  <access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>|<cancel_penalty_amount>
  ```

  *Original data schema:*

  ```
  <access_code>|<booking_number>|<error_code>|<product_type>|<cancellation_status>|<cancellation_feee>|<signature>
  ```

  * **access\_code (String, required)** – Access code provided by Gotadi to the Partner.
  * **booking\_number (String, required)** – Reference code for the booking.
  * **error\_code (String, required)** – Error code.
  * **product\_type (String, optional)** – Product type, with possible values: `AIR` (flight) or `HOTEL` (hotel), corresponding to the purchased product.
  * **cancellation\_status (String, optional)** – Cancellation status information:
    * **CANCEL\_UNKNOWN** – Status is unknown and requires rechecking.
    * **CANCEL\_PENALTY\_MISMATCH** – The cancellation penalty fee does not match. Call the API for checking cancellation eligibility and penalty fees before resubmitting the cancellation request.
    * **CANCEL\_WAITING\_CONFIRM** – Cancellation request sent successfully, waiting for confirmation from the provider.
    * **CANCEL\_CONFIRMED** – Cancellation confirmed successfully.
    * **CANCEL\_EXPIRED** – Cancellation request has expired.
    * **product\_type (String, optional)** – Product type (`AIR` for flight, `HOTEL` for hotel).
    * **cancel\_penalty\_amount (String, optional)** – Cancellation fee amount, formatted to two decimal places (0.00).

</details>