Booking API

Create a new hotel booking from a room BookingCode returned by the Search API.

Endpoint

POST {BaseURL}/api/booking/book

Property	Value
URI	`{BaseURL}/api/booking/book`
Method	`POST`
Content-Type	`application/json`

Authorization

Send the Basic Auth header described in Authentication.

Request Parameters

Important: RoomBookingCodes must contain between 1 and 32 unique GUIDs returned by Search. Use codes from the same search context and hotel, and do not reuse an expired BookingCode. MescoGo validates that the selected rooms can be booked together. For broad integration compatibility, sending one RoomBookingCodes value is recommended.

Parameter	Type	Description
`RoomBookingCodes`	GUID list	1–32 unique room booking codes returned by Search. Codes must belong to the same search context and hotel.
`CustomerDetails`	object list	Customer information. The adult/child distribution and child ages must match the occupancy sent in the corresponding Search request.
`ClientReferenceId`	string	API client system reference ID. Recommended for request/response correlation.
`BookingReferenceId`	string	API client system booking, PNR, order, or reservation reference. Can be empty if not applicable.
`TotalFare`	decimal	Total price for the selected rooms. Must match the selected search result.
`EmailId`	string	Email id of the first person in the customer list
`PhoneNumber`	string	Required. Must be a valid phone number and max 20 characters.
`BookingType`	string	Fixed booking mode. Send `Voucher`. This is the only supported value and indicates a confirmed booking/voucher flow.
`PaymentMode`	string	`Limit` or `NewCard`. Default is `Limit`
`PaymentInfo`	object	Customer payment info (required if PaymentMode is `NewCard`)
`BillingAmount`	decimal	Total amount to bill. It must match `TotalFare`.
`BillingCurrency`	string	Required. Send USD; it must match the currency returned by Search.
`CardHolderAddress`	object	Customer card address (required if PaymentMode is `NewCard`)

Reference Identifiers Note

ClientReferenceId and BookingReferenceId are optional API client-supplied reference values.

ClientReferenceId: API client system value recommended for request/response correlation. If provided, the same value is returned in the success response.
BookingReferenceId: API client system reservation, order, PNR, booking, or reference number. It can be empty when no separate reference exists.

These fields are correlation values. They do not provide an idempotency or persistence guarantee.

How To Populate These Fields

ClientReferenceId should identify the booking request in your system.
Recommended values: request number, cart/order number, CRM correlation ID, or session-based booking attempt ID.
Example value: CLIENT-EXAMPLE-001.
BookingReferenceId can be used when a reservation, order, PNR, or booking reference already exists in your system before calling MescoGo.
If your final reservation number is created only after confirmation, send an empty string.
These values are supplied in the request; they are not obtained from a MescoGo endpoint in advance.

BookingType

BookingType is fixed for this API. Send Voucher; do not send another value.

PaymentMode Values

Value	Description
`Limit`	Use the payment arrangement assigned to your account when no complete card details are sent.
`NewCard`	Pay with the card details in `PaymentInfo`.

Payment Notes

For account-based payment, send PaymentMode = "Limit" without PaymentInfo or CardHolderAddress.
To pay with card, send PaymentMode = "NewCard" with complete PaymentInfo and CardHolderAddress.
If complete card information is sent, the request is processed as a card payment.
Do not send partial card information. BillingAmount and TotalFare must represent the same total amount.

Card data security

PaymentInfo contains sensitive card data. Send it only over HTTPS, never log or store the full card number or CVV, never put card data in a URL, and follow the security and PCI DSS requirements applicable to your payment integration. Do not include real card data in documentation, tests, or support tickets.

CustomerDetails

Parameter	Type	Description
`Title`	string	Customer title
`FirstName`	string	Customer firstname
`LastName`	string	Customer last name
`BirthDate`	string	Customer birth date. Use `YYYY-MM-DD` where possible.
`Type`	string	`Adult` for adult guests, `Child` for child guests

PaymentInfo

Parameter	Type	Description
`CvvNumber`	string	Customer card cvv number
`CardNumber`	string	Customer card number
`CardExpirationMonth`	string	Customer card expiration month
`CardExpirationYear`	string	Customer card expiration year
`CardHolderFirstName`	string	Customer card first name
`CardHolderLastName`	string	Customer card last name

CardHolderAddress

Parameter	Type	Description
`AddressLine1`	string	Address 1
`AddressLine2`	string	Address 2
`City`	string	Customer city
`PostalCode`	string	Customer postal code
`CountryCode`	string	Customer country code

Example Requests

Example data note: The identifiers, guest details, dates, contact values, and amounts in the request examples below are synthetic and illustrative. Do not copy them as live booking or customer data.

Example Request - Account Payment

{
  "RoomBookingCodes": ["00000000-0000-4000-8000-000000000003"],
  "CustomerDetails": [
    {
      "Title": "Mr",
      "FirstName": "Sample",
      "LastName": "Guest",
      "BirthDate": "1990-01-01",
      "Type": "Adult"
    }
  ],
  "ClientReferenceId": "CLIENT-EXAMPLE-001",
  "BookingReferenceId": "00000000-0000-4000-8000-000000000004",
  "TotalFare": 100.0,
  "EmailId": "guest@example.com",
  "PhoneNumber": "+10000000000",
  "BookingType": "Voucher",
  "PaymentMode": "Limit",
  "BillingAmount": 100.0,
  "BillingCurrency": "USD"
}

Example Request - Card Payment

{
  "RoomBookingCodes": ["00000000-0000-4000-8000-000000000003"],
  "CustomerDetails": [
    {
      "Title": "Mr",
      "FirstName": "Sample",
      "LastName": "Guest",
      "BirthDate": "1990-01-01",
      "Type": "Adult"
    }
  ],
  "ClientReferenceId": "CLIENT-EXAMPLE-001",
  "BookingReferenceId": "00000000-0000-4000-8000-000000000004",
  "TotalFare": 100.0,
  "EmailId": "guest@example.com",
  "PhoneNumber": "+10000000000",
  "BookingType": "Voucher",
  "PaymentMode": "NewCard",
  "BillingAmount": 100.0,
  "BillingCurrency": "USD",
  "PaymentInfo": {
    "CvvNumber": "<cvv-number>",
    "CardNumber": "<card-number>",
    "CardExpirationMonth": "<card-expiration-month>",
    "CardExpirationYear": "<card-expiration-year>",
    "CardHolderFirstName": "Sample",
    "CardHolderLastName": "Guest"
  },
  "CardHolderAddress": {
    "AddressLine1": "100 Example Avenue",
    "AddressLine2": "Example Suite",
    "City": "Sample City",
    "PostalCode": "00000",
    "CountryCode": "US"
  }
}

Success Response

Example data note: The identifiers in this response are synthetic and illustrative. Do not copy them as live booking data.

{
  "Status": {
    "Code": 200,
    "Description": "Successful"
  },
  "ClientReferenceId": "CLIENT-EXAMPLE-001",
  "ConfirmationNumber": "00000000-0000-4000-8000-000000000001"
}

Error cases

Business validation errors return a Status object.

Payment information not found

{
  "Status": {
    "Code": 404,
    "Description": "Payment Information Not Found"
  }
}

Account payment limit unavailable

{
  "Status": {
    "Code": 404,
    "Description": "<description>"
  }
}

Processing error

{
  "StatusCode": 500,
  "Reason": "<reason-phrase>",
  "Error": "<error-message>",
  "ErrorDetails": "<optional-details>"
}

Validation and business errors may be returned with HTTP 200 and a body Status.Code such as 404, 409, or 500. A successful booking is identified by both Status.Code = 200 and a non-empty ConfirmationNumber.

Every failed response body must be evaluated independently of the HTTP status. When these fields are present, use them as follows:

Field	Meaning
`RequiresNewSearch`	The selected search result should not be reused; perform a new search before another booking attempt.
`RequiresReconciliation`	The booking outcome needs to be checked before any retry.
`RetryAllowed`	Whether the same operation may be attempted again according to the response.

If RequiresReconciliation is true or RetryAllowed is false, do not automatically retry the same request. A conflict response can have this shape regardless of the HTTP status:

{
  "StatusCode": 409,
  "Reason": "<reason-phrase>",
  "Error": "<error-message>",
  "RequiresNewSearch": true,
  "RequiresReconciliation": false,
  "RetryAllowed": false
}

Endpoint​

Authorization​

Request Parameters​

Reference Identifiers Note​

How To Populate These Fields​

BookingType​

PaymentMode Values​

Payment Notes​

Card data security​

CustomerDetails​

PaymentInfo​

CardHolderAddress​

Example Requests​

Example Request - Account Payment​

Example Request - Card Payment​

Success Response​

Error cases​

Payment information not found​

Account payment limit unavailable​

Processing error​