Introdução#
Uma transação Pix envolve duas operações básicas de transferência de recursos monetários de forma digital: débito e crédito.Operação de Débito (CashOut): A transação começa quando a conta pagadora envia um pagamento para uma conta recebedora. A instituição financeira da conta pagadora envia a transferência para o Sistema de Pagamentos Instantâneos (SPI) do Banco Central (Bacen). O SPI notifica a instituição financeira da conta recebedora em tempo real.Operação de Crédito (CashIn): A transação termina quando a instituição financeira da conta recebedora liquida o pagamento na conta, completando a operação de crédito.Burocracias Pix#
A API da Bankspace utiliza o DICT (Diretório de Identificadores de Contas Transacionais), uma base de dados que armazena informações cadastrais de usuários recebedores e suas contas transacionais.As consultas de chave no DICT são limitadas pelo BACEN usando um sistema de baldes e fichas (token bucket) conforme o Manual Operacional do DICT. Essa política visa equilibrar o uso do sistema, a fim de evitar sobrecargas nas APIs e proteger a segurança e privacidade das informações dos clientes bancários.O funcionamento do Token Bucket é regido pelas normas do BACEN, que estabelecem as regras de acréscimo e decréscimo de fichas durante as consultas de chaves. Se o limite for excedido, serão retornados erros diretamente do controle do BACEN no SPI.Manual Operacional do Diretório de Identificadores de Contas Transacionais (DICT) do BACEN
Regras de consulta ao balde de fichas junto ao BACEN#
Pessoa Jurídica:Quantidade de fichas: 1000
Decréscimo: Cada consulta válida consome 1 ficha, enquanto consultas inválidas retiram 20 fichas.
Acréscimo: Cada consulta após o recebimento da ordem de pagamento pelo SPI acrescenta 1 ficha.
Incremento temporal: A cada minuto, são adicionadas 2 fichas.Prevenção a ataques de leitura#
Existem dois cenários que podem desencadear os mecanismos de prevenção a ataques de leitura ao DICT do BACEN:Cenário 1 - Consultas sem liquidação: Ocorre quando as consultas não resultam em transações efetivas. Para evitar esse cenário, utilize o endpoint Consultar chave Pix apenas para iniciar cashouts e evite consultas desnecessárias. Não use o endpoint de consulta de chaves para escanear informações do destinatário.Cenário 2 - Consultas inválidas: Ocorre quando são feitas consultas com chaves não registradas, como um CPF com menos de 11 dígitos. Para evitar esse problema, certifique-se de sempre consultar chaves em formatos válidos, consulte a aba de Utilização dos endpoints de consulta e cashout para mais detalhes.Se as regras de consulta definidas pelo DICT não forem seguidas e o limite de consultas for ultrapassado, o BACEN emitirá um erro durante a consulta. O excesso de consultas pode acionar o mecanismo de prevenção a ataques de leitura do BACEN, bloqueando novas validações de chaves por 1 hora.
Identificadores de Transação:#
banking_external_id: Este é o identificador fornecido pela aplicação do cliente para referenciar a transação no contexto do cliente.
transactionId: Este é o identificador da transação gerado e utilizado internamente pela API.Ambos os identificadores aparecerão em endpoints futuros.