Complete Example Flows

All requests (except the /login step) must include the Authorization: Bearer ... header using your current JWT. Always use Content-Type: application/json on POST requests.
Ensure you use the serviceprovider that match your environment

1. MOTO: Tokenization → Payment → Reversal (Server-to-Server)

Step 0: Login (Obtain JWT Token)

POST https://{baseUrl}/login
Content-Type: application/json

{
  "username": "YOUR-USERNAME",
  "password": "YOUR-PASSWORD"
}

Sample Response:

{
    "username": "YOUR-USERNAME",
    "roles": [
        "USER"
    ],
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiO...",
    "token_type": "Bearer",
    "expires_in": 4800
}

Save the access_token. All further requests use:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Step 1: Tokenization

POST https://{baseUrl}/V2/0000/createToken
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "cardNo": "4242424242424242",
  "valid": "2026-03-30",
  "cvc": "123",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-07-01T09:00:00",
  "cardText": "Jane Smith",
  "serviceProvider": "windcave"
}

Response:

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

Step 2: Payment

POST https://{baseUrl}/V2/0000/pay
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "tokenNo": "0000040000123456",      // Use tokenNo from step 1
  "amount": "7500",
  "currency": "EUR",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-07-01T09:01:00",
  "text": "Room Reservation #1234",
  "serviceProvider": "windcave"
}

Response:

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

Step 3: Reversal

POST https://{baseUrl}/V2/0000/reversal
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "transactionID": "TXN_PAYMENT_001",   // Use transactionID from step 2
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "MOTOUSER",
  "datetime": "2025-07-01T09:05:00",
  "currency": "EUR",
  "amount": "7500",
  "serviceProvider": "windcave"
}

Response:

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

2. eCommerce HPP/Terminal Flow with Polling

Step 0: Login (Obtain JWT Token)

(As shown in MOTO flow above.)

Step 1: Initiate Payment

POST https://{baseUrl}/V2/0000/initpayNoIframe
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "ECOMUSER",
  "datetime": "2025-07-01T10:00:00",
  "serviceProvider": "spayengine",
  "amount": "2000",
  "currency": "EUR",
  "cardInfoRefID": "WEB-REF-999",
  "resNo": "RES-0001",
  "callbackSuccessUrl": "https://yourapp.example/success",
  "callbackAbortUrl": "https://yourapp.example/abort",
  "description": "Online booking payment",
  "supportedFeatures": ""
}

Response:

{
  "viewUrl": "https://{baseUrl}/0000/spayengine/payment?PD=...",
  "requestID": "REQ_ECOM_123",
  "dateTime": "2025-07-01T10:00:00",
  "stateRetrivalUrl": "https://{baseUrl}/0000/paystatus?requestid=REQ_ECOM_123&serviceProvider=spayengine",
  "returnCode": "0",
  "serviceProvider": "spayengine"
}

Show the customer the viewUrl for payment.

Step 2: Poll for Status

Url for the call is provide in the stateRetrivalUrl of the init request!

GET https://{baseUrl}/0000/paystatus?requestid=REQ_ECOM_123&serviceProvider=spayengine
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Possible Responses:

  • In Progress: { "state": 0 }
  • Success: { "state": 1, "result": "PAYOBJID=5678" }
  • Error: { "state": 2, "result": "ERROR=Customer+aborted" }

Step 3: Retrieve Transaction Details

GET https://{baseUrl}/V2/0000/transaction?requestid=REQ_ECOM_123&serviceProvider=spayengine
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Response:

{
  "amount": 2000,
  "cardInfoRefID": "WEB-REF-999",
  "creationtime": "2025-07-01T10:00:00",
  "currency": "EUR",
  "customer": "1",
  "description": "Online booking payment",
  "maskedCardNo": "424242......4242",
  "operation": "initpayNoIframe",
  "paymentObjID": "PAYOBJID=5678",
  "requestID": "REQ_ECOM_123",
  "returnCode": "0",
  "serviceProvider": "spayengine",
  "status": "_done",
  "transactionID": "TXN_PAYMENT_999",
  "surchargeApplied": false
}

3. Tokenization (initCreateTokenNoIframe) → Payment → Reversal (eCommerce/Browser-Initiated Token Flow)

Step 0: Login

(Same as above.)

Step 1: Initiate Tokenization

POST https://{baseUrl}/V2/0000/initCreateTokenNoIframe
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "WEBUSER",
  "datetime": "2025-07-01T11:00:00",
  "serviceProvider": "spayengine",
  "cardInfoRefID": "WEB-TOKEN-100",
  "callbackSuccessUrl": "https://yourapp.example/token-success",
  "callbackAbortUrl": "https://yourapp.example/token-abort",
  "tokenType": "eCommerce",
  "theme": "bright"
}

Response:

{
  "viewUrl": "https://{baseUrl}/0000/spayengine/create?PD=...",
  "requestID": "REQ_TOKENIZE_200",
  "dateTime": "2025-07-01T11:00:00",
  "stateRetrivalUrl": "https://{baseUrl}/0000/paystatus?requestid=REQ_TOKENIZE_200&serviceProvider=spayengine",
  "returnCode": "0",
  "serviceProvider": "spayengine"
}

The user opens the viewUrl to enter card details and complete tokenization.

Step 2: Poll for Tokenization Status

Url for the call is provide in the stateRetrivalUrl of the init request!

GET https://{baseUrl}/V2/0000/paystatus?requestid=REQ_TOKENIZE_200&serviceProvider=spayengine
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Response on success:

{ "state": 1, "result": "TOKENOBJID=98765" }

Step 3: Retrieve Token Details

GET https://{baseUrl}/V2/0000/transaction?requestid=REQ_TOKENIZE_200&serviceProvider=spayengine
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Sample Response:

{
  "amount": 0,
  "cardInfoRefID": "WEB-TOKEN-100",
  "maskedCardNo": "424242......4242",
  "operation": "initCreateTokenNoIframe",
  "token": "0000040000789100",
  "tokenValidUntil": "2028-12-31",
  "requestID": "REQ_TOKENIZE_200",
  "returnCode": "0",
  "serviceProvider": "spayengine",
  "status": "_done",
  "transactionID": "TXN_TOKEN_200"
}

Save the token field for future payments.

Step 4: Pay with Token

POST https://{baseUrl}/V2/0000/pay
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "tokenNo": "0000040000789100",      // Use token from previous step
  "amount": "1500",
  "currency": "EUR",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "WEBUSER",
  "datetime": "2025-07-01T11:05:00",
  "text": "Token payment",
  "serviceProvider": "spayengine"
}

Response:

{
  "cardType": "4",
  "cardNo": "424242......4242",
  "cardTypeCode": "visa",
  "serviceProvider": "spayengine",
  "transactionID": "TXN_PAYMENT_200",
  "returnCode": "0"
}

Step 5: Reversal

POST https://{baseUrl}/V2/0000/reversal
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "transactionID": "TXN_PAYMENT_200",
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "WEBUSER",
  "datetime": "2025-07-01T11:10:00",
  "currency": "EUR",
  "amount": "1500",
  "serviceProvider": "spayengine"
}

Response:

{
  "cardType": "4",
  "serviceProvider": "spayengine",
  "transactionID": "TXN_REVERSAL_200",
  "returnCode": "0"
}

4. eCommerce HPP/Terminal Flow with Polling including surcharges

Step 0: Login (Obtain JWT Token)

(As shown in MOTO flow above.)

Step 1: Initiate Payment

POST https://{baseUrl}/V2/0000/initpayNoIframe
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

{
  "hotelID": "1",
  "hotelIDType": "SIHOT.PMS",
  "user": "ECOMUSER",
  "datetime": "2025-07-01T10:00:00",
  "serviceProvider": "spayengine",
  "amount": "2000",
  "currency": "EUR",
  "cardInfoRefID": "WEB-REF-999",
  "resNo": "RES-0001",
  "callbackSuccessUrl": "https://yourapp.example/success",
  "callbackAbortUrl": "https://yourapp.example/abort",
  "description": "Online booking payment",
  "supportedFeatures": "surcharge"
}

Response:

{
  "viewUrl": "https://{baseUrl}/0000/spayengine/payment?PD=...",
  "requestID": "REQ_ECOM_123",
  "dateTime": "2025-07-01T10:00:00",
  "stateRetrivalUrl": "https://{baseUrl}/0000/paystatus?requestid=REQ_ECOM_123&serviceProvider=spayengine",
  "returnCode": "0",
  "serviceProvider": "spayengine"
}

Show the customer the viewUrl for payment.

Step 2: Poll for Status

Same as e-commerce / terminal payments without surcharge.

Step 3: Retrieve Transaction Details

GET https://{baseUrl}/V2/0000/transaction?requestid=REQ_ECOM_123&serviceProvider=spayengine
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Response:

{
  "amount": 2230,
  "cardInfoRefID": "WEB-REF-999",
  "creationtime": "2025-07-01T10:00:00",
  "currency": "EUR",
  "customer": "1",
  "description": "Online booking payment",
  "maskedCardNo": "424242......4242",
  "operation": "initpayNoIframe",
  "paymentObjID": "PAYOBJID=5678",
  "requestID": "REQ_ECOM_123",
  "returnCode": "0",
  "serviceProvider": "spayengine",
  "status": "_done",
  "transactionID": "TXN_PAYMENT_999",
  "surchargeApplied": true,
  "surchargeAmount": 230,
  "surchargePercentUsed": 11.5
}