Part of ZenUML for Confluence · For payments, banking and fintech engineering teams
Document Every Step a Payment Takes
When money moves between your services, banks, card networks and payment gateways, the order of calls is where the bugs hide. Write those flows as sequence diagrams in Confluence, next to the specs, runbooks and decisions that explain them.
Install Free — Lite Plan · See the example diagrams
✓ Sequence diagrams, Mermaid, draw.io and OpenAPI in one app ✓ Diagrams stored in your Confluence site ✓ Every save kept in version history
Correctness is a property of the sequence
A double charge, a refund that settles before its capture, a retry that hits the gateway twice: these failures come from the order of messages between systems. A box-and-arrow picture hides that order. A sequence diagram shows it, including the branches for retries, timeouts and declines.
ZenUML sequence diagrams are written as text, so engineers can review a change to a payment flow the same way they review code.
Payment flows
Show how retries avoid a double charge
Idempotency keys only work if every service checks them in the right place. Put the check in the diagram so reviewers can see it.
title Card Payment with an Idempotency Key
@Actor Customer
@Boundary Checkout
@Control Payments
@Database Ledger
@Boundary Gateway
Customer->Checkout.pay(order) {
Checkout->Payments.authorize(order, key) {
previous = Ledger.find(key)
if(previous) {
// Retry of a request we already handled: no second charge
return previousResult
} else {
Ledger.reserve(key)
result = Gateway.authorize(amount, card)
Ledger.record(key, result)
return result
}
}
}
Agree on the states a payment can be in
Product, engineering, operations and finance often disagree about when a payment counts as "done". A Mermaid state diagram gives them one definition.
stateDiagram-v2
[*] --> Initiated
Initiated --> Authorized: Issuer approves
Initiated --> Declined: Issuer declines
Authorized --> Captured: Merchant captures
Authorized --> Voided: Cancelled before capture
Captured --> Settled: Funds settled
Settled --> Refunded: Refund issued
Settled --> Disputed: Chargeback raised
Disputed --> Settled: Dispute won
Disputed --> Refunded: Dispute lost
Declined --> [*]
Voided --> [*]
Refunded --> [*]
The exact source above, rendered live in your browser by Mermaid.js — the same library the ZenUML macro uses.
Keep the API contract next to the flow
Publish your payment API as an OpenAPI document on the same page as the sequence diagram, so partners and internal teams read the contract and the behaviour together.
Operations and controls
Make reconciliation steps explicit
End-of-day reconciliation involves the ledger, bank statements and an exceptions queue. Draw the process once and keep it with the operations runbook.
flowchart TD
A[Bank statement file received] --> B[Load into reconciliation job]
L[Internal ledger entries for the day] --> B
B --> C{Every entry matched?}
C -- Yes --> D[Mark day as reconciled]
C -- No --> E[Create exception for each unmatched entry]
E --> F[Finance operations review]
F --> G{Cause found?}
G -- Timing difference --> H[Carry to next day]
G -- Error --> I[Post correcting entry]
H --> D
I --> D
Rendered live in your browser by Mermaid.js.
Show where compliance checks happen
Onboarding flows touch identity verification, sanctions screening and manual review. A sequence diagram shows exactly where each check runs and what happens when one fails.
title Account Opening with KYC and Sanctions Screening
@Actor Applicant
@Boundary App
@Control Onboarding
@Boundary KYC
@Boundary Sanctions
@Actor Analyst
Applicant->App.apply(docs) {
App->Onboarding.open(case) {
kyc = KYC.verify(docs)
screen = Sanctions.check(name)
if(kyc.passed && screen.clear) {
Onboarding->Onboarding.activate()
} else {
Onboarding->Analyst.review(case)
}
}
}
Keep a record of every change
Each save of a diagram is kept in its version history, and the page keeps its Confluence page history. When someone asks how a flow looked at a given time, you can open the earlier version.
Let your AI agent read the flows
The ZenUML MCP server lets Claude Code, Codex, Cursor and other MCP clients find, read, create and update your diagrams in Confluence. The agent signs in as you and reaches only the pages your Confluence permissions allow.
Example diagrams
Every example on this page is a working diagram. Copy the source into a ZenUML macro and it renders on your Confluence page. The systems, names and rules are illustrative, not a recommendation for your own payment design.
| Example | Diagram type |
|---|---|
| Card payment with an idempotency key | ZenUML sequence diagram |
| Payment lifecycle | Mermaid state diagram |
| Daily reconciliation | Mermaid flowchart |
| Account opening with KYC and sanctions screening | ZenUML sequence diagram |
Frequently asked questions
Where are the diagrams stored?
Diagrams are stored as Confluence custom content in your Atlassian site, under the same permissions as the page. ZenUML sequence, Mermaid, draw.io and OpenAPI diagrams render in the reader's browser. PlantUML is the exception: its source is sent to the public plantuml.com service to produce the image, so avoid PlantUML for content that must not leave your site. See the Confluence app FAQ for details.
Can we see who changed a diagram and when?
Yes. Every save of a diagram is kept as a new version of its Confluence custom content, and the page keeps its own Confluence page history. Earlier versions can be reviewed and restored.
Can we keep the diagram source in Git as well?
Yes. ZenUML sequence diagrams, Mermaid and PlantUML are plain text. Copy the source into a repository to review changes in pull requests next to the code they describe.
Does ZenUML handle payments or customer data?
No. ZenUML is a diagramming app for Confluence. It documents how your payment and onboarding systems work; it does not process transactions or store customer records.
Start with the example diagrams
Install ZenUML for Confluence from the Atlassian Marketplace and paste any example above into a page. The Lite plan is free.