Post Booking API Process

Post Booking API Process

Overview

The RCM Post Booking API allows you to retrieve booking information and also update bookings that already exist within RCM. 

The following information cannot be changed on the booking using the Post Booking API:
  1. Pickup/drop off locations
  2. Pickup/drop off dates and times
  3. Vehicle category
The following information can be updated or added using the Post Booking API:
  1. Optional fees can be added or removed.
  2. Insurance options can be added or changed.
  3. Customer details can be updated.
  4. Additional drivers can be added to the booking.
  5. Credit Cards or Payment information can be added to the booking.
  6. Images can be uploaded and saved against the booking.
  7. If the E-Signature function has been setup within RCM, the signatures can be collected and saved.
  8. A quote can be converted to a booking. 

Post Booking Process

Depending on what sort of updates you would like to make with this API, a general sequence of events would be:
  1. Request Authorisation Token
  2. FindBooking – get the correct ReservationRef to identify the booking
  3. BookingInfo – get all the information for the booking, including booking dates, times, locations, vehicle category; customer details; additional drivers, booking rates; optional extras; insurance; payment information
  4. BookingOptions – get lists of options to present to the customer, for e.g. optional extras available, insurance options, extra kilometre (mileage) options
  5. CalcTotal – returns an updated total amount and subtotals for the booking based on changed optional extras or insurances
  6. EditBooking – update customer details, insurance, optional extras and some other information about the booking.
  7. ExtraDriver – add, edit or delete an additional driver for this booking
  8. Any other of the following functions:
    1. Add Credit Card to the RCM Vault
    2. Submit payment information for payment collected externally
    3. Add Electronic Signature for primary or additional drivers
    4. Submit a link to an image for any uploaded documents, for e.g. drivers license

ReservationRef

All methods that relate to a specific booking will need to pass in the “reservationref” as the unique identifier.

ReservationRef is the unique alpha-numeric id to identify the reservation, it is not usually known by the customer. It is not the same value as the “reservationNo” which is printed on all customer correspondence between RCM and the customer.

You may already have the ReservationRef as it is one of the parameters returned from the API when the original booking was made. If you have this value, you may proceed to call “bookinginfo” which will give you all the information about the booking, and proceed to “editbooking” etc.

If you don’t know the ReservationRef, you will need to call the “findbooking” method. This method can retrieve a booking based on a combination of ReservationNo (or agent reference number) and the customer’s last name or email address.

API Methods and how to use them

Find Booking (findbooking)

The first thing you will need to do to edit a booking is find it, based on a range of values. You can do this with the “findbooking” method. FindBooking takes the data that the customer is likely to know, i.e. ReservationNo with email or last name.
Findbooking will accept the following combinations to look up a booking:
  1. (ReservationNo OR AgentRefNo)* & Customer Last Name
  2. (ReservationNo OR AgentRefNo)* & Customer Email
*The same field is used for both ReservationNo & AgentRefNo. The code will first check for a Reservation match (unallocated as well as allocated). If it doesn't find a match, it will try based on agent reference.

The findbooking method, if successful, will return a value for “reservationref” – this value can then be used for all other methods. Note that if you already have this value for a reservationref, you can skip the “findbooking” step and go straight to “bookinginfo”.

If the findbooking method does not find a matching reservation, or finds more than one match, it will return an error (not found). If you are an agent, you will only be able to match those reservations that were originally made by you.

Booking Information (bookinginfo)

Use the bookinginfo method to get all the finalised information about the booking in one call. Data returned includes booking dates, times, locations, vehicle category; customer details; additional drivers, booking rates; optional extras; insurance; payment information.

Bookinginfo takes a single parameter “reservationref”. If you don’t know this value, you will need to call “findbooking” to retrieve it first.

Note that possible values for the “reservationstatus” field are as follows:
Where a vehicle has been allocated to a booking (isvehicleallocated = true):
  1. Reservation = reserved (confirmed), awaiting hire
  2. Hired = currently on hire
  3. Maintenance = booked out for vehicle maintenance
  4. Cancelled = cancelled reservation
  5. Returned = returned from hire
Where a vehicle hasn't yet been allocated to a booking (isvehicleallocated = false):
  1. Reservation = reserved (confirmed), awaiting vehicle allocation prior to hire
  2. Reservation Request = not yet confirmed.
  3. Cancelled = cancelled reservation
  4. Quotation = a quotation rather than an actual reservation

Note: Bookings that are currently on hire, overdue for hire, or already returned cannot be updated using the editbooking method.

Retrieving a list of available Booking Options (bookingoptions)

Calling this method will return you four datasets which will be relevant if you are wanting the user to update their booking:
  1. LocationFees – more information about the pickup & dropoff locations including any rules for these which might apply to booking updates (for e.g. some locations require the field “flightin”)
  2. OptionalFees – a list of optional extras available for this booking, for e.g. baby seat or GPS
  3. InsuranceOptions – a list of insurances applicable for this booking
  4. KmCharges – a list of kilometre (mileage) charge options, for e.g. Unlimited kilometres, 100km free per day + $0.50 for each km over
The “id” fields for each of these options will need to be passed in to the “editbooking” method to make the updates.

There is also a reference list for options that make up part of the booking:
  1. list of rentalsources,
  2. list of countries,
  3. list of AreaOfUse options.
Bookingoptions takes a single parameter “reservationref”. If you don’t know this value, you will need to call “findbooking” to retrieve it first.

Calculating an interim total for the booking (calctotal)

Rather than calculating the (sometimes complex) totals for various selected booking options yourself, you can call our “calctotal” method, passing in all the relevant options for the booking.

You can call this method at any time – it passes back calculated totals and subtotals for display to the user. For e.g. if you display a running total booking amount on your page, when the user selects a different insurance option, make a quick call to “calctotal” to update your totals to indicate what the amount will be if this option is submitted.

*NOTE* This method does not save any data against the booking – to save the selected options you will need to call “editbooking”.

Editing a booking or quotation (editbooking)

Call this method (“editbooking”) to make adjustments to details such as optional extras, insurance and driver information.

Converting a quotation to a booking (convertquote)

This method can be used to convert a quotation into an unallocated booking. You can optionally include payment or vault data in the request. Some rental car companies require payment to be included otherwise the quote won’t be converted. This option is determined by this system setting:



If this value is set to Yes then you must provide either payment information or vault data with the request.

To send a confirmation email to the hirer, set the parameter “emailoption” to either “1” or “2”.

Adding or editing Additional Drivers for an existing booking (extradriver)

This method (“extradriver”) can be called separate to “editbooking” in order to add, update or delete Additional Drivers.
  1. To Add a new driver, the customerID field should be “0”
  2. To Edit an existing driver, the customerID field should be the same as the customerID field in the “bookinginfo” extradrivers dataset.
  3. To Delete an existing driver, the customerID field should be the negative value of the customerID field in the “bookinginfo” extradrivers dataset. For e.g. if the customerID is 321, to delete this driver, set customerID to -321

Using the Credit Card Vault

The Rental Car Manager system does not directly handle any credit card numbers, this is outsourced to a PCI Level 1 compliant provider, AURIC. The AURIC Credit Card Vault securely stores a customer’s credit card, such that it can be safely retrieved later for payment processing. Rental Car Manager only stores the tokens required to access the card information.

The Vault does not process any payments. If you wish to take a payment directly from the customer, skip this section - you will need to link to your own payment processing service. See the “Submit Payment Information” section for more details.

If you wish to incorporate the Auric credit card vault into your API implementation, you will need to display the Credit Card Vault Entry screen directly in an IFrame on your own page.

Step 1
Call the method “getvaulturl” using the “reservationref” id.
The API will return a variable url containing the base64-encoded url of the vault that the user needs to be redirected to.

Step 2
On the client-side, create an iframe and set the source to the url returned from the API call.

Step 3
Once the user has finished entering card details, the page will receive a message (event) from the iframe. Javascript on the client page needs to check for this message. If the card details were saved successfully then call the “vaultentry” method of the API.

Example:



*NOTE* After the vault triggers the “ADD” event, the credit card vault token has not yet been linked to the booking/customer in RCM. You now need to call our API method “vaultentry” to record the data returned from the vault (step 4 below).

Sample data returned from vault = 8K7Qlw4mwA0Wj0B1122,Visa,R M Test,08/18,123,ADD

Step 4
Use the data returned from the vault to call the “vaultentry” api method. The vaultentry method has input parameters of “reservationref” and “data”. “data” must be the entire data string returned from the vault as above, encrypted in Base64 format.

Submit Payment Information (savepayment)

If you would like to charge the customer, you will need to interface with your own payment processing provider. The alternative is entering credit card information to the vault (see previous section).

Once you have processed the payment, you must call our “savepayment” method so that the payment can be recorded against the booking.

Electronic Signing (savesignature)

Note: Not all companies who use Rental Car Manager are set up to use Electronic Signing. Check first if this is a valid call for your company.

There are two formats of signature that RCM accepts:
  1. JSON: The “savesignature” method takes JSON signature data in the form supported by jquery.signature.js (http://keith-wood.name/signature.html), or
  2. PNG: base64-encoded PNG image. Please note there are size restrictions on the image, you may need to resize the image before uploading. Check the error field returned.
Note: If you need to know in advance whether a signature is required, already recorded, or not required we will have to do a little bit of set up for you to define some rules. Please contact us at  RCM Support (support@rentalcarmanager.com).

Document/Image Storage

Our API now has a method to link a document (such as a pdf or image) to a reservation. Rental Car Manager does not actually save the document on our own servers, but we do have a third-party document store with Cloudinary (https://cloudinary.com/). Documents/images stored with cloudinary are signed and private. Depending on the sensitivity of the image, it may only be viewable through a logged-in session of RCM. Sensitive images (e.g. drivers licence pic) will not be available to the API once they are uploaded.

You can either use RCM’s Cloudinary account (free of charge), or upload images to your own server/image store.

The document/image storage API is a little bit complicated so requires a bit of explanation of the various methods available.

1. Get a list of documents/images required or already uploaded (documentlist)
The “documentlist” method will return a list of required documents/images. This list is based on rules that are set up in RCM, and are defined per Workflow. So, what we need to do is set up a workflow for you. An example of a workflow which is already set up is “checkin”, which defines the upload requirements for a customer completing their online check in process. The “checkin” workflow may have some rules about image uploads, for example we must collect an image of a drivers licence from the primary driver as well as any additional (extra) drivers.

If you need different image upload rules, or a new workflow (e.g. “convertquotation”), please contact us with your requirements – RCM Support (support@rentalcarmanager.com)

So, for an example where we have workflowcode “checkin”, and we have defined the rule that we need to collect drivers licence from each driver, then a call to the “documentlist” method would return one record for each driver as below (showing primary driver only):



The record above shows some of the rules that are defined for this upload. It is likely that most of these fields can be ignored if you are building your own implementation, however there are a couple of fields worth drawing your attention to…

Fields highlighted blue above:
Isuploaded: Use this field to determine if the user has already completed this requirement. For example, if they have uploaded their drivers licence already, you can skip this step so that they don’t have to do it again.
Url: If an image has already been uploaded, the url for the image may be displayed here. Where an image is marked as “contains sensitive data” (“containssensitivedata”), we don’t return the URL through the API – these images are only available via a logged-in session of RCM. An example of an image containing sensitive data is a drivers licence, passport, or selfie of the driver.

Fields highlighted yellow above:
Documentlinksetupid: You will need to use this id field when storing a new image using the “storeupload” method.
Customerid: You will need to use this id field when storing a new image using the “storeupload” method. This is very important, it is used to distinguish which driver you are uploading the image for.
2. Use the Cloudinary Widget to upload the document/image to Cloudinary

You may decide to host your own images, or use a different image storage provider, in which case you can skip ahead to “storeupload”. If you wish to use our own image provider, you will need to include some references to the Cloudinary API.

The sample code provided here uses Cloudinary’s Upload Widget, which you can find more information about here: https://cloudinary.com/documentation/upload_widget

Cloudinary’s Upload Widget follows this process:
  1. Launch the widget which requests the user to choose a file or camera
  2. Call a function to Sign the upload (mentioned below as the “upload_signature” parameter)
  3. Complete the upload to cloudinary’s server
  4. Return the upload results, including URL of the image.
This section describes Step 1 above – launching the widget. The first step is to include the javascript reference:



When you are ready to capture the image/document, launch the Cloudinary widget as follows:



Notes about sample Cloudinary widget code above:

Items above highlighted in yellow:
  1. upload_preset, api_key, cloud_name - Use the exact values provided in the sample code. These values are fixed, and relate to RCM’s account with Cloudinary.

Items above highlighted in green:
  1. upload_signature – the value for this need to be a reference to a function that will return an RCM-signed value that verifies the upload to Cloudinary. The function that is referenced must call our API method “signupload”. See the next section for further information and sample code.

Item above highlighted in blue:
  1. This is a reference to a function that will be called after the Cloudinary upload is successful. This function must call our API method “storeupload”. See following sections for further information and sample code.
3. Sign the request to Cloudinary (signupload)

Remembering Cloudinary’s upload widget’s process…
  1. Launch the widget which requests the user to choose a file or camera
  2. Call a function to Sign the upload (mentioned above as the “upload_signature” parameter)
  3. Complete the upload to cloudinary’s server
  4. Return the upload results, including URL of the image.
… we are now up to Step 2 = generate a signature for the Cloudinary request.

RCM’s account at Cloudinary requires all uploads to be authorised via Signing using a secret key that has been provided to RCM. We have provided an API method that will complete this process called “signupload”.

Using the sample code from above, we define a method to call our API:



Here, Cloudinary will call the function “generateUploadedDocSignature” (as this was originally passed in to the openUploadWidget method as parameter value for “upload_signature”) passing in its own callback function, and the parameters to sign. We need to take the parameters to sign, pass them to RCM’s “signupload” method, and then call Cloudinary’s “callback” method to complete the processing.

Note, the yellow highlighted methods above are used here for callback_on_success and callback_on_failure. The ajaxCall here is referencing a local function that handles all RCM API requests (code not provided).

4. Send the new URL and other data to RCM (storeupload)

Remembering Cloudinary’s upload widget’s process…
  1. Launch the widget which requests the user to choose a file or camera
  2. Call a function to Sign the upload (mentioned above as the “upload_signature” parameter)
  3. Complete the upload to cloudinary’s server
  4. Return the upload results, including URL of the image.
… We are now up to Step 4 – processing the results returned from Cloudinary. On a successful upload, Cloudinary will call our method “processUploadResult” (as this was the method passed in as the final parameter when launching the Upload Widget). Here we will show what to do with the result in order to record it against the reservation in RCM.






The yellow fields highlighted above should come from the “documentlist” method mentioned back at the start of this section. All the other fields should be reasonably easy to work out. Once a document has been successfully recorded in RCM, calling the “documentlist” method should show that it has now been uploaded.

    Important Articles


      • Related Articles

      • Useful Post Booking API Methods

        Overview As well as the methods which are used in the Post Booking Process, there are other methods which are part of the Post Booking API. They are all discussed below. Get Location Details (locationdetails) The locationdetails method can be used to ...

      • Getting Started with Post Booking API

        Introduction Version 3.2 of the Post-Booking API allows web developers to access the core post-booking methods for Rental Car Manager systems. Note that the methods in this document all refer to post-booking methods, i.e. involving the update of ...

      • API V3.2 Booking Process

        Overview The RCM API and Agent API allow you to make unallocated bookings for a specified vehicle category, for a specified pickup and drop off date. An unallocated booking is a booking that has been made for a particular category (e.g. small car), ...

      • Updating Bookings using Post Booking API

        Overview The Post Booking contains methods which allow you to perform different actions on a booking in RCM. Two of the methods allow you to update the booking information. The difference between the two methods is the information that you are able ...

      • Useful API V3.2 Methods

        Overview As well as the methods which are used in the Booking Process, there are other methods which are part of the API V3.2. They are all discussed below. Editing a Booking or Quotation Post-booking methods are available to edit booking details ...