> ## Documentation Index
> Fetch the complete documentation index at: https://firmngin.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Device Billing Overview

> Charge customers for device use: public pages, orders, payments, and sessions

Device Billing turns connected devices into paid services. A merchant can publish a public page, sell prepaid services, meter postpaid usage, accept invoice or QR payments, withdraw settled balance through payouts, and review orders, sessions, revenue, and device-level logs.

\[image:Device Billing dashboard with revenue, orders, sessions, and merchant public page status]

> [!NOTE]
>
> Device Billing is currently available for Indonesia-focused payment flows. Available payment methods depend on the channels enabled for your merchant.

## Business modes

Every linked device runs in one business mode. **Service** sells session-based use of the device. **Vending** sells physical items that the device dispenses after payment, and it can also run an on-device kiosk checkout. **Terminal** turns the device into a QRIS payment terminal: the merchant enters an amount on the device and the customer scans the QR code to pay.

Business mode decides what happens after the order is confirmed. Prepaid and postpaid decide when the customer pays.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant Client as Client (Payer)
    participant Firmngin
    participant Device
    Client->>Firmngin: Complete the order
    alt Service mode
        Firmngin->>Device: Start the paid session
        Device->>Client: Provide the service
        Client->>Firmngin: End the session
        Firmngin->>Device: Stop the service
        Firmngin->>Client: Close the order
    else Vending mode
        Firmngin->>Device: Send the paid units to dispense
        Device->>Client: Dispense the items
        Firmngin->>Client: Show the receipt
    else Terminal mode
        Device->>Client: Show a QRIS code for the entered amount
        Client->>Firmngin: Scan and pay
        Firmngin->>Device: Confirm the payment
    end
```

> **[Business Modes](https://firmngin.dev/docs/device-billing/business-modes)**
>
> Compare Service, Vending, and Terminal, and set the mode for a linked device.

> **[Vending and kiosk](https://firmngin.dev/docs/device-billing/vending-mode.md)**
>
> Multi-item carts, per-device stock, and kiosk checkout on the device screen.

## Prepaid and postpaid

The main difference is when the final amount becomes known and when the customer pays.

| | Prepaid | Postpaid |
| - | - | - |
| When the price is known | Before the service starts | After usage or duration is measured |
| When the customer pays | Before using the service | After the session ends |
| How the amount is calculated | Fixed item price × quantity | Start amount + measured usage or duration |
| Quantity | Can allow multiple quantities | One measured session per order |
| Best for | Fixed packages, access fees, and known-price services | Energy, water, rental time, sensor values, and event-based services |
| Configuration | Set a fixed catalog price | Attach an active price rule |

Choose **Prepaid** when every customer should see and pay the final amount before the service begins. Choose **Postpaid** when the final bill depends on what happens during the session.

> **[Prepaid](https://firmngin.dev/docs/device-billing/prepaid.md)**
>
> Charge a fixed amount before the customer starts using the service.

> **[Postpaid](https://firmngin.dev/docs/device-billing/postpaid.md)**
>
> Calculate the final amount from usage or duration and collect payment after the session.

> **[Payouts](https://firmngin.dev/docs/device-billing/payouts.md)**
>
> Withdraw available settled merchant balance to a supported payout destination.

## Payouts

Customer payments move through their payment and settlement lifecycle before becoming available merchant balance. When balance is settled, use **Payout** to withdraw it to a supported bank account or e-wallet.

The current dashboard requires a minimum payout of IDR 20,000 and prevents withdrawal above the available settled balance. See [Payouts](https://firmngin.dev/docs/device-billing/payouts.md) for the direct payout and payout link flows.

## Prepaid flow

```mermaid actions={false} theme={null}
sequenceDiagram
    participant Client as Client (Payer)
    participant Firmngin
    participant Merchant
    participant Device
    Client->>Firmngin: Select item and review fixed price
    Client->>Firmngin: Complete payment
    Firmngin->>Merchant: Confirm paid order
    Firmngin->>Device: Activate the purchased service
    Device->>Client: Provide the purchased service
```

## Postpaid flow

```mermaid actions={false} theme={null}
sequenceDiagram
    participant Client as Client (Payer)
    participant Firmngin
    participant Merchant
    participant Device
    Client->>Firmngin: Start a postpaid session
    Firmngin->>Merchant: Confirm the service session
    Firmngin->>Device: Start the metered service
    Device->>Client: Provide the metered service
    Client->>Firmngin: End the session
    Firmngin->>Device: End the metered service
    Firmngin->>Client: Show the final bill
    Client->>Firmngin: Complete payment
    Firmngin->>Merchant: Confirm payment
```

## Plan limits

When your workspace exhausts the message quota on its active plan, Firmngin automatically disables the merchant. While the merchant is disabled, it cannot receive new orders.

Upgrade your plan to restore merchant availability and continue accepting orders.

## Main objects

| Object | Meaning |
| - | - |
| Merchant | Workspace-owned Device Billing profile and public page settings. |
| Item | Sellable product or service attached to one or more devices. |
| Order | Customer purchase intent and payment lifecycle. |
| Session | Time-bound or usage-bound access to a device or service. |
| Payment | Invoice, QR, or provider-specific payment record. |

## Payment state

An order page shows the latest payment state so customers know what to do next.

| State | Meaning |
| - | - |
| Pending | The customer still needs to complete payment. |
| Processing | The payment is being confirmed. |
| Paid | Payment is complete and the order can continue. |
| Expired or cancelled | The payment can no longer be completed from that order. |

## Session detail

Session detail shows the start time, end time, device, item, payment method, who ended the session, and whether the service is still active.

## Public pages

Public pages should:

* Show only device names allowed by workspace settings.
* Show whether a device is currently available.
* Keep the customer's active order visible while the service is running.
* Present clear payment, verification, and session actions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.