Webservices
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 |