This section contains all the key information you need to know while using the REST API. You can find here how filtering, pagination, and sorting can be used but also how date fields, and header parameters work. It includes a list of all the error codes you can come across while using our API.

Besides this, we have created some flows on the most used scenarios. These flows define step by step how you can create a booking module or use the events from the REST API.

There is also a webhook available to push information to your system instead of using the REST API to pull information.

Host :

• Test/Acceptance: https://api-test.maxxton.net
• Production/Staging: https://api.maxxton.net

BasePath : /maxxton/v2 Schemes : HTTPS

Maxxton External APIs are secure RESTful web services and authentication(OAuth2) is required to access them, user will be authenticated based on the token passed in the request.

Generate access token

POST /maxxton/v2/authenticate

 
curl --location ‘https://api.maxxton.net/maxxton/v2/authenticate’ --header ‘Content-Type: application/x-www-form-urlencoded’ --header ‘locale: nl_NL’ --data-urlencode ‘grantType={grant type}’ --data-urlencode ‘clientId={client id}’ --data-urlencode ‘clientSecret={client secret}’ --data-urlencode ‘scope={concern code}’

Request body(x-www-form-urlencoded)

The responses that can be returned are:

Responses

After generating the token, the access token can be used by adding it to the header parameters with key: Authorization and value: {token_type} {access_token}

• The clientId and the clientSecret will be provided by Maxxton/Maxxton client as part of API credentials.
• Please contact the particular Maxxton client to request API credentials to access their Maxxton environment and data.
• Scope can be used for passing the concern parameter but scope is preferred as it is fully oauth2 compatible.

For more information: Login

The API costs are based on the number of requests per month, the first 750,000 requests per month(25,000 requests per day) are not charged. Subsequent requests are charged as per the API price calculator. The processes can be speeded up by making multiple API requests at the same time, this is called concurrent calls in the model. Concurrent calls have a bigger impact on the Maxxton API resources, therefore extra costs are charged.

Pricing-slider

Notes applicable to the API Pricing

• The number of concurrent calls is limited to the maximum number per IP, by default this is 15.
• The number of concurrent calls will be used as a logarithmic parameter in the pay-per-use model and will impact the charges on actual usage.
• The number of requests is not limited and will be charged based on actual usage.
• Costs only apply to the new Maxxton REST API.
• The number of requests only applies to the production API (api.maxxton.net).
• The acceptance (api-test.maxxton.net) API can be used free of charge, subject to adherence to the fair use policy.
• Fair use policy applies to both production and acceptance API.
• API Support is included for daily support questions
• Development of new features and project guidance/management are charged per hour.
• Clients can request new features to decrease the REST API usage. Maxxton will, commercially reasonable, develop new features on request to decrease API usage.

Fair Use Policy

On our API we do not have a fixed restriction on the number of API calls. However, a Fair Use Policy applies to the usage of the API.

Normal usage is permitted. Excessive usage is not permitted. Excessive usage means, the usage which has an impact on our server performance or impact on other customers who use the API.

Many calls contain filtering, this is a way to filter the output of the calls. In the REST documentation, it says filter parameter where this can be used. filtering means you can filter on any non-nested field in the output with the following features:

These are the operators you can use in the filtering of the filter:

Note: The above operators need to be encoded to work in some cases.

Pagination is used to divide large response into small response which leads minimizing the response time. General concept is separating a large page into small pages. Most of the Maxxton External API endpoints follow pagination. You can control the number of results returned in a single request by specifying the page number and page size. Page and Size are 2 request parameters that can be used with request to control pagination.

With every response, there are few parameters in response that gives information about the pagination followed in request.

Sorting is used to order the response based on the values of a particular field of the response. General concept is fetching a page/list of response in the ascending or descending order of the specified field. Sorting is possible in all the endpoints where pagination is supported.

This can be done by specifying the sort request parameter with the field name and order of descending, as follows: sort=fieldname,desc or sort=fieldname,asc

With every sorted response, there are few parameters under the section sort at the end of page that gives information about the sorting followed in request.

Following is the description of different date fields used in various domains of API endpoints.

Header parameters contain important meta-data related to the API request and response. These parameters can be used with Maxxton APIs to customize the behavior of the request and response. Below are the header parameters you can use:

Swagger enables the import of all endpoints into your preferred API tool based on the Open API specification, allowing for a comprehensive overview and streamlined integration. Additionally, the Swagger documentation provides a complete list of available endpoints.

Url: The Swagger UI Rest client

Location, Accommodation Type, Unit

Location: A location is a group of accommodation types at the same location which provides an array of accommodation types typically including entertainment and recreational activities. A location may contain one or multiple accommodation types.

Accommodation Type: An accommodation type is a group of similar units, where units are configured to define the type (Room, Bungalow, Chalet, etc.) and other configurations (Representation, Capacity, Cashflow, Rentability, Reservability, Amenities, etc.). An accommodation type may contain one or multiple units.

Unit: A unit is a room, group of rooms, or bungalow in which someone may live or stay. It can be a single room, bungalow, chalet, etc.

Diagrammatic representation of Location, Accommodation types, and Units:

Resources and Reserved Resources

In the Maxxton system, resources (items) are available in multiple types such as Accommodation type, add-on, or offers. These resources can be booked when creating a reservation, where a reserved resource is added to the reservation as a booked version of the actual resource. A resource is unique in the system and used across multiple reservations, while a reserved resource is unique to the reservation.

Diagrammatic representation of Resources and Reserved resources:

The Flows section provides a detailed breakdown of the most common integration processes for the REST API, offering step-by-step guidance on how to seamlessly incorporate API functionalities into your project. Users can gain a comprehensive understanding of the most common integration scenarios, enabling them to efficiently navigate and implement API interactions within their applications.

Any change (creation, deletion, or modification) made in any of the entities will generate events, which are stored and can be fetched using the Events endpoint. Below are the events generated with their description. The details of the entity along with the changes can be fetched through separate endpoints mentioned for every event type below.

Events are not logged for entity records that become invalid or inactive after a given date. For example, the validTo date in cashflowrule. In this case, no events will be logged for the cashflowrule entity after the respective validTo date of that cashflowrule is passed.

Events Generated

ACCOMMODATION_TYPE_EVENT

Any change made to the accommodation type, which includes creation, modification, or deletion of accommodation type or any of its entities like address, images, amenities, capacities etc. will generate an ACCOMMODATION_TYPE_EVENT. In case of an ACCOMMODATION_TYPE_EVENT, the entity id logged will be the resourceId of the accommodation type that was changed.

To refresh the data the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: maxxton/v2/accommodationtypes/{resourceId}/details

To refresh specific data following endpoints can be used:

• GET: maxxton/v2/accommodationtypes/{resourceId}
• GET: maxxton/v2/accommodationtypes/{resourceId}/capacities
• GET: maxxton/v2/accommodationtypes/{resourceId}/images
• GET: maxxton/v2/accommodationtypes/{resourceId}/amenitylinks

To refresh the data for multiple accommodation types at the same time the resourceId can be combined using the following endpoint:

• GET: /maxxton/v2/accommodationtypes?filter=resourceId:[resourceId1,resourceId2,resourceId3...]

ADDITION_EVENT

Any change made to the additions, which includes creation, modification, or deletion of an addition will generate an ADDITION_EVENT. The entity id logged will be the resourceId of the accommodation type, addition, or offer on which the addition was added.

To refresh the data the following endpoints can be used with the resourceId fetched from the event endpoint:

• GET: maxxton/v2/accommodationtypes/{resourceId}/additions
• GET: maxxton/v2/offers/{resourceId}/additions
• GET: maxxton/v2/accommodationtypes/additions?filter=resourceId:[resourceId1,resourceId2,resourceId3...]
• GET: maxxton/v2/offers/additions?filter=resourceId:[resourceId1,resourceId2,resourceId3...]

ADDON_EVENT

Any changes that include creation, modification, or deletion of extras or products will generate an ADDON_EVENT. The entity id logged will be the resourceId of the add-on that was changed.

To refresh the data the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: maxxton/v2/add-ons/{resourceId}

AVAILABILITY_EVENT

Changes in the availability of resources will generate an AVAILABILITY_EVENT. The event is created once the available is processed in the availability indexes and available from below defined endpoints. The following scenarios will generate an availability event:

• When the prices or availability of a certain accommodation type changes this will be processed in the availability index once running. When this is processed an availability event is created
• When the prices or rentability of an offer change this will be processed in the availability index once running. When this is processed an availability event is created for all the accommodation types for which this offer is applicable.
• When the last unit of an accommodation type is booked, it is removed from the availability index right away and an availability event is created near real-time.

The entity id logged will be the resourceId of the accommodation type whose availability was changed.

To refresh the data the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: maxxton/v2/accommodationtypes/availability

CUSTOMER_EVENT

Any change made to the customers, which includes creation, modification, or deletion of a customer or any of its fields will generate CUSTOMER_EVENT. The entity id logged will be the customerId of the customer that was changed.

To refresh the data the following endpoints can be used with the customerId fetched from the event endpoint:

• GET: maxxton/v2/customers/{customerId}
• GET: maxxton/v2/customers/{customerId}/communications
• GET: maxxton/v2/customers/{customerId}/files

To refresh the data for multiple customers at the same time the customerIds can be combined using the following endpoint:

• GET: maxxton/v2/customers?filter=customerId:[customerId1,customerId2,customerId3...]

The customer event also contains events about the merged customers by the deduplication script running in the Maxxton system. This is indicated by the entityAction MERGE and will provide the customer id which is removed in the oldEntityId field and the customer id where the data is merged to(the customerId it has become) in the entityId field.

Incase of changes to the loyalty status or loyalty transactions also a customer event is generated. To refresh this data the following endpoints can be used:

GET: maxxton/v2/customers/{customerId}/loyalty

GET: maxxton/v2/customerstatus?filter=customerId:{customerId}

DISTRIBUTIONCHANNEL_EVENT

Any change made to a distribution channel, which includes the creation, modification, or deletion of a distribution channel or any of its fields will generate DISTRIBUTIONCHANNEL_EVENT. The entity id logged will be the distributionChannelId of the distribution channel that was changed.

To refresh the data the following endpoints can be used with the distributionChannelId fetched from the event endpoint:

• GET: maxxton/v2/distributionchannels/{distributionChannelId}

To refresh the data for multiple distribution channels at the same time the distributionChannelIds can be combined using the following endpoint:

• `GET: maxxton/v2/distributionchannels?filter=distributionChannelId:[distributionChannelId1,distributionChannelId2,distributionChannelId3…​

IMPLY_EVENT

Any change made to the implies, which includes creation, modification, or deletion of the imply of an accommodation type, unit, add-on, or offer will generate an IMPLY_EVENT. The entity ID logged will be the resourceId of the accommodation type, add-on, or offer. In case of a unit, it will be unitId. Based on the entityType, it can be identified if it’s an accommodation type, unit, add-on, or offer.

To refresh the data, the following endpoints can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/accommodationtypes/{resourceId}/implies
• GET: /maxxton/v2/add-ons/{resourceId}/implies
• GET: /maxxton/v2/offers/{resourceId}/implies
• GET: /maxxton/v2/units/{unitId}/implies

OFFER_EVENT

Any change made to the offers, which includes creation, modification, or deletion will generate an OFFER_EVENT. The entity ID logged will be the resourceId of the offer that was changed.

To refresh the data, the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/offers/{resourceId}
• GET: /maxxton/v2/offers?filter=resourceId:[resourceId1,resourceId2,resourceId3,…]

OWNER_EVENT

Any change made to the owners, which includes creation, modification, or deletion of an owner or any of its fields will generate an OWNER_EVENT. The entity ID logged will be the ownerId of the owner that was changed.

To refresh the data, the following endpoints can be used with the ownerId fetched from the event endpoint:

• GET: /maxxton/v2/owners/{ownerId}

To refresh the data for multiple owners at the same time, the ownerIds can be combined using the following endpoint:

• GET: /maxxton/v2/owners?filter=ownerId:[ownerId1,ownerId2,ownerId3,…]

RATE_EVENT

Any change made to the rates, which includes creation, modification, or deletion of the rate of an accommodation type, add-on, or offer will generate a RATE_EVENT. The entity ID logged will be the resourceId of the accommodation type or offer. Based on the entityType, it can be identified if it’s an accommodation type or offer.

To refresh the data, the following endpoints can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/accommodationtype/{resourceId}/rates
• GET: /maxxton/v2/offers/{resourceId}/rates

RENTABILITY_EVENT

Any change made to the rentability, which includes creation, modification, or deletion of the rentability of an accommodation type or offer will generate a RENTABILITY_EVENT. The entity ID logged will be the resourceId of the accommodation type, add-on, or offer. Based on the entityType, it can be identified if it’s an accommodation type or offer.

To refresh the data, the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/rentability/config?resourceId={resourceId}
• GET: /maxxton/v2/rentability/stays?resourceId={resourceId}&distributionChannelId={distributionchannelId}

RESERVABILITY_EVENT

Any change made to the reservability, which includes creation, modification, or deletion in the reservability of an accommodation type, unit, add-on, or offer will generate a RESERVABILITY_EVENT. The entity ID logged will be the resourceId of the accommodation type, add-on, or offer. In case of a unit, it will be unitId. Based on the entityType, it can be identified if it’s an accommodation type, add-on, offer, or unit.

To refresh the data, the following endpoints can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/resourcereservability?resourceId={resourceId}
• GET: /maxxton/v2/unitreservability?unitId={unitId}

RESERVATION_EVENT

Any change made to the reservations, which includes creation, modification, or deletion in the reservation will generate a RESERVATION_EVENT. The entity ID logged will be the reservationId of the reservation that was changed.

To refresh the data, the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/reservations/{reservationId}/details

To refresh specific data, the following endpoints can be used:

• GET: /maxxton/v2/reservations/{reservationId}
• GET: /maxxton/v2/reservations/{reservationId}/preferences
• GET: /maxxton/v2/reservations/{reservationId}/bills
• GET: /maxxton/v2/reservations/{reservationId}/content
• GET: /maxxton/v2/reservations/{reservationId}/subjects

To refresh the data for multiple reservations at the same time, the reservationIds can be combined using the following endpoint:

• GET: /maxxton/v2/reservations?filter=reservationId:[reservationId1,reservationId2,reservationId3,…]

RESORT_EVENT

Any change made to the locations, which includes creation, modification, or deletion of the location will generate a RESORT_EVENT. The entity ID logged will be the locationId of the location that was changed.

To refresh the data, the following endpoint can be used with the locationId fetched from the event endpoint:

• GET: /maxxton/v2/locations/{locationId}/details

To refresh specific data, the following endpoints can be used:

• GET: /maxxton/v2/locations/{locationId}
• GET: /maxxton/v2/locations/{locationId}/amenitylinks
• GET: /maxxton/v2/locations/{locationId}/subjects

To refresh the data for multiple locations at the same time, the locationIds can be combined using the following endpoint:

• GET: /maxxton/v2/locations?filter=locationId:[locationId1,locationId2,locationId3,…]

UNIT_EVENT

Any change made to the units, which includes creation, modification, or deletion of the unit will generate a UNIT_EVENT. The entity ID logged will be the unitId of the unit that was changed.

To refresh the data, the following endpoint can be used with the unitId fetched from the event endpoint:

• GET: /maxxton/v2/units/{unitId}/details

To refresh specific data, the following endpoints can be used:

• GET: /maxxton/v2/units/{unitId}
• GET: /maxxton/v2/units/{unitId}/capacities
• GET: /maxxton/v2/units/{unitId}/amenitylinks

To refresh the data for multiple units at the same time, the unitIds can be combined using the following endpoint:

• GET: /maxxton/v2/units?filter=unitId:[unitId1,unitId2,unitId3,…]

ALLOTMENT_EVENT

Any change made to the allotments, which includes creation, modification, or deletion of the allotment will generate an ALLOTMENT_EVENT. The entity ID logged will be the resourceId of the accommodation type whose allotment was changed.

To refresh the data, the following endpoint can be used with the resourceId fetched from the event endpoint:

• GET: /maxxton/v2/accommodationtypes/{resourceId}/allotments

To refresh the data for multiple accommodation types at the same time, the resourceIds can be combined using the following endpoint:

• GET: /maxxton/v2/allotments?filter=resourceId:[resourceId1,resourceId2,resourceId3,…]

A reservation is basically used for booking or reserving an accommodation type by a guest. Reservations include reserving a particular type of accommodation type for a particular guest for a given period of time.

1) Availability and Prices

There are 2 options to fetch the availability. One is to call the Maxxton API realtime and show it on the website, this also provides filter possibilities. Option 2 is to fetch all possible availabilities and prices and populate your own availability and price index to search offline on the external application.

Option 1:

Using the availability search you can search what accommodation types are available and for which periods. This endpoint also makes it possible to filter the search results and provide you with all possible filter options.

There are two search endpoints for different purposes:

• POST /maxxton/v2/accommodationtypes/search
• POST /maxxton/v2/accommodationtypes/arrivalrangesearch

Check the accommodation type search and arrival_range_search endpoints for details.

Option 2:

Using the availability call you can fetch all available stays and prices for all accommodation types. This endpoint is usually used to fill a dedicated availability/price index at the third party side.

• POST /maxxton/v2/accommodationtypes/availability

Check the accommodation type availability endpoint for details.

Optional: In case you also would like to fetch all the mandatory costs (implies) to add this to your index, the following call can be used:

• POST /maxxton/v2/accommodationtypes/availability/implies

Check the accommodation type availability implies endpoint for details.

2) Accommodation Types Configuration/Master Data

Using the accommodation type endpoints you can get the accommodation type configuration i.e. translatable name and descriptions, units, amenities, images, etc. It is also possible to filter the response.

There are multiple endpoints available for different purposes, below two will contain most information regarding accommodation types and units:

• GET /maxxton/v2/accommodationtypes/{resourceId}/details
• GET /maxxton/v2/units/{unitId}/details

If only specific data is needed the following endpoints can be used:

• GET /maxxton/v2/accommodationtypes
• GET /maxxton/v2/units
• GET /maxxton/v2/accommodationtypes/{resourceId}/amenitylinks
• GET /maxxton/v2/accommodationtypes/{resourceId}/images

Check the full list of accommodation type and related endpoints here.

3) Reservation Proposal

• POST: https://api.maxxton.net/maxxton/v2/reservations/proposals

When a possibility is chosen based on the search endpoints, a reservation proposal can be created. A reservation proposal provides the proposal on reservation costs for the specified criteria in the request and doesn't create an actual reservation in the system.

It is used to validate if the accommodation type is available for the specified arrival date and duration.

The reservation id and reservation number are not generated since no reservation is created. The proposal also provides you with all possible additions that can be added in the reservation. It also includes installments as per the reservation bill.

This proposal can be used multiple times until you are fine with the reservation, nothing is saved in our system, and no reservation costs apply by using this.

Check the reservation proposal endpoint for details.

4) New Reservation

• POST: https://api.maxxton.net/maxxton/v2/reservations

When the reservation is correct and you have checked this with the proposal call, you can use the new reservation endpoint to create an actual reservation.

At this moment, the new reservation is stored in our system and the reservation id and reservation number are generated.

Once the request is sent by the user, the request is validated as per the availability of the resource for which the reservation needs to be created. The mandatory parameters that need to be passed in the new reservation request are as follows:

• accommodationTypes: the details of the accommodation type on which reservation is to be made
  • duration: the duration for which a user wants to make a reservation and the duration should be passed in days ex: 7.
  • resourceId: unique id associated with the accommodation type.
  • subjects: details related to the subjects who will come for a stay in an accommodation type for whom the reservation is to be created
    • persons: details related to the persons for whom the accommodation type is booked in the reservation.
      • age: age of the person
      • quantity: total number of persons for whom the accommodation type is booked in the reservation.
• categoryCode: unique code associated with reservation category.
• distributionChannelCode: unique code associated with the distribution channel.
• customer: details of the guest doing the booking. Or, you can use customerId field instead of customer in case you have customerId of the guest who is doing the booking.

If the resource is available as per the request criteria, then the reservation will be created successfully, and the status of the reservation can be provisional, optional, quotation, or request reservation.

Check the new reservation endpoint for details.

5) Update Reservation

The reservation status can be updated to different status using:

• PUT: https://api.maxxton.net/maxxton/v2/reservations/{reservationId}

The status which can be updated to different status. Please refer to below status chart:

• QUOTATION(-5) -> CONFIRM(will result in PROVISIONAL(12) or DEFINITIVE(21)), DECLINE(-10)
• OPTIONAL(11) -> CONFIRM(will result in PROVISIONAL(12) or DEFINITIVE(21)), DECLINE(-10)
• REQUEST(10)->DECLINE(-10), CONFIRM(will result in PROVISIONAL(12) or DEFINITIVE(21))
• PROVISIONAL(12) -> CANCEL(-12), DECLINE(-10)
• DEFINITIVE(21)->CANCEL(-12), CHECKED_IN(31)
• CHECKED_IN(31)->CHECKED_OUT(41).

The user can change the status of the reservation as per the above status flow specified.

It's also possible to update the expectedArrivalDateTime and expectedDepartureDateTime, the value should be passed in the below format,

'YYYY-MM-DDThh:mm:ss'

The above fields are mainly used by the receptionist of the location, by the maintenance department, and housekeeping.

Check the update reservation endpoint for details.

6) Reservation Status Flow Overview

After creating a reservation it starts with the INIT (an initial reservation) status. After completing the reservation, having added a customer and some add-ons, there are multiple options. We can update it to DELETED(these reservations are removed regularly), to OPTIONAL(which is a temporary confirmation), or PROVISIONAL(a confirmed reservation without a payment). Both OPTIONAL and PROVISIONAL get a reservation number assigned. This means they may no longer be deleted from the system, for financial reasons.

Reservation starts with OPTIONAL, QUOTATION, PROVISIONAL, or DEFINITVE status when it is confirmed through the API.

OPTIONAL: will go to EXPIRED if not confirmed (after x number of hours/days based on configuration) or to PROVISIONAL/DEFINITIVE based on the API user configuration settings if confirmed. With this status, the accommodation type price and availability are guaranteed for the reservation.

QUOTATION: will go to the EXPIRED if not confirmed after x number of hours/days based on configuration or to PROVISIONAL/DEFINITIVE based on API user if confirmed. With this status, the accommodation type rates are guaranteed for the reservation period and not the availability. So, some other guests can also book the reservation and then it is no longer available to the guest who created a QUOTATION reservation.

PROVISIONAL: A confirmed booking without a payment.

DEFINITIVE: If a payment is made(partial or full), a PROVISIONAL reservation will be changed to DEFINITIVE. When the guest arrives it will change to CHECKED_IN and finally to CHECKED_OUT when the guest leaves.

If a guest decides not to use the reservation, it can be changed from PROVISIONAL to DECLINED or to CANCELLED and from DEFINITIVE to CANCELLED.

DECLINED: There are no costs for the guest and the reservation is no longer available.

CANCELLED: It implies that some sort of payment is involved. That is why DEFINITIVE can only go to CANCELLED(since something was paid already). From CANCELLED it can go to DEF_CANCELLED(if the guest decides to cancel absolutely), or back to either PROVISIONAL or DEFINITIVE (depending on payments made) if the guest opts for reservation again.

Maxxton works using a DTAP (Development, Testing, Acceptance, Production) approach. For this, there are 4 environments available, and the code is promoted from the left to the right. The staging is not available for all clients. In case no staging is available, the test can be used.

The development environment is not externally available and only available to the Maxxton developers.

Both staging and production environments use the same API URLs because they use the same infrastructure, with the difference that the database used is a test/staging database on staging.

Environment Refresh

The Test environment can be refreshed with production data. In this case, all test environment data will be overridden with the data from the production environment, including the API users. For security reasons, the API keys are excluded, and the test API keys that existed before the refresh are kept during the refresh process. This means the API keys from the production and test environment will always be different and never overridden. However, the API users are the same. In case no API user is available on the production environment, the API key on the test environment is removed by the refresh process. This means after a refresh, users who don't have access to the production environment will also not have access to the test environment.

This can result in a scenario where it will no longer be possible to login to the test environment. This can be solved by creating a new API user and API key after the refresh process is finished. If the user already existed on the production environment and no API key was available on the test environment, a new API key has to be generated as well to gain access. Contact the Maxxton client to provide you with new API details if necessary.

Maxxton is using Worldline as a default PSP (Payment service provider). Because of this, the payments can be automatically added to a reservation made in the Maxxton system using an integration that is already in place, however, to do this a couple of additional parameters are needed.

The integration works as follows:

Recommended option: The flow 1 in the above diagram is the redirect URL. This can be generated from the Maxxton REST API by using the Reservation payment link endpoint. The endpoint will automatically provide the url to the correct Ingenico platform(Ingenico direct or the legacy version of Ingenico). The url provided from the response can be used in the website or application created by the company that is creating the booking module or website.

Alternative option(Legacy): Previously, this payment link had to be created manually. Below provides the URL for the legacy Worldline platform (Non Worldline direct), this is not needed if you use the above endpoint to generate the payment link:Incase you would like to integrate directly with Worldline direct. The Worldline direct documentation can be found here.

1. POST https://secure.ogone.com/ncol/prod/orderstandard_utf8.asp
2. POST request
   1. Headers: Content-Type: application/x-www-form-urlencoded
   2. Request body (key-value pair):
      1. PSPID: ClientPSPID //Worldline PSPID to use
      2. orderID: 00019026850000_827efb46dc7bb2f //the order id should have the following structure: reservationNumber_anyRandomNumber
      3. amount: 1234 //the amount to be paid in the below-defined currency in cents(for example 12,35 should be defined as 1235)
      4. currency: EUR //currency of the payment
      5. language: nl //The language the Worldline Hosted Payment Page is displayed to your customer. The value is a combination of ISO 639-1 (language) and ISO 3166-1 (country) for example: nl_NL, en_US, fr_FR
      6. EMAIL: customer@maxxton.com //email of the customer
      7. SHASign: 0b105725955aa9e0cba8d9906ccd64d66b0ca422 //see Worldline backoffice how this is created and what needs to be used here
      8. accepturl: https://book.maxxton.com/reservation/success //URL where the customer should be redirected to in case of a successful payment
      9. declineurl: https://book.maxxton.com/reservation/cancel //URL where the customer should be redirected to in case of a declined payment
      10. exceptionurl: https://book.maxxton.com/reservation/cancel //URL where the customer should be redirected to in case of a failed payment
      11. cancelurl: https://book.maxxton.com/reservation/cancel //URL where the customer should be redirected to in case of a canceled payment
      12. PARAMPLUS: distributionchannelId%3D51142%26reservationId%3D4181444%26employeeId%3D80041%26concernId%3D22 //mandatory parameters which will be used by Maxxton to process the payment on the proper reservation.
          1. a) distributionchannelId: id of the distribution channel where the reservation is created for, this can be found in the response of the reservation confirm call
          2. b) reservationId: id of the reservation that was just created to make the payment for, this can be found in the response of the reservation confirm call
          3. c) employeeId: id of the employee which should add the payment in the Maxxton system, this can be found in the response "client_id" of the REST API authentication call
          4. d) concernId: id of the concern/environment of the Maxton client, this can be found in the response "concern_id" of the REST API authentication call
      13. TP: https://book.maxxton.com/ingenico/template.html //the URL to the Worldline template to be used, this is optional.
3. This is the redirect from the Worldline hosted payment page to the website, see Worldline documentation for all possible parameters. This can be used by the booking module or website to provide feedback that the payment has been processed. For Worldline Direct you have to call the Worldline hosted checkout status Endpoint to fetch the status. This can be done using this endpoint. The "hostedCheckoutId" to provide is returned from the redirect URL (when using Reservation payment link endpoint you can add this in the "returnUrl" parameter) of Worldline hosted payment page to your website. The "merchantId" is the PSPId used for the payment. For the Worldline legacy platform: In case using the Maxxton Reservation payment link endpoint this can be provided in the fields (acceptUrl, cancelUrl, exceptionUrl, declineUrl).
4. The asynchronous callback from Worldline to Maxxton. There is no additional development needed here and this will work right away if the correct structure for the redirect URL (number 1) is used. In the Worldline backoffice the "URL of the merchant's post-payment page" should be configured and point to Maxxton (this is already configured for existing Maxxton clients using Worldline most of the time).

Introduction

The webhook solution is integrated into Maxxton Software's Integration Manager and will push data when certain configured data changes are triggered. Unlike the REST API, webhooks cannot be polled but will push data to the subscribed endpoint. Maxxton’s webhook implementation follows standard webhook guidelines. The data structures used are the same as those for the REST API, meaning the REST API documentation applies, and any adjustments made to the REST API will also apply to the webhooks.

Concept

There are three main concepts in the Maxxton webhook system:

1. Context: High-level entities in the Maxxton system, such as reservations, determine the context for the events and data that can be configured in the webhook request.
2. Events: Events that trigger the webhook (e.g., a change in reservation status).
3. Data: The actual data structure (fields) that are included in the webhook request.

How the Webhook Works

1. You configure your webhook in the Maxxton Software Integration Manager.
2. Once enabled, if any of the entities/data configured as a trigger is changed (i.e., there is new, changed, or removed data in the respective entity), the webhook will be triggered.
3. The webhook engine is triggered, and if the change meets the configured events, it will initiate a request.
4. For every change, the relevant data is fetched from the REST API. After that, the webhook container, which includes all the data, is created.
5. Optionally, the receiving endpoints may have authentication. If authentication is configured, the request will include authentication details or request a valid token first.
6. The webhook container, including all the data, is then pushed to the external URL configured in the webhook.
7. The receiving system (the webhook subscriber) can then process the data further.

Request Structure

Every webhook request will have the following structure:

 
{
    "notificationId": "2342040", // unique id of the webhook request
    "webhookId": 1, // unique id of the configured webhook
    "webhookName": "Maxxton test service", // webhook name as configured in Maxxton software integration manager
    "eventOccurred": "2024-07-31T08:39:44.709527Z", // date and time when the event occurred
    "sentDate": "2024-07-31T08:39:46.203144Z", // the date and time when the webhook request was sent out to push the event
    "type": "reservation.status.changed", // type of event to identify what event triggered the webhook
    "data": { // data structure as configured for this webhook
        ...
    }
}

Available Context & Events

Events are organized by context and type. The context determines the available events and data for the webhook request. The specific event that triggered the webhook request can be identified by the “type” field in the webhook request. The following contexts and events are currently supported:

Reservations

• Status Change (type: reservation.status_change): The status of the reservation changed (e.g., provisional, definitive, or canceled).
• Stay Period Change (type: reservation.stay_period_change): The arrival and/or departure date of the reservation changed.
• Bill Change (type: reservation.bill_change): There was a change to the total bill amount for the customer, paying customer, or agent.
• Payment Received (type: reservation.payment_received): Triggered when a payment is received.
• Refund Given (type: reservation.refund_given): Triggered when a refund is issued.

Available Data

The data available depends on the selected context. All data is populated through the REST API, and the data structure is the same as that of the REST API. For specific field and entity descriptions, please refer to the REST API documentation.

Example Data for Webhooks

Security

Authentication

The endpoint used to send the webhook requests can optionally require authentication. The following authentication types are supported:

• Basic Authentication:plaintextCopy codeAuthorization: Basic {credentials}
• OAuth 2.0 (Client Credential Grant):plaintextCopy codeAuthorization: Bearer {token}
• No Authentication: The endpoint is freely accessible from the internet or has IP whitelisting applied.

Sender Validation

The receiving party can use a webhook secret to verify that the delivered message is from Maxxton. During webhook setup, the user can provide a secret token, which must be stored securely on their server. Each incoming webhook payload must be validated against the token.

Maxxton will use HMAC-SHA256 (Hash-based Message Authentication Code) to generate a hash signature. The signature is generated using the payload content and the provided webhook secret. The signature is sent in the webhook-signature HTTP header.

Example:

 
codewebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Access & Usage

Webhooks can be configured through the Maxxton Software Integration Manager under the Webhooks tab. Access to this module is required to set up new webhooks or view statistics. Please note that Maxxton does not grant access to this module; it is managed by our clients, who are responsible for configuring the webhooks.

To receive requests, you do not need access to Maxxton software.

API Pricing and Fair Use Policies apply to the usage of webhooks.

Support

If you have questions, please contact the party who configured the webhooks for you (usually the Maxxton client). In case of technical queries, a ticket can be created in the Maxxton ticket system or an email can be sent to api@maxxton.com.

In case of questions, feedback, or issues you can contact the Maxxton API support by creating a ticket through the Maxxton ticket system (you need an account for this) or reach out to our support team by using the email address below:

Contact Email: api@maxxton.com

Ticket system: https://support.maxxton.com