INTRODUÇÃO

Conheça a API Pix

A API Pix foi desenvolvida pela Cielo como prestadora de serviços de pagamento, provedora de conta transacional e participante direto do Pix. Esta API segue os padrões definidos pelo Banco Central do Brasil no Regulamento do Pix e demais documentos relacionados.

Essa interface padronizada permite que aplicações automatizem a interação com os participantes do Pix, possibilitando uma experiência integrada e segura para o usuário final. As APIs de recebimento via Pix permitem ao cliente recebedor gerenciar integralmente seus pagamentos, desde a geração de QR Codes até a conciliação dos valores recebidos, abrangendo tanto transações por QR Code quanto transferências Pix.

Confira abaixo alguns dos maiores benefícios oferecidos por esta solução:

• Não é necessário disponibilizar o app do seu banco para os funcionários realizarem vendas e nem expor sua chave Pix para seus clientes
• Pode ter conta em qualquer banco. As informações de vendas, recebimentos e taxas estarão no site e app Cielo gestão para acompanhamento das vendas
• Um mesmo equipamento pode ser utilizado para vender débito, crédito, voucher e Pix
• Nosso time de suporte está preparado para atender suas dúvidas.

Modelos de negócio

A API Pix é destinada a clientes que utilizam soluções de captura como, por exemplo, TEF, Cielo Smart e E-commerce, e desejam realizar transações Pix por meio dessas plataformas.

• TEF (Transferência Eletrônica de Fundos): Integra a automação comercial do estabelecimento ao sistema Cielo, permitindo vendas com cartões por meio de leitores de tarja magnética e chip.
• Cielo Smart: É uma plataforma aberta que possibilita a integração completa com sistemas de gestão de loja. Para quem já possui um sistema de gestão completo, oferece integração simples e rápida. Para quem não possui, disponibiliza relatórios de pagamento, catálogo de produtos, leitor de código de barras e outros recursos exclusivos.
• E-commerce: É uma solução digital para pagamentos online no checkout do seu site. Com recursos avançados como blindagem antifraude e inteligência de dados, você acompanha o status da transação diretamente no nosso portal.

Primeiros passos

Está iniciando agora a sua jornada de integração e não sabe por onde começar? Aqui, você encontra uma visão simplificada dos principais passos para integrar com a API Pix.

1. Acesso à documentação: Consulte a documentação técnica da API Pix e explore o  Swagger, onde estão disponíveis os endpoints, métodos, parâmetros e exemplos de requisições e respostas.

2. Solicitação de credenciais Sandbox: A solicitação deve ser realizada por e-mail. Você vai precisar de Client ID e Client Secret (credenciais de autenticação OAuth2) e de uma Chave Pix transacional (tipo aleatória).

3. Homologação: Suporte na execução de testes e validações juntamente com apontamento de correções e melhorias.

4. Geração de certificado mTLS: Em produção, é obrigatório o uso de mTLS para: geração de cobranças, devoluções, consultas. No ambiente Sandbox, o mTLS não é exigido.

5. Recebimento de notificações: Esta etapa é opcional, porém altamente recomendada. Enquanto o polling realiza consultas periódicas para verificar atualizações de status, o webhook envia notificações automaticamente sempre que uma alteração ocorre. Você pode optar por utilizar apenas um dos métodos, mas a abordagem mais robusta e eficiente é combinar ambos

6. Habilitação do Pix: Habilite a funcionalidade Pix no Portal Cielo.

7. Credenciais e chaves de produção: Gere suas credenciais e chaves de produção.

8. Rollout: Com a integração concluída, é possível gerar e pagar QR Codes, realizar devoluções, fazer transações de Pix automático e testar notificações.

Ao longo desta documentação, todas estas etapas são descritas detalhadamente.

Glossário

Este glossário reúne os principais termos utilizados no ecossistema da API Pix. Ele foi criado para facilitar a compreensão de conceitos técnicos e operacionais, promovendo uma integração mais eficiente com nossas soluções. Consulte-o sempre que tiver dúvidas sobre siglas, nomenclaturas ou funcionalidades.

Termo	Descrição
Chave	Campo obrigatório que determina a chave Pix registrada junto ao Banco Central. Essa chave identifica o usuário recebedor e os dados da conta transacional à qual a cobrança está vinculada.
Client_ID	Componente de acesso à API Pix que identifica um elemento de software cliente do usuário. Para acessar a API, é necessário utilizar o Client_ID e um segredo, ambos fornecidos pelo PSP do usuário durante o cadastramento. Um mesmo usuário pode ter mais de um Client_ID, caso possua múltiplos elementos de software cliente.
Escopos	Definem as autorizações associadas a cada serviço da API. Cada Client_ID possui acesso a um ou mais escopos, determinando quais serviços podem ser acessados.
Facilitador de Serviço de Saque (FSS)	Participante do Pix que atua como provedor de conta transacional e é autorizado pelo Banco Central do Brasil a oferecer o serviço de saque, diretamente ou por meio de agente de saque, mediante contrato específico.
Payload JSON	Conteúdo retornado a partir da chamada à URL, obtido por meio da leitura do QR Code dinâmico, que representa uma cobrança.
PSP Pagador	Instituição do Pix na qual o usuário pagador mantém sua conta transacional. Atua como ponte técnica e regulatória entre o usuário pagador e o sistema de pagamentos.
PSP Recebedor	Instituição do Pix na qual o usuário recebedor mantém sua conta transacional. Para oferecer integração automatizada com o arranjo Pix, deve seguir as especificações da API Pix definidas pelo Banco Central.
TransactionId (txid)	Identificador único da transação, gerado pelo usuário recebedor e enviado ao PSP recebedor na criação da cobrança. Utilizado para conciliação de pagamentos e deve ser único por usuário recebedor (CPF/CNPJ).
Usuário pagador	Pessoa que efetua o pagamento de uma cobrança via Pix, tendo sua conta transacional debitada.
Usuário recebedor	Pessoa que recebe cobranças via Pix e pode utilizar a API Pix para automatizar a geração de cobranças e a conciliação de pagamentos.

Suporte técnico

Nosso objetivo é apoiar você em cada etapa. Caso tenha dúvidas, envie um e-mail para apipix.suporte@cielo.com.br.

Seja um parceiro

A Aliança Cielo objetiva construir parcerias estratégicas com empresas de tecnologia, ampliando nossa atuação no mercado com soluções integradas e completas. A proposta é democratizar o acesso à inovação, conectando nossos serviços às soluções dos parceiros. A maioria das parcerias é formada por meio da integração entre os produtos da Cielo e as soluções dos parceiros. Também há troca de leads qualificados, criando oportunidades comerciais para ambos os lados.

Quem pode ser parceiro?

O programa é destinado a empresas de tecnologia de todos os portes que atuam nos segmentos do varejo físico e do e-commerce. Isso inclui Software Houses, TEF Houses, desenvolvedores de soluções integradas com maquininhas e aplicativos para Cielo Smart, além de plataformas de e-commerce, orquestradores de pagamento, agências implementadoras e criadores de marketplaces.

Ficou com dúvidas? Envie um e-mail para parcerias@cielo.com.br ou acesse o site com mais informações sobre o programa de parcerias e seus benefícios.

VISÃO GERAL TÉCNICA

Funcionalidades

A API Pix disponibiliza um conjunto de recursos projetados para otimizar a jornada de pagamento, ampliar a automação operacional e proporcionar maior controle sobre as transações financeiras. Entre os principais destaques estão:

Cobrança

• Geração de QR Code imediato para pagamento instantâneo, válido para uma única utilização;
• Personalização do tempo de expiração do QR Code;
• Alteração ou remoção de um QR Code imediato previamente gerado;
• Geração de cobranças, por meio do Pix Automático.
  
  

Conciliação

• Geração de relatórios e consulta de transações, utilizando TXID ou ID E2E como parâmetros;
• Consulta de informações de um QR Code imediato específico;
• Lista de todos os QR Codes imediatos disponíveis.

Devolução

• Devolução de transações Pix, sempre de forma individual, identificando a transação original a ser devolvida de forma total ou parcial.
  
  

Pix automático

• Criação de pedidos de autorização de recorrência, nos quais o usuário pagador concede permissão para que cobranças automáticas sejam debitadas de sua conta transacional em intervalos pré-estabelecidos;
• Consulta, atualização ou cancelamento de recorrências ativas, garantindo total controle sobre o ciclo de cobrança.
  

Fluxo da API Pix

A API Pix é o elemento do arranjo responsável por viabilizar que usuários pagadores ou recebedores automatizem a comunicação com seus respectivos Prestadores de Serviços de Pagamento (PSPs). Por meio dessa interface, é possível realizar ou receber transações Pix de maneira integrada, segura e sem necessidade de interações manuais.

O foco da API está na automação do fluxo do usuário recebedor, permitindo que ele:

• Gere cobranças de forma programática;
• Acompanhe e confirme, via integração, o pagamento dessas cobranças dentro do próprio arranjo Pix.
  
  Abaixo, você confere os possíveis caminhos de integração dos sistemas do usuário recebedor com a API Pix do PSP, neste caso a Cielo.

Primeira etapa: Cobrança com geração do QR Code

1. Uma venda é iniciada no ponto de venda (PDV);
2. O software de automação comercial recebe essa informação e envia os dados para ERP, Sefaz (quando houver nota fiscal) e para a impressora fiscal quando necessário;
3. Em seguida, o software de automação solicita ao módulo TEF/Gateway que gere uma cobrança Pix;
4. O TEF ou Gateway se conecta à API Pix do PSP recebedor;
5. A API Pix gera um QR Code dinâmico contendo as informações necessárias;
6. O QR Code gerado é exibido no PDV para o cliente.

Segunda etapa: Pagamento pelo usuário pagador

1. O pagador lê o QR Code com o app do banco ou carteira digital;
2. O app envia a ordem de pagamento ao PSP pagador (banco do cliente);
3. O PSP pagador envia o pagamento ao PSP recebedor, usando a infraestrutura do Banco Central.

Terceira etapa: Confirmação do pagamento e retorno ao comércio

1. O PSP recebedor recebe o pagamento e atualiza o status da cobrança.
2. A API Pix comunica ao Gateway/TEF que a cobrança foi liquidada. Isso ocorre por consulta ativa ou por notificação (webhook), dependendo da integração.
3. O TEF/Gateway informa o SW de automação comercial que o pagamento foi confirmado.
4. O PDV então libera a venda, finaliza o pedido, registra no ERP, emite nota fiscal pela Sefaz e/ou dispara outros processos automáticos internos.

Recebimento de Pix

Para usar o Pix, os clientes Cielo podem escolher a opção que preferirem da Conta Pix, sendo Gestão Simplificada ou Gestão de Livre Movimentação.

• Gestão Simplificada: o saldo é transferido automaticamente para a conta bancária cadastrada no estabelecimento comercial. Além disso, é possível acessar o extrato Pix e informações das operações.

• Gestão de Livre Movimentação: o cliente tem acesso a todas as funções do Pix, por meio do App Cielo Gestão. Além disso, o saldo pode ser usado para transferências e pagamentos via Pix. Nessa opção o saldo das vendas feitas com o Pix não é transferido automaticamente.

Todos os clientes habilitados para o Pix Cielo, assim como os novos clientes, terão a opção Gestão Simplificada ativada automaticamente. Se desejar, o cliente Cielo pode alterar essa opção a qualquer momento. Caso o cliente Cielo opte pela Gestão de Livre Movimentação, a funcionalidade de transferência automática será desativada. 

Entidades de negócio

A API Pix está estruturada em torno de algumas entidades de negócio, que agrupam conjuntos de atributos, conforme definido abaixo:

Cobrança (/cob):

Representa cada uma das cobranças geradas por meio da API Pix, a fim de permitir que o usuário pagador efetue um pagamento identificado para o usuário recebedor. A cobrança é caracterizada por um conjunto de informações que são utilizadas para que o usuário pagador execute um pagamento por meio do Pix, geralmente, em função de acordo comercial entre o usuário pagador e o usuário recebedor, sem se confundir com o pagamento Pix em si. O modelo de cobrança utilizado é para pagamento imediato.

Estados da cobrança:

• a) ATIVA: indica que a cobrança foi gerada e pronta para ser paga;
• b) CONCLUÍDA:: indica que a cobrança já foi paga e, por conseguinte, não pode acolher outro pagamento67;
• c) REMOVIDO_PELO_USUARIO_RECEBEDOR: indica que o usuário recebedor solicitou a remoção da cobrança; e
• d) REMOVIDO_PELO_PSP: indica que o PSP Recebedor solicitou a remoção da cobrança.
  
  

Pix (/pix) Representa um pagamento recebido por meio do arranjo de pagamentos Pix.

Devolução (devolução): representa uma solicitação de devolução de um Pix realizado, cujos fundos já se encontrem disponíveis na conta transacional do usuário recebedor.

Estados da devolução:

• a) EM_PROCESSAMENTO: indica que a devolução foi solicitada, mas ainda está em processamento no SPI;
• b) DEVOLVIDO: indica que a devolução foi liquidada pelo SPI; e
• c) NAO_REALIZADO: indica que a devolução não pode ser realizada em função de algum erro durante a liquidação (exemplo: saldo insuficiente).

Cardinalidade entre as entidades

• Uma Cobrança pode estar associada a um ou mais Pix (mesmo txid);
• Um Pix pode estar associado a uma única Cobrança. O Pix, no entanto, pode existir independentemente da existência de uma Cobrança;
• Um Pix pode ter uma ou mais Devoluções associadas a ele. Uma Devolução está sempre associada a um Pix.
• Uma Cobrança somente pode estar associada a um PayloadLocation e, num determinado momento, o PayloadLocation só pode estar associado a uma cobrança.

Ciclo de vida do TransactionID (txid)

Há duas situações de uso para o campo TransactionId (txid), que envolvem regras distintas para seu preenchimento.

As cobranças para pagamentos imediatos ou com vencimento criadas por meio da API Pix são identificadas unicamente por meio de um txid. O txid pode ser enviado pelo usuário recebedor quando da geração da cobrança, e não poderá se repetir entre cobranças distintas, a fim de garantir a correta conciliação dos pagamentos. Alternativamente, no caso de cobranças para pagamento imediato, é possível que o usuário recebedor delegue a geração do txid para o seu PSP.

Uma vez que seja solicitada a criação de uma cobrança por meio da API Pix, o PSP Recebedor deve assegurar que não exista repetição do txid para o mesmo usuário recebedor, seja ele enviado pelo usuário ou gerado pelo próprio PSP. Assim, o conjunto CNPJ ou CPF e txid deve ser único para um dado PSP.

O txid deve ter, no mínimo, 26 caracteres e, no máximo, 35 caracteres de tamanho. Os caracteres aceitos neste contexto são: A-Z, a-z, 0-9.

Funcionalidades e endpoints

As funcionalidades da API Pix, na versão atual, estão definidas em grupos:

I – Gerenciamento de Cobranças com pagamento imediato (Cob), que trata do ciclo de vida da entidade Cobrança:

Criação e atualização de cobrança	PUT/cob/{txid}
Criação de uma cobrança sem passar txid	POST/cob
Consulta de uma cobrança	GET/cob/{txid}
Consulta de lista de cobranças	GET/cob
Alteração de uma cobrança	PATCH/cob/{txid}

II – Gerenciamento de Pix Recebidos (Pix), que trata do ciclo de vida das entidades Pix e Devolução:

Solicitação de devolução	PUT/pix/{e2eid}/devolucao/{id}
Consulta de devolução	GET/pix/{e2eid}/devolucao/{id}

CASOS DE USO

O objetivo dessa seção é trazer exemplos de como a API Pix pode ser utilizada na automação das interações entre usuários recebedores e seus respectivos PSPs em transações associadas ao Pix. Esses casos de uso NÃO pretendem esgotar as formas de utilização ou as funções disponibilizadas pela API Pix.

Pagamento imediato (no ato da compra) com QR Code Dinâmico

Aplicação: Comerciantes com volumes de vendas médios ou altos. Comércios online.

1. O usuário pagador, ao realizar a compra, informa que deseja pagar com Pix;

2. O software de automação utilizado pelo usuário recebedor acessa a API Pix para criação de uma cobrança e, com os dados recebidos como resposta, gera um QR Code Dinâmico, que é apresentado em um dispositivo de exibição qualquer:

• a. em uma compra presencial, tipicamente uma tela próxima ao caixa ou mesmo um POS;
• b. nas compras online, no dispositivo em uso pelo pagador.

Serviço invocado: PUT /cob/{txid}  Devem ser informados todos os dados necessários para criação do payload da cobrança, conforme especificação detalhada. Alternativamente, se o usuário recebedor não quiser identificar a cobrança imediata com seu próprio número {txid}, pode-se optar por utilizar o método POST /cob.

3. O usuário pagador lê, a seguir, o QR Code com o App do seu PSP e efetua o pagamento;

4. O usuário recebedor, de forma automatizada, por meio de nova consulta à API Pix, verifica se o pagamento foi realizado: Serviço invocado: GET /cob/{txid};

5. O usuário recebedor libera os produtos para o usuário pagador ou, no caso das compras online, confirma o recebimento do pagamento. Alternativamente, o passo 4 pode ser realizado com o uso de webhooks configurados no serviço correspondente. Nesse caso, o usuário recebedor seria informado pelo PSP Recebedor do crédito de um Pix associado a um txid na sua conta transacional.

Efetuar uma devolução

Aplicação: várias (devolução de produto, erro na cobrança, indisponibilidade do produto em estoque etc.) Premissa: Quando comprador e vendedor estiverem de acordo, será possível realizar o processo de devolução de uma transação Pix. Esse processo deverá ser iniciado pelo vendedor, ou seja, por quem recebeu a transação Pix. É importante se atentar aos prazos (de acordo com regulamento do Banco Central).

• Para Pix Saque ou Pix Troco: a devolução deverá ser concluída no prazo máximo de até 1 hora após a conclusão da transação.
• Para transferências, vendas e demais transações com o Pix: até 90 dias após a conclusão da transação.

Importante: a devolução está disponível exclusivamente para clientes que possuem livre movimentação da conta e deverá ser realizada por meio do App Cielo Gestão ou, caso o cliente possua, pelos meios de captura via API Pix Banco Central (TEF, LIO Integrada ou E-commerce) ou ainda pela API 3.0 (E-commerce). Os clientes que optarem pela transferência automática não conseguirão efetivar a operação de devolução, devido falta de saldo em conta. Para ter acesso a efetivação, devem alterar o seu perfil para Livre Movimentação.

O usuário pagador solicita ao usuário recebedor, via algum meio de comunicação adequado, a devolução total ou parcial de um pagamento realizado;

O usuário recebedor concorda e identifica o pagamento original realizado pelo Pix. Há duas situações possíveis:

a. Quando o Pix está associado a uma Cobrança:

• Serviço invocado: GET /cob/{txid}  Como resultado, será recebida uma entidade Cobrança que contém uma relação dos Pix recebidos, cada um com a sua identificação (EndToEndId).

b. Quando o Pix não está associado a uma Cobrança. Nesse caso, é necessário saber, por outros meios, o EndToEndId do Pix original. Alternativamente, pode ser uma consulta ampla, trazendo a relação dos Pix recebidos.

• Serviço invocado: GET /pix/  Podem ser informados parâmetros para limitar a consulta temporalmente (parâmetros início e “fim” podem ser usados). Além disso, pode-se limitar a busca a um usuário pagador específico, por meio do CNPJ/CPF do pagador.

O software de automação do usuário recebedor aciona a API Pix para realizar a devolução.

• Serviço invocado: PUT /pix/{e2eid}/devolucao/{id}  No caso, “id” é um código gerado pelo sistema do usuário recebedor que identifica a devolução associada ao Pix original. Observar, que um Pix pode ter várias devoluções associadas a ele, desde que o montante das devoluções não ultrapasse o valor do Pix original. O “id” deve ser único por EndToEndID Pix. O software de automação do usuário recebedor aciona a API Pix para verificar se a devolução foi liquidada:

• Serviço invocado: GET /pix/{e2eid}/devolucao/{id} O usuário pagador recebe um Pix com o valor de devolução acordado.

Jornada de Adesão

Por jornada de adesão, entende-se o processo por meio do qual um usuário recebedor passa a utilizar os serviços de um PSP específico. Do ponto de vista da API Pix, tal processo deve incluir o fornecimento de credenciais de acesso (Client_IDs e senhas) e de certificados ao usuário recebedor.

No processo de adesão, o Client_ID disponibilizado pelo PSP deve possuir um conjunto de escopos que determinarão as funcionalidades às quais o Usuário Recebedor terá acesso. Os critérios de autorização nos escopos são de responsabilidade do PSP, que pode criar critérios diferenciados em função das características do Usuário Recebedor.

Dessa forma, é possível, por exemplo, que determinadas funcionalidades estejam acessíveis apenas por usuários que cumpram requisitos adicionais de segurança estipulados por cada PSP.

CREDENCIAIS E AUTENTICAÇÃO

Para utilizar a API PIX, as requisições devem ser executadas utilizando as respectivas credenciais dos ambientes de Homologação e Produção.

Ambientes

• Produção: Ambiente transacional integrado ao ambiente da Cielo. As operações realizadas nesse ambiente são reais e não podem ser desfeitas.
• Homologação: Ambiente destinado à realização de testes. As operações são executadas em ambiente real, porém não produtivo.

Homologação

Para obter acesso ao ambiente Sandbox, solicite à Cielo, por meio do e‑mail apipix.suporte@cielo.com.br, as seguintes credenciais:

• Client ID e Client Secret (utilizados para autenticação via OAuth2);
• Chave Pix transacional (tipo: aleatória).

Produção

Produção: Para os parceiros acessarem os dados dos clientes da Cielo, os clientes precisam informar as “chaves” ao parceiro.

E como funciona o fluxo de criação das credenciais em produção?

Importante: Para cada estabelecimento comercial devem ser geradas novas credenciais.

1º: No site da Cielo, o cliente Cielo acessa o portal Minha Conta e clica em Meu Cadastro.

2º: Na aba Autorizações clique em Pix.

3º: Para criar as credenciais, selecione a opção Novo acesso.

4º: Depois, clique em Criar credencial.

5º: Selecione o parceiro.

6º: E clique em Criar.

7º: Aceite os termos de uso e marque a caixa.

8º: E depois clique no botão Autenticar e continuar.

9º: Insira o token de segurança.

Importante: a ativação do token deve ser realizada através do Cielo Gestão.

10º: Pronto! Credencial criada com sucesso.

Após essa etapa, o cliente poderá copiar o Cliente ID, Client Secret e Chave Transacional para realizar onboarding no portal parceiro.

Importante: as credenciais precisam ser copiadas/baixadas dentro de 3 minutos. Caso contrário, será necessário gerar uma nova credencial.

ESPECIFICAÇÃO TÉCNICA

Protocolos e tecnologias

A API Pix adotará os seguintes protocolos e tecnologias:

Definição da API: A API Pix está detalhada no formato OpenAPI 3.077. Formato: O formato de dados utilizados é o JSON. Protocolo: a automação do usuário recebedor interage com a API utilizando web services baseados em REST sobre HTTPS.

Segurança

Os PSPs devem desenvolver e implementar a API seguindo boas práticas de segurança, atendendo aos requisitos obrigatórios abaixo e às recomendações detalhadas nesta seção.

Requisitos de segurança obrigatórios

O PSP deve obrigatoriamente observar os seguintes requisitos:

1. O processo de cadastro/onboarding do cliente para acesso à API deve ser realizado em ambiente logado no PSP, e deve incluir um canal seguro para envio das credenciais ao usuário, de forma a permitir a rastreabilidade das ações executadas.
2. A API deve suportar múltiplos níveis de autorização ou papéis, segregando as funcionalidades de acordo com perfis (escopos OAuth) dos usuários clientes.
3. O PSP deve implementar tecnologia que permita garantir a alta disponibilidade da API.
4. A API deve garantir a confidencialidade e a integridade das informações dos usuários e de suas transações, tanto em trânsito como em repouso.
5. O PSP deve manter logs de auditoria dos acessos à API pelo período mínimo de 1 ano.
6. A credencial de acesso utilizada na autenticação (Client_ID) deve ser vinculada ao CNPJ ou CPF do usuário recebedor e deve permitir acesso a recursos apenas de contas transacionais de titularidade do CNPJ ou CPF associado.

Segurança

Devem ser observadas para desenvolver e implementar a API seguindo boas práticas de segurança, atendendo aos requisitos obrigatórios abaixo.

Requisitos de segurança obrigatórios:

1. A conexão à API deve ser criptografada utilizando o protocolo TLS versão 1.2 ou superior, permitindo apenas cipher suites que atendam ao requisito de forward secrecy.
2. O PSP deve implementar o framework OAuth 2.0 (RFC 6749) com TLS mútuo (mTLS – RFC 8705) para autenticação na API, conforme especificações abaixo:

a. Os certificados digitais dos clientes da API poderão ser emitidos pelo próprio PSP ou por ACs externas, conforme definido por cada PSP. Não deverão ser aceitos certificados auto-assinados pelo cliente. b. Cada PSP deve possuir seu próprio Authorization Server e Resource Server associado à API Pix, e ambos devem implementar TLS mútuo. c. O Authorization Server do PSP deve implementar a técnica de vinculação do certificado do cliente aos access tokens emitidos (“Client Certificate-Bound Access Tokens”), conforme seção 3 da RFC 8705. d. O Resource Server do PSP deve confirmar que o thumbprint do certificado associado ao access token apresentado pelo cliente é o mesmo do utilizado na autenticação TLS (proof-of-possession). e. O fluxo OAuth a ser utilizado é o “Client Credentials Flow”. f. Os escopos OAuth serão definidos na especificação Open API 3.0 da API Pix e permitirão associar diferentes perfis de autorização ao software cliente.

1. O processo de cadastro/onboarding do cliente para acesso à API deve ser realizado em ambiente logado no PSP, e deve incluir um canal seguro para envio das credenciais ao usuário, de forma a permitir a rastreabilidade das ações executadas.
2. A API deve suportar múltiplos níveis de autorização ou papéis, segregando as funcionalidades de acordo com perfis (escopos OAuth) dos usuários clientes.
3. O PSP deve implementar tecnologia que permita garantir a alta disponibilidade da API.
4. A API deve garantir a confidencialidade e a integridade das informações dos usuários e de suas transações, tanto em trânsito como em repouso.
5. O PSP deve manter logs de auditoria dos acessos à API pelo período mínimo de 1 ano.
6. A credencial de acesso utilizada na autenticação (Client_ID) deve ser vinculada ao CNPJ ou CPF do usuário recebedor e deve permitir acesso a recursos apenas de contas transacionais de titularidade do CNPJ ou CPF associado.
7. Para a funcionalidade de webhooks, as notificações oriundas do PSP recebedor ao usuário recebedor trafegarão utilizando um canal mTLS.

a. Recomenda-se que os certificados utilizados para autenticação mútua no canal TLS do webhook sejam os mesmos da API Pix. De todo modo, não há objeção quanto à utilização de outros certificados, mediante acordo entre o PSP e o usuário recebedor.

O BC entende que os PSPs poderão adotar as tecnologias e soluções de segurança para a API que mais acharem apropriados, desde que sejam atendidos os requisitos obrigatórios de segurança e, sempre que possível, as recomendações descritas acima, com atenção também aos elementos listados nos tópicos a seguir.

SWAGGER: API PIX

Acesse nosso Portal de Desenvolvedores para visualizar a especificação técnica da API no formato Swagger.