Cancellation API

Document Hotel API Cancellation

Luồng huỷ phòng khách sạn

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

Example 1: Cancellation fee per night

[{
    "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

[{
    "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

[{
    "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

[{
    "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

[{
    "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

[{
    "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

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

Returns room cancelability status information, and cancellation penalty information.

Request Body

Model

Request Body

• bookingNumber (String, Required)

  Reference code (Unique)

Example

Response

Code 200

OK

Model

• 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)

---

2. API request to cancel hotel booking

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

Model

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

Response

Code 200

OK

Model

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

3. API to Check Room Cancellation Status

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

Model

• 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

Response

Code 200

OK

Model

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