Token Bucket

The Central Bank controls the flow of access to Directory of Transactional Account Identifiers (DICT) services, which is carried out through request limitation policies using a token bucket algorithm.

In short, there are two token buckets: one for EMAIL and PHONE type keys and another for CPF, CNPJ and EVP (random) type keys.

Each bucket has a maximum capacity of 1000 tokens, and 2 tokens are replaced per minute until the bucket's maximum capacity. If the number of tokens reaches zero, requests will be limited.

How to use my token bucket?

Antiscan policy counting rule:

  • When HTTP Status 200 is returned in a payment initiation request, 1 token is subtracted;
  • When a payment confirmation is made, 1 token is added;
  • When HTTP Status 404 is returned in a payment confirmation request for a non-existent key, 20 tokens are subtracted;

Banco BS2 provides a DICT Key validation endpoint, which can be used to check the validity of a DICT key before starting a payment flow, mitigating HTTP Status 404 returns. Pagamento - Iniciar pagamento por chave .

Banco BS2 performs DICT Key Validation automatically in the asynchronous payment flow.

Below is the Central Bank documentation on the subject:

If you are initializing transactions without using DICT Keys, the rules of token bukets are not appliables.