Introduction

Swikly is a third party specialised in the management of online security deposits for tourism. With Swikly, you can protect a good, such as an apartment or a car, from damages, without the constraints of cheques, transfers or payments terminals. You can improve your customer experience and automatically request in a single transaction, the security deposit and , as an option, the payment of the balance. Swikly security deposits are made without debiting or even blocking the limits of the guest 's credit cards. The service also includes the management of any disputes with tenants, as well as a payment guarantee for the landlord.

Purpose of Swikly integration is to give Property Manager (PM) a possibility to request automatically a security deposit and optionally the balance payment with the PMS automation functionalities. It is based on few key principles below, that the PMS must have : 

• a way to configure a security deposit amount per property or group of property
• a way to know the amount and the status of our security deposit per booking. The goal is to inform the PM and let him know if it  is secured or not (usually it is on a bookings level)
• a way to send security deposit request depending on booking source (mainly to exclude Airbnb) : Property managers want to send security deposit request for OTA’s who do not manage security deposit only
• a way to send reminder to the guest when the security deposit is not yet secured / alternatively a way to not sent a request when it  is already secured 

Définition 

• deposit : is a pre-payment that is usually requested at booking time when the full payment is not paid. it s a commitment to buy the rental service for the guest. Usually deposit are not refund if the guest cancel his booking.
• balance : is the rest of the amount due by the guest when he has not fully paid the booking. Usually balance is due few weeks/months before the checkin
• security deposit : ⚠️a "deposit" et totally different from a "security deposit", security deposit is usually an amount of money that is paid to the property manager in order to cover potential degradation of the property. With Swikly, security deposit are NOT paid (there is no money transfer), it is just a fully guaranteed credit card imprint  so there is no need to refund it after the stay.

How it works ?

The requests are sent by the PMS emailing system few days before check-in. It is an automatic email with a Swikly link redirecting the guest to a single form where he can record his personal information and his credit card number. 

Most of PMS have a module that allows to send emails based on templates at the right time and with email content that adapts dynamically to the interlocutor. You usually can configure the sending period (e.g. 5 days before arrival), choose your language, define the subject of your email,  and use variables like first name, lastname, PMS booking ID etc. The Swikly integration use this PMS functionality to provide a way for Swikly to get the minimum needed data like a bookingID and an accountID. These 2 information will then be used to retrieve the full data (security deposit amount, balance amount, start date, end date, firstName, lastName, email, phone, language, PMS booking Id ) from the PMS trough the PMS API in order to build the final link where the guest will be redirected to. This will be done as soon as the guest click on the link in order to be sure that data are up to date (cf. schema below  "Technical principles").

If the PMS do not have API to provide the full data, the PMS need to get a link and send it in the email. To do this, the PMS must either :

• call Swikly API to get a fully working link based on the booking data with this Swikly API documentation. 
• or calculate a working permanent link based on the booking data with this permalink documentation  

As soon as a guest secure his security deposit and/or pays the balance, the Swikly Integration need to update the PMS booking with these status information. This is usually done by Swikly thanks :

• to a call-back URL which is called at the end of a successful Swikly transaction
• and a call to the PMS API in order to log the fact that the Security deposit is secured and/or the payment of the balance is done.

If the PMS do not have API to update the booking data, neither a way to listen to the Swikly call-back url and update data himself, then there is no possibility to update this information in the PMS, in this case :

• it is possible to call Swikly API to check the status of a security deposit when the PM consult a booking (our API can retrieve a status based on the PMS booking ID)
• or the PM will need to go in Swikly back-office website to manually check if the security deposit is done for a specific booking. A search is available available based on the Pms Booking ID.

Integration level 

We define 2 level of integration as a set of needed functionality and prerequisite for the PMS .

For the record, the most chosen integration (by our customers) is the one with balance payment + security (level 2) deposit in one transaction, mainly because it is the best for the customer experience, since guests do not need to fill-in twice the credit card number. 

Level 1 : first base minimum set of functionality in the PMS - Must Have 

• Transactions Management: Security Deposit management (no balance payment) : 
  • the amount of the security deposit must be available for a property or group of properties
  • the information status of the security deposit must be available at booking level (ex: "secured by Swikly" , "not secured" ). This information shall take in account the fact that there is no money transfer with Swikly (so no need to refund).
  • the Swikly link send by email will cover the security deposit transaction only 
• Automatic email sending to the guest with a link :
  • filtering capacity to send email X days before check-in
  • filtering capacity to send email depending on booking source (ex: do not send mail for booking from airbnb)
  • filtering capacity to send email only if a security deposit is needed for the property or a booking (ex : do not send an automatic email if the security deposit amount is zero, do NOT send an automatic email if the security deposit is already secured)
• Information update in the PMS when the security deposit the secured :
  • need a field status or a tag at the booking level to state than a security deposit is secured. It can also be an amount of a security deposit plus an information that it is a "Swikly security Deposit"

Level 2 : All Level 1 functionalities + balance management - Nice to Have 

• Transactions Management: Security Deposit AND balance management
  • same as level 1 + 
  • capacity to choose the Swikly mode between these 3 : "security deposit only", "balance only", "both"
  • the amount of the security deposit AND the balance must be available for a booking
  • the swikly link send by email will cover the security deposit amount AND the balance amount 
• Automatic email sending to the guest with a link :
  • same as level 1
• Information update in the PMS when the security deposit the secured and the balance is paid:
  • same as level 1 + 
  • need a way to update the payment transaction for the balance 

⚠️Level 1 without email filtering based on security deposit status

Some PMS do not have the capacity to filter automatic email based on filtering like security deposit amount is zero or security deposit already secured. One simple way is to use a tag management functionality that the PMS may have and create a tag named "security deposit ok". Then the PMS emailing system must be able to filter the sending based on this tag. To keep a good customer experience, this functionality is a MUST, otherwise :

- some guest will receive an email asking to secure a security deposit to 0 euro !

- there is no capacity to send a reminder email for instance 3 days before booking, the transaction acceptation will be very low and all the integration will not bring value to the property manager 

Authentication

In order to exchange data, there is a need to setup a secure authentication. It can works as follow.

Shared PMS account ID for PMS with API

When the PMS has API , the standard is to set a PMS partnership page in Swikly user profile . The property manager will then need to copy and paste the PMS account id and eventually a API secret into the Swikly website in order to connect the tow accounts. Swikly will check and record these information. These data will then be used by Swikly when the guest clic on the link to connect to the PMS API and retrieve the needed data (the recorded PMS accountID must match the accountID in the clicked url parameter).

Shared Secret for PMS without API

Usually this authentication method is used when the PMS has no API. Swikly permalink authentication is based on a control key calculation based on a shared secret (detailed instruction here). In order to set a working link, the PMS need to have the needed data to calculate the control key :

• the swikly user ID (userId), available in the Swikly user profile
• the link secret () available in the Swikly user profile

These 2 data can be copied and pasted in the PMS by the property manager in order to connect the tow accounts. It means that the integration must include a Swikly Partnership page with these tow fields (so far there is no way to verify that the copied data are correct to inform the PM as soon as he has copied the data). Then the PMS can use these data to calculate the right link.

⚠️ It is strongly recommended to control user's credential when copied and pasted in the PMS Profile. This can be done by building a link with a fake amount and test it based on the http return code 200 if authorized or 401 if not.

⚠️ when the PMS build the full permalink, it needs a link ID (linkId) in the parameter of the url. As as standard the link ID should be set to the following string : [pms_name]_permalink (ex: MyPMSName_permalink)

Technical principles for PMS with read and write API

The integration principle is based on these schema bellow.

PMS with API

PMS without API 

Not recommended if PS APIs are available. 

FAQ

Q1 - Why sending the email few days before check-in and not use the already existing credit card number or token ?

It s not really accepted to secure a security deposit at booking time, moreover delay is sometime huge between booking and checkin , could be an issue for us if the credit card expiry happen in between.

Q2 - why do we need to use PMS emailing system and not Swikly emailing module?

Guest communication will be done in a coherent way like other communication. 

Q3 - What are the fields & information to provide to Swikly in order to secure a deposit  ?

(*) if your API provide different types of format, Swikly will convert data during the integration process.

(**) if not available, we will user language browser

(***) good to have, if not available we can adapt the integration

Technical information are also mandatory (like Swikly userId, control Key ... ) , see the Swikly Link Documentation for more information.

-