Pix QR Code rendering
Pix pay-in orders return the QR Code in the following fields:
| Field | Content |
|---|---|
qrcodeData | Pix copy-and-paste payload (EMV BR Code) |
qrcodeBase64 (or qrcodeImageBase64) | PNG image of the QR Code, in Base64 |
qrcodeLink | URL of the same image |
The simplest and safest option is to display the image returned by the API. If you need to render your own image (for example, to add a logo or match your layout), follow the rules below.
General rules
Section titled “General rules”- Encode the
qrcodeDatavalue exactly as received, byte for byte. Do not trim, change letter case, add line breaks or rebuild the payload. The last four characters are a CRC over the whole string, and any change makes the code invalid. - Use byte mode encoding. The payload is plain ASCII.
- Always show the copy-and-paste text next to the image, so the payer has a fallback when the camera cannot read the code.
- Keep a quiet zone (white margin) of at least 4 modules around the code.
- Use dark modules on a light background. Do not invert colors, apply gradients or round the three corner squares (finder patterns).
- Export as PNG or SVG. Avoid JPEG, which blurs module edges, and never stretch the image.
- On screens, use at least 4 pixels per module, which means an image of around 300 px or more. In print, use at least 0.33 mm per module.
Error correction level
Section titled “Error correction level”QR Codes carry redundant data that lets a reader recover damaged areas. The error correction level defines how much. A logo placed over the code is damage from the reader’s point of view, so it consumes this margin.
| Scenario | Level | Notes |
|---|---|---|
| Without logo | M | Recovers about 15%. Keeps the code less dense. |
| With logo | Q | Recovers about 25%. Required whenever a logo is added. |
Never use level L with a logo. Level H is not recommended either: it increases the QR version, which makes the modules denser and places the logo over alignment patterns, and in practice it read worse than Q in our tests.
Adding a logo
Section titled “Adding a logo”- Use error correction level Q.
- Limit the logo, including any white padding around it, to 10% of the QR Code area (about 30% of its side).
- Center the logo. Do not cover the three corner squares or the timing lines between them.
- Validate every new layout with at least two different readers before publishing it.
Readability tests
Section titled “Readability tests”The table below shows the read rate of a real Pix payload (QR version 8 to 13, depending on the level) under simulated camera conditions: downscaling, blur, noise, perspective and low contrast, each read by two different decoders. The logo percentage is the share of the QR Code area covered by the logo and its padding.
| Level | Without logo | Logo 4% | Logo 7% | Logo 10% | Logo 15% | Logo 20% |
|---|---|---|---|---|---|---|
| L | 95% | 72% | 13% | 0% | 0% | 0% |
| M | 95% | 95% | 90% | 95% | 0% | 0% |
| Q | 95% | 95% | 95% | 95% | 90% | 81% |
| H | 90% | 90% | 90% | 72% | 0% | 0% |
A code that reads well in one app may still fail in another, because payer apps use different decoding libraries. Staying within the limits above keeps a safety margin for the weaker readers.
Homologation checklist
Section titled “Homologation checklist”Before going live with a custom QR Code layout:
- Payload encoded from
qrcodeDatawithout any change. - Error correction level M (without logo) or Q (with logo).
- Logo, if any, within 10% of the area and away from the corner squares.
- Quiet zone of at least 4 modules.
- Image in PNG or SVG, at least 300 px on screen.
- Copy-and-paste text displayed next to the image.
- Code scanned successfully in the apps of several different banks.
- Copy-and-paste text pasted manually in the same apps.