PixKey

This scheme defines a Pix key.

Remarks

1. Key types

Pix can be sent to bank account details (just like TED) or to Pix keys, which could be an email address, a phone number, a taxpayer number (CPF/CNPJ) or a random key (an UUID). There is also the method commonly called "copy and paste", which consists on copying the QRCode payload context as raw text and pasting on the banking app.

Formatting the CPF/CNPJ with dots or slashes is optional. For BankAccounts, you may either pass a BankAccount object or a stringified JSON.

2. Pix implementation stages - for non-individualized setups only

Pix's DICT, which is the directory owned by the Central Bank that stores all existing Pix keys and its routes, includes measures against database scanning: in order to prevent bots from gathering information about Pix keys in batch, a scoring system is used as a rate-limiter. It is fully explained on DICT's documentation, but in short terms, a scale like the following is considered: 0, 1, 5, 10, 50, 100, 500, 1000, 5000, 10000...

And three time windows are considered: last 3 days, last 30 days and last 6 months.

In order to issue a Pix transfer to a key, it is needed to lookup at the actual routing info (i.e. the bank account behind the Pix key). This lookup costs 1 "credit". Once a transfer is completed to such bank account, this 1 "credit" is given back. If, however, no transaction is sent (e.g. we have figured out that the Pix key belongs to a third party, and not to the user - since we can only get the taxpayer number after the look-up, if it is not a taxpayer number-based Pix key such as a CPF or CNPJ key -, and therefore we will not proceed with the withdrawal), this credit is not reimbursed.

These credits do not actually cost money and cannot be bought or sold, but if they are zeroed, we become unable to lookup at new Pix keys and may find issues to send new Pixes.

In order to calculate how many credits we have, the Central Bank verifies how many transactions were made on the three time windows, and round these numbers up to the next number in the scale above.

For example, let's say we have sent 50 transfers on the last 3 days, 2000 on the last 30 days and 30000 on the last 6 months. Rounding up these numbers to the next one on the scale, we will have: 5, 5000 and 50000. These are our total scores. If, however, we have already done 5 lookups on the next 3 days without sending a transfer, we must wait before being able to do new lookups (and therefore we cannot send transfers to Pix keys).

These limits exist for all banks, and are applied on a per-origin account basis (but since we only hold one bank account, we have the same limits applied for one bank accounts in the whole operation).

For this reason, and to prevent the Pix cash-out operation to stop early after some users to attempt to send funds to third parties, the Pix cash-out implementation must be done in two different stages:

First stage: initially, we should only offer Pix methods that allow us to know the user's taxpayer number and run the screening before the look-up is done. These methods are: bankaccount, cpf, cnpj (or cpfcnpj).

Second stage: followingly, after reaching a good score which makes it safe to start the operation without or with less risk of zeroing the credits, the remaining methods could be added.

Individualized setups can use any type of Pix key since the beginning, however using other methods than "bankaccount" and tax ID ("cpf", "cnpj" or "cpfcnpj" - the latter is an alias for both "cpf" and "cnpj") will lead to your user being able to send transfers to third parties - which is perfectly compliant with Brazilian laws.