Skip to content

Services

This chapter describes the webservices that are to be provided by the payment provider.

Authentication

Authentication is realized via JWT tokens.

Login Request

To request a token the login endpoint is called with a username and password.

POST /login

Fields for login:

Field name Description Usage
username User name Mandatory
password password Mandatory

Login Response

The following fields are sent in the response to the token-creation request:

Field name Description
username User name
roles Array of roles defined
access_token Validity date of the token, ISO-8601
token_type Bearer
expires_in Seconds to expiry of the access_token

Example for login

Address:

https://test-token-eu.sihot.com/login

Body:

{
  "username": "sherlock",
  "password": "QwZw49J7TtSWuqy4XeYq",
}

Response:

{
  "username": "sherlock",
  "roles": ["USER"],
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzaGVybG9jayIsIm5iZiI6MTYwOTE3MzQ1NSwicm9sZXMiOlsiUk9MRV9ERVRFQ1RJVkUiXSwiaXNzIjoia2V5cGFzcyIsImV4cCI6MTYwOTE3NzA1NSwiaWF0IjoxNjA5MTczNDU1fQ.SRQkYoFIHJeEPWvUVrikOTpDic4QaiI6Vi8nEx8-F0s",
  "token_type": "Bearer",
  "expires_in": 3600
}

Creating a token

Path for creating a token:

POST /V2/$customer/createToken

Request

Fields for creating a token:

Field name Description Usage
cardNo Credit card number Mandatory
valid Validity date of the card, ISO-8601 Mandatory
user SIHOT.PMS user ID Mandatory
datetime Timestamp of the transaction Mandatory
cvc CVC-Number Optional
authorize Flag for Pre-Authorization Optional
currency Currency for Pre-Authorization Optional
cardType Type of the Card Optional
cardTypeCode Type of the Card Optional
transactionID Transaction ID from Payment Provider Optional
serviceProvider The service provider to use
cardText Credit card text Mandatory for some providers

If no currency is sent, the default currency for this property is used.

A card validation e.g., using a pre-authorization is required if field "authorize" isn’t sent or is "true". Otherwise, the "authorize" field must be "false".

Response

The following fields are sent in the response to the token-creation request:

Field name Description
tokenNo Token number
tokenRefID ShopperReference
tokenExpiry Validity date of the token, ISO-8601
tokenCVC Token for CVC number (optional)
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
serviceProvider ServiceProvider used for this action
cardTypeCode Card type as defined by Payment Provider
cardType Card type as defined by SIHOT (optional)

Payment

Path for making a payment:

POST /V2/$customer/pay

You can send a negative amount in the request. In this case a refund will be done.

Note: Not all providers allow negative payments, without a payment reference. Refer to the "reversal" method instead.

Request

Fields needed to settle a payment:

Field name Description Usage
tokenNo Token number Mandatory
tokenRefID ShopperReference Mandatory for some Providers
currency Currency as 3-digit ISO-Code Mandatory
amount Amount in lowest unit, e.g. Cent Mandatory
user SIHOT.PMS user ID Mandatory
datetime Timestamp of the transaction Mandatory
text Custom text to be annexed to the transaction Optional
resNo Reservation number linked to payment Optional
serviceProvider ServiceProvider to use for this action Optional

Response

The following fields are sent in the response to the payment request:

Field name Description
transactionID Transaction ID of the payment
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
serviceProvider ServiceProvider used for this action
cardType Type of the used card
cardNo Masked number of the card (not all providers return this information)

Reversal of payment

Path for making a reversal (cancel payment):

POST /V2/$customer/reversal

Used for cancelling settled authorizations or payments.

Request

Field name Description Usage
transactionID Transaction ID of the payment Mandatory
user SIHOT.PMS user ID Mandatory
datetime Timestamp of the transaction Mandatory
currency Currency as 3-digit ISO-Code Optional
amount Amount in lowest unit, e.g. Cent Optional
authorizationCode Authorization code returned from the authorization request Optional
text Custom text to be annexed to the transaction Optional
serviceProvider ServiceProvider to use for this action Optional

Response

Field name Description
transactionID Transaction ID of the payment
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
serviceProvider ServiceProvider used for this action
cardType Type of the used card

Authorization

Path for making an authorization:

POST /V2/$customer/authorize

Request

Fields needed to request an authorization

Field name Description Usage
tokenNo Token number Mandatory
tokenRefID ShoppferReference Mandatory for some Providers
currency Currency as 3-digit ISO-Code Mandatory
amount Amount in lowest unit, e.g. Cent Mandatory
user SIHOT.PMS user ID Mandatory
datetime Timestamp of the transaction Mandatory
text Custom text to be annexed to the transaction Optional
resNo Reservation number to link payment Optional
serviceProvider ServiceProvider to use for this action Optional

Response

The following fields are sent in the response to the authorization request:

Field name Description
authorizationCode Authorization Code
transactionID Transaction ID of the payment
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
serviceProvider ServiceProvider used for this action
cardType Type of the used card
cardNo Masked number of the card

Settle Authorization

Path for settling an authorization:

POST /V2/$customer/settleAuthorization

Request

Fields needed to settle an authorization:

Field name Description Usage
transactionID Transaction ID of the authorization Mandatory
user SIHOT.PMS user ID Mandatory
datetime Timestamp of the transaction Mandatory
authorizationCode Authorization code returned from the authorization request Optional
text Custom text to be annexed to the transaction Optional
serviceProvider ServiceProvider used for this action Optional

Response

The following fields are sent in the response to the payment request:

Field name Description
transactionID Transaction ID of the authorization
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
serviceProvider ServiceProvider used for this action

Cancel Authorization

Path for cancelling an authorization:

POST /V2/$customer/cancelAuthorization

Used for canceling authorizations, which are not settled yet.

Request

Fields needed for cancelling an authorization:

Field name Description Usage
transactionID Transaction ID of the authorization Mandatory
user SIHOT.PMS user ID Mandatory
datetime Timestamp of the transaction Mandatory
authorizationCode Authorization code returned from the authorization request Optional
text Custom text to be annexed to the transaction Optional
serviceProvider ServiceProvider used for this action Optional

Response

Field name Description
transactionID Transaction ID of the authorization
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
serviceProvider ServiceProvider used for this action

Init Pay

Path for initializing a payment with credit card present

POST /V2/$customer/initpay

Used for eCommerce and Terminal integrations

Request

Fields needed for initializing:

Field name Description Usage
securityID Required for callback functionality Mandatory
cardInfoRefID Reference ID from PMS Mandatory
amount Amount to be collected Mandatory
currency Currency for the transaction Mandatory
commitCallbackUrl Call back URL for a successful payment Mandatory
abortCallbackUrl Call back URL for a failed transaction Mandatory
resNo Booking reference of PMS Optional
cardText Optional
description Additional information from PMS Optional
datetime Timestamp of the transaction Mandatory
hotelID ID of the property Optional
hotelIDType ID type of the property Optional
user SIHOT user Mandatory
emvTerminal Terminal ID mandatory for terminal integration Optional
serviceProvider ServiceProvider used for this action Mandatory

Response

Field name Description
transactionID Transaction ID of the authorization
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
dateTime Timestamp of the transaction
requestID Request ID of the Payment Provider
viewUrl URL for the payment page / terminal display
stateRetrivalUrl URL for paystatus requests
serviceProvider ServiceProvider used for this action

Init Auth

Path for initializing a payment with credit card present

POST /V2/$customer/initauth

Used for eCommerce and Terminal integrations

Request

Fields needed for initializing:

Field name Description Usage
securityID Required for callback functionality Mandatory
cardInfoRefID Reference ID from PMS Mandatory
amount Amount to be collected Mandatory
currency Currency for the transaction Mandatory
commitCallbackUrl Call back URL for a successful payment Mandatory
abortCallbackUrl Call back URL for a failed transaction Mandatory
resNo Booking reference of PMS Optional
cardText Optional
description Additional information from PMS Optional
datetime Timestamp of the transaction Mandatory
hotelID ID of the property Optional
hotelIDType ID type of the property Optional
user SIHOT user Mandatory
emvTerminal Terminal ID mandatory for terminal integration Optional
serviceProvider ServiceProvider used for this action Mandatory

Response

Field name Description
transactionID Transaction ID of the authorization
returnCode Error code
returnCodeSP Error code from the service provider
returnTextSP Response text from the service provider
returnText Response text from the tokenization service
dateTime Timestamp of the transaction
requestID Request ID of the Payment Provider
viewUrl URL for the payment page / terminal display
stateRetrivalUrl URL for paystatus requests
serviceProvider ServiceProvider used for this action

Pay status

Path for request status information from the payment page / terminal backend.

GET /V2/$customer/paystatus?requestid&serviceProvider=spayengine

Used for eCommerce and Terminal integrations

Request

Query parameter Description
requestid RequestID from response of initpay/initauth
serviceProvider Service provider as referenced in SIHOT.PAYENGINE

Response

Field name Description
state State of the transaction
result Additional info for PMS e.g. error messages

Possible states

Code Description
0 In progress
1 Success
2 Error