APIs do PIX: Como Funcionam?

PIX é o nome dado pelo Banco Central para o sistema de pagamentos instantâneos do Brasil. Além de ser gratuito para pessoas físicas, ele possibilitará a realização de transferências bancárias em tempo real, 24 horas por dia e 7 dias por semana.

O objetivo deste artigo é descrever brevemente os motivadores e objetivos do PIX, bem como fornecer uma rápida introdução as APIs e serviços que constituem o arranjo operacional do PIX.

Como funciona o PIX? 

Como já mencionado, o objetivo do PIX é prover um meio de pagamentos que se destaque pela velocidade, disponibilidade e custo. Mais informações a respeito do sistema de pagamentos instantâneos e de seu funcionamento podem ser extraídas da página do PIX no site do Bacen.

Abaixo deixo um vídeo curtinho que explica de forma rápida e simples um pouco mais sobre o PIX.

O PIX possui dois módulos, o SPI (Sistema de Pagamentos Instantâneos) e o DICT (Diretório de Identificadores de Contas Transacionais), que serão abordados durante este artigo.

A interação com estes módulos é feita de modo direto ou indireto por três tipos de participantes:

Participante direto: bancos e instituições financeiras que possuem conta de pagamento dentro do SPI e se comunicam diretamente com a infraestrutura do SPI, aqui estão como players os principais bancos brasileiros;

Participante indireto: instituições que oferecem contas transacionais para o cliente, mas que não possuem conta de pagamento no PIX e nem comunicação direta com a infraestrutura do SPI, fazendo uso de APIs fornecidas por um participante direto para sua operação;

Parceiro que usa o PIX como meio de pagamento: pode ser um vendedor que utiliza o PIX em seus canais de venda a fim de automatizar o controle dos recebimentos.

O Bacen disponibiliza uma lista com todos os participantes diretos e indiretos do PIX.

Sistema de Pagamentos Instantâneos (SPI)

O módulo nomeado de SPI é responsável por prover serviços relacionados a liquidação e a gestão da Conta de Pagamentos Instantâneos. Basicamente, este é o módulo responsável pelo motor de pagamentos do PIX. As APIs relativas ao SPI funcionam de forma assíncrona e unidirecional, ou seja, partem do participante direto para o Bacen (e nunca do SPI para o participante).

ICOM (Interface de Comunicação do SPI) é o nome dado a interface pela qual é realizada a comunicação com o SPI, é ela a responsável por realizar a troca de mensagens entre o Banco Central e os participantes do DICT. Todas as mensagens trafegadas seguem o formato XML e estão definidas na ISO 20022, seguindo um padrão internacional e que é adotado na implementação de serviços de pagamentos em diversos países. 

Abrindo assim a possibilidade de integração com Sistemas de Pagamentos internacionais.

Na ICOM estão definidos dois serviços principais, pelos quais são possíveis enviar e receber mensagens de diferentes tipos. Sejam elas de envio de pagamento, recebimento, devolução, assim como mensagens administrativas, todas elas definidas na ISO 20022.

Através de um POST para /api/v1/in/{ispb}/msgs podemos enviar uma ou diversas mensagens para o SPI, onde o ISPB é o código que identifica o participante que está operando, sendo ele os 8 primeiros dígitos do CNPJ da instituição.

POST /api/v1/in/11111111/msgs

HTTP/1.1 Host: icom.pi.rsfn.net.br

Content-Type: application/xml; charset=utf-8 Content-Length: 4587 User-Agent: instancia 1; versao 1.1 [xml]

<--- HTTP/1.1 201 Created PI-ResourceId: UEkBbgR78VqKK/uvuq9O0r9bqXyBH9Ur

Acima podemos ver o exemplo de um POST para realizar o envio de uma mensagem, no lugar do que está como [xml] no exemplo, enviaríamos uma das mensagens definidas na ISO 20022, onde poderíamos encaminhar, por exemplo, uma mensagem informando um pagamento a ser realizado.

Para ler mensagens que o SPI está interessado de enviar para o parceiro, realizamos um GET para /api/v1/out/{ispb}/stream/start onde podemos consultar de uma até 10 mensagens. Essas mensagens podem ser novamente de diferentes tipos, como por exemplo, um recebimento de pagamento, uma confirmação de pagamento realizado, o retorno de uma mensagem administrativa, dentre outros. Importante ressaltar que toda mensagem enviada ao SPI possui um MessageId, que identifica uma mensagem e pode ser utilizado para tratar a sua resposta.

--> GET /api/v1/out/11111111/stream/start HTTP/1.1

<--- HTTP/1.1 200 OK PI-ResourceId: UEkBbgR78VqKK/uvuq9O0r9bqXyBH9Ur PI-Pull-Next: /api/v1/out/11111111/stream/f0d744d792d6
[xml]

Em razão dos fluxos de comunicação com o SPI serem todos implementados de forma assíncrona, tecnologias de mensageria estão sendo adotadas em larga escala nas implementações do PIX em diversas instituições, isso pode ser um tema bastante interessante para um artigo futuro 🙂 .

Mais detalhes sobre o fluxo do SPI podem ser vistos na documentação oficial. Como mencionado acima, detalhes quanto as mensagens trafegadas via XML nas requisições de exemplo podem ser obtidas através da ISO 20022. Exemplos de payloads dessas mensagens podem ser obtidos através da página de referência do SPI.

Diretório de Identificadores de Contas Transacionais (DICT)

Toda conta bancária é identificada no PIX através de uma chave, de escolha do cliente final, que pode ser o CPF, CNPJ, e-mail, telefone ou EVP (valor gerado aleatoriamente). O DICT é o componente responsável por realizar a gestão dessas chaves, disponibilizando os serviços de cadastro, atualização e exclusão dos vínculos entre os identificadores e as contas bancárias.

Certamente, o fluxo que será mais utilizado no DICT é o de consulta de chaves, que será necessário a cada pagamento efetuado, pois é no momento prévio a efetuação de um pagamento que o usuário informa a chave da conta para a qual deseja realizar a transferência. Tendo assim, uma volumetria de acessos muito maior do que as outras operações do DICT.

Um exemplo de consulta a chave no DICT pode ser feita desta forma, onde informamos no path da URL a chave a ser consultada.

GET https://dict-h.pi.rsfn.net.br:16522/api/v1-rc6/entries/{{Key}}

A response será no modelo abaixo:

<?xml version="1.0" encoding="UTF-8"?>
<GetEntryResponse>
   <Signature />
   <Entry>
      <Key>11122233300</Key>
      <KeyType>CPF</KeyType>
      <Account>
         <Participant>12345678</Participant>
         <Branch>0001</Branch>
         <AccountNumber>0007654321</AccountNumber>
         <AccountType>CACC</AccountType>
         <OpeningDate>2010-01-10T03:00:00Z</OpeningDate>
      </Account>
      <Owner>
         <Type>NATURAL_PERSON</Type>
         <TaxIdNumber>11122233300</TaxIdNumber>
         <Name>João Silva</Name>
      </Owner>
      <CreationDate>2019-11-18T03:00:00Z</CreationDate>
      <KeyOwnershipDate>2019-11-18T03:00:00Z</KeyOwnershipDate>
      <OpenClaimCreationDate>2019-11-19T03:00:00Z</OpenClaimCreationDate>
   </Entry>
</GetEntryResponse>

O DICT também é responsável pelos fluxos de portabilidade, quando o usuário pretende migrar a conta bancária associada ao seu CPF, por exemplo, e de reivindicação de uma chave sua que pode estar sob posse de uma pessoa indevida, o que pode ter ocorrido por troca de titularidade ou, até mesmo, por uma fraude. A especificação destes serviços pode ser vista aqui, bem como a documentação detalhada de todas APIs do DICT.

Diferentemente dos serviços do SPI, no entanto, todos os fluxos de comunicação com o DICT são síncronos. Mais detalhes podem ser vistos na documentação oficial.

Modos de pagamento e o QR Code

Os pagamentos no PIX podem ser feitos de diferentes formas. O usuário poderá usar uma chave do DICT, informar manualmente os dados da conta à qual deseja realizar uma transferência ou, ainda, usar um QR Code.

O PIX utiliza dois tipos de QR Code:

• QR Code Estático: pode ser reutilizado em diversos pagamentos e terá um valor fixo. Um vendedor cujo produto mais vendido custa R$ 10, por exemplo, pode gerar o QR Code, imprimi-lo e colocá-lo à mostra junto com o produto;

• QR Code Dinâmico: contém informações dinâmicas e que podem ser resolvidas de acordo com diversos parâmetros.

Mais detalhes sobre os modos de pagamento e QR Code podem ser vistos aqui.

Conclusão

O PIX surgiu para facilitar a vida do cliente e tem potencial para mudar a forma como estamos acostumados a realizar transações e pagamentos. A primeira versão a ser disponibilizada para os usuários tem previsão de implantação nas primeiras semanas de Novembro de 2020. 

O DICT já estará no ar a partir do dia 5 de outubro, quando os usuários poderão começar a vincular chaves a suas contas, podendo assim já se ambientar com o novo meio de pagamento e antecipando certas etapas necessárias para fazer uso desta nova tecnologia.

Além da possibilidade de realizar transferências de uma maneira rápida, prática e barata, o PIX tem um roadmap de outras funcionalidades que tendem a mudar a forma com que o Brasileiro interage com o seu dinheiro. Além de viabilizar um novo meio de pagamentos, que está em linha com a revolução tecnológica em curso, ele abrirá um novo leque de possibilidade para novos negócios.