Skip to main content

​
Core Concepts

Vouchers, sessions, settlement, and the Bleepay execution flow.
Understanding these concepts will help you integrate and operate Bleepay correctly.

​
Voucher (6-digit code)

A voucher is a short-lived, human-readable code generated by the payer’s wallet and bound to an authorization context. It acts as an ephemeral proxy for payment authorization.
  • Format: Typically 6 digits (numeric) or 6 alphanumeric characters, depending on mode.
  • Transmission: Can be passed by any channel: typed, spoken, QR, NFC, or messaging.
  • Lifecycle: Reserved at generation, unreserved when the session is completed or expired.
  • Security: Does not expose public or private keys; only the payer’s wallet can sign the resulting transaction.

​
Session

A voucher session is the short-lived state on Bleepay’s side that links:
  • One or more voucher codes
  • The payer’s identity (bound cryptographically)
  • Transaction parameters (amount, currency, destination, etc.)
A session can contain multiple transactions — not just a single payment. Each voucher within a session is treated independently, with its own lifecycle, but all share the same session context for grouping and tracking. The session exists from voucher generation until all transaction objects are retrieved and authorized by the payer. After that, the session is finalized and voucher codes are returned to the pool.

​
Payment flow (high level)

  1. Payer logs in and opens a context → receives a context code that links their identity to the payment session.
  2. Payer shares the context code with the payee (typed, spoken, QR, etc.).
  3. Payee authenticates using their API key (x-api-key header), reserves a voucher using the context code (receives a 6-digit code), and redeems it by specifying what they expect to receive (expectedPayment) — currency, amount, and destination address.
  4. Bleepay validates the voucher, syncs transaction metadata, and builds the transaction (swap/bridge/transfer) for the appropriate chain and token.
  5. Payer reviews, signs in their wallet, and submits the receipt via resolve-voucher; the wallet broadcasts to the network.
  6. Settlement — funds arrive at the payee’s address (or via liquidation partner for fiat).

​
Non-custodial model

  • Client-side signing: Private keys stay in the user’s wallet. Bleepay provides transaction payloads; all signatures happen locally.
  • No custody: Bleepay never holds user funds. Settlement is on-chain or via regulated off-ramp partners.
  • Session integrity: Codes are ephemeral and bound to a specific payment intent, reducing replay and misuse.

​
Chain-agnostic merchant experience

Merchants integrate using financial metadata only: amount, currency, wallet address. They do not:
  • Choose chains or tokens (the system determines the network from the currency)
  • Manage gas or RPC
  • Write or deploy smart contracts
Bleepay’s backend handles routing, gas, cross-chain, and DEX logic so the merchant stays chain-agnostic.

​
Next steps