Getting paid / QR payment block
A QR payment block that still scans off the printed page
A machine-readable payment code beside the amount and reference, so a payer can scan instead of typing an account number.
Why this block is harder than it looks
Two problems stacked. The layout one is that a code is a physical object with a minimum size and a mandatory margin of blank space around it, and both of those get lost the moment somebody adjusts the block to fit. The information one is that a payment code is only useful if the human-readable details beside it say the same thing, and they are usually rendered by different code from different variables, so they drift. A code that encodes the old reference next to a printed new one is worse than no code, because the payment arrives unmatched.
The decisions that make it work
Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.
- Size the code in millimetres, never as a percentage. A code is a physical measurement and a percentage makes its size depend on whatever the container happened to be.
- Put the quiet zone on the container as padding rather than trusting the encoder to include it. That way it survives a change of encoder and it is visible in the markup.
- Encode from exactly the same variables that print beside it, in the same pass, so the code and the text cannot disagree.
- Print the payment details in full as text as well. A code is a convenience, not the only route, and scanners fail.
- Embed as SVG. A rasterised code is resampled at print resolution and the module edges drift, which is the whole tolerance.
- Keep the code out of the fold line and away from the edge if the document will be posted. A crease through a code is a code that does not scan.
The fragment
Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.
<section class="pay">
<div class="code">
<!-- SVG from your own encoder, sized in millimetres -->
<img src="data:image/svg+xml;base64,..." alt="Payment code"
width="120" height="120">
</div>
<dl class="detail">
<dt>Amount</dt><dd>5,016.00 EUR</dd>
<dt>Reference</dt><dd>WH-2026-0418</dd>
<dt>IBAN</dt><dd>GB29 NWBK 6016 1331 9268 19</dd>
</dl>
</section>
<style>
.pay {
display: grid;
grid-template-columns: auto 1fr;
column-gap: 8mm;
align-items: start;
break-inside: avoid;
margin-top: 12pt;
}
.pay .code {
padding: 4mm; /* the quiet zone, owned by the container */
background: #fff;
}
.pay .code img {
display: block;
width: 32mm; /* a physical size, not a percentage */
height: 32mm;
}
.pay .detail { display: grid; grid-template-columns: auto 1fr;
column-gap: 8pt; row-gap: 3pt; margin: 0; font-size: 9pt; }
.pay .detail dt { color: #555; white-space: nowrap; }
.pay .detail dd { margin: 0; font-variant-numeric: tabular-nums; }
</style>What breaks when it is built the obvious way
Letting the quiet zone come from the surrounding layout. It is present while the block sits in the middle of a white page and it vanishes the day somebody puts a tinted panel behind the payment section, at which point the code stops scanning and nothing in the diff explains why.
How to prove it survived pagination
Print at actual size and scan it with a phone, on paper, under office lighting rather than on screen. Then read the amount and reference in the scanned result against the ones printed beside it. Both have to match, and that is the check people skip.
Where it sits in a finished document
This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The invoice template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.
Frequently asked
Will this fragment work on its own?
Not as a whole document. It has no page rule, no margins and no base type, because those belong to the document rather than to the block, and duplicating them in every fragment would mean thirty copies to keep in step. Paste it into a template that already has them.
Why does it look right in a browser and wrong in the PDF?
Because a browser window is one continuous surface and a document is a stack of fixed rectangles. Nothing in a scrolling view exercises a page boundary, so every break rule in the fragment is inert until the content is paginated. Render the real thing with enough content to cross two or three boundaries, then look.
Do I need a special option on the render request for this?
No. Everything on this page is CSS and markup, which is your side of the boundary. What the render has to give you is a real page size with real margins, and after that the layout is decided by the stylesheet.
Other parts of a document
The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.
A bank details block that can be transcribed without errors
Account number, sort code or routing number, IBAN and BIC, set so that a person copying them into a banking screen gets them right the first time.
Payment terms and due date that cannot be missed or misread
The line that says when the money is due and what happens if it is not, which is short, easy to write and easy to place somewhere nobody reads.
A tear-off remittance slip at the foot of an invoice
A detachable panel at the bottom of the page carrying the reference, the amount and the payee, meant to be torn off and returned with a payment.
A signature block that never lands alone on the last page
Rule, printed name, title and date, laid out to be signed by hand, and required to stay attached to the text it is signing.
Invoice, as a complete file
The whole document with this block already in place, ready to copy and change.
image-rendering in paged output
The property carrying the weight here, with its real support status.
Every part of a document
The full list, grouped by the kind of problem the block poses.
Paste the fragment into the playground inside a page rule and see what it does at a real page size. That is the only way any of this gets confirmed.