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

# Protocol Flow

> Detailed voucher generation, redemption, and settlement sequence.

This page describes the **algorithmic flow** of the Bleepay voucher-based protocol: generation, transmission, redemption, invoice retrieval, and settlement.

## Phase 1: Voucher generation

* **S101** — Payer starts a digital payment in the wallet. Wallet builds `VOUCHER_INIT` (e.g. payer identifier, optional context, timestamp, nonce).
* **S102** — Wallet signs `VOUCHER_INIT` with the payer's private key (e.g. ECDSA/Ed25519).
* **S103** — Request sent over secure transport (e.g. HTTPS/TLS 1.3 or gRPC).
* **S104** — Payment server verifies signature, timestamp, nonce.
* **S105** — Server generates a unique voucher code (e.g. 6-char alphanumeric via CSPRNG).
* **S106** — Server creates a session record (voucher, payer ref, TTL, context) in storage.
* **S107** — Server returns `VOUCHER_ISSUE` (voucher code, TTL, session metadata).
* **S108** — Wallet displays the voucher to the user.

## Phase 2: Voucher transmission

* **S109** — Payer transmits the voucher by any channel: manual entry (numeric or alphanumeric), QR, NFC, BLE, messaging, etc. The system is transport-agnostic.

## Phase 3: Redemption and invoice generation

* **S201** — Payee interface captures the voucher and builds `VOUCHER_REDEEM` (voucher code + payee transaction parameters: amount, asset, destination, network).
* **S202** — Payee sends `VOUCHER_REDEEM` over secure transport.
* **S203** — Server looks up the active session by voucher; verifies TTL has not expired.
* **S204** — Server builds a blockchain-compatible **unsigned** transaction object `TX_UNSIGNED` (e.g. destination, asset, amount, nonce placeholder, fee/gas template, optional contract calldata). No signature or private-key operation is applied on the server.
* **S205** — Server marks the session as pending-signature and sends `TX_PENDING_NOTIFY` to the payer's wallet (e.g. WebSocket/push) so the wallet knows `TX_UNSIGNED` is ready for retrieval.

## Phase 4: Invoice retrieval and payer authorization

* **S206** — Wallet receives the notification and sends `TX_FETCH` (voucher/session ref), signed by the payer's private key.
* **S207** — Server verifies the signature against the payer bound to the session and returns `TX_UNSIGNED`.
* **S208** — Server finalizes the session: marks it completed, deletes session metadata, unreserves the voucher code and returns it to the pool.
* **S209** — Wallet displays transaction details (amount, asset, destination, fees).
* **S210** — If allowed by the protocol, the wallet may fill or adjust dynamic fields (e.g. nonce, max fee) before signing.
* **S211** — After payer confirmation, the wallet validates `TX_UNSIGNED` and signs it, producing `TX_SIGNED`.

## Phase 5: Signing and settlement

* **S212** — Wallet broadcasts `TX_SIGNED` via the network's native interface (e.g. JSON-RPC/Web3, REST, node API).
* **S213** — The blockchain processes and settles the transaction according to its consensus rules.
* **S214** — Wallets and systems update balances/status from on-chain confirmations.

## State machine

```text theme={null}
RESERVED → REDEEMED (via redeemVoucher)
RESERVED → DISCARDED (via discardVoucher)
REDEEMED → RESOLVED (via resolveVoucher)
REDEEMED → DISCARDED (via discardVoucher)
Any → EXPIRED (automatic, when expiresAt < now)
```

## Message types (summary)

| Message             | Direction        | Purpose                                        |
| ------------------- | ---------------- | ---------------------------------------------- |
| VOUCHER\_INIT       | Wallet → Server  | Voucher generation request.                    |
| VOUCHER\_ISSUE      | Server → Wallet  | Voucher code and session data.                 |
| VOUCHER\_REDEEM     | Payee → Server   | Redemption request with payee parameters.      |
| TX\_PENDING\_NOTIFY | Server → Wallet  | Pending invoice ready for retrieval.           |
| TX\_FETCH           | Wallet → Server  | Signed request to retrieve transaction object. |
| TX\_UNSIGNED        | Server → Wallet  | Unsigned transaction for signing.              |
| TX\_SIGNED          | Wallet → Network | Signed transaction for broadcast.              |

Encoding and transport (JSON, CBOR, gRPC, etc.) can vary; the logical sequence and roles are as above.

## Next steps

* [Terminology](/home/reference/terminology) — definitions of voucher, session, invoice, etc.
* [Voucher modes](/home/reference/voucher-modes) — numeric vs alphanumeric.
* [Simple Payments](/home/web2-web3-payments/simple-payments) — SIMPLE voucher examples.