The Open Financial Protocol for interoperable payments.
Public rules, contracts, certification criteria and a federation model — implementable by anyone, controlled by no one.
The protocol exists independently of any operator.
| Protocol | github.com/banza-protocol/banza — this repository |
| Knowledge System | github.com/banza-protocol/banzai |
| Reference | BANZA_REFERENCIA.md (PT — canonical) · BANZA_REFERENCE.md (EN) |
| Website | banza.network |
BANZA is a protocol — a set of public rules that defines how certified payment operators interoperate.
HTTP → Web
SMTP → Email
BGP → Internet routing
BANZA → Interoperable payments
BANZA defines rules (financial invariants), contracts (OpenAPI, webhook schemas, QR payload, event schemas), certification (L0–L4), federation (inter-operator routing), trust (a PKI hierarchy) and governance (an open ADR/RFC process).
BANZA does not process payments, store balances, maintain accounts, move money, or depend on any specific rail, operator or technology stack.
HTTP does not define browsers. SMTP does not define email clients. BGP does not define routers. In the same way, BANZA does not define wallets, apps, software or companies.
If every current operator ceased operations tomorrow, the BANZA protocol — its rules, contracts, invariants, certification criteria and federation model — would remain fully valid and available to any new operator.
Payment infrastructure exists. What is missing is a common protocol layer. Without one, operators cannot interoperate without bilateral agreements, trust must be negotiated case by case, and there is no shared definition of correct financial behaviour — nor an open path to prove it.
BANZA defines the rules. Operators implement them. Any operator that passes conformance becomes certified. Certified operators federate — route payments between each other — without bilateral agreements.
BANZA = Open Financial Protocol (defines)
BANZA CA = Certification Authority (certifies)
Operators = Independent implementations (implement)
BanzAI = Protocol Knowledge System (explains)
These roles never merge. No operator is privileged. No technology is mandated. Examples in BANZA documentation use Operator A, Operator B, Operator C — never real commercial names.
The protocol's integrity guarantees. Any certified operator must enforce them, regardless of implementation technology:
| Invariant | Description |
|---|---|
INV-LEDGER-001 |
Every posting sums to zero (double-entry) |
INV-LEDGER-002 |
Ledger entries are immutable after creation |
INV-LEDGER-003 |
All monetary values are integers (no floating point) |
INV-LEDGER-004 |
Postings are atomic — never partially applied |
INV-WALLET-001 |
balance = available + reserved at all times |
INV-STL-001 |
gross = net + fee (no money creation) |
INV-IDEM-001 |
Same idempotency key always produces the same result |
Families: INV-LEDGER-* · INV-WALLET-* · INV-SETTLE-* · INV-IDEM-* ·
INV-RECON-* · INV-QR-*. Behaviour specs: docs/core/.
| Level | Name | What it means |
|---|---|---|
| L0 | Protocol Sandbox | Protocol-correct sandbox; financial invariants verifiable |
| L1 | Core Payment Capability | Wallets, ledger, transfers, idempotency |
| L2 | Payment Initiation Capability | QR payments and payment links |
| L3 | Inter-Operator Interoperability | Routes to and receives from other certified operators |
| L4 | External Interoperability | Integrates with external infrastructure |
Certification is verified by a deterministic conformance suite — never by self-declaration. The BANZA CA issues certificates. BanzAI explains the criteria but does not certify.
Quick start — conformance evidence:
BANZA is a protocol, not a runtime or operator. Operators implement it
independently and expose public endpoints; conformance testing is URL-based
against those endpoints. The recommended operator-facing tool is the
banza-conformance CLI.
Available on official PyPI:
pip install banza-conformance==0.1.0
banza-conformance \
--url https://sandbox.operador.exemplo \
--level 0 \
--output banza-l0-report.jsonOr run the official Docker image, available on GHCR (pinned tag — no latest):
docker pull ghcr.io/banza-protocol/banza-conformance:v0.1.0
docker run --rm -v "$PWD/reports:/reports" \
ghcr.io/banza-protocol/banza-conformance:v0.1.0 \
--url https://sandbox.operador.exemplo \
--level 0 \
--output /reports/banza-l0-report.jsonA PASS produces conformance evidence, not a certificate. Before the official release, the distribution was validated on TestPyPI; the current recommended path is official PyPI.
How operators participate:
- Read the protocol reference —
BANZA_REFERENCIA.md(PT) ·BANZA_REFERENCE.md(EN) - Read the certification framework —
BANZA_CERTIFICATION.md - Implement the protocol in your chosen technology stack and expose a public sandbox endpoint (
/health,/.well-known/banza/operator.json) - Run
banza-conformanceagainst your public URL to generate an evidence report - Submit the evidence later, when production certification opens — the BANZA CA verifies it and signs a certificate only after the M2/M3 milestones
There is no approved SDK, approved language, or approved infrastructure. The
conformance suite verifies correctness; the runner and test vectors live in
tools/banza-conformance/ and conformance/.
Certification status:
| Item | Status |
|---|---|
| Conformance runner | Available |
CLI package (banza-conformance) |
Available on official PyPI (0.1.0) |
| Official PyPI | Available |
| TestPyPI | Validation channel (previously validated) |
| Docker / GHCR image | Available (v0.1.0 — no latest) |
| Production certificates | Not live |
| Certified operators | None |
| M2/M3 | Required for production issuance |
A PASS is conformance evidence for the requested level — not production certification. Production certification remains M2/M3-gated, and BANZA CA issuance is a separate step. Conformance does not replace legal, regulatory, KYC/KYB or banking obligations.
Developer / internal fallback (for contributors working inside the BANZA repository):
python3 tools/banza-conformance/run.py \
--url http://localhost:3000 \
--level 0 \
--output report.jsonCertified operators at L3+ federate:
- Operator A routes a payment to a user of Operator B
- No bilateral agreement required — trust is cryptographically proven by BANZA certificates
- Routing follows open protocol contracts; settlement rules are defined by the protocol
Details: docs/federation/ · test vectors: conformance/
Root Key (offline · ceremony-controlled · INV-ROOT-001)
↓
Issuing Keys (HSM-protected)
↓
Operator Certificates (ed25519 · 90-day maximum lifetime)
↓
Protocol Capability Manifests (signed · /.well-known/banza/operator.json)
Operators pin the root key once and use it to verify all subsequent
certificates. BanzAI never holds production keys.
Details: ADR-026 · ADR-029 · docs/security/
The protocol evolves through an open process, available to all operators:
- ADRs record accepted architecture decisions —
docs/adr/ - RFCs propose protocol changes for open comment —
docs/rfc/ - Historical and operator-era records are preserved in
docs/history/
Model: BANZA_GOVERNANCE.md
BANZA does not prescribe implementation technology. The protocol defines behaviour, never stack:
- Monetary values: integer arithmetic in minor units — no floating point
- Ledger writes: synchronous and atomic at the posting step
- Double-entry: every debit has a corresponding credit
- Wallet balances: always ledger-derived
- Every financial operation: idempotent and replay-safe
Any language, database or runtime that satisfies the invariants and passes conformance is a valid implementation.
BanzAI is the adjacent knowledge system at banza.network/banzai. It explains
the rules; it never makes them:
| BanzAI does | BanzAI does NOT do |
|---|---|
| Explain protocol rules with citations | Define or change rules |
| Explain certification criteria and gaps | Issue certificates |
| Explain recorded traces against invariants | Execute the authoritative conformance suite |
| Search and navigate ADRs, RFCs, contracts | Hold production keys |
| Validate documents against published schemas | Make certification decisions |
Repository: banza-protocol/banzai · Documentation: docs/banzai/
Tools determine truth. AI explains truth.
All protocol specifications live in contracts/:
| Path | Content |
|---|---|
contracts/openapi/ |
REST API definitions — what operators must expose |
contracts/webhooks/ |
Webhook payload schemas |
contracts/qr/ |
QR code content specification |
contracts/events/ |
Event schemas |
contracts/federation/ |
Federation event and key-manifest contracts |
No feature exists in prose only: once implementation begins, every feature has
a corresponding artifact in contracts/.
banza/
├── contracts/ Protocol contracts (canonical specifications)
├── conformance/ Conformance suite — certification test vectors
├── docs/
│ ├── adr/ Architecture Decision Records (active)
│ ├── rfc/ Protocol RFCs (open for comment)
│ ├── core/ Protocol behaviour — ledger, wallets, QR, settlement
│ ├── federation/ Federation protocol documentation
│ ├── governance/ Operating rules, language policy, audits
│ ├── security/ Root key ceremony (M2)
│ ├── architecture/ Lifecycles, diagram registry and standards
│ └── history/ Historical archive (non-normative)
├── examples/ Conceptual examples (illustrative only)
├── tools/ Identity, purity, conformance and SVG checks
├── apps/docs/ Public documentation website
├── apps/website/ Institutional protocol website (banza.network, pt-PT)
├── BANZA_REFERENCIA.md Protocol reference (PT — canonical)
├── BANZA_REFERENCE.md Protocol reference (EN)
├── BANZA_ARCHITECTURE.md Protocol architecture
├── BANZA_CERTIFICATION.md Certification levels L0–L4
├── BANZA_CONFORMANCE.md Conformance suite
├── BANZA_GOVERNANCE.md Governance model and ADR process
├── BANZA_SECURITY.md Security model
└── BANZA_MANIFESTO.md Protocol manifesto
Not in this repository: SDKs, operator implementations, integrations and
product code — those live with operators. Enforced by make purity-check and
make identity-check (CI: identity-guard).
| BANZA is | BANZA is not |
|---|---|
| An open protocol specification | A consumer app or wallet |
| Rules for interoperable payments | A payment processor |
| A certification framework (L0–L4) | A card gateway |
| A federation model for operators | Any operator's private property |
| A PKI trust model (BANZA CA) | A specific product or company |
Is BANZA a product? No. BANZA is a protocol specification. Products are built by independent certified operators.
Who can become an operator? Any entity that implements the contracts, satisfies the invariants and passes the deterministic conformance suite. Certification is issued by BANZA CA.
Which technology stack is required? None. The protocol defines behaviour, never stack.
Does BANZA depend on BanzAI? No. Remove BanzAI and the protocol loses nothing normative. BanzAI depends on BANZA — never the other way around.
Who owns the protocol? No one operator. Governance is open via ADRs and RFCs; the specification is published under open licenses.
make identity-check # no operator-specific brand contamination
make purity-check # protocol-only artifacts, no build outputs
make conformance-check # conformance vectors against a live operator
make svg-check # required protocol diagrams presentContributions welcome to protocol contracts, the conformance suite, documentation (ADRs, RFCs, reference material) and examples. See CONTRIBUTING.md. Protocol rule changes happen here — via the open ADR/RFC process.
Report vulnerabilities to security@banza.network. Do not open public issues. See BANZA_SECURITY.md.
License: contracts and specifications under Apache 2.0; documentation under Creative Commons CC BY 4.0. BANZA is operator-neutral protocol infrastructure — no operator owns it.