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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gotadi.com/english/b2b2c-partner/api-method/hotel/cancellation-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.