Concepts·PayNotes

Concepts

PayNotes

PayNotes are how money joins the same interaction model as everything else in Blue. Not a new rail. Not a new currency. A document attached to a transaction that governs what should happen with it.

The key idea

A normal transaction often has almost no visible process around it. A PayNote adds that process:

  • secure the funds now
  • complete the payment later
  • cancel before completion
  • reverse after completion
  • wait for delivery confirmation
  • require approval or a review window
  • settle commission splits
  • trigger follow-on transactions

That is what makes money composable with the rest of a Blue world.

Participants

A PayNote usually has at least:

  • payer
  • payee
  • guarantor — the trusted financial participant controlling the rail-side action

Additional participants may matter: courier, verifier, service provider, marketplace, insurer.

Why PayNotes matter

Without PayNotes, a payment is often just an isolated transaction with logic hidden in a platform or processor. With PayNotes, the payment becomes part of the same explicit world as:

  • the order
  • the delivery
  • the mandate
  • the review policy
  • the partner split
  • the downstream service logic
Without PayNotes, a payment is an isolated transaction. With PayNotes, it is part of the same explicit world as everything else.

Relation to mandates

A mandate defines what an agent or delegated actor is allowed to do. A PayNote governs what should happen with the money once a transaction is in play. They are different blocks, but they often work together:

  • mandate says the agent may buy within certain rules
  • PayNote says the transaction only completes after delivery confirmation and review

Why this is not "just escrow"

Escrow is one possible pattern a PayNote can represent. But PayNotes are broader — they can represent:

  • conditional completion
  • staged release
  • review-window logic
  • marketplace settlement
  • split flows
  • recurring patterns
  • agent-governed spending
  • bank-guaranteed conditional flows
For the full type definitions, lifecycle vocabulary, canonical requests/responses, and worked examples, see the PayNote reference. There is also paynotes.blue ↗ for rail-specific extensions.