[{"data":1,"prerenderedAt":263},["ShallowReactive",2],{"cds-site:languages":3,"cds-site:style":5,"cds-site:globals":48,"cds-site:menu":54,"hp-footer-menus":226,"page-en-/guide/integration-scenarios":241},[4],"en",{"id":6,"name":7,"template":8,"logo":9,"logoMark":10,"favicon":11,"values":12,"cssProperties":14},"style_docs","Documentation","@checkin247/template-docs","hotelplatform-logo","hotelplatform-mark","favicon",{"icon_background":13},"#0B1B33",{"--color-ink":13,"--color-deep":15,"--color-signal":16,"--color-signal-deep":17,"--color-signal-light":18,"--color-canvas":19,"--color-error":20,"--color-brand-50":19,"--color-brand-100":21,"--color-brand-200":22,"--color-brand-300":23,"--color-brand-400":24,"--color-brand-500":25,"--color-brand-600":26,"--color-brand-700":15,"--color-brand-800":27,"--color-brand-900":13,"--color-brand-950":28,"--color-neutral-50":29,"--color-neutral-100":30,"--color-neutral-200":31,"--color-neutral-300":32,"--color-neutral-400":33,"--color-neutral-500":34,"--color-neutral-600":35,"--color-neutral-700":36,"--color-neutral-800":37,"--color-neutral-900":38,"--color-neutral-950":13,"--color-primary":25,"--color-primary-hover":15,"--color-surface":39,"--color-background-default":19,"--color-background-dark":13,"--color-text-strong":38,"--color-text-dark":38,"--color-text-body":36,"--color-text-default":36,"--color-text-muted":40,"--color-text-on-dark":41,"--color-border":31,"--color-border-default":31,"--font-heading":42,"--font-body":43,"--font-mono":44,"--radius-control":45,"--radius-card":46,"--radius":45,"--container-content":47},"#14306E","#4FC3B0","#136558","#8FE0D2","#F6F9FC","#B4442F","#EAF0F9","#CBD9F0","#A3BCE4","#6389C8","#2A56A8","#204487","#0F2452","#071223","#F8FAFC","#F1F5FA","#E3E9F2","#CFD8E6","#A6B3C6","#8494AB","#6C7C93","#5A6A80","#3B4A61","#12233F","#FFFFFF","#5D6C82","#D5E1F2","\"Outfit\", ui-sans-serif, system-ui, sans-serif","\"IBM Plex Sans\", ui-sans-serif, system-ui, sans-serif","\"IBM Plex Mono\", ui-monospace, monospace","10px","16px","780px",{"id":49,"siteName":50,"copyright":51,"footerText":52,"defaultLanguage":4,"vimeo":53,"linkedin":53,"youtube":53,"github":53,"logo":53,"logoMark":53,"favicon":53,"ogImage":53},"site","HotelPlatform.io Documentation","© 2026 key-card / HotelPlatform","API documentation of the HotelPlatform.",null,[55,64,70,78,83,90,96,102,106,113,119,125,129,136,142,146,153,159,163,170,177,184,191,198,205,212,219],{"id":56,"label":57,"description":53,"icon":53,"trailing_icon":53,"href":58,"sort":59,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":61,"to":53,"menu":62},"m_main_api","API Documentation","/api-reference",1,"published",[],{"position":63},"main",{"id":65,"label":66,"description":53,"icon":53,"trailing_icon":53,"href":67,"sort":59,"status":60,"parent_item":56,"target":53,"isCanonical":53,"translations":68,"to":53,"menu":69},"m_main_api_AccessControl","AccessControl","/api-reference/accesscontrol/latest",[],{"position":63},{"id":71,"label":72,"description":53,"icon":53,"trailing_icon":53,"href":73,"sort":59,"status":60,"parent_item":53,"target":74,"isCanonical":53,"translations":75,"to":53,"menu":76},"m_footer_int_access","Access control systems","https://hotelplatform.io/en-gb/integrations/access-control-system","_blank",[],{"position":77},"footer-integrations",{"id":79,"label":66,"description":53,"icon":53,"trailing_icon":53,"href":67,"sort":59,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":80,"to":53,"menu":81},"m_footer_api_accesscontrol",[],{"position":82},"footer-apis",{"id":84,"label":85,"description":53,"icon":53,"trailing_icon":53,"href":86,"sort":87,"status":60,"parent_item":56,"target":53,"isCanonical":53,"translations":88,"to":53,"menu":89},"m_main_api_Configuration","Configuration","/api-reference/configuration/latest",2,[],{"position":63},{"id":91,"label":92,"description":53,"icon":53,"trailing_icon":53,"href":93,"sort":87,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":94,"to":53,"menu":95},"m_main_guide","Guide","/guide",[],{"position":63},{"id":97,"label":98,"description":53,"icon":53,"trailing_icon":53,"href":99,"sort":87,"status":60,"parent_item":53,"target":74,"isCanonical":53,"translations":100,"to":53,"menu":101},"m_footer_int_pms","Hotel property management systems","https://hotelplatform.io/en-gb/integrations/hotel-property-managing-system",[],{"position":77},{"id":103,"label":85,"description":53,"icon":53,"trailing_icon":53,"href":86,"sort":87,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":104,"to":53,"menu":105},"m_footer_api_configuration",[],{"position":82},{"id":107,"label":108,"description":53,"icon":53,"trailing_icon":53,"href":109,"sort":110,"status":60,"parent_item":56,"target":53,"isCanonical":53,"translations":111,"to":53,"menu":112},"m_main_api_HotelApi","HotelApi","/api-reference/hotelapi/latest",3,[],{"position":63},{"id":114,"label":115,"description":53,"icon":53,"trailing_icon":53,"href":116,"sort":110,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":117,"to":53,"menu":118},"m_main_about","About","/about",[],{"position":63},{"id":120,"label":121,"description":53,"icon":53,"trailing_icon":53,"href":122,"sort":110,"status":60,"parent_item":53,"target":74,"isCanonical":53,"translations":123,"to":53,"menu":124},"m_footer_int_payment","Payment terminals and gateways","https://hotelplatform.io/en-gb/integrations/credit-card-terminal-payment-gateway",[],{"position":77},{"id":126,"label":108,"description":53,"icon":53,"trailing_icon":53,"href":109,"sort":110,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":127,"to":53,"menu":128},"m_footer_api_hotelapi",[],{"position":82},{"id":130,"label":131,"description":53,"icon":53,"trailing_icon":53,"href":93,"sort":132,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":133,"to":53,"menu":134},"m_sb_overview","Overview",4,[],{"position":135},"sidebar",{"id":137,"label":138,"description":53,"icon":53,"trailing_icon":53,"href":139,"sort":132,"status":60,"parent_item":56,"target":53,"isCanonical":53,"translations":140,"to":53,"menu":141},"m_main_api_EventSubscription","EventSubscription","/api-reference/eventsubscription/latest",[],{"position":63},{"id":143,"label":138,"description":53,"icon":53,"trailing_icon":53,"href":139,"sort":132,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":144,"to":53,"menu":145},"m_footer_api_eventsubscription",[],{"position":82},{"id":147,"label":148,"description":53,"icon":53,"trailing_icon":53,"href":149,"sort":150,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":151,"to":53,"menu":152},"m_sb_introduction","Introduction","/guide/introduction",5,[],{"position":135},{"id":154,"label":155,"description":53,"icon":53,"trailing_icon":53,"href":156,"sort":150,"status":60,"parent_item":56,"target":53,"isCanonical":53,"translations":157,"to":53,"menu":158},"m_main_api_Payment","Payment","/api-reference/payment/latest",[],{"position":63},{"id":160,"label":155,"description":53,"icon":53,"trailing_icon":53,"href":156,"sort":150,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":161,"to":53,"menu":162},"m_footer_api_payment",[],{"position":82},{"id":164,"label":165,"description":53,"icon":53,"trailing_icon":53,"href":166,"sort":167,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":168,"to":53,"menu":169},"m_sb_getting_started","Getting started","/guide/getting-started",6,[],{"position":135},{"id":171,"label":172,"description":53,"icon":53,"trailing_icon":53,"href":173,"sort":174,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":175,"to":53,"menu":176},"m_sb_pagination","Pagination & Filtering","/guide/pagination-and-filtering",7,[],{"position":135},{"id":178,"label":179,"description":53,"icon":53,"trailing_icon":53,"href":180,"sort":181,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":182,"to":53,"menu":183},"m_sb_integration_scenarios","Integration scenarios","/guide/integration-scenarios",8,[],{"position":135},{"id":185,"label":186,"description":53,"icon":53,"trailing_icon":53,"href":187,"sort":188,"status":60,"parent_item":53,"target":53,"isCanonical":53,"translations":189,"to":53,"menu":190},"m_sb_changelogs","Changelogs","/guide/changelogs",12,[],{"position":135},{"id":192,"label":193,"description":53,"icon":53,"trailing_icon":53,"href":194,"sort":195,"status":60,"parent_item":185,"target":53,"isCanonical":53,"translations":196,"to":53,"menu":197},"m_sb_changelog_AccessControl","AccessControl Changelog","/guide/changelogs/accesscontrol",13,[],{"position":135},{"id":199,"label":200,"description":53,"icon":53,"trailing_icon":53,"href":201,"sort":202,"status":60,"parent_item":185,"target":53,"isCanonical":53,"translations":203,"to":53,"menu":204},"m_sb_changelog_Configuration","Configuration Changelog","/guide/changelogs/configuration",14,[],{"position":135},{"id":206,"label":207,"description":53,"icon":53,"trailing_icon":53,"href":208,"sort":209,"status":60,"parent_item":185,"target":53,"isCanonical":53,"translations":210,"to":53,"menu":211},"m_sb_changelog_HotelApi","HotelApi Changelog","/guide/changelogs/hotelapi",15,[],{"position":135},{"id":213,"label":214,"description":53,"icon":53,"trailing_icon":53,"href":215,"sort":216,"status":60,"parent_item":185,"target":53,"isCanonical":53,"translations":217,"to":53,"menu":218},"m_sb_changelog_EventSubscription","EventSubscription Changelog","/guide/changelogs/eventsubscription",16,[],{"position":135},{"id":220,"label":221,"description":53,"icon":53,"trailing_icon":53,"href":222,"sort":223,"status":60,"parent_item":185,"target":53,"isCanonical":53,"translations":224,"to":53,"menu":225},"m_sb_changelog_Payment","Payment Changelog","/guide/changelogs/payment",17,[],{"position":135},[227,235],{"title":57,"links":228},[229,231,232,233,234],{"text":66,"href":67,"target":230},"_self",{"text":85,"href":86,"target":230},{"text":108,"href":109,"target":230},{"text":138,"href":139,"target":230},{"text":155,"href":156,"target":230},{"title":236,"links":237},"Integrations",[238,239,240],{"text":72,"href":73,"target":74},{"text":98,"href":99,"target":74},{"text":121,"href":122,"target":74},{"id":242,"slug":243,"title":179,"description":244,"blocks":245,"contentBlocks":256,"seo":262},"p_integration-scenarios","integration-scenarios","How the HotelPlatform APIs work together: PMS reservation sync, kiosk key cards, PIN codes, terminal payments, webhooks and n8n workflows.",[246],{"id":247,"type":248,"title":53,"subtitle":53,"content":249,"image":53,"ctaText":53,"ctaUrl":53,"module":250,"alignment":53,"ratio":53,"colorScheme":251,"settings":252,"items":253,"texts":254},"b_integration-scenarios","markdown","\u003Ch1>Integration scenarios\u003C/h1>\n\u003Cp>These scenarios show how the HotelPlatform APIs work together in real hotel integrations: a property management system (PMS) feeding reservations, a self check-in kiosk that issues key cards, a guest web app with PIN codes, card payments at the front office, and clients that stay in sync through webhooks and workflows. Each scenario links to the API categories it uses.\u003C/p>\n\u003Ch2 id=\"a-pms-pushes-reservations-and-profiles\" tabindex=\"-1\">A PMS pushes reservations and profiles\u003C/h2>\n\u003Cp>A PMS, a channel manager or any other third-party client keeps the HotelPlatform up to date with its hotel reservations. It creates every new booking with its stays and guest profiles, and sends changes as they happen in the PMS.\u003C/p>\n\u003Cp>\u003Cimg src=\"/media/images/diagrams/scenario-pms-push.svg\" alt=\"Sequence diagram: a PMS or other third-party client creates a reservation with stays and guest profiles in the Hotel API, updates it when it changes, assigns a room and cancels its stays when the booking is cancelled.\">\u003C/p>\n\u003Cul>\n\u003Cli>Create and update bookings with the \u003Ca href=\"/api-reference/hotelapi/latest#tag/reservations\">Reservations\u003C/a> endpoints. Send the PMS's own id as \u003Ccode>externalId\u003C/code>, so you can find the reservation again without storing HotelPlatform ids.\u003C/li>\n\u003Cli>Keep guest data in \u003Ca href=\"/api-reference/hotelapi/latest#tag/profiles\">Profiles\u003C/a>: name, contact details, addresses and preferred language.\u003C/li>\n\u003Cli>Arrival, departure, room assignment and services belong to the \u003Ca href=\"/api-reference/hotelapi/latest#tag/stays\">Stays\u003C/a> of a reservation.\u003C/li>\n\u003Cli>When a booking is cancelled, set the status of its stays to \u003Ccode>Cancelled\u003C/code> instead of deleting the reservation. The booking and its history stay available, and subscribers receive a \u003Ccode>stayUpdated\u003C/code> event they can act on.\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"self-check-in-kiosk-issues-a-key-card\" tabindex=\"-1\">Self check-in kiosk issues a key card\u003C/h2>\n\u003Cp>A kiosk in the lobby checks guests in without the front desk. It reads the reservation, lets the guest complete the registration, encodes a key card for the stay and hands it out from the card dispenser.\u003C/p>\n\u003Cp>\u003Cimg src=\"/media/images/diagrams/scenario-kiosk-keycard.svg\" alt=\"Sequence diagram: a guest checks in at a kiosk, which reads the reservation from the Hotel API, updates the guest profile, creates the key card with one createKey call that encodes it and moves it out of the card dispenser, and sets the stay to checked in.\">\u003C/p>\n\u003Cul>\n\u003Cli>Look up the booking in \u003Ca href=\"/api-reference/hotelapi/latest#tag/reservations\">Reservations\u003C/a> and check that the stay is eligible: arrival today, a room assigned and no amount due.\u003C/li>\n\u003Cli>Save the registration details to the guest's \u003Ca href=\"/api-reference/hotelapi/latest#tag/profiles\">profile\u003C/a>.\u003C/li>\n\u003Cli>Encode the key card with \u003Ca href=\"/api-reference/accesscontrol/latest#tag/key\">Key\u003C/a> (\u003Cem>Create a Key\u003C/em>, \u003Ccode>POST /access/controllers/{controllerId}/key\u003C/code>) on the card encoder's controller. When that controller references the kiosk's card dispenser, the same call moves the card out to the guest; no separate dispenser request is needed. \u003Ca href=\"/api-reference/accesscontrol/latest#tag/carddispenser\">CardDispenser\u003C/a> is there for the dispenser's status and maintenance.\u003C/li>\n\u003Cli>Set the stay to checked in through \u003Ca href=\"/api-reference/hotelapi/latest#tag/stays\">Stays\u003C/a>. The encoder and the dispenser are set up once in the \u003Ca href=\"/api-reference/configuration/latest#tag/configuration\">Configuration API\u003C/a>.\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"guest-web-app-issues-a-pin-code\" tabindex=\"-1\">Guest web app issues a PIN code\u003C/h2>\n\u003Cp>Guests who arrive late or skip the front desk get a PIN code for their room in a web app, linked from the booking confirmation. The PIN is valid from arrival to departure only.\u003C/p>\n\u003Cp>\u003Cimg src=\"/media/images/diagrams/scenario-webapp-pin.svg\" alt=\"Sequence diagram: a guest opens a web app before arrival, the app reads the stay from the Hotel API, checks that the stay has no key yet and has the AccessControl API create a PIN code, which the guest sees in the app.\">\u003C/p>\n\u003Cul>\n\u003Cli>Read the stay from \u003Ca href=\"/api-reference/hotelapi/latest#tag/reservations\">Reservations\u003C/a>, then create the PIN code with \u003Ca href=\"/api-reference/accesscontrol/latest#tag/key\">Key\u003C/a> (\u003Cem>Create a Key\u003C/em>) on the controller of the PIN locks; a controller's type decides whether it issues key cards or PIN codes.\u003C/li>\n\u003Cli>Before creating one, list the stay's keys with \u003Ca href=\"/api-reference/accesscontrol/latest#tag/key\">Key\u003C/a> and show the PIN it already has: a guest who opens the app twice should not get a second code. To guarantee one PIN per reservation, let a workflow issue it (see the n8n example below).\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"front-office-takes-a-payment-on-a-terminal\" tabindex=\"-1\">Front office takes a payment on a terminal\u003C/h2>\n\u003Cp>The front office collects the amount due on a card terminal. A payment intent starts the transaction on the terminal; once it completes, the payment is recorded on the reservation. See the \u003Ca href=\"/api-reference/payment/latest\">Payment API\u003C/a> reference.\u003C/p>\n\u003Cp>\u003Cimg src=\"/media/images/diagrams/scenario-front-office-payment.svg\" alt=\"Sequence diagram: the front office starts a payment intent with the Payment API, the guest pays on the card terminal, the front office reads the final status and records the payment on the reservation in the Hotel API.\">\u003C/p>\n\u003Cul>\n\u003Cli>Start the transaction with a \u003Ca href=\"/api-reference/payment/latest#tag/intent\">payment intent\u003C/a> (\u003Ccode>POST /intents\u003C/code>, amount in the lowest currency unit). It returns at once with status \u003Ccode>processing\u003C/code>; the result arrives as the \u003Ccode>intentUpdated\u003C/code> event or on a later read.\u003C/li>\n\u003Cli>A terminal handles one transaction at a time: a second intent for the same terminal is refused with \u003Ccode>409\u003C/code> until the first one is final.\u003C/li>\n\u003Cli>Record the payment on the booking with \u003Ca href=\"/api-reference/hotelapi/latest#tag/payments\">Payments\u003C/a> in the Hotel API.\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"a-client-keeps-in-sync-through-webhooks\" tabindex=\"-1\">A client keeps in sync through webhooks\u003C/h2>\n\u003Cp>Changes made by kiosks, web apps or the front office have to reach the PMS and other systems. Instead of polling, a client subscribes to the events it needs and receives them as signed webhooks.\u003C/p>\n\u003Cp>\u003Cimg src=\"/media/images/diagrams/scenario-webhook-sync.svg\" alt=\"Sequence diagram: a client subscribes to events, answers the signed verification challenge, and later receives signed profileUpdated and stayUpdated events, verifies them, reads the changed records from the Hotel API and applies them.\">\u003C/p>\n\u003Cul>\n\u003Cli>Create a webhook subscription with \u003Ca href=\"/api-reference/eventsubscription/latest#tag/subscription\">Subscription\u003C/a>, listing events such as \u003Ccode>profileUpdated\u003C/code>, \u003Ccode>stayUpdated\u003C/code> or \u003Ccode>keyCreated\u003C/code>. Your endpoint has to answer the signed verification challenge before the subscription is active.\u003C/li>\n\u003Cli>Check every request as described in \u003Ca href=\"/api-reference/eventsubscription/latest#description/webhook-security\">Webhook security\u003C/a>, and use \u003Ccode>webhook-id\u003C/code> to drop duplicates.\u003C/li>\n\u003Cli>By default an event carries the resource type and id; read the current record from the Hotel API. With \u003Ccode>dataRequired: true\u003C/code> the full event data comes along.\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"pre-arrival-pin-code-built-in-n8n\" tabindex=\"-1\">Pre-arrival PIN code built in n8n\u003C/h2>\n\u003Cp>Workflow tools such as n8n, Make or Zapier receive the same webhooks and turn events into automations without code on your servers. In this n8n example, a new booking triggers a pre-arrival email with the guest's PIN code.\u003C/p>\n\u003Cp>\u003Cimg src=\"/media/images/diagrams/scenario-n8n-workflow.svg\" alt=\"Sequence diagram: an n8n workflow receives the signed reservationCreated webhook, answers the verification challenge, verifies the signature, reads the reservation from the Hotel API, issues the stay's single PIN code with the idempotent AccessControl call and emails it to the guest.\">\u003C/p>\n\u003Cul>\n\u003Cli>A \u003Cem>Webhook\u003C/em> trigger receives the events; a \u003Cem>Respond to Webhook\u003C/em> node echoes the \u003Ccode>challenge\u003C/code> of the verification request so the subscription becomes active.\u003C/li>\n\u003Cli>A \u003Cem>Code\u003C/em> node checks the signature over the raw body (\u003Ca href=\"/api-reference/eventsubscription/latest#description/webhook-security\">Webhook security\u003C/a>) and stops the workflow when it does not match.\u003C/li>\n\u003Cli>One \u003Cem>HTTP Request\u003C/em> node reads the reservation from \u003Ca href=\"/api-reference/hotelapi/latest#tag/reservations\">Reservations\u003C/a>; a second one issues the PIN with \u003Ca href=\"/api-reference/accesscontrol/latest#tag/key\">Key\u003C/a> (\u003Cem>Create or Reconcile a Key for a Stay\u003C/em>). That call is idempotent: when n8n retries or the event arrives twice, the stay keeps its single PIN code. An email node sends the message. For workflows on your own workflow server, a subscription with \u003Ccode>eventType: workflow\u003C/code> starts the workflow directly.\u003C/li>\n\u003C/ul>\n",[],"default",{},[],{"body":255},"# Integration scenarios\n\nThese scenarios show how the HotelPlatform APIs work together in real hotel integrations: a property management system (PMS) feeding reservations, a self check-in kiosk that issues key cards, a guest web app with PIN codes, card payments at the front office, and clients that stay in sync through webhooks and workflows. Each scenario links to the API categories it uses.\n\n## A PMS pushes reservations and profiles\n\nA PMS, a channel manager or any other third-party client keeps the HotelPlatform up to date with its hotel reservations. It creates every new booking with its stays and guest profiles, and sends changes as they happen in the PMS.\n\n![Sequence diagram: a PMS or other third-party client creates a reservation with stays and guest profiles in the Hotel API, updates it when it changes, assigns a room and cancels its stays when the booking is cancelled.](/media/images/diagrams/scenario-pms-push.svg)\n\n- Create and update bookings with the [Reservations](/api-reference/hotelapi/latest#tag/reservations) endpoints. Send the PMS's own id as `externalId`, so you can find the reservation again without storing HotelPlatform ids.\n- Keep guest data in [Profiles](/api-reference/hotelapi/latest#tag/profiles): name, contact details, addresses and preferred language.\n- Arrival, departure, room assignment and services belong to the [Stays](/api-reference/hotelapi/latest#tag/stays) of a reservation.\n- When a booking is cancelled, set the status of its stays to `Cancelled` instead of deleting the reservation. The booking and its history stay available, and subscribers receive a `stayUpdated` event they can act on.\n\n## Self check-in kiosk issues a key card\n\nA kiosk in the lobby checks guests in without the front desk. It reads the reservation, lets the guest complete the registration, encodes a key card for the stay and hands it out from the card dispenser.\n\n![Sequence diagram: a guest checks in at a kiosk, which reads the reservation from the Hotel API, updates the guest profile, creates the key card with one createKey call that encodes it and moves it out of the card dispenser, and sets the stay to checked in.](/media/images/diagrams/scenario-kiosk-keycard.svg)\n\n- Look up the booking in [Reservations](/api-reference/hotelapi/latest#tag/reservations) and check that the stay is eligible: arrival today, a room assigned and no amount due.\n- Save the registration details to the guest's [profile](/api-reference/hotelapi/latest#tag/profiles).\n- Encode the key card with [Key](/api-reference/accesscontrol/latest#tag/key) (*Create a Key*, `POST /access/controllers/{controllerId}/key`) on the card encoder's controller. When that controller references the kiosk's card dispenser, the same call moves the card out to the guest; no separate dispenser request is needed. [CardDispenser](/api-reference/accesscontrol/latest#tag/carddispenser) is there for the dispenser's status and maintenance.\n- Set the stay to checked in through [Stays](/api-reference/hotelapi/latest#tag/stays). The encoder and the dispenser are set up once in the [Configuration API](/api-reference/configuration/latest#tag/configuration).\n\n## Guest web app issues a PIN code\n\nGuests who arrive late or skip the front desk get a PIN code for their room in a web app, linked from the booking confirmation. The PIN is valid from arrival to departure only.\n\n![Sequence diagram: a guest opens a web app before arrival, the app reads the stay from the Hotel API, checks that the stay has no key yet and has the AccessControl API create a PIN code, which the guest sees in the app.](/media/images/diagrams/scenario-webapp-pin.svg)\n\n- Read the stay from [Reservations](/api-reference/hotelapi/latest#tag/reservations), then create the PIN code with [Key](/api-reference/accesscontrol/latest#tag/key) (*Create a Key*) on the controller of the PIN locks; a controller's type decides whether it issues key cards or PIN codes.\n- Before creating one, list the stay's keys with [Key](/api-reference/accesscontrol/latest#tag/key) and show the PIN it already has: a guest who opens the app twice should not get a second code. To guarantee one PIN per reservation, let a workflow issue it (see the n8n example below).\n\n## Front office takes a payment on a terminal\n\nThe front office collects the amount due on a card terminal. A payment intent starts the transaction on the terminal; once it completes, the payment is recorded on the reservation. See the [Payment API](/api-reference/payment/latest) reference.\n\n![Sequence diagram: the front office starts a payment intent with the Payment API, the guest pays on the card terminal, the front office reads the final status and records the payment on the reservation in the Hotel API.](/media/images/diagrams/scenario-front-office-payment.svg)\n\n- Start the transaction with a [payment intent](/api-reference/payment/latest#tag/intent) (`POST /intents`, amount in the lowest currency unit). It returns at once with status `processing`; the result arrives as the `intentUpdated` event or on a later read.\n- A terminal handles one transaction at a time: a second intent for the same terminal is refused with `409` until the first one is final.\n- Record the payment on the booking with [Payments](/api-reference/hotelapi/latest#tag/payments) in the Hotel API.\n\n## A client keeps in sync through webhooks\n\nChanges made by kiosks, web apps or the front office have to reach the PMS and other systems. Instead of polling, a client subscribes to the events it needs and receives them as signed webhooks.\n\n![Sequence diagram: a client subscribes to events, answers the signed verification challenge, and later receives signed profileUpdated and stayUpdated events, verifies them, reads the changed records from the Hotel API and applies them.](/media/images/diagrams/scenario-webhook-sync.svg)\n\n- Create a webhook subscription with [Subscription](/api-reference/eventsubscription/latest#tag/subscription), listing events such as `profileUpdated`, `stayUpdated` or `keyCreated`. Your endpoint has to answer the signed verification challenge before the subscription is active.\n- Check every request as described in [Webhook security](/api-reference/eventsubscription/latest#description/webhook-security), and use `webhook-id` to drop duplicates.\n- By default an event carries the resource type and id; read the current record from the Hotel API. With `dataRequired: true` the full event data comes along.\n\n## Pre-arrival PIN code built in n8n\n\nWorkflow tools such as n8n, Make or Zapier receive the same webhooks and turn events into automations without code on your servers. In this n8n example, a new booking triggers a pre-arrival email with the guest's PIN code.\n\n![Sequence diagram: an n8n workflow receives the signed reservationCreated webhook, answers the verification challenge, verifies the signature, reads the reservation from the Hotel API, issues the stay's single PIN code with the idempotent AccessControl call and emails it to the guest.](/media/images/diagrams/scenario-n8n-workflow.svg)\n\n- A *Webhook* trigger receives the events; a *Respond to Webhook* node echoes the `challenge` of the verification request so the subscription becomes active.\n- A *Code* node checks the signature over the raw body ([Webhook security](/api-reference/eventsubscription/latest#description/webhook-security)) and stops the workflow when it does not match.\n- One *HTTP Request* node reads the reservation from [Reservations](/api-reference/hotelapi/latest#tag/reservations); a second one issues the PIN with [Key](/api-reference/accesscontrol/latest#tag/key) (*Create or Reconcile a Key for a Stay*). That call is idempotent: when n8n retries or the event arrives twice, the stay keeps its single PIN code. An email node sends the message. For workflows on your own workflow server, a subscription with `eventType: workflow` starts the workflow directly.\n",[257],{"id":247,"type":248,"title":53,"subtitle":53,"content":249,"image":53,"ctaText":53,"ctaUrl":53,"module":258,"alignment":53,"ratio":53,"colorScheme":251,"settings":259,"items":260,"texts":261},[],{},[],{"body":255},{},1793893888307]