Hotels API

Refund

Refund a payment through the original payment gateway, or register a refund you handled outside the platform. A refund does not cancel any service.

POST/booking/refund

Refund is money only

A refund does not cancel the hotel, and Cancel does not refund the guest. When a guest cancels, call Cancel first, check that it succeeded, then refund what they paid minus the fee.

Request

Headers

auth-tokenstringrequired
Any valid token.
Accept-EncodingstringrequiredDocs
gzip
Content-Typestringrequired
application/json

Body

orderNumberstringrequiredSpec
The order number of the payment to refund. Don't assume it equals your externalReference.
amountnumber
How much to refund. 0 or omitted refunds the full remaining amount.
manualRefundbooleanUnverified
Default false. Most likely false refunds through the original payment gateway, true registers a refund you handled outside the platform.

Response

200 OK

bookingReferencestring
Trip reference of the order.
orderNumberstring
Echo of the order number.
amountnumber
The amount refunded.
manualRefundboolean
Echo of the flag.
paymentRefundStatusstringSpec
NONE, PARTIAL or COMPLETE: how much of the payment has been refunded.
secondPaymentRefundStatusstringUnverified
The spec doesn't describe it. Probably the same status for a second payment on the order.
auditDataAuditResponseVO
Includes traceId (one per token: log it) and authToken (redact it before logging).

When to use it

Who took the guest's paymentWhat to do
The platform, through its payment gatewayCall Refund with manualRefund: false (the default). Unverified
You, through your own payment providerRefund in your provider. You can register it here with manualRefund: true so the booking's payment record matches. Unverified
  • For a cancellation, refund the amount paid minus the penalty from Cancellation fee.
  • The spec doesn't say where to read orderNumber. The payment object in Get booking is the likely place. Unverified

After a refund

  • A REFUND webhook fires when a refund succeeds. Docs Accept it with a 2xx, like every webhook type. Verified See Webhooks.
  • Don't send the same refund again after a timeout. Wait for the REFUND webhook or check the booking first. Unverified

Errors

The spec documents no error schema and no status codes. Treat any non-2xx response as a failure and keep the raw body and the trace id. Spec

Service cancellation fee

The generic cancellation fee for a hotel service in a booking. Besides the fee, it returns the cancellation types the service supports and any related service with its own fee.

Client requests

Conversations attached to a booking. Ask for an amendment or a cancellation, raise a question or a complaint, reply, and reopen or close the thread. New requests and replies trigger a CLIENT_REQUEST webhook.