Adapter - E Visitor Authentication
This page describes version 2.0.5 of the adapter.
Overview
The E Visitor Authentication adapter is a specialized adapter that connects to two different API sources provided by the Singapore Tourism Board (STB). The first connection uses the OAUTH API Host Address, the STB provided API Key, the STB provided Client ID and the STB provided Client secret to obtain an authorization or bearer token. This token is used with the second connection defined in the E-Visitor Authentication API Host Address field to send guest information to the Singapore Tourism board upon checking into the hotel. For information regarding error codes and their meanings returned by the E-Visitor Authentication API please reference the Interface between STB adn Hotel's System guide provided by STB.
Properties
| Name | Display | Is Required | Comments | Type | Default Value | Maximum Value | Minimum Value | Maximum Length | Minimum Length |
|---|---|---|---|---|---|---|---|---|---|
| checkInUri | E-Visitor Check-in API URL | True | The URL for the Singapore Tourism Board API service and port. If the port is unspecified, the default will be assumed. https - 443, http - 8080. | string | https://api.stb.gov.sg:443/services/eva/v1/visitors/transactions | 1024 | |||
| apiKey | E-Visitor Authentication API Key | True | The API Key necessary to access the Visitor API service. | password | 1024 | ||||
| hotelCode | Hotel ID | True | Hotel ID refers to the hotel's license number as issued by the Hotel Licensing Board (HLB). | string | 5 | ||||
| accessTokenUri | OAUTH Access Token API Host URL | True | The URL for the Singapore Tourism Board OAUTH service and port. If the port is unspecified, the default will be assumed. https - 443, http - 8080. | string | https://api.stb.gov.sg:443/oauth/accesstoken | 1024 | |||
| clientId | API Consumer Key | True | The ID provided by the Singapore Tourism Board following the registration process used to create authorization token. | string | 1024 | ||||
| clientSecret | API Consumer Secret | True | The Secret provided by the Singapore Tourism Board following the registration process used to create authorization token. | password | 1024 |
Configuration
Currently all configuration properties are required and the connection only supports a secure https:// configuration using port 443 for both connections. The default FQDN host addresses suggested by the configuration are the current addresses provided by the Singapore Tourism Board and should be used unless STB publishes new ones.
Commands
Visitor Check In (visitorCheckIn)
Send guest data to Singapore Tourism Board for E-Visitor Authentication.
Request Properties
| Name | Display | Description | Is Required | Type |
|---|---|---|---|---|
| guestName | Guest Name | Name of Visitor from passport. | True | string |
| nationality | Nationality Code | Nationality code from passport. | True | string |
| passportNumber | Passport Number | Passport Number from passport. | True | string |
| dateOfBirth | Date of birth | Date of Birth Format: YYYYMMDD, YYYYMM00, YYYY0000, or YYYY-MM-DD. | True | string |
| checkInDate | Check In Date | Date of guest check in Format: YYYYMMDD, YYYY-MM-DD. | True | string |
| checkOutDate | Check Out Date | Date of guest check out Format: YYYYMMDD, YYYY-MM-DD. | True | string |
| bookingId | Booking ID | The guest's booking id. | True | string |
| imgPhoto | Kiosk Photo Image | Base64 string of photo that is taken on the spot at the hotel check-in counter. | True | string |
| imgScannedTd | Scanned Passport Image | Base64 string of image of passport scanned. | True | string |
| imgRef | Cropped Passport Photo | Base64 string of image of cropped photo from passport scanned that is used to compare with Photo of the Day. | True | string |
| manualInput | Was data manually input? | To indicate if guest data is manually input true: Guest data was manually entered false: if otherwise. False is the default setting. | False | string |
| gender | Gender | A single character gender code. Acceptable gender codes : F, M, O, U, X. F - Female, M - Male, O - Unspecified, U - Unspecified, X - Unspecified. | False | string |
| passportType | Passport Type Code | A single digit code to indicate passport type. Acceptable passport type codes: B, I, N. B - Biometric, I - ICAO, N - Non-ICAO. | False | string |
| mrzData | (MRZ) Data. | Raw Machine Readable Zone (MRZ) Data. | False | string |
| kioskId | Kiosk ID | The ID of the kiosk where the check in took place. | False | string |
| kioskUserId | Kiosk User ID | ID of user logged in to Kiosk to provide Kiosk ID if information is not available. | False | string |
| staffName | Staff Name | Name of Hotel Staff. *If kioskId and kioskUserId are populated, nameStaff and idNoStaff are not mandatory. Applicable if the check-in process was intervened by a staff to complete. | False | string |
| staffId | Staff ID | Name of Hotel Staff. *If kioskId and kioskUserId are populated, nameStaff and idNoStaff are not mandatory. Applicable if the check-in process was intervened by a staff to complete. | False | string |
Response Properties
| Name | Description | Type |
|---|---|---|
| data.responseDateTime | The date and time the response was returned from STB. | string |
| data.resultCode | Code indicating the status of the results. | string |
| data.stbEvaTransactionId | Unique transaction ID created by STB for corresponding between Hotel, STB and ICA Format: STBEVA034120210128152815115. | string |
| data.errorCodeList | Validation errors returned for the transaction or the fields if there are any. | array |
| data.errorMsg | Implemented if additional error messaging is needed in the response. | string |
| createdAt | Time stamp of the transaction record created Format: 2021-01-28T07:28:15.118+08:00. | string |
| status.code | HTTP Code - 200,- 400,- 401,- 404,- 405,- 414,- 415,- 422,- 500. | string |
| status.errorCodeList | Validation errors returned for the transaction or the fields if there are any. | array |
| status.message | Status Message Returned from E-Visitor Authentication Service regarding the transaction. | string |
| code | Adapter failure code returned from the adapter. | string |
| error | Adapter error message returned from the adapter. | string |
Release History
| Version | Type | Description | Tracking # | Date |
|---|---|---|---|---|
| 2.0.1 | Initial(E-Visitor Authentication) | First release in the Adapter Type store. | ||
| 2.0.3 | Bug fix & Maintenance | Adapter did not load and trust UIP Trusted CA certificates. Updated third-party components and improved maintainability. |
NAP-23861 NAP-23945 |
2022-11-29 |
| 2.0.4 | Bug fix | Added debugging info and increased retries for Authtoken calls. | NAP-24610 | 2022-12-19 |
| 2.0.5 | Bug fix | Include an User-Agent header in the HTTPS requests sent to EVA/STB | NAP-27214 | 2023-10-20 |