---
sidebar_label: 'Custom hardware integrations'
sidebar_position: 5
---

# Custom hardware integrations

:::note
Each diagram below illustrates one possible high-level integration flow, not a fixed specification. For the authoritative reference on each integration, see the the specific integration articles.
:::

The message flow between the kiosk frontend, FO, the kiosk integration (cloud and on-device), and the POS depends on which capabilities your kiosk integration provides. This article gives one diagram per scenario, so find the heading that matches your integration rather than reading all of them.

## Scanner integration

If your kiosk uses barcode or QR code scanning, refer to the following diagram. Scanning does not depend on, or change, the payment or printing flow.

This diagram shows the messages exchanged when the guest scans a barcode or QR code, independent of any payment or printing scenario below.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over intdevice : User scans code
    intdevice->>plugin: Code scan 'abc123'
    plugin->>ui: Code scan 'abc123'
    note over ui : UI and associated<br/>systems handle<br/>scanned code
```

See [Scanner service](../frontend-plugins/services/scanner-service.md) for the plugin-side implementation.

## Without external payment terminal integration

Use this section if the kiosk does not integrate with a payment terminal — for example, if the guest pays with a mobile wallet, a stored value card, or another payment method that is not connected to the kiosk itself.

### Non-fiscal country

#### Without receipt printing option selection

This diagram shows a kiosk order placed without any kiosk payment terminal integration, in a non-fiscal country, with no receipt printing option offered to the guest.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant pos as POS

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    ui->>pos: Place order
    alt Successful order placement
    pos-->>ui: Order Placed
    note over ui : Order confirmed
    else Failed order placement
    pos-->>ui: Failed to Place
    note over ui : Order placement failed
    end
```

#### With receipt printing option selection

This diagram shows the same non-fiscal, no-payment-terminal scenario, but with the guest offered a receipt printing option after a successful order placement.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant pos as POS
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    ui->>pos: Place order
    alt Successful order placement
    pos-->>ui: Order Placed
    note over ui : Allow guest to<br/>select receipt option
    alt User selects to print receipt
    ui->>plugin: Print receipt
    plugin->>intdevice: Print receipt
    note over intdevice : Print receipt
    else User selects not to print receipt
    note over ui : Order confirmed without receipt
    end
    else Failed order placement
    pos-->>ui: Failed to Place
    note over ui : Order placement failed
    end
```

### Fiscal country

When payment does not go through the kiosk's own payment terminal integration, there is no payment reservation or capture flow to anchor fiscalization to. Instead, Kiosk Integration Cloud listens for the [order.placed_in_pos](../../events/order/placed-in-pos) event from FO and fiscalizes based on that event.

#### Without receipt printing option selection

This diagram shows a kiosk order placed without any kiosk payment terminal integration, in a fiscal country, with no receipt printing option — Kiosk Integration Cloud fiscalizes directly off the `order.placed_in_pos` event.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant intcloud as Kiosk Integration<br/>Cloud

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    ui->>pos: Place order
    alt Successful order placement
    pos-->>ui: Order Placed
    fo-->>intcloud: order.placed_in_pos event
    note over intcloud : Fiscalize
    note over ui : Order confirmed
    else Failed order placement
    pos-->>ui: Failed to Place
    note over ui : Order placement failed
    end
```

#### With receipt printing option selection

This diagram shows the same fiscal, no-payment-terminal scenario, but with a receipt printing option offered to the guest. If a receipt option selection dialog is shown, fiscalization happens in line with that choice — with the print, or with the order cleared message if the guest declines. If neither of those is observed, for example because the dialog times out, Kiosk Integration Cloud must still fiscalize on its own once it has received the `order.placed_in_pos` event, since the fiscal obligation does not depend on whether a receipt was printed.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    ui->>pos: Place order
    alt Successful order placement
    pos-->>ui: Order Placed
    fo-->>intcloud: order.placed_in_pos event
    note over ui : Allow guest to<br/>select receipt option
    alt User selects to print receipt
    ui->>plugin: Print receipt
    plugin->>intdevice: Print receipt
    note over intdevice : Fiscalize
    note over intdevice : Print receipt
    else User selects not to print receipt
    ui->>plugin: Order cleared
    plugin->>intdevice: Order cleared
    note over intdevice : Fiscalize
    end
    note over intcloud : If no order cleared event is<br/>observed from the plugin, or<br/>on timeout, fiscalize anyway<br/>since order.placed_in_pos<br/>was already received
    else Failed order placement
    pos-->>ui: Failed to Place
    note over ui : Order placement failed
    end
```

## With external payment terminal integration

When a kiosk needs to accept card payment through a payment terminal Future Ordering does not already integrate with, you can connect that terminal by integrating the terminal as an [External Payment Provider](../external-payment-provider/overview.md).

Use one of the following sections if the kiosk integrates with a payment terminal via a [External Payment Provider](../external-payment-provider/overview.md). Pick the section matching whether the terminal supports `AUTH` separated from `CAPTURE`, whether the country is a fiscal country, and whether or not the integration also provides receipt printing options as well.

### AUTH separated from CAPTURE

#### Non-fiscal country

##### Without receipt printing option selection

This diagram shows a payment terminal that supports `AUTH` separated from `CAPTURE`, in a non-fiscal country, with no receipt printing option offered to the guest — the terminal captures and prints the receipt automatically once the order is placed.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>intdevice: Reserve amount
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    intdevice->>intcloud: Payment reserved
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>intdevice: Capture reservation
    note over intdevice : Capture reservation
    note over intdevice : Print receipt
    intdevice->>intcloud: Reservation captured
    intcloud->>fo: Reservation Captured
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    intcloud->>intdevice: Annul reservation
    note over intdevice : Annul reservation
    intdevice->>intcloud: Reservation annulled
    intcloud->>fo: Reservation annulled
    end
```

##### With receipt printing option selection

This diagram shows the same AUTH/CAPTURE-separated, non-fiscal scenario, but with the guest offered a receipt printing option after a successful order placement, instead of the receipt being printed automatically.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>intdevice: Reserve amount
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    intdevice->>intcloud: Payment reserved
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>fo: Reservation Captured
    note over ui : Allow guest to<br/>select receipt option
    alt User selects to print receipt
    ui->>plugin: Print receipt
    plugin->>intdevice: Print receipt
    note over intdevice : Print receipt
    else User selects not to print receipt
    end
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    intcloud->>intdevice: Annul reservation
    note over intdevice : Annul reservation
    intdevice->>intcloud: Reservation annulled
    intcloud->>fo: Reservation annulled
    end
```

#### Fiscal country

##### Without receipt printing option selection

This diagram shows the AUTH/CAPTURE-separated scenario in a fiscal country with no receipt printing option offered to the guest — the terminal captures, prints, and fiscalizes automatically once the order is placed.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>intdevice: Reserve amount
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    intdevice->>intcloud: Payment reserved
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>intdevice: Capture reservation
    note over intdevice : Capture reservation
    note over intdevice : Print receipt
    note over intdevice : Fiscalize
    intdevice->>intcloud: Reservation captured
    intcloud->>fo: Reservation Captured
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    intcloud->>intdevice: Annul reservation
    note over intdevice : Annul reservation
    intdevice->>intcloud: Reservation annulled
    intcloud->>fo: Reservation annulled
    end
```

##### With receipt printing option selection

This diagram shows the AUTH/CAPTURE-separated scenario in a fiscal country with a receipt printing option offered to the guest — fiscalization happens in line with the guest's print or order-cleared choice instead of automatically at capture.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>intdevice: Reserve amount
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    intdevice->>intcloud: Payment reserved
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>fo: Reservation Captured
    note over ui : Allow guest to<br/>select receipt option
    alt User selects to print receipt
    ui->>plugin: Print receipt
    plugin->>intdevice: Print receipt
    note over intdevice : Fiscalize
    note over intdevice : Print receipt
    else User selects not to print receipt
    note over intdevice : This also needs to happen<br/>on timeout if capture<br/>has been requested
    ui->>plugin: Order cleared
    plugin->>intdevice: Order cleared
    note over intdevice : Fiscalize
    end
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    intcloud->>intdevice: Annul reservation
    note over intdevice : Annul reservation
    intdevice->>intcloud: Reservation annulled
    intcloud->>fo: Reservation annulled
    end
```

### Single SALE operation (AUTH + CAPTURE together)

#### Non-fiscal country

##### Without receipt printing option selection

This diagram shows a payment terminal that performs `AUTH` and `CAPTURE` as a single SALE operation, in a non-fiscal country, with no receipt printing option offered to the guest.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>intdevice: Perform Payment
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    intdevice->>intcloud: Payment performed
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>fo: Reservation Captured
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    intcloud->>intdevice: Reverse payment
    note over intdevice : Reverse payment
    intdevice->>intcloud: Reservation annulled
    intcloud->>fo: Reservation annulled
    end
```

##### With receipt printing option selection

This diagram shows the same single-SALE, non-fiscal scenario, but with the guest offered a receipt printing option after a successful order placement.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>intdevice: Perform Payment
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    intdevice->>intcloud: Payment performed
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>fo: Reservation Captured
    note over ui : Allow guest to<br/>select receipt option
    alt User selects to print receipt
    ui->>plugin: Print receipt
    plugin->>intdevice: Print receipt
    note over intdevice : Print receipt
    else User selects not to print receipt
    end
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    intcloud->>intdevice: Reverse payment
    note over intdevice : Reverse payment
    intdevice->>intcloud: Reservation annulled
    intcloud->>fo: Reservation annulled
    end
```

#### Fiscal country

Since AUTH and CAPTURE cannot be separated, the terminal must fiscalize and print the receipt as part of the single SALE operation, before FO knows whether the POS will accept the order (POS integrations can build POS-specific functionality to reduce risk of order placement failures, such as pre-loading the order to the POS before starting payment). If the POS later rejects the order, there is no automated way to reverse a fiscal receipt that has already been printed — this is why annulment in this scenario falls back to a manual store-side process.

##### Without receipt printing option selection

This diagram shows the single-SALE scenario in a fiscal country with no receipt printing option offered to the guest — fiscalization and printing happen upfront as part of the SALE, before FO knows whether the POS will accept the order (POS integrations can build POS-specific functionality to reduce risk of order placement failures, such as pre-loading the order to the POS before starting payment).

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>fo: Get order info
    fo-->>intcloud: Order info
    intcloud->>intdevice: Perform Payment
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    note over intdevice : Fiscalize
    note over intdevice : Print Receipt
    intdevice->>intcloud: Payment performed
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>fo: Reservation Captured
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    note over intcloud: Reverse payment and fiscal<br/>or trigger manual process to<br/>handle on store side
    intcloud->>fo: Reservation annulled
    end
```

##### With receipt printing option selection

This diagram shows the single-SALE scenario in a fiscal country with a receipt printing option offered to the guest — the terminal fiscalizes upfront during the SALE, then again in line with the guest's later print or order-cleared choice.

```mermaid
sequenceDiagram
    participant ui as User Interface
    participant fo as FO
    participant pos as POS
    participant plugin as Kiosk Integration<br/>Frontend Plugin
    participant intcloud as Kiosk Integration<br/>Cloud
    participant intdevice as Kiosk Integration<br/>On-device

    note over ui : Page is loaded,<br/>which loads plugins.<br/>Plugins register services
    note over ui : User works with basket
    note over ui : User moves to payment<br/>method selection
    note over ui : User selects to<br/>pay with kiosk terminal
    ui->>fo: Start payment
    note over fo: Create transaction and<br/>start orchestration
    fo->>intcloud: Reserve amount<br/>(inc. FO kiosk device id)
    intcloud->>fo: Get order info
    fo-->>intcloud: Order info
    intcloud->>intdevice: Perform Payment
    note over intdevice : Guide user through<br/>payment process on<br/>terminal
    note over intdevice : Fiscalize
    note over intdevice : Print Receipt
    intdevice->>intcloud: Payment performed
    intcloud->>fo: Payment reserved
    fo->>pos: Place order
    alt Successful order placement
    pos-->>fo: Order Placed
    fo->>intcloud: Capture reservation
    intcloud->>fo: Reservation Captured
    note over ui : Allow guest to<br/>select receipt option
    alt User selects to print receipt
    ui->>plugin: Print receipt
    plugin->>intdevice: Print receipt
    note over intdevice : Fiscalize
    note over intdevice : Print receipt
    else User selects not to print receipt
    note over intdevice : This also needs to happen<br/>on timeout if capture<br/>has been requested
    ui->>plugin: Order cleared
    plugin->>intdevice: Order cleared
    note over intdevice : Fiscalize
    end
    else Failed order placement
    pos-->>fo: Failed to Place
    fo->>intcloud: Annul reservation
    note over intcloud: Reverse payment and fiscal<br/>or trigger manual process to<br/>handle on store side
    intcloud->>fo: Reservation annulled
    end
```

## See also

- [External Payment Provider Integrations](../external-payment-provider/overview.md)
- [Frontend Plugins - Receipt service](../frontend-plugins/services/receipt-service.md)
- [Frontend Plugins - Scanner service](../frontend-plugins/services/scanner-service.md)
- [External Kiosk Monitor](../custom-kiosk-shell/external-kiosk-monitor.md)
- [order.placed_in_pos](../../events/order/placed-in-pos)