SynXis Property Hub - Folio Api

SynXis Property Hub
Folio
REST API
PMS Integration

What is it?

The Folio Integration API provides you with the necessary tools to manage Folios within SynXis Property Hub (SPH).

Folios are used in SPH to track and separate all financial transactions, like payments and charges. Each guest reservation contains three Guest Folios by default and up to six are supported.

Today, this API offers operations on Guest Folios such as:

  • Post charges and payments
  • Manage payment methods
  • Read Folios
  • Read credit card logs
  • Email Folio
  • View charge routing configuration
  • Pre-post charges before Night Audit

And the below operations on House Account Folios:

  • Post charges and payments
  • View House account details
  • Update House account details

Please note that other types of Folios are NOT currently supported, including Group Folios and Accounts Receivables.

Why use it?

Through this Folio Integration API, your system could directly perform financial transactions, manage payment methods, query transactions, and read credit card logs among other things. We believe this API is especially valuable to vendors of Kiosks, Point-of-Sale systems, and accounting systems, but the sky is the limit.

Here are some sample use cases:

  • When the guest arrives at the hotel and uses the front office kiosk to check in, the kiosk captures an incidental payment card before issuing the key.
  • The guest adds two theme park tickets at the front office kiosk, so the kiosk posts a charge with a description stating the details before printing ticket vultures.
  • When the guest dines at the hotel’s restaurant, the charge is posted to the Primary Guest Folio through a POS system used at the restaurant.
  • The guest wants to use a different card, using the kiosk the guest adds the new card and removes the old one.
  • The guest requests and receives an emailed receipt for the stay on the hotel’s website.

How it works

Post Charge

Post Charge executes the following steps to display a charge on an account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Validates if the folioId passed is valid.
  3. Validates if the amount passed in the request is not equal to 0.00.
  4. Retrieves the charge transaction code data by the given transactionCode.
  5. Retrieves the account information data by the given account.
  6. Once all the data is retrieved and valid then calls proper down-line services to process the request.
  7. If the request is executed successfully, maps the response data to a normalized data model.
  8. In-case of failure, response object will have a message with the error info.

Post Payment

Post Payment, executes the following steps to display a payment on an account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Validates if the folioId passed is valid.
  3. Validates if the amount passed in the request is not equal to 0.00.
  4. Retrieves the payment transaction code data by the given transactionCode.
  5. Retrieves the account information data by the given account.
  6. Once all the data is retrieved and valid then calls proper down-line services to process the request.
  7. If the request is executed successfully, maps the response data to a normalized data model.
  8. In-case of failure, response object will have a message with the error info.

Additionally, the following steps are executed when using creditCard to post the payment:

  1. Validates if the creditCard object that is passed is having valid ccExpiration, ccToken, ccType as per the pattern mentioned in the spec file.
  2. If the creditCard used to post payment is not existing on the account, will add the credit card details as the payment method on the account.
  3. Calls the payment gateway to post the payment with the details on the account.
  4. Once the payment is completed on gateway, maps the response data to normalized data model.

Additionally, the following steps are executed when using DirectBill to post the payment:

  1. Retrieves the Accounts Receivable information based on the receivablesAccountId passed.
  2. If the account is found then calls proper down-line services to process the request.
  3. Else an error message is returned as the response.

Pre-Post

Pre-Post Room charge executes the following steps to display a pre-post on an account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId.
  2. Validates if the accountType passed in request param is 'GUEST'.
  3. Validates if the prePostRequest object in the body is not null.
  4. Calls the proper down-line service to execute the request and maps the response data to a normalized data model.

Email Folio(s)

Email Folio(s) executes the following steps to get an email of folios of the account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Validates if the folioIds passed are valid.
  3. Validates if the emailIds passed are valid as per the pattern mentioned in the spec file.
  4. Retrieves the folio's information for all the given folioIds.
  5. Retrieves the account information data by the given account.
  6. Once all the data is retrieved and valid then calls proper down-line services to process the request.
  7. If the request is executed successfully, maps the response data to a normalized data model.
  8. In-case of failure, response object will have a message with the error info.

View Folio Details

View Folio Details executes the following steps to get the details of folio:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Validates if the folioId passed is valid.
  3. Retrieves the account information by the given account.
  4. Retrieves the information of the given folioId.
  5. Once all the data is retrieved, maps the response data to a normalized data model.
  6. In-case of failure, response object will have a message with the error info.

View Folio Routings

Retrieves all the routing details available on all folios for a reservation or an account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Retrieves the account information by the given account.
  3. If routing has been mapped to the given account, retrieves all the routing information on all the folios.
  4. Once all the data is retrieved, maps the response data to a normalized data model.
  5. In-case of failure, response object will have a message with the error info.

View Folios Summary

Retrieves the summary of transactions on all the folios for a reservation or any account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Retrieves the account information by the given account.
  3. Retrieves the transactions on all the folios and calculates the summary like balance, share percentage, total expected balance on each of the folio.
  4. Retrieves the payment method info that are configured for any folio.
  5. Once all the data is retrieved, maps the response data to a normalized data model.
  6. In-case of failure, response object will have a message with the error info.

View Credit Card logs

Retrieves all the credit card transactions on all the folios for a reservation or any account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Retrieves the account information by the given account.
  3. Retrieves all the credit card transactions on the account for all the existing folios.
  4. Once all the data is retrieved, maps the response data to a normalized data model.
  5. In-case of failure, response object will have a message with the error info.

View Folio Transactions

Retrieves all the transactions on all the folios for a reservation or any account:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Retrieves the account information by the given account.
  3. Retrieves all the transactions on the account for all the existing folios.
  4. Retrieves the payment method info as well for each folio if configured.
  5. Retrieves the routing info of the transaction on the folio if configured.
  6. Once all the data is retrieved, maps the response data to a normalized data model.
  7. In-case of failure, response object will have a message with the error info.

Update Transaction Description

Updates the description of any existing transaction for the given unique identifier of the transaction:

  1. Validates if the vendorCode is subscribed for the combination of given chainId and hotelId
  2. Retrieves the account information by the given account.
  3. validates if any transaction is existing for the given unique identifier transactionGUID, chainId and hotelId combo.
  4. Once all the data is retrieved, updates the description and saves it and maps the response data to a normalized data model.
  5. In-case of failure, response object will have a message with the error info.

How to use

Folio Integration APIs

To ensure successful API operations, all the requests should contain the below information:

  1. Add tenantId in the request header.
  2. Add chainId in the request header.
  3. Add hotelId in the request header.
  4. Add vendorCode in the request header.
  5. Add account as path variable in the request.
  6. Add accountType as a request param in the request.

Note: All The APIs will validate if the vendorCode is configured for combination of given chainId and hotelId before retrieving it.

Post Charge

Post Charge on an account for the given account type

To ensure successful posting of a charge on an account, the request should contain the below information:

  1. Add amount in the Post Charge request.
  2. Add folioId (valid folioId) in the Post Charge request.
  3. Add transactionCode (transactionCode that is configured in SPH app) in the Post Charge request.

Note: The API will validate if the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested doesn't exist the request will not be processed.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "Breakfast"
}

Post Payment

Post Payment with Cash as payment method on an account for the given account type

To ensure successful posting of a Cash payment on an account, the request should contain the below information:

  1. Add amount in the Post Payment request.
  2. Add folioId (valid folioId) in the Post Payment request.
  3. Add transactionCode (Cash Payment transactionCode that is configured in SPH app) in the Post Payment request.
  4. Add cashierId if cashierId is different to the userId who is posting transaction in the Post Payment request.

Note: The API will validate if the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested doesn't exist the request will not be processed.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "CASH",
  "cashierId": "DJohn"
}

Post Payment with Credit Card or Virtual Credit Card as payment method on an account for the given account type

To ensure successful posting of a Credit Card payment on an account, the request should contain the below information:

  1. Add amount in the Post Payment request.
  2. Add folioId (valid folioId) in the Post Payment request.
  3. Add transactionCode (Any of the credit card related Payment transactionCodes that is configured in SPH app) in the Post Payment request.
  4. Add creditCard object with valid ccExpiration, ccToken, ccType as per the pattern mentioned in the spec file.
  5. Add debit flag to true if the credit card added is of type debit else set it to false in the Post Payment request. By-default it's false.

Note: The API will validate creditCard object if ccExpiration, ccToken, ccType are passed as per the pattern mentioned in the spec file along with the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "VISA",
  "creditCard": {
    "ccExpiration": "1223",
    "ccToken": "ID:4534j345dfdfg",
    "ccType": "VISA"
  },
  "debit": true
}

Post Payment with Direct Bill as payment method on an account for the given account type

To ensure successful posting of a Direct Bill payment on an account, the request should contain the below information:

  1. Add amount in the Post Payment request.
  2. Add folioId (valid folioId) in the Post Payment request.
  3. Add transactionCode (Direct Bill payment transactionCode that is configured in SPH app) in the Post Payment request.
  4. Add receivablesAccountId Accounts Receivable ID to posting the transaction in the Post Payment request.

Note: The API will validate if the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested doesn't exist the request will not be processed.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "DB",
  "receivablesAccountId": "HA12345"
}

Pre-Post

Pre Post Room Charge

To ensure successful pre posting of a Room Charge on an account, the request should contain the below information:

  1. Add postDuringNightAudit flag to true or false based on if Room Charge should be posted again during Night Audit in the Pre Post request. By-default it's false.

Note: The API will validate if the accountType is GUEST_ACCOUNT since pre-post is not supported for other Account Types.

{
  "postDuringNightAudit": true
}

Email Folios

Email Folio or multiple folios to an email or multiple emails.

To ensure successful emailing of folios on an account, the request should contain the below information:

  1. Add folioIds as a request param in the Email Folios request.
  2. Add emailIds as a request param in the Email Folios request.

Note: The API will validate if the folioIds are valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the emailIds requested are valid per the pattern provided in spec.

Post Charge

Post Charge on an account for the given account type

To ensure successful posting of a charge on an account, the request should contain the below information:

  1. Add amount in the Post Charge request.
  2. Add folioId (valid folioId) in the Post Charge request.
  3. Add transactionCode (transactionCode that is configured in SPH app) in the Post Charge request.

Note: The API will validate if the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested doesn't exist the request will not be processed.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "Breakfast"
}

Post Payment

Post Payment with Cash as payment method on an account for the given account type

To ensure successful posting of a Cash payment on an account, the request should contain the below information:

  1. Add amount in the Post Payment request.
  2. Add folioId (valid folioId) in the Post Payment request.
  3. Add transactionCode (Cash Payment transactionCode that is configured in SPH app) in the Post Payment request.
  4. Add cashierId if cashierId is different to the userId who is posting transaction in the Post Payment request.

Note: The API will validate if the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested doesn't exist the request will not be processed.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "CASH",
  "cashierId": "DJohn"
}

Post Payment with Credit Card or Virtual Credit Card as payment method on an account for the given account type

To ensure successful posting of a Credit Card payment on an account, the request should contain the below information:

  1. Add amount in the Post Payment request.
  2. Add folioId (valid folioId) in the Post Payment request.
  3. Add transactionCode (Any of the credit card related Payment transactionCodes that is configured in SPH app) in the Post Payment request.
  4. Add creditCard object with valid ccExpiration, ccToken, ccType as per the pattern mentioned in the spec file.
  5. Add debit flag to true if the credit card added is of type debit else set it to false in the Post Payment request. By-default it's false.

Note: The API will validate creditCard object if ccExpiration, ccToken, ccType are passed as per the pattern mentioned in the spec file along with the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "VISA",
  "creditCard": {
    "ccExpiration": "1223",
    "ccToken": "ID:4534j345dfdfg",
    "ccType": "VISA"
  },
  "debit": true
}

Post Payment with Direct Bill as payment method on an account for the given account type

To ensure successful posting of a Direct Bill payment on an account, the request should contain the below information:

  1. Add amount in the Post Payment request.
  2. Add folioId (valid folioId) in the Post Payment request.
  3. Add transactionCode (Direct Bill payment transactionCode that is configured in SPH app) in the Post Payment request.
  4. Add receivablesAccountId Accounts Receivable ID to posting the transaction in the Post Payment request.

Note: The API will validate if the amount is not equal to 0, folioId is valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the transactionCode requested doesn't exist the request will not be processed.

{
  "amount": 10.21,
  "folioId": 1,
  "transactionCode": "DB",
  "receivablesAccountId": "HA12345"
}

Pre-Post

Pre Post Room Charge

To ensure successful pre posting of a Room Charge on an account, the request should contain the below information:

  1. Add postDuringNightAudit flag to true or false based on if Room Charge should be posted again during Night Audit in the Pre Post request. By-default it's false.

Note: The API will validate if the accountType is GUEST_ACCOUNT since pre-post is not supported for other Account Types.

{
  "postDuringNightAudit": true
}

Email Folios

Email Folio or multiple folios to an email or multiple emails.

To ensure successful emailing of folios on an account, the request should contain the below information:

  1. Add folioIds as a request param in the Email Folios request.
  2. Add emailIds as a request param in the Email Folios request.

Note: The API will validate if the folioIds are valid like 1, 2, 3, 4, 5 for regular folios, 8 for package folio and between 101 and 110 for additional guest also if the emailIds requested are valid per the pattern provided in spec.

Get Folio Summary

Display folio summary

To ensure successful folio summary retrieval, the request should contain the six default parameters descriped the top of the document.

[GET] /service/v1/folio/{account}/folios-summary?accountType=Guest

Get Folios Transactions

Display folios transactions

To ensure successful folio summary retrieval, the request should contain the six default parameters descriped the top of the document.

[GET] /service/v1/folio/{account}/transactions?accountType=Guest

Update Transaction Description

Update transaction description

To ensure successful update transaction description, the request should contain the below information as well as the six default parameters descriped the top of the document:

  1. Add transactionGUID as a request param in the Update Transaction Description request.
  2. Add updatedDesc as a request param in the Update Transaction Description request.

[PATCH] /service/v1/folio/{account}/transactions/{transactionGUID}?accountType=Guest&updatedDesc=NewDescription

Get Hotel Details

Display hotel details

To ensure successful hotel details retrieval, the request should contain the below information:

  1. Add tenantId in the View Hotel Details request header.
  2. Add chainId in the View Hotel Details request header.
  3. Add hotelId in the View Hotel Details request header.
  4. Add vendorCode in View Hotel Details request header.

Note: The API will validate if the vendorCode is configured for combination of given chainId and hotelId before retrieving it.

[GET] /service/v1/hotel-details

View Credit card logs

This API returns the list of credit card transactions

To ensure successful credit logs' retrieval, the request should contain all the basic information that mentioned at the top.

View Folios Routing :

[GET] /service/v1/folio/{account}/routing

  • This API returns the routing details on the folio .
  • In case of no routing on the folio returns the message, "No Routing on the folios requested for the account".
  • In case the fetching of routing details is not successful returns the message, "Unable to view routing details".

Payment Methods APIs

To manage the payment method in the Guest folio in SPH.

Get Payment methods

[GET] /service/v1/folio/{account}/payment-methods

This API returns the payment methods assigned to all the folios of the selected reservation.

Add Payment method

[POST] /service/v1/folio/{account}/payment-methods

Request body:

The AddPaymentMethodRequest request object.

This API will validate the json for :

  • paymentMethod is not empty.
  • paymentCode is not empty
  • guaranteeType is not empty and is one of the values - CASH, CC , VCC or DB.
  • If the guaranteeType is DB or VCC , receivablesAccountId cannot be empty.
  • If the guaranteeType is CC , cardType, creditCardToken and creditCardExpirationDate cannot be empty.

Note: Please refer to Model specification for much detailed description of each attribute.

Sample jsons for AddPaymentMethodRequest object for various payment methods:

Cash : CASH

{
  "cardType": "CASH",
  "guaranteeType": "CASH",
  "paymentCode": "CASH",
  "paymentMethod": "CASH"
}

Credit card : CC

To add a payment method of type credit card , the API will validate the cardType, creditCardToken, creditCardExpirationDate are passed as specified in the Model spec .

{
  "creditCardToken": "ID:777735176205553",
  "cardType": "MC",
  "creditCardExpirationDate": "1225",
  "debit": false,
  "folio": 0,
  "groupRsv": false,
  "guaranteeCodeDescription": "MASTERCARD",
  "guaranteeType": "CC",
  "managePayment": false,
  "paymentCode": "MC",
  "paymentMethod": "MC"
}

Direct Bill : DB

{
  "cardType": "DIRECT BILL",
  "guaranteeType": "DB",
  "paymentCode": "DIRECT BILL",
  "paymentMethod": "DIRECT BILL",
  "receivablesAccountId": "200626726H",
  "virtualCard": false
}

Virtual credit card : VCC

To add a payment method of type VCC , the API will validate if the virtualCard is passed as true and receivablesAccountId is not empty.

{
  "cardType": "VCC",
  "guaranteeType": "VCC",
  "managePayment": true,
  "paymentCode": "VCC",
  "paymentMethod": "VCC",
  "primary": null,
  "receivablesAccountId": "WDRGS612",
  "virtualCard": true
}

Edit Payment method

[PUT] /service/v1/folio/{account}/payment-methods

This API will validate the json for :

  • paymentMethod is not empty.
  • folioId is not empty.
  • itemId is not empty. The itemID is a sequence number for each payment method assigned to the account . First entry is 100 , second entry for the same payment method is 101.

Sample jsons :

To update a payment method as primary : primary should be set to true and folioId should be set to -1.

(Update the DIRECT BILL payment method as primary)

{
  "debit": false,
  "folioId": -1,
  "itemId": 100,
  "paymentCode": "DIRECT BILL",
  "primary": true,
  "projectNumber": "",
  "virtualCard": false
}

To update the payment method of type VCC :

(Assign the VCC payment method to Folio 2)

{
  "debit": false,
  "folioId": 2,
  "itemId": 100,
  "paymentCode": "VCC",
  "primary": false,
  "projectNumber": "TEST123",
  "virtualCard": true
}

To update payment method of type CASH :

(Assign the CASH payment method to Folio 3)

{
  "folioId": 3,
  "itemId": 100,
  "paymentCode": "CASH",
  "primary": false
}

Delete Payment method

[DELETE] /service/v1/folio/{account}/payment-methods

Sample jsons :

To remove a payment method of type CASH :

{
  "account": "CNF12345",
  "accountType": "guest",
  "paymentMethod": "CASH",
  "sequence": 100
}

To remove a payment method of type DIRECT BILL:

{
  "account": "CNF123845",
  "accountType": "guest",
  "paymentMethod": "DIRECT BILL",
  "sequence": 100
}

View House Account Details

View House Account Details

To ensure successful house account details retrieval, the request should contain the below information:

  1. Add tenantId in the View House Account Details request header.
  2. Add chainId in the View House Account Details request header.
  3. Add hotelId in the View House Account Details request header.
  4. Add vendorCode in View House Account Details request header.
  5. Add account in View House Account Details request header

Note: The API will validate if the vendorCode is configured for combination of given chainId and hotelId before retrieving it.

[GET] /service/v1/folio/{account}/houseAccountDetails

Update House Account Details

To ensure successful updation of house account details, the request should contain the below information:

  1. Add tenantId in the Update House Account Details API request header.
  2. Add chainId in the Update House Account Details API request header.
  3. Add hotelId in the Update House Account Details API request header.
  4. Add vendorCode in Update House Account Details API request header.
  5. Add account which is the house account Id in Update House Account Details API request header.

Note: The API will validate if the vendorCode is configured for combination of given chainId and hotelId before retrieving it.

The UpdateHouseAccountDetailsRequest json request object - contains the attributes to be updated in the house account.

This API will validate the json for:

  • houseAccountName is not empty.
  • Length of the houseAccountName is not more than 15 characters.
  • Length of the houseAccountDescription is not more than 50 characters.
  • email is valid as per the pattern provided in the spec.
  • Length of the phoneNumber is not more than 15 characters.
  • Length of the phoneExtension is not more than 10 characters.

Note: Please refer to Model specification for much detailed description of each attribute in the UpdateHouseAccountDetailsRequest object.

Cannot update the house account status to inactive: If there are interfaces are associated with the house [ Error message: Cannot De-activate an Associated House Account] (or) If there are routings associated with the account. [ Error message: Cannot De-activate a House Account associated with Routing]

[POST] /service/v1/folio/{account}/update-house-account-details

Sample json :

To update a house account :

{
  "active": true,
  "email": "ben@test.com",
  "firstName": "Ben",
  "houseAccountDescription": "This is house account description",
  "houseAccountName": "Manifest",
  "lastName": "Stone",
  "phoneContacts": [
    {
      "phoneNumber": "585689895689",
      "phoneExtension": "784",
      "phoneType": "BUSINESS",
      "primary": true,
      "order": 1
    },
      {
      "phoneNumber": "676767",
      "phoneExtension": "78",
      "phoneType": "MOBILE",
      "primary": false,
      "order": 2
    }
  ]
}