PMS API 1 – Wallet

Posted22/07/2025

Updated20/11/2025

ByGari Iruretagoiena

Version – 19/11/2025.

Scope

The scope is integration with the PMS to obtain reservation information and manage physical key recording.
With this information, we can provide the option of connecting to Vingcard Wallet.

For this scope, the following information is received and sent between VConnect and the PMS:

	PMS -> VConnect	VConnect -> PMS
Reservation information	* Reservation info event (Reports current reservation information)	–
Keycard	* Create key * Read Key (optional) * Update additional access (optional) * Get encoders list (optional) * Get doors list (optional)	–

Introduction

This document describes the public HTTP API of VConnect for receiving messages from PMS systems integrated with Vingcard Wallet.

The categories of messages needed from the PMS are:

Reservation events (required): PMS must send an event every time a reservation is updated. On creation, cancellation, update, check-in, room move, stays dates changes and check-out.
KeyCard commands (optional): Commands to create a plastic key or to read and other functionalities of the key.

VConnect supports two types of messages, Commands and Events. Below we describe what an event and a command are:

Event: message generated by a System (S1), which is delivered to VConnect and only waits for the ACK of that delivery. After responding with ACK, VConnect does whatever it has to do with it. By default, VConnect sends the event to all Systems that support receiving it. In this case:
- The PMS sends the event ‘reservation.event.info’ to VConnect.
- VConnect responds with the ACK to the PMS.
- VConnect does whatever it has to do with this information.
Command: message generated by a System (S1), which passes through VConnect and has to be executed by another System (S2) and S1 waits for the result of the execution of S2. For example, an order to read a key card, arrives from a PMS, passes through VConnect, waits for the response from the Door Lock System and returns the result. Every command has a response.
- The PMS sends the event ‘keycard.command.createKey’ to VConnect.
- The PMS waits for a response.
- VConnect sends it to a Door Lock system.
- VConnect receives the response from the Key Access system and send it to the PMS.

PMS -> VConnect Communication protocol

VConnect API receives events and commands from the external system (PMS), processes them, and sends them to the VConnect core to be distributed to other hotel systems.
VConnect API acts as an HTTP server and the PMS acts as an HTTP client sending messages to the server.
The communication protocol is HTTPS with HTTP Basic authentication. Requests will be sent using HTTP POST Requests. The message is encoded as “application/json”.
VConnect technicians will provide BASE_URL and Authentication values to be used by the PMS System.
VConnect provides unique endpoints for each external system of a subscription. If a single subscription/hotel has two external systems of the same type, different endpoints will be provided for each of the external systems.

For Keycard messages the url should be:

 POST [BASE_URL]/command

For Reservation messages the url should be:

POST [BASE_URL]/event

Message flow

The communication from the PMS system to VConnect will follow this flow.

HTTP client -> HTTP server: sends POST request (to command or event url) + json payload body
Response HTTP server -> HTTP client:
- HTTP response CODE: will indicate the result at the HTTP link level: 200 OK (received), 404 unauthorized, etc.
- If HTTP code 200, the response will include in the BODY a json with information about the processing of the message:
  - For /event messages: the response body indicates the result of processing message by the receiver. VConnect response only indicates if there is any error in processing the received JSON, it will not indicate the result of sending that data to other systems.
  - For /command messages: will return the result of executing the command in the Door Lock System.

Request Payload

All messages will send a JSON containing:

Identifying part (id, action, etc.)
Payload: Dependent on the type of action being processed.

Name	Type	Description	Notes
action	string	See list below	[required]
payload	JSON request structure	Content will depend on each action.	[optional or required depending on type of message]
id	string	Unique Id to identify each request. It will be used in responses and to help tracing of requests for support purposes. VConnect will always send a unique ID in its request to other systems. It is not required for other systems to include this field in their requests to VConnect. VConnect will generate an unique ID if receives a request without it.	[optional]
stamp	YYYY-MM-ddTHH:mm:ssZ	Date time of the external system in UTC format. It can be useful when dealing with support requests in order to look for specific logs in external system time.	[optional]

Response Payload

All responses will include a JSON containing:

Payload: Dependent on the type of action being processed.
Common part with result, identifiers, etc. (code, description, id, etc.)

Name	Type	Description	Notes
code	string	Result code: “0”: OK “1xx” error that requires retry (range 100-125) “2xx” non-recoverable error on retry (range 200-225)	[required]
payload	JSON response struct	Content will depend on each event/command	[optional/required depending on type of message]
description	string	Message with technical description in case of error	[recommended]
end_user_message	string	Message to be shown to end users. This is useful mainly for commands. For example, if a PMS sends a keycard.command.createKey. EndUserMsg will include a message to be shown to end user in the PMS UI.	[optional]
request_id	string	ID from the request message. VConnect will include this field when acting as server in order to help tracing at requester’s logs. VConnect does not require order systems to include this field in their responses.	[optional]
id	string	Unique ID for this response message. VConnect will include this ID in their responses. VConnect does not require order systems to include this field in their responses.	[optional]

List of result codes

Code	Description
0	OK
1xx	Not accepted, Retry later. To be used if the receiver had some kind of internal problem that requires the sender to keep the message in queue and send it again later.
201	Not accepted, don’t retry later.

List of actions

Reservation

Reservation.event.info

Action	Description	Notes
reservation.event.info	Reports current reservation information	Mandatory for wallet

The PMS must send a reservation.even.info message with information about a reservation when any of these changes are done in the PMS.

Method: POST [BASE_URL]/event

Name	Type	Description	Notes
chain	string	Hotel Chain ID.	[optional]
property	string	Hotel ID.	[optional]
reservation_id	string	Reservation number.	[required]
confirmation_id	string	Confirmation number.	[recommended]
status	string	Current reservation status. Possible values: – expected – checkedin – checkedout – canceled – noshow	[required]
locator	string	Public locator of the booking, if it does not exist, the same value as the ‘id’ field will be sent.	[optional]
room	string	Room name occupied by the booking. Required for the “check-in”, “checkout” status. In case of room move, new room assigned.	[optional]
account	string	Account associated to the booking. If the PMS trats them ata occupant level, it is the account of the main guest.	[optional]
arrival	string	Arrival Date-Time (UTC) in fomat YYYY-MM-DDTHH:NN:SSZ	[required]
departure	string	Departure Date-Time (UTC) in fomat YYYY-MM-DDTHH:NN:SSZ	[required]
level	string	Generic VIP level of the booking. If the PMS treats them at occupant level, it must be used the VIP level of the main guest.	[optional]
pax	number	Total number of occupants.	[optional]
children	number	Number of children.	[optional]
notes_stay	string	Notes of the stay.	[optional]
notes_preference	string	Notes of the preferences.	[optional]
origin	string	Reservation Origin.	[optional]
agency	string	Reservation Agency.	[optional]
rate_plan	string	Reservation rate plan.	[optional]

booking_guests	Array	Guest list for the reservation:
guest_id	string	Internal guest UID.	[required]
guest_main	boolean	true: Main Guest. false: Additional occupant. If the PMS does not send the specific data, VConnect will assing the first in the list as the main guest.	[optional]
guest_adult	boolean	true: adult false: children	[optional]
guest_account	string	Account associated with the guest.	[optional]
guest_title	string	Guest treatment.	[optional]
guest_firstname	string	Guest’s name.	[required]
guest_lastname	string	Guest’s surname.	[required]
guest_gender	string	Guest’s gender.	[optional]
guest_level	string	Guest’s VIP level.	[optional]
guest_nationality	string	Guest’s nationality.	[optional]
guest_language	string	Guest’s language.	[required]
guest_birth_date	string	Date of birth in format YYYY-MM-DD	[optional]
guest_email	string	Guest’s e-mail address.	[required]
guest_phone	string	Guest’s phone number.	[required]
guest_allow_contact	boolean	true: Contact is allowed. false: Contact is not allowed.	[optional]
guest_passport	string	Guest’s passport.	[optional]
guest_identity_card	string	Guest’s identity card.	[optional]
guest_address	string	Guest’s address.	[optional]
guest_postal_code	string	Guest’s postal/ZIP code.	[optional]
guest_state	string	Guest’s state.	[optional]
guest_country	string	Guest’s country.	[optional]

reservation.event.info example:

{
    "id": "804fb2b2-1986-4d01-83af-3f81a0788a45",
    "stamp": "2025-11-14T15:45:02.839Z",
    "action": "reservation.event.info",
    "payload": {
        "chain": "4433",
        "property": "A1122",
        "reservation_id": "74147",
        "confirmation_id": "475471",
        "status": "expected",
        "locator": "95754",
        "room": "110",
        "account": "58815",
        "arrival": "2025-11-14T10:22:13Z",
        "departure": "2025-11-19T10:00:00Z",
        "level": "VIP",
        "pax": 1,
        "children": 0,
        "booking_guests": [
       {
            "guest_id": "442123_1",
            "guest_main": true,
            "guest_adult": true,
            "guest_account": "58815_1",
            "guest_title": "Mr.",
            "guest_firstname": "John",
            "guest_lastname": "Doe",
            "guest_gender": "male",
            "guest_level": "VIP",
            "guest_nationality": "US",
            "guest_language": "en",
            "guest_birth_date": "1980-01-01",
            "guest_email": "john.doe@example.com",
            "guest_phone": "+1234567890",
            "guest_allow_contact": true,
            "guest_passport": "271234111",
            "guest_identity_card": "33126423C",
            "guest_address": "123 Main St",
            "guest_city": "Anytown",
            "guest_postal_code": "12345",
            "guest_state": "CA",
            "guest_country": "US"
        }
    ],
    "notes_stay": "comming with one kids",
    "notes_preferences": "king size bed, please",
    "origin": "Spain",
    "agency": "Booking",
    "rate_plan": "AI"
  }
 }

Response

{
    "action": "reservation.event.info",
    "code": 0,
    "description": "",
    "end_user_message": "",
    "id": "939b2eda-9397-49b9-8301-e2d25e1fc8a4",
    "request_id": "804fb2b2-1986-4d01-83af-3f81a0788a45",
    "stamp": "2025-11-14T15:45:03.123433601Z"
}

Keycard

Action	Description	Notes
keycard.command.createKey	Create a Key. VConnect will order the Door Lock System (DLS) to create the key and return the result to the PMS.	Mandatory to generate plastic cards.
keycard.command.readKey	Read a plastic Key. VConnect will order the Door Lock System to read a key and return the result to the PMS.	Optional.
keycard.command.getEncoders	Obtains list of encoders. Retrieves the identifiers of the Encoders configured in the Door Lock System.	Optional.
keycard.command.getDoors	Obtains list of doors (room and aditional accesses). Retrieves the list of doors configured in the Door Lock System.	Optional.

Method: POST [BASE_URL]/command

Keycard.command.createKey payload (physical key)

This command can be used by the PMS to send and order to create a plastic key card.

VConnect receives the command, sends it to the Door Lock System and returns the result of the execution of the command to the PMS.

Name	Type	Description	Notes
key_type	number	For key card the value is 2	[required]
main	boolean	true: Indicates the creation of New/Primary key card. false: Indicates a Duplicate/Copy key card.	[required]
card_encoder	string	ID of the Door Lock System encoder to be used to create the plastic key card.	[required]
cards_qty	number	Number of cards to be recorded.	[required]
chain	string	Chain Hotel ID.	[optional]
property	string	Hotel ID.	[optional]
reservation_id	string	Reservation number.	[required]
confirmation_id	string	Confirmation number.	[recommended]
room	string	Room number.	[required]
arrival	YYYY-MM-ddTHH:mm:ssZ	Arrival date and time (UTC).	[required]
departure	YYYY-MM-ddTHH:mm:ssZ	Departure date and time (UTC).	[required]
name	string	Name of the main guest.	[recommended]
email	string	Email of the main guest.	[recommended]
extra_rooms	Array	Extra rooms in the array should be enclosed in quotation marks and delimited by commas.	[optional]
extra_access	Array	Extra accesses in the array should be enclosed in quotation marks and delimited by commas.	[optional]
keytrack1	string	Additional data recorded on the public tracks of the card.	[optional]
keytrack2	string	Additional data recorded on the public tracks of the card	[optional]

keycard.command.createKey example:

{
    "id": "4d2eb7d1-9802-4581-9b46-cb9eaa3af53f",
    "stamp": "2025-11-14T07:21:36.728Z",
    "action": "keycard.command.createKey",
    "payload": {
        "key_type": 2,
        "main": true,
        "card_encoder": "1",
        "cards_qty": 1,
        "chain": "1234",
        "property": "33333",
        "reservation_id": "74147",
        "confirmation_id": "475471",
        "room": "110",
        "arrival": "2025-11-14T10:22:13Z",
        "departure": "2025-11-16T10:00:00Z",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "extra_rooms": ["111","112"],
        "extra_access": ["SPA"],
        "keytrack1": "track1",
        "keytrack2": "track2"
    }
}

Response

Based on the “Response Payload” section, the fields with relevant information are:

code: Response code.
description: Provides technical details in case of an error.
end_user_message: Message to be displayed as a user-friendly message to the end user.
payload:
- serialNumbers: Serial number of the recorded key card.

Response of a key card recording operation (OK)

{
    "action": "keycard.command.createKey",
    "code": 0,
    "description": "createKey command executed successfully:",
    "id": "aea2780a-1d75-48b3-9a76-ea462d9dacc1",
    "end_user_message": "",
    "payload": {
        "credential": "",
        "internalCardId": [
            "c527529d-ba04-4982-b53d-d81e3e848ee7"
        ],
        "keytrack2": [
            "0491a2b2d97281"
        ],
        "serialNumbers": [
            "0491a2b2d97281"
        ],
        "token": ""
    },
    "request_id": "4d2eb7d1-9802-4581-9b46-cb9eaa3af53f",
    "stamp": "2025-11-14T07:21:44.631928638Z"
}

Response when an error occurs:

{
    "action": "keycard.command.createKey",
    "code": 200,
    "description": "error sending order HardKeyCreate to Assavostio: ErrorCode:ENCODER_NOT_FOUND Message: Could not find encoder 2",
    "end_user_message": "Could not find encoder 2. Please make sure the encoder is defined in Vostio",
    "id": "4cf57b91-e8e1-4739-84e2-85ccf63808ce",
    "payload": {
        "credential": "",
        "token": ""
    },
    "request_id": "4f836930-15ff-4c58-b4f2-444056b2a359",
    "stamp": "2025-11-14T12:05:19.452531183Z"
}

Keycard.command.readKey payload (physical key)

This command can be used by the PMS to send and order to read the information from a plastic key card.

VConnect receives the command, sends it to the Door Lock System and returns the result of the execution of the command to the PMS.

Name	Type	Description	Notes
key_type	number	For Keycard the value is 2	[required]
card_encoder	string	ID of the Door Lock System encoder to be used to create the plastic key card.	[required]
chain	string	Chain Hotel ID	[optional]
property	string	Hotel ID	[optional]

Example:

{
    "id": "5b26bee0-792c-4a11-bcb5-5b9e3d01cf4f",
    "stamp": "2025-11-14T08:18:10.698Z",
    "action": "keycard.command.readKey",
    "payload": {
        "key_type": 2,
        "card_encoder": "1",
        "chain": "1234",
        "property": "33333"
    }
}

Response

Based on the “Response Payload” section, the fields with relevant information are:

code: Response code.
description: Provides technical details in case of an error.
end_user_message: Message to be displayed as a user-friendly message to the end user.
payload:
- createdAtUtc: Date / Time of the recording of the key card.
- media_card_uid: Serial number of the recorded key card.
- validFromUtc: From Date / Time.
- validToUtc: To Date / Time.
- doors:
  - name: Room number.

Response payload (OK):

{
    "action": "keycard.command.readKey",
    "code": 0,
    "description": "ok",
    "end_user_message": "Key successfully read",
    "id": "24588818-cca8-4953-851c-a7ed092c70a3",
    "payload": {
        "createdAt": "2025-11-14T13:10:40Z",
        "createdAtUtc": "2025-11-14T12:10:40Z",
        "createdUsing": "VOSTIO_GUEST_API",
        "doors": [
            {
                "code": 0,
                "description": "",
                "id": 0,
                "name": "110",
                "pms_id": "",
                "type": "GuestDoor"
            }
        ],
        "hasCheckedOut": false,
        "id": "712981c2-9c40-4b25-853a-bcb2b258417c",
        "media_card_uid": "0491a2b2d97281",
        "media_type": "Card",
        "validFrom": "2025-11-14T13:10:00Z",
        "validFromUtc": "2025-11-14T12:10:00Z",
        "validTo": "2025-11-16T10:00:00Z",
        "validToUtc": "2025-11-16T09:00:00Z"
    },
    "request_id": "2a6177ae-d507-4ff7-9992-e8502ac3e3cd",
    "stamp": "2025-11-14T12:11:01.682375336Z"
}

keycard.command.updateAdditionalAccess payload

This command can be used by the PMS to update access permissions for an existing key or reservation. Not supported by all Door Lock Systems. ONLY valid for “online” Door Lock Systems that supports receiving access permissions update for existing keys/reservations.
VConnect receives the command, sends it to the Door Lock System and returns the result of the execution of the command to the PMS.

Name	Type	Description	Notes
key_type	number	Value: 5	[required]
chain	string	Chain Hotel ID	[optional]
property	string	Hotel ID	[optional]
reservation_id	string	Reservation number	[required]
confirmation_id	string	Confirmation number	[recommended]
room	string	Room number	[required]
arrival	YYYY-MM-ddTHH:mm:ssZ	Arrival date and time (UTC)	[optional]
departure	YYYY-MM-ddTHH:mm:ssZ	Departure date and time (UTC)	[optional]
extra_rooms	Array	Extra rooms in the array should be enclosed in quotation marks and delimited by commas.	[optional]
extra_access	Array	Extra acceses in the array should be enclosed in quotation marks and delimited by commas.	[optional]

Request of Update Additional Access example:

{
    "id": "6ec56aa7-5ca8-4fb3-baf4-d72d3fc46280",
    "stamp": "2025-11-14T12:25:20.488Z",
    "action": "keycard.command.updateAdditionalAccess",
    "payload": {
        "key_type": 5,
        "chain": "1234",
        "property": "33333",
        "reservation_id": "74147",
        "confirmation_id": "475471",
        "room": "110",
        "arrival": "2025-11-14T10:22:13Z",
        "departure": "2025-11-19T10:00:00Z",
        "extra_rooms": [
            "101"
        ],
        "extra_access": [
            "SPA"
        ]
    }
}

Response

Based on the “Response Payload” section, the fields with relevant information are:

code: Response code.
description: Provides technical details in case of an error.
end_user_message: Message to be displayed as a user-friendly message to the end user.

Response payload with example (OK):

{
    "action": "keycard.command.updateAdditionalAccess",
    "code": 0,
    "description": "updateAdditionalAccess command executed successfully: Reservation ID: 475471, Room: 110, ExtraRooms: [101], ExtraAccess: [SPA]",
    "end_user_message": "",
    "id": "d1fd7149-8ea9-4b9c-8ade-6864414f6994",
    "payload": {
        "credential": "",
        "token": ""
    },
    "request_id": "6ec56aa7-5ca8-4fb3-baf4-d72d3fc46280",
    "stamp": "2025-11-14T12:25:20.982019256Z"
}

Response payload with example (DLS returned and error):

{
    "action": "keycard.command.updateAdditionalAccess",
    "code": 200,
    "description": "error sending AssignAccess to Vostio: assign access request returned != 201. Returned: 422 - {ErrorCode:DOOR_NOT_FOUND Message:Could not find door with id POOL Code:0 Id: CausedBy:[]}",
    "end_user_message": "Could not find door with id POOL",
    "id": "a7a7373a-264a-488a-8798-d9fd4ab2a69e",
    "payload": {
        "credential": "",
        "token": ""
    },
    "request_id": "9d5fa8b5-9b03-43e3-8eee-cbae53b0de65",
    "stamp": "2025-11-14T12:32:15.282756182Z"
}

keycard.command.getEncoders payload

Retrieves encoder list from the Door Lock System, if supported by the connected system.

The ‘id’ field in the response corresponds to the internal encoder identifier used during physical key encoding and reading.

Name	Type	Description	Notes
chain	string	Chain Hotel ID	[optional]
property	string	Hotel ID	[optional]

Encoder request example:

{
    "id": "3235fce6-fb01-4b7e-8ff5-4d83f0a45cd5",
    "stamp": "2025-11-19T12:07:56.421Z",
    "action": "keycard.command.getEncoders",
    "payload": {
        "chain": "4433",
        "property": "A1122"
    }
}

Response

Based on the “Response Payload” section, the fields with relevant information are:

code: Response code.
description: Provides technical details in case of an error.
end_user_message: Message to be displayed as a user-friendly message to the end user.
payload:
- encoders:
  - id: Encoder ID.
  - name: Name of the encoder.

{
    "action": "keycard.command.getEncoders",
    "code": 0,
    "description": "ok, getEncoders command executed successfully: 2 encoders received",
    "end_user_message": "",
    "id": "b8effa6b-5794-4d8d-9e38-d65dbe3789e5",
    "payload": {
        "encoders": [
            {
                "id": "1",
                "name": "Encoder 1"
            },
            {
                "id": "2",
                "name": "Encoder 2"
            }
        ]
    },
    "request_id": "17487c82-40fc-410c-8f37-29b6eb2d79f9",
    "stamp": "2025-11-19T12:11:12.19303439Z"
}

keycard.command.getDoors payload

Retrieves rooms and common spaces list from the Door Lock System, if supported by the connected system.

The ‘name’ field in the response corresponds to the room used during physical key encoding and reading.

Name	Type	Description	Notes
chain	string	Chain Hotel ID	[optional]
property	string	Hotel ID	[optional]

Example for doors request:

{
    "id": "1f8f6549-d98e-479e-9a16-44be6d54a6b0",
    "stamp": "2025-11-19T12:24:51.226Z",
    "action": "keycard.command.getDoors",
    "payload": {
        "chain": "4433",
        "property": "A1122"
    }
}
    "code": 0,

Response of door request:

Based on the “Response Payload” section, the fields with relevant information are:

code: Response code.
description: Provides technical details in case of an error.
end_user_message: Message to be displayed as a user-friendly message to the end user.
payload:
- doors:
  - name: Room name.
  - type: Type of doors (Values: GuestDoor, CommonDoor, EntranceDoor, Elevator)

{
    "action": "keycard.command.getDoors",
    "code": 0,
    "description": "ok, getDoors command executed successfully: 3 doors received",
    "end_user_message": "",
    "id": "f21a9836-38f9-4170-901c-c6fec1a7770a",
    "payload": {
        "doors": [
            {
                "code": 0,
                "description": "",
                "id": 100,
                "name": "100",
                "pms_id": "",
                "type": "GuestDoor"
            },
            {
                "code": 0,
                "description": "",
                "id": 101,
                "name": "101",
                "pms_id": "",
                "type": "GuestDoor"
            },
            {
                "code": 0,
                "description": "",
                "id": 0,
                "name": "SPA",
                "pms_id": "",
                "type": "CommonDoor"
            }
        ]
    },
    "request_id": "1f8f6549-d98e-479e-9a16-44be6d54a6b0",
    "stamp": "2025-11-19T12:24:51.56571493Z"
}

VConnect API-s

PMS API 1 – Wallet

Version – 19/11/2025.

Scope

Introduction

PMS -> VConnect Communication protocol

Message flow

Request Payload

Response Payload

List of result codes

List of actions

Reservation

Reservation.event.info

Keycard

Keycard.command.createKey payload (physical key)

Keycard.command.readKey payload (physical key)

keycard.command.updateAdditionalAccess payload

keycard.command.getEncoders payload

keycard.command.getDoors payload