PMS API 1 – Wallet

Posted22/07/2025

Updated30/07/2025

ByGari Iruretagoiena

Version – 23/07/2025.

Scope

This API enables the PMS to integrate with the hotel’s key system and with the Vingcard Wallet Web Provisioning Portal In order to create Apple Wallet and Google Wallet keys, as well as plastic cards (optional).

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

	PMS -> VConnect	VConnect -> PMS
Reservation information	* Create * Cancel * Checkin * Checkout * Room move * Update	–
Keycard	* Create key (optional) * Read Key (optional)	–

Introduction

This document describes the public HTTP API of VConnect for receiving messages (events and commands) from PMS systems integrated with Vostio and Vingcard Wallet web Provissioning Portal.

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 a plastic key from PMS’s User Interface.

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

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

PMS -> VConnect Communication protocol

The diagram below describes the communication flows to and from the GRMS System. (In this case, it is only necessary to implement the “External system (PMS) -> VConnect public api” flow):

PMS -> VConnect public API

VConnect public 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 (Vostio and Wallet Web Provissioning Portal).
VConnect public 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 URLs 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.

There will be one endpoint for commands and another for events:

POST [BASE_URL]/command
POST [BASE_URL]/event

The base URL for all public endpoints will be:

https://api.vconnect.vingcard.com/publicapi/v1/{{chainId}}/{{hotelId}}/{{**connector.id** }}

chainId and hotelId can be decided by char or by the external system. By default, if not defined, they will be “nochid” and “nohid”.
connector.id : unique ID for each connection with an external system. It will be automatically assigned by VConnect.

Message flow

The communication From PMS 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 commands: will return the result of executing the command.

Request Payload

All messages (events and commands) will send a json containing:

Identifying part (id, group, 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 event/command.	[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.	[optiontal]
stamp	YYYY-MM-ddTHH:mm:ssZ	Date time of the external system. It can be useful when dealing with supporte requests in order to look for specific logs in external system time.	[optiontal]

Response Payload

All responses (to events and commands) 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	Event/command 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	event/command not accepted, don’t retry later.

List of actions by group/category

Reservation

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:

— pre check-in —

Create a reservation.
Update information in an existing reservation.
Cancel an existing reservation.

— during stay —

Check-in of a reservation.
Check-out of a reservation.
Change room of a reservation (room move)
Change stay dates of a reservation
Change in any other information of a reservation. Guests information, notes, etc.

The reservation.event.info payload MUST include at least this information required for Wallet operations:

“reservation_id”: reservation ID
“status”: current reservation status. Possible values: “expected”|”canceled”|”checkedin”|”checkedout”|”noshow”
“arrival”: arrival date and time
“departure”: departure date and time
“room”: current room. Only mandatory if status=”checkedin”
Main Guest information
- “guest_email”
- “guest_phone”: guest phone must contain the country prefix. If it doesn’t contain the prefix it won’t be possible to use SMS/Phone Multi Factor Authentication.

The reservation.event.info can include additional details that could be interesting for integrations with other systems. This information is not required for Wallet integrations.

reservation.event.info example:

{
    "id": "123e4567-e89b-12d3-a456-426614174003",
    "stamp": "2025-02-09T12:34:56Z",
    "action": "reservation.event.info",
    "payload": {
        "reservation_id": "reservation-id",
        "confirmation_id": "comfirmation-id",
        "status": "checkedin",
        "room": "103",
        "arrival": "2025-02-09T12:34:56Z",
        "departure": "2025-06-10T12:34:56Z",
        "pax": 2,
        "children": 1,
        "cos_pbx": "calls_allowed",
        "cos_tv": "tv_allowed",
        "cos_inet": "inet_allowed",
        "booking_guests": [
            {
                "guest_id": "guest-id",
                "guest_main": true,
                "guest_adult": true,
                "guest_title": "Mr.",
                "guest_firstname": "John",
                "guest_lastname": "Doe",
                "guest_language": "en",
                "guest_birth_date": "1980-01-01",
                "guest_email": "john.doe@example.com",
                "guest_phone": "+1234567890",
                "guest_allow_contact": true,
                "guest_passport": "passport-id",
                "guest_identity_card": "id-card",
                "guest_address": "123 Main St",
                "guest_city": "Anytown",
                "guest_postal_code": "12345",
                "guest_state": "CA",
                "guest_country": "US"
            }
        ],
        "notes_stay": "coming with two kids",
        "notes_preferences": "king size bed, please",
        "origin": "Spain",
        "agency": "Booking",
        "rate_plan": "AI"
    }
}

You can see detailed json examples in the the Postman Collection we will provide.

Keycard

Action	Description	Notes
keycard.command.createKey	Create a Key. VConnect will order the key system to create the key and return the result to the PMS.	optional
keycard.command.readKey	Read a plastic Key. VConnect will order the key system to read a key and return the result to the PMS.	optional

Keycard.command.createKey payload (plastic key card)

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.

The keycard.command.createKey payload MUST include at least this information:

“key_type”: 2 (this value can change in other cases to create other type of keys like wallets, etc)
“main”: <true/false> indicates creation of primary (true) or companion key (copy) (false)
“room”: room.
“arrival”: arrival date and time
“departure”: departure date and time
“card_encoder”: id of the Door Lock System encoder to be used to create the plastic key card.
“card_encoder_provider”: 100 (this value will only be different if the Hotel is using a printer/encoder from a third party vendor)
“extra_access”: array of additional allowed accesses. Can be empty.
“extra_rooms”: array of additional allowed room. Can be empty.
“reservation_id”: reservation ID from the PMS (only required if the DLS requires. Mandatory for Vostio v10)
“confirmation_id”: (optional) confirmation ID. This is the confirmation ID used by the PMS to identify the reservation. It is not mandatory but it is has to be included for those integrations that require that information for key creation.

keycard.command.createKey response payload with example (ok):

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-02-09T12:34:56Z",
    "action": "keycard.command.createKey",
    "payload": {
        "key_type": 2,
        "main": true,
        "arrival": "2025-02-09T12:34:56Z",
        "departure": "2025-04-09T00:00:01Z",
        "name": "John Doe",
        "extra_rooms": [],
        "extra_access": [],
        "card_encoder_provider": 100,
        "card_encoder": "enc1",
        "cards_qty": 1,
        "reservation_id": "reservation-id2",
        "confirmation_id": "confirmation-id2",
        "keytrack1": "track1",
        "keytrack2": "track2",
        "room": "102"
    }
}

keycard.command.createKey response payload with example (DLS returned and error):

{
    "action": "keycard.command.createKey",
    "code": 0,
    "description": "ok",
    "end_user_message": "",
    "id": "40954fda-ba98-483c-9f46-f5fbf9d057a7",
    "payload": {
        "serialNumbers": [
            "test_serial_number"
        ],
    },
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-07-01T07:44:00.289095+02:00"
}

keycard.command.createKey example:

{
    "action": "keycard.command.createKey",
    "code": 200,
    "description": "error sending order ReservationUpdate to Vostio: reservation update request returned != 200. Returned: 422 - {ErrorCode:INVALID_REQUEST Message:End date must be a future date Code:0 CausedBy:[]}",
    "end_user_message": "Unexpected error. Contact technical support",
    "id": "47cc29cc-a19d-49b2-805e-474da733ea96",
    "payload": {
    },
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-07-01T07:35:58.438269+02:00"
}

Keycard.command.readKey payload (plastic key card)

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