Articles in this section

RezdyConnect specification

Avatar
Dusan Zahoransky
Updated
Follow

Please read RezdyConnect Overview if you haven't done it yet, before continuing.

 

 

Steps for RezdyConnect integration

  1. Setup your products on Rezdy - RezdyConnect allows you to synchronize availability and bookings with your system, however you still need to have copies of your products setup on Rezdy.

  2. Select a booking strategy - Choose between 1-step or 2-step booking strategy

  3. Implement REST endpoints - Implement endpoints that Rezdy will call to pull availability and pricing from, and push bookings to.

  4. Setup your RezdyConnect URLs - manually setup the URLs of your endpoints for each of your products on Rezdy

  5. Optionally use Webhooks or Rezdy API to fine tune your integration - To enhance your integration with additional features, setup webhooks to receive events like booking updates, or use other Rezdy API services to update or cancel your bookings on Rezdy, update a specific session price or availability, etc.

 

 

1- Setup your products on Rezdy

Assuming that your supplier account on Rezdy is ready, you can either manually create products or use the Create Product service. The service is part of the Rezdy API and allows you to create products with description and other details and also to upload product images.

 

2- Select a booking strategy

There are currently 2 common strategies to implement the integration:

  • 1-step booking strategy - requires implementation of availability and booking endpoints, and optionally cancellation endpoint
  • 2-steps booking strategy (recommended) - requires implementation of availability, reservation, confirmation and cancellation endpoints

1-step booking strategy

Flow for 1-step booking strategy:

  1. Once a day, Rezdy calls GET /availability to refresh the next 6 month's availability for each product (6 x 1 month)
  2. Rezdy shows cached sessions to customers and agents in general searches
  3. When the customer or agent selects a specific session, Rezdy calls GET /availability to refresh that single time's availability and pricing
  4. If there are seats available, checkout is possible
  5. During the checkout process, Rezdy will:
    1. GET /availability to refresh that single time's availability
    2. Process payment (when applicable)
    3. Create the booking on Rezdy (or external agent system)
  6. Rezdy then calls the product's POST /booking endpoint to create the booking in the supplier system

 

There are disadvantages using this strategy:

  • customer payment is processed before the booking is created in your system, which may lead to booking inconsistency. This is especially risky in case of credit card payment on the agent side.
  • In some situations there might be no evidence of the failed booking in your system (e.g. internal failure of supplier system). We will generate alerts by email which will need to be dealt with manually.

 

 2-steps booking strategy (recommended)

We recommend using this strategy, because it minimizes the booking integrity issues between Rezdy and external systems.

Rezdy will use availability endpoint to refresh availability and pricing. Once a customer submits a booking to Rezdy, Rezdy will ensure the availability in your system. Rezdy will then send a booking in 'PROCESSING' state to your system by calling the Reservation endpoint. If that call fails, we stop the booking process.

Otherwise, we create booking internally and charge the customer. If the charge fails, we cancel the booking internally and call your Cancellation endpoint. If no error occur during the booking flow, we call the Confirmation endpoint.

Screen&requests flow for 2-steps booking strategy:

  1. Rezdy shows cached sessions to a customer
  2. Customer selects a session
  3. Rezdy calls the product's Availability endpoint to refresh the session availability and pricing
  4. If there are seats available, customer can proceed with the booking
  5. Booking is created on Rezdy
  6. Rezdy calls the product's Booking Reservation Endpoint
  7. If error response is received, the booking will be deleted and customer will be notified
  8. The customer's payment is processed
  9. If any error occur, the booking will be deleted and Booking Cancellation Endpoint will be called
  10. Otherwise Rezdy calls Booking Confirmation Endpoint

 

3- Implement REST endpoints

Product code mapping

Rezdy product codes are used when making availability or booking call, so you can either:

  • Map Rezdy product codes to your own internal codes in your RezdyConnect implementation
  • Specify your internal codes as a part of the endpoints URLs for each product using query parameters, Rezdy will preserve the parameters, that you setup for the endpoints, when constructing the URL for the calls.

 

Events triggering endpoint calls

There are several events that can result in a call to the external endpoints. Calls to the booking endpoints are based on the booking strategy you implement.

Availability calls to refresh availability and pricing will occur when:

  1. Daily batch update - load the next 6 months availability for each product, in 1-month intervals
  2. Customer selects a specific session and starts a checkout process - refresh of the specific session, start and end time are same
  3. Product scheduling settings are updated - one week availability synchronization to test the endpoint

Below is an example of the start and end time parameters for batch availability refresh for 6 months. Rezdy will do separate calls for each month, start time is the 00:00 of the first day of the month, end time is 23:59:59 last day of the month of the suppliers timezone setup on Rezdy. Exception is the first month, when the start time is set to the current time. Past sessions are never refreshed. In the example batch starts on Mar 13 14:20:00 UTC, when supplier's timezone is UTC+14.

startTime - endTime: Mar 13 14:20:00 UTC - Mar 31 12:59:59 UTC
startTime - endTime: Mar 31 13:00:00 UTC - Apr 30 13:59:59 UTC
startTime - endTime: Apr 30 14:00:00 UTC - May 31 13:59:59 UTC
startTime - endTime: May 31 14:00:00 UTC - Jun 30 13:59:59 UTC
startTime - endTime: Jun 30 14:00:00 UTC - Jul 31 13:59:59 UTC
startTime - endTime: Jul 31 14:00:00 UTC - Aug 31 13:59:59 UTC

Note: soon Rezdy will use a dynamic configuration for batch availability refresh, which can be setup to better reflect your system. The batch start time, frequency and date range will be configurable.

 

Model and sample Requests & Responses

Availability Endpoint

  • Regardless of using 1-step or 2-steps booking strategy, you will need to implement the availability endpoint in the same way. Rezdy will call the endpoint using HTTP GET method and decorate the endpoint URL with additional query parameters productCode, startTime, endTime. All three parameters are mandatory - always set by Rezdy.
  • Session response contain an array of Session objects
  • Session response should contain all the sessions between specified startTime and endTime, including session with 0 availability (Sold out).
  • If you don't need to support dynamic pricing per session, or the pricing of a certain session is the same as the product default price, you can omit priceOptions array.

Let's consider the endpoint URL, configured as Product Availability Endpoint, to be:

https://api.supplier.com/availability?apiKey?ABC123456

Sample request made by Rezdy (to refresh availability and pricing of a single session), will be as follows:

GET: https://api.supplier.com/availability?apiKey?ABC123456&productCode=ABCDEF&endTime=2014-03-04T22:00:00Z&startTime=2014-03-04T22:00:00Z

Sample RESPONSE:

{
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "sessions": [
    {
      "productCode": "ABCDEF",
      "startTime": "2014-03-04T22:00:00.000Z",
      "endTime": "2014-03-05T00:00:00.000Z",
      "allDay": false,
      "seats": 10,
      "seatsAvailable": 10,
      "priceOptions": [
        {
          "price": 99.99,
          "label": "Adult"
        }
      ]
    }
  ]
}

Booking (Reservation, Confirmation and Cancellation) endpoint 

Booking workflow and endpoints are different based on your selected booking strategy. Some general rules apply in any case:

  • Request and (successful) response contain exactly one Booking object in the Request body/Response envelope
  • Rezdy always sends a single bookingItem per booking in the request, and you should never return multiple items per booking in your response. Also the order of participants in the participants array has to be maintained between request and response
  • you can either used the Rezdy generated orderNumber from the request in the format R12345 or you can generate you own and return it in the response, Rezdy will then use your order number to store the booking internally and use your orderNumber for the next requests (confirmation, cancellation) in case of 2-steps booking 
  • Rezdy will append orderNumber as the last URL path segment, before the query part, for cancellation and confirmation endpoint calls, e.g. ...cancel/R123456?apiKey...
  • if you use your own orderNumber, it has to be unique for each booking and maximum 20 characters long
  • Successful reservation and booking response must contain a booking object with at least orderNumber field and request status with success flag set to true (Cancellation endpoint, does not need to return the booking object)
  • Other fields processed by Rezdy from the booking response include participants barcodes, comments, reseller comments, pickup location

1-step booking

Let's consider your endpoint URL, configured as Product Booking Endpoint, to be:

https://api.supplier.com/booking?apiKey=ABC123456

Sample request made by Rezdy, will be as follows:

POST: https://api.supplier.com/booking?apiKey?ABC123456 

{
    "orderNumber": "RHQRL3N",
    "status": "CONFIRMED",
    "supplierId": 1075,
    "supplierName": "Rezdy Demo",
    "resellerId": 9401,
    "resellerName": "Dusan",
    "resellerUser": {
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "email": "dusan@test.com"
    },
    "customer": {
      "id": 2749,
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "name": "Dusan Zahoransky"
    },
    "items": [
      {
        "productName": "DEMO Lunch Cruise with Live Music on Sydney Harbour",
        "productCode": "P347HK",
        "startTime": "2016-10-02T13:00:00Z",
        "endTime": "2016-10-03T13:00:00Z",
        "startTimeLocal": "2016-10-03 00:00:00",
        "endTimeLocal": "2016-10-04 00:00:00",
        "quantities": [
          {
            "optionLabel": "Adult",
            "optionPrice": 75,
            "value": 1
          },
          {
            "optionLabel": "Child under 12",
            "optionPrice": 55,
            "value": 1
          }
        ],
        "totalQuantity": 2,
        "amount": 130,
        "extras": [],
        "participants": [
          {
            "fields": [
              {
                "label": "First Name",
                "value": "Dusan",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              },
              {
                "label": "Last Name",
                "value": "Zahoransky",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              }
            ]
          }
        ],
        "subtotal": 75,
        "pickupLocation": {
          "locationName": "Town hall Train Station",
          "address": "Town Hall Train Station, Sydney, New South Wales, Australia",
          "pickupTime": "2016-10-02 23:45:00",
          "pickupInstructions": "Meet outside the station\r\nPlease be at this location 15 minutes before pick up"
        },
        "vouchers": []
      }
    ],
    "totalAmount": 130,
    "totalCurrency": "AUD",
    "totalPaid": 130,
    "totalDue": 0,
    "dateCreated": "2016-09-28T06:40:03Z",
    "dateConfirmed": "2016-09-28T06:40:03Z",
    "datePaid": "2016-09-28T06:40:05Z",
    "dateReconciled": "2016-09-28T06:40:03Z",
    "comments": "",
    "internalNotes": "",
    "payments": [
      {
        "type": "CREDITCARD",
        "amount": 130,
        "currency": "AUD",
        "date": "2016-09-28T06:40:05Z",
        "label": "Payment proceed at agent side"
      }
    ],
    "fields": [],
    "source": "MARKETPLACE_PREF_RATE",
    "resellerSource": "INTERNAL",
    "sourceChannel": "dusan",
    "resellerComments": "",
    "commission": 11.25,
    "vouchers": [],
    "paymentOption": "CREDITCARD"
  } 

Sample response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "bookings": [
    {
      "orderNumber": "MyOrderNumber1490069083572",
      "items": [
        {
          "participants": [
            {
              "fields": [
                {
                  "label": "Barcode",
                  "value": "XYZ123"
                }
              ]
            }
          ],
          "pickupLocation": {
            "locationName": "Central Station"
          }
        }
      ],
      "comments": "Thank you for booking. Please call us to confirm the pickup and specify drop-off location on 012345679.",
      "resellerComments": "BookingReference: 123456789"
    }
  ]
} 

2-steps booking

Let's consider your endpoints configuration:

Capture.PNG

Endpoints URLs can be same or different, configuration is up to you. For all 3 requests, Reservation, booking and cancellation, the request data will be almost similar. Rezdy will always send a full booking object. Only differences among the calls is HTTP method used for the request and booking status:

  • Reservation endpoint: HTTP POST, booking.status = "PROCESSING"
  • Booking endpoint: HTTP PUT, booking.status = "CONFIRMED"
  • Cancellation endpoint: HTTP DELETE, booking.status = "CANCELLED" or "ABANDONED_CART"

Reservation request example made by Rezdy:

POST: https://api.supplier.com/reserve?apiKey?ABC123456 

{
    "orderNumber": "RHAUL5R",
    "status": "PROCESSING",
    "supplierId": 1075,
    "supplierName": "Rezdy Demo",
    "resellerId": 9401,
    "resellerName": "Dusan",
    "resellerUser": {
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "email": "dusan@test.com"
    },
    "customer": {
      "id": 2749,
      "firstName": "Dusan",
      "lastName": "Zahoransky",
      "name": "Dusan Zahoransky"
    },
    "items": [
      {
        "productName": "DEMO Lunch Cruise with Live Music on Sydney Harbour",
        "productCode": "P347HK",
        "startTime": "2016-10-02T13:00:00Z",
        "endTime": "2016-10-03T13:00:00Z",
        "startTimeLocal": "2016-10-03 00:00:00",
        "endTimeLocal": "2016-10-04 00:00:00",
        "quantities": [
          {
            "optionLabel": "Adult",
            "optionPrice": 75,
            "value": 1
          },
          {
            "optionLabel": "Child under 12",
            "optionPrice": 55,
            "value": 1
          }
        ],
        "totalQuantity": 2,
        "amount": 130,
        "extras": [],
        "participants": [
          {
            "fields": [
              {
                "label": "First Name",
                "value": "Dusan",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              },
              {
                "label": "Last Name",
                "value": "Zahoransky",
                "requiredPerParticipant": false,
                "requiredPerBooking": false
              }
            ]
          }
        ],
        "subtotal": 75,
        "pickupLocation": {
          "locationName": "Town hall Train Station",
          "address": "Town Hall Train Station, Sydney, New South Wales, Australia",
          "pickupTime": "2016-10-02 23:45:00",
          "pickupInstructions": "Meet outside the station\r\nPlease be at this location 15 minutes before pick up"
        },
        "vouchers": []
      }
    ],
    "totalAmount": 130,
    "totalCurrency": "AUD",
    "totalPaid": 130,
    "totalDue": 0,
    "dateCreated": "2016-09-28T06:40:03Z",
    "dateConfirmed": "2016-09-28T06:40:03Z",
    "datePaid": "2016-09-28T06:40:05Z",
    "dateReconciled": "2016-09-28T06:40:03Z",
    "comments": "",
    "internalNotes": "",
    "payments": [
      {
        "type": "CREDITCARD",
        "amount": 130,
        "currency": "AUD",
        "date": "2016-09-28T06:40:05Z",
        "label": "Payment proceed at agent side"
      }
    ],
    "fields": [],
    "source": "MARKETPLACE_PREF_RATE",
    "resellerSource": "INTERNAL",
    "sourceChannel": "dusan",
    "resellerComments": "",
    "commission": 11.25,
    "vouchers": [],
    "paymentOption": "CREDITCARD"
  }

Sample Reservation response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "bookings": [
    {
      "orderNumber": "RHAUL5R"
     }
  ]
}

 

Sample Booking request made by Rezdy:

PUT: https://api.supplier.com/book?apiKey?ABC123456 

{
    "orderNumber": "RHAUL5R",
    "status": "CONFIRMED",
...

Sample Booking response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  },
  "bookings": [
    {
      "orderNumber": "RHAUL5R"
     }
  ]
}

 

Sample Cancellation request made by Rezdy:

PUT: https://api.supplier.com/cancel?apiKey?ABC123456 

{
    "orderNumber": "RHAUL5R",
    "status": "CANCELLED",
...

 Sample Cancellation response:

{
  {
  "requestStatus": {
    "success": true,
    "version": "v1"
  }
}

 


3- Setup your RezdyConnect URLs

Configure your endpoints URLs, based on the booking strategy and supported media type. After you Save the product, Rezdy will request one week availability, to ensure the availability endpoint is working fine and validates URLs for other endpoints.


Capture.PNG

 

 

4- Using Webhooks and Rezdy API

This section will be available soon

Related articles

Comments

0 comments

Please sign in to leave a comment.