How does Pix QRCode work?

Pix is the name of the instant payment scheme in Brazil.

You can read more about Pix in English here Brazil Central Bank Pix.

Before we dive into how Pix QRCode works, we will cover a few other Pix concepts

Pix Alias

The first concept that you need to learn about Pix is the concept of Alias or Pix Key.
A Pix alias enables you to associate a given key to a particular bank account, and if needed you could reassociate to another bank account.

A good association is that a bank account is like an IP and the Pix Alias is like a DNS, that will route the payment to the correct bank account.

Pix alias is managed by PSP (Payment Service Providers) using the DICT API

Pix Charge

A Pix Charge is a payment request that accepts a single payment and it is used to reconcile a payment. Each Pix Charge has a unique txid.
If you want to receive a single payment and reconcile it, this is the preferred method.
You can check the charge status and also receive a webhook when the charge is paid.

Pix Location

A location is an endpoint that contains charge information.
You can modify a location to point to another charge.
This makes it possible to print a QRCode that will show different charge information based on the system or payer.

Pix QRCode

Pix QRCode is called BR Code.
BR Code uses the standard EMV (Europay, Mastercard, and Visa).
The same standard as the payment cards.
EMV uses TLV to store information

Here is an example of BR Code

00020101021226910014br.gov.bcb.pix2569qrcodes.fiduciascm.digital/v1/qr/ded35b9c-fdf8-4789-ba97-24f26cc9327252040000530398654041.005802BR5910Woovi_Demo6009Sao_Paulo6229052544e554f94d8a4d4cb72a1848f630470AA

If you render this BR Code in a QRCode and scan it in your Brazil payment app will be able to pay it, only if somebody has not paid it yet. Can you be the first one?

We can have 2 types of QRCodes, one that uses a Pix Key and another one that uses a Pix Location.
When using the Pix Key in the QRCode you can have an identifier in the QRCode to group many payments.
When using a Pix Location the bank while reading the QRCode will fetch the last information about the charge from the location endpoint.

Reading the BR Code

We built a BR Code decoding tool.

We can see that this BR Code is using a location qrcodes.fiduciascm.digital/v1/qr/ded35b9c-fdf8-4789-ba97-24f26cc93272

If you download the content of this location you will get a JWT payload

eyJhbGciOiJQUzUxMiIsImtpZCI6IkJGRUVBM0Q4ODA4NzYyNkY0QTJBNUEyNUVGMkU0NTMxNzAwRTM3MzkiLCJ4NXQiOiJ2LTZqMklDSFltOUtLbG9sN3k1Rk1YQU9OemsiLCJ0eXAiOiJKV1MiLCJqa3UiOiJodHRwczovL3FyY29kZXMuZmlkdWNpYXNjbS5kaWdpdGFsLy53ZWxsLWtub3duL2p3a3MifQ.eyJjYWxlbmRhcmlvIjp7ImV4cGlyYWNhbyI6MzE1NjExMzAsImNyaWFjYW8iOiIyMDI0LTA3LTEzVDIwOjAwOjExLjAzMVoiLCJhcHJlc2VudGFjYW8iOiIyMDI0LTA3LTEzVDIwOjAwOjExLjAzMVoifSwidmFsb3IiOnsib3JpZ2luYWwiOiIxLjAwIiwibW9kYWxpZGFkZUFsdGVyYWNhbyI6MH0sInJldmlzYW8iOjAsImNoYXZlIjoiYTUyNzc4YWMtYTBjMS00MTBkLTgwMjgtZTk3YjE3ZDU3NGJjIiwidHhpZCI6IjQ0RTU1NEY5NEQ4QTRENENCNzJBMTg0OEYzQjRDNUM5Iiwic3RhdHVzIjoiQVRJVkEifQ.oYCkb-u8cZqo0ISPL9Ny29vDs8LlneYE1X9TnbEUfF3fzPFl3SY-2P7lYjcenPnSPUbWaDV0F4LIkcaXpTIWoHbdZWQJnrgn5anPTgNOUXo4GCvjpkNLGVLlz6WPUU3buwPeRt8cuGvjxSj0kLMlxTmrfLt-xW7J1kPNKwviMU2rMkXUfP225YZiAhMfNlPJ7oGi14ov1AnOyN2OAbbekoEKgqCX3lCnFo9GFDUqVMdoxvNGKHKIaqt2clRf265_0DiIhNBUZWgb8bM15SJLTGhADJAhoVcISXbRvhFIIy8loMkNNOhwUmP5HZm45RuNnr9XQoKr-h-74ROMWRY3KQ

{
  "alg": "PS512",
  "kid": "BFEEA3D88087626F4A2A5A25EF2E4531700E3739",
  "x5t": "v-6j2ICHYm9KKlol7y5FMXAONzk",
  "typ": "JWS",
  "jku": "https://qrcodes.fiduciascm.digital/.well-known/jwks"
}

The JWT header gives you the jku with the JWKS location URL that you need to use to validate the JWT against the certificates.

Only valid certificates from PSP with licenses are accepted by the banks.

{
  "calendario": {
    "expiracao": 31561130,
    "criacao": "2024-07-13T20:00:11.031Z",
    "apresentacao": "2024-07-13T20:00:11.031Z"
  },
  "valor": {
    "original": "1.00",
    "modalidadeAlteracao": 0
  },
  "revisao": 0,
  "chave": "a52778ac-a0c1-410d-8028-e97b17d574bc",
  "txid": "44E554F94D8A4D4CB72A1848F3B4C5C9",
  "status": "ATIVA"
}

The body payload contains the Pix Charge information like value, and payer, and could also have discounts, interests, and fines.
txid is the unique identifier of this Pix Charge.
When the Pix Charge is paid a transaction is generated with the same txid to be able to reconcile.

In Conclusion

I hope this article gives you more technical details of how Pix works.
Pix is a huge success in Brazil.
Brazil Central Bank is working on more improvements to Pix, and Open Finance to enable even more use cases like Pix Automatic that could replace installments with credit cards.

If you want to play with Pix go to Woovi demos and decode some BR Codes.

If you are not from Brazil and want to get more insights about Pix, send me a message.

References

https://github.com/bacen/pix-api
https://github.com/bacen/pix-dict-api
Pix API
QRCode Debug
EndToEndId Debug
QRCode Render

Woovi
Woovi is a Startup that enables shoppers to pay as they like. Woovi provides instant payment solutions for merchants to accept orders to make this possible.

If you want to work with us, we are hiring!