PAYENGINE Web Services – API Reference

Full documentation for every core API endpoint.
All field types, required/optional markers, and copy-paste examples are included.

MOTO Endpoints

POST /V2/{customerID}/createToken

Description: Tokenizes a credit card for later payment. Caller must be PCI DSS-compliant.

Request Fields

Field	Type	Required	Description
cardNo	string	Yes	Full card number
valid	string	Yes	Expiry date (YYYY-MM-DD)
cvc	string	No	Card verification code
hotelID	string	Yes	Property identifier
hotelIDType	string	Yes	Property type (e.g., SIHOT.PMS)
user	string	Yes	User performing operation
datetime	string	Yes	ISO-8601 date/time
cardText	string	No	Cardholder name
cardType	string	No	SIHOT card type code (see appendix)
cardTypeCode	string	No	Provider card type (see appendix)
transactionID	string	No	Reference for this tokenization
serviceProvider	string	Yes	Payment provider name

Example Request

{
  "cardNo": "4242424242424242",
  "valid": "2026-03-30",
  "cvc": "123",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-06-01T10:00",
  "cardText": "John Doe",
  "serviceProvider": "windcave"
}

Response Fields

Field	Type	Description
tokenNo	string	Tokenized card number
tokenExpiry	string	Token expiry date (YYYY-MM-DD)
cardType	string	SIHOT card type code
cardTypeCode	string	Provider card type code
cardNo	string	Masked card number
transactionID	string	Transaction reference
serviceProvider	string	Provider used
returnCode	string	"0" for success

Example Response

{
  "tokenNo": "0000040000289815",
  "tokenExpiry": "2026-03-31",
  "cardType": "4",
  "cardTypeCode": "visa",
  "cardNo": "424242......4242",
  "transactionID": "00000004000aaea1",
  "serviceProvider": "windcave",
  "returnCode": "0"
}

POST /V2/{customerID}/pay

Description: Charges a payment using a previously created token.

Request Fields

Field	Type	Required	Description
tokenNo	string	Yes	Token returned by createToken
amount	string	Yes	Amount in smallest unit (e.g. cents)
currency	string	Yes	ISO-4217 3-letter code
hotelID	string	Yes	Property identifier
hotelIDType	string	Yes	Property type
user	string	Yes	User
datetime	string	Yes	ISO-8601 date/time
text	string	No	Payment description
resNo	string	No	Reservation number
serviceProvider	string	Yes	Payment provider
supportedFeatures	string	No	List of features to use.

Example Request

{
  "tokenNo": "0000040000289815",
  "amount": "2000",
  "currency": "EUR",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-06-01T10:05",
  "text": "Payment for Reservation",
  "serviceProvider": "windcave",
  "supportedFeatures": "tip"
}

Response Fields

Field	Type	Description
transactionID	string	Payment transaction ID
cardType	string	SIHOT card type code
cardNo	string	Masked card number
cardTypeCode	string	Provider card type code
serviceProvider	string	Payment provider
returnCode	string	"0" for success
amount	integer	Total amount in smallest unit (e.g. cents)
amountSurcharge	integer	Surcharge amount in smallest unit (e.g. cents)
amountTip	integer	Tip amount in smallest unit (e.g. cents)
surchargeApplied	boolean	iF `true` then the amount includes the surcharge amount already.
surchargePercentUsed	decimal	The percentage of the surcharge (e.g. `5.5` for 5.5 %)

Example Response

{
  "cardType": "4",
  "cardNo": "424242......4242",
  "cardTypeCode": "visa",
  "serviceProvider": "windcave",
  "transactionID": "00000003004e22ac",
  "returnCode": "0",
  "amount": 2000,
  "surchargeApplied": false
}

POST /V2/{customerID}/reversal

Description: Cancels (refunds) a payment.

Request Fields

Field	Type	Required	Description
transactionID	string	Yes	ID of transaction to reverse
user	string	Yes	User
datetime	string	Yes	ISO-8601 date/time
currency	string	No	Currency (if needed)
amount	string	No	Amount to reverse
hotelID	string	Yes	Property identifier
hotelIDType	string	Yes	Property type
serviceProvider	string	Yes	Provider name
text	string	No	Description

Example Request

{
  "transactionID": "00000003004e22ac",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-06-01T10:10",
  "currency": "EUR",
  "amount": "2000",
  "serviceProvider": "windcave"
}

Response Fields

Field	Type	Description
transactionID	string	Reversal transaction ID
cardType	string	SIHOT card type code
serviceProvider	string	Provider
returnCode	string	"0" for success

Example Response

{
  "cardType": "4",
  "serviceProvider": "windcave",
  "transactionID": "00000003004e22ae",
  "returnCode": "0"
}

POST /V2/{customerID}/authorize

Description: (Optional) Pre-authorizes an amount with the card/token.

Request Fields

(Same as /pay, but intended for pre-authorization; see appendix for all fields)

POST /V2/{customerID}/settleAuthorization

Description: Captures a previously authorized amount.

Request Fields

Field	Type	Required	Description
transactionID	string	Yes	Authorization transaction ID
user	string	Yes	User
datetime	string	Yes	ISO-8601 date/time
authorizationCode	string	No	From provider, if needed
text	string	No	Description
serviceProvider	string	No	Provider name
tokenNo	string	No	Token used for authorization
tokenExpiry	string	No	Token expiry
cardType	string	No	SIHOT card type
cardTypeCode	string	No	Provider card type
maskedCardNo	string	No	Masked card number
supportedFeatures	string	No	List of features to use.

Example Request

{
  "transactionID": "F1022CBA-C2E7-45EB-AC6D-533C788EF91E",
  "authorizationCode": "614082",
  "currency": "EUR",
  "amount": "200",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-06-01T10:20",
  "text": "Capture for Reservation",
  "serviceProvider": "windcave",
  "tokenNo": "0000040000289815",
  "tokenExpiry": "2026-03-31",
  "cardType": "4",
  "cardTypeCode": "visa",
  "maskedCardNo": "424242......4242",
  "supportedFeatures": ""
}

Response

Field	Type	Description
transactionID	string	Settlement transaction ID
returnCode	string	"0" for success
serviceProvider	string	Provider
amount	integer	Total amount in smallest unit (e.g. cents)
amountSurcharge	integer	Surcharge amount in smallest unit (e.g. cents)
amountTip	integer	Tip amount in smallest unit (e.g. cents)
surchargeApplied	boolean	iF `true` then the amount includes the surcharge amount already.
surchargePercentUsed	decimal	The percentage of the surcharge (e.g. `5.5` for 5.5 %)

Example Response

{
  "returnCode": "0",
  "transactionID": "F1022CBA-C2E7-45EB-AC6D-533C788EF91E",
  "serviceProvider": "windcave",
  "amount": 200,
  "surchargeApplied": false
}

POST /V2/{customerID}/cancelAuthorization

Description: Cancels a pre-authorization.

Request Fields

Field	Type	Required	Description
transactionID	string	Yes	Authorization transaction ID
user	string	Yes	User
datetime	string	Yes	ISO-8601 date/time
authorizationCode	string	No	From provider, if needed
text	string	No	Description
serviceProvider	string	No	Provider name
tokenNo	string	No	Token used for authorization
tokenExpiry	string	No	Token expiry
cardType	string	No	SIHOT card type
cardTypeCode	string	No	Provider card type
maskedCardNo	string	No	Masked card number

Example Request

{
  "transactionID": "F1022CBA-C2E7-45EB-AC6D-533C788EF91E",
  "authorizationCode": "614082",
  "currency": "EUR",
  "amount": "200",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-06-01T10:20",
  "text": "Capture for Reservation",
  "serviceProvider": "windcave",
  "tokenNo": "0000040000289815",
  "tokenExpiry": "2026-03-31",
  "cardType": "4",
  "cardTypeCode": "visa",
  "maskedCardNo": "424242......4242"
}

Response

Field	Type	Description
transactionID	string	Settlement transaction ID
returnCode	string	"0" for success
serviceProvider	string	Provider

Example Response

{
  "returnCode": "0",
  "transactionID": "F1022CBA-C2E7-45EB-AC6D-533C788EF91E",
  "serviceProvider": "windcave"
}

eCommerce & Terminal Endpoints

POST /V2/{customerID}/initpayNoIframe

Description: Initiate a payment for HPP or terminal. Returns a URL for the payment page/terminal.

Request Fields

Field	Type	Required	Description
hotelID	string	No	Property identifier
hotelIDType	string	No	Property type (e.g., SIHOT.PMS)
user	string	Yes	SIHOT user ID
datetime	string	Yes	ISO-8601 date/time
serviceProvider	string	Yes	Payment provider name
amount	string	Yes	Amount in smallest unit (e.g., cents)
currency	string	Yes	3-letter ISO code
cardInfoRefID	string	Yes	Reference from PMS
resNo	string	No	Reservation number
cardText	string	No	Cardholder name (optional)
description	string	No	Additional info
callbackSuccessUrl	string	Yes	Callback URL for success
callbackAbortUrl	string	Yes	Callback URL for abort
emvTerminal	string	No	Terminal ID (required for terminal integration)
customerInfo	object	No	End customer data, see below
supportedFeatures	string	No	List of features to use.

customerInfo (object, optional)

Why is `customerInfo` required?

The customerInfo block is included in requests for eCommerce Hosted Payment Page (HPP) integrations because some payment service providers (PSPs)—as well as special requirements from networks such as VISA and Mastercard—require additional end-customer data for security, fraud prevention, or compliance reasons. Whether this block is required depends on the selected PSP and project configuration.

Note: The customerInfo block is only relevant for endpoints providing a Hosted Payment Page (HPP). For physical or virtual terminal integrations, this data is ignored.

Best Practice: We recommend always supplying as much customer information as is available (especially mobile phone number and email address), even if not currently enforced by your PSP. This proactive approach helps avoid major integration changes later, should your PSP requirements change, or if you switch to another provider that mandates this data.

Please note that certain data points, specifically the mobile phone number and email address, are often used by payment networks or providers for enhanced security checks (such as Strong Customer Authentication or fraud scoring).

In summary:

Check with your payment provider for exact requirements.
Providing customerInfo is strongly recommended to ensure future-proof integration and maximize transaction acceptance.

customerInfo (object, optional)

Field	Type	Required	Description
mobilePhone	string	no	Mobile phone number
landPhone	string	no	Landline phone number
email	string	no	Email address
firstName	string	no	First name
lastName	string	no	Last name
companyName	string	no	Company name
address	object	no	See address fields below

Note: All fields are optional and can be omitted if not available. See address for address details.

address (Object, optional)

Field	Type	Required	Description
street1	string	no	Address line 1
street2	string	no	Address line 2 (optional)
street3	string	no	Address line 3 (optional)
city	string	no	City
country	string	no	Country code (2-letter ISO)
postalCode	string	no	Postal code
state	string	no	State/region

Example Request

{
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "WEBUSER",
  "datetime": "2025-06-01T11:00:00",
  "serviceProvider": "spayengine",
  "amount": "2000",
  "currency": "EUR",
  "cardInfoRefID": "2270",
  "resNo": "20008505/1",
  "callbackSuccessUrl": "https://yourapp/success",
  "callbackAbortUrl": "https://yourapp/failure",
  "description": "Online payment",
  "customerInfo": {
    "mobilePhone": "+491701234567",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street1": "Musterstr. 1",
      "city": "Berlin",
      "country": "DE",
      "postalCode": "12345",
      "state": "Berlin"
    }
  }
}

Response Fields

Field	Type	Description
viewUrl	string	Payment page/terminal URL
requestID	string	Payment request reference
dateTime	string	Timestamp
stateRetrivalUrl	string	Status polling URL
returnCode	string	"0" for success
serviceProvider	string	Provider used
transactionID	string	Transaction ID (may be present in some cases)

Example Response

{
  "viewUrl": "https://service.stage.payengine.sihot.com/0000/spayengine/payment?PD=...",
  "requestID": "0a64c038-82f3-1c79-8183-14d9babb0018",
  "dateTime": "2025-06-01T11:00:00",
  "stateRetrivalUrl": "https://service.stage.payengine.sihot.com/0000/paystatus?requestid=0a64c038-82f3-1c79-8183-14d9babb0018&serviceProvider=spayengine",
  "returnCode": "0",
  "serviceProvider": "spayengine"
}

POST /V2/{customerID}/initCreateTokenNoIframe

Description: Initiate a tokenization session (browser or terminal) and receive a URL for the user to complete the process.

Request Fields

Field	Type	Required	Description
hotelID	string	No	Property identifier
hotelIDType	string	No	Property type (e.g., SIHOT.PMS)
user	string	Yes	SIHOT user ID
datetime	string	Yes	ISO-8601 date/time
serviceProvider	string	Yes	Payment provider name
cardText	string	No	Cardholder name
resNo	string	No	Reservation number
description	string	No	Additional info
cardRefID	string	Yes	Card reference from third party (e.g. SIHOT.PMS)
accountNo	number	No	Account number (long, optional)
callbackSuccessUrl	string	Yes	Callback URL for success
callbackAbortUrl	string	Yes	Callback URL for abort
tokenType	string	no (default: "eCommerce")	Specifies the type of tokenization: "eCommerce" (default, with 3DS/PSD2) or "moto" (MOTO/telephone order, 3DS/PSD2 disabled).
theme	string	No	"bright", "dark", or empty (optional)
emvTerminal	string	No	Terminal ID (required for terminal integration)
customerInfo	object	No	End customer data, see /initpayNoIframe

The tokenType field indicates whether the tokenization process should be handled as an eCommerce scenario (such as web shop or online booking, which is the default), or as a MOTO (Mail Order/Telephone Order) scenario.

"eCommerce": Tokenization for regular online transactions (with 3DS/PSD2 if enabled)

"moto": Tokenization for MOTO transactions (without 3DS/PSD2, higher risk, only for PCI-compliant systems)

Default: "eCommerce" if not supplied.

Warning: Using "moto" disables strong customer authentication. Only use if your business and technical process is fully PCI DSS compliant. Warning: Not all payment service provider allow the tokenType "moto" and ignore the hint.

Example Request

{
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "WEBUSER",
  "datetime": "2025-06-01T11:05:00",
  "serviceProvider": "spayengine",
  "cardText": "John Doe",
  "resNo": "20008505/1",
  "accountNo": 5678,
  "cardRefID": "2271",
  "callbackSuccessUrl": "https://yourapp/success",
  "callbackAbortUrl": "https://yourapp/failure",
  "tokenType": "eCommerce",
  "theme": "dark",
   "customerInfo": {
    "mobilePhone": "+491701234567",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street1": "Musterstr. 1",
      "city": "Berlin",
      "country": "DE",
      "postalCode": "12345",
      "state": "Berlin"
    }
  }
}

Response Fields

Field	Type	Description
viewUrl	string	Tokenization page/terminal URL
requestID	string	Tokenization request reference
dateTime	string	Timestamp
stateRetrivalUrl	string	Status polling URL
returnCode	string	"0" for success
serviceProvider	string	Provider used
transactionID	string	Transaction ID (may be present in some cases)

Example Response

{
  "viewUrl": "https://service.stage.payengine.sihot.com/0000/spayengine/create?PD=...",
  "requestID": "c0a802bb-81ca-12b8-8181-cae2ea2c0000",
  "dateTime": "2025-06-01T11:05:00",
  "stateRetrivalUrl": "https://service.stage.payengine.sihot.com/0000/paystatus?requestid=c0a802bb-81ca-12b8-8181-cae2ea2c0000&serviceProvider=spayengine",
  "returnCode": "0",
  "serviceProvider": "spayengine"
}

POST /V2/{customerID}/initauthNoIframe

Description: Initiate an authorization flow (HPP/terminal). Returns a URL for the user to complete authorization.

Request Fields

Field	Type	Required	Description
hotelID	string	No	Property identifier
hotelIDType	string	No	Property type (e.g., SIHOT.PMS)
user	string	Yes	SIHOT user ID
datetime	string	Yes	ISO-8601 date/time
serviceProvider	string	Yes	Payment provider name
amount	string	Yes	Amount in smallest unit (e.g., cents)
currency	string	Yes	3-letter ISO code
cardInfoRefID	string	Yes	Reference from PMS
resNo	string	No	Reservation number
cardText	string	No	Cardholder name (optional)
description	string	No	Additional info
callbackSuccessUrl	string	Yes	Callback URL for success
callbackAbortUrl	string	Yes	Callback URL for abort
emvTerminal	string	No	Terminal ID (required for terminal integration)
customerInfo	object	No	End customer data, see /initpayNoIframe
supportedFeatures	string	No	List of features to use.

Example Request

{
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "WEBUSER",
  "datetime": "2025-06-01T11:10:00",
  "serviceProvider": "spayengine",
  "amount": "1500",
  "currency": "EUR",
  "cardInfoRefID": "2272",
  "resNo": "20008505/1",
  "callbackSuccessUrl": "https://yourapp/success",
  "callbackAbortUrl": "https://yourapp/failure",
  "supportedFeatures": "",
   "customerInfo": {
    "mobilePhone": "+491701234567",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "street1": "Musterstr. 1",
      "city": "Berlin",
      "country": "DE",
      "postalCode": "12345",
      "state": "Berlin"
    }
  }
}

Response Fields

Field	Type	Description
viewUrl	string	Authorization page/terminal URL
requestID	string	Authorization request reference
dateTime	string	Timestamp
stateRetrivalUrl	string	Status polling URL
returnCode	string	"0" for success
serviceProvider	string	Provider used
transactionID	string	Transaction ID (may be present in some cases)

Example Response

{
  "viewUrl": "https://service.stage.payengine.sihot.com/0000/spayengine/payment?PD=...",
  "requestID": "c0a802bb-81ca-12b8-8181-cae2ea2c0000",
  "dateTime": "2025-06-01T11:10:00",
  "stateRetrivalUrl": "https://service.stage.payengine.sihot.com/0000/paystatus?requestid=c0a802bb-81ca-12b8-8181-cae2ea2c0000&serviceProvider=spayengine",
  "returnCode": "0",
  "serviceProvider": "spayengine"
}

Status & Utility

GET /V2/{customerID}/paystatus?requestid={requestID}&serviceProvider={provider}

Description: Get status of payment/authorization.

Query Parameter	Type	Required	Description
requestid	string	Yes	Request reference
serviceProvider	string	Yes	Provider name

Response

Field	Type	Description
state	int	0=in progress, 1=success, 2=error
result	string	Additional result info

Example

{
  "state": 1,
  "result": "PAYOBJID=123456"
}

GET /V2/{customerID}/transaction?requestid={requestID}&serviceProvider={provider}`

Description: Returns all details about a transaction.

Query Parameters: Same as /paystatus.

Response: Returns a full object with all information about the transaction, including status, codes, timestamps, token, masked card, etc.

Example

{
  "amount": 2000,
  "cardInfoRefID": "2270",
  "creationtime": "2025-06-01T11:00:00",
  "currency": "EUR",
  "customer": "1",
  "description": "Online payment",
  "maskedCardNo": "424242......4242",
  "operation": "initpayNoIframe",
  "paymentObjID": "PAYOBJID=123456",
  "requestID": "0a64c038-82f3-1c79-8183-14d9babb0018",
  "returnCode": "0",
  "serviceProvider": "spayengine",
  "status": "_done",
  "transactionID": "00000003004e22ac",
  "supportedFeatures": "",
  "surchargeApplied": false
}

POST /V2/{customerID}/onboard

Description: Registers a new customer/provider.

Request/response:

Field	Type	Required	Description
datetime	string	Yes	ISO-8601 date/time
user	string	Yes	SIHOT user
providerName	string	Yes	Name of payment provider
providerType	string	Yes	Type of payment provider
defaultCurrency	string	Yes	ISO-4217 3-letter code
testMode	boolean	Yes	Use provider in test mode

Example Request

{
  "datetime": "2025-06-01T12:00:00",
  "user": "ADMIN",
  "providerName": "stripe",
  "providerType": "stripe",
  "defaultCurrency": "EUR",
  "testMode": true
}

Example Response

{
  "returnCode": "0",
  "viewUrl": "https://service.stage.payengine.sihot.com/0000/stripe/onboardSuccess?id=c0a80357-8b23-104c-818b-23f0e7530000",
  "dateTime": "2025-06-01T12:00:00",
  "requestID": "c0a80357-8b23-104c-818b-23f0e7530000"
}

See Appendix for global reference tables: card types, provider names, and error codes.

Payengine

PAYENGINE Web Services – API Reference

MOTO Endpoints

POST /V2/{customerID}/createToken

POST /V2/{customerID}/pay

POST /V2/{customerID}/reversal

POST /V2/{customerID}/authorize

POST /V2/{customerID}/settleAuthorization

POST /V2/{customerID}/cancelAuthorization

eCommerce & Terminal Endpoints

POST /V2/{customerID}/initpayNoIframe

customerInfo (object, optional)

Why is customerInfo required?

customerInfo (object, optional)

address (Object, optional)

POST /V2/{customerID}/initCreateTokenNoIframe

POST /V2/{customerID}/initauthNoIframe

Status & Utility

GET /V2/{customerID}/paystatus?requestid={requestID}&serviceProvider={provider}

GET /V2/{customerID}/transaction?requestid={requestID}&serviceProvider={provider}`

POST /V2/{customerID}/onboard

Why is `customerInfo` required?