Introdução

Desenvolvimento da API Pix (Application Programming Interface) pela Cielo na qualidade de prestadora de serviço de pagamento e provedora de conta transacional e participante direto do Pix, considerando os padrões definidos pelo Banco Central do Brasil (“Banco Central”) no Regulamento do Pix e demais documentos correlatos.

A API Pix é uma interface de programação de aplicações padronizada pelo Banco Central para possibilitar que o usuário final possa automatizar a interação com o participante do Pix que lhe presta serviço de pagamento.

A API Pix contempla as funcionalidades necessárias para viabilizar o recebimento de cobranças em casos de negócio focados em pagamentos imediatos, a exemplo de pontos de venda em lojas físicas e de soluções para comércio eletrônico.

A responsabilidade da API Cielo é gerar um QR Code para pagamentos via Pix, seguindo os padrões de segurança exigidos pelo Banco Central e identificando algumas informações durante a transação: data e a hora da transação, nome da pessoa que está realizando a transação, assim como o nome do recebedor e o valor envolvido.

Público principal

Clientes que possuem soluções de captura TEF, LIO Integrada e E-commerce e desejam transacionar Pix por meio destas soluções de captura.

• TEF (Transferência Eletrônica de Fundos): As soluções TEF integram a automação comercial do estabelecimento com o sistema Cielo, possibilitando a realização de vendas com cartões por meio de leitoras de tarja magnética e leitoras de chip.
• Lio Integrada: é uma plataforma aberta que possibilita a integração de todos os seus sistemas de gestão de loja. Para quem já possui um sistema de gestão completo, possibilita uma integração muito mais simples e rápida. Para quem não trabalha com um sistema de gestão, Cielo LIO entrega relatórios de pagamentos, catálogo de produtos, leitor de código de barras, entre outros benefícios exclusivos.
• E-commerce: transferência de informação através da internet para pagamento online, com centenas de recursos. Uma solução digital mais completa. Seu negócio sempre disponível, Blindagem antifraude, mais conversão, simples, modular e flexível, Data intelligence.

O que é Pix?

O Pix é o meio de pagamento criado pelo Banco Central em que os recursos são transferidos entre contas e poucos segundos, a qualquer hora ou dia. O Pix é um novo jeito de vender de forma instantânea, segura e simples pelas soluções da Cielo.

Como funciona o recebimento do Pix na Cielo?

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.

Importante: 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. 

A API Pix contempla as funcionalidades necessárias para viabilizar:

O recebimento de cobranças em casos de negócio focados em pagamentos imediatos, a exemplo de pontos de venda em lojas físicas e de soluções para comércio eletrônico;

Estamos disponibilizando as APIs

• 1. API Cobrança: Disponível para a geração de QR Code pelo usuário recebedor, para ser utilizado uma única vez, iniciando o pagamento instantâneo. Nesse momento vamos disponibilizar o QR Code dinâmico com pagamento imediato. Prazo para expirar o qrcode (60min).

• 2. API Conciliação: Disponível para geração de relatórios (Opcional para o cliente).

• 3. API Devolução: Disponível para efetuar a devolução das transações. Sempre individual, identificando a transação a ser devolvida. 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.

A API Cielo-Pix-v1 funciona da seguinte forma: O software de automação/Front-end utilizado pelo usuário recebedor (EC) acessará a API Cielo-Pix-v1 e, com os dados recebidos como resposta da API, apresentará um QR Code Dinâmico em algum dispositivo para que o usuário pagador faça a leitura do QR Code por meio de seu dispositivo móvel para efetivar o pagamento.

Contexto da API Pix

A API Pix é o componente do arranjo que visa possibilitar que o usuário pagador ou recebedor, no contexto P2B64 ou B2B65, possa automatizar a interação com seu prestador de serviços de pagamento (PSP), a fim de realizar ou receber transações no âmbito do arranjo Pix.

Nesse contexto, a presente versão da API Pix busca automatizar a interação do usuário recebedor com seu prestador de serviços de pagamento (PSP), a fim de gerar cobranças e confirmar o recebimento do pagamento dessas cobranças por meio do Pix.

Na figura acima, pode-se visualizar possíveis caminhos de integração dos sistemas do usuário recebedor com a API Pix do PSP.

O usuário recebedor poderá, via API Pix:

• i. Gerar cobranças que poderão ser pagas via QR Code pelos seus clientes;
• ii. Alterar dados da cobrança;
• iii. Verificar a liquidação da cobrança por meio de Pix recebidos;
• iv. Realizar a conciliação dos pagamentos de maneira facilitada;
• v. Suportar o processo de devolução de valores, que pode ser acionado em função, por exemplo, da devolução de uma compra.

A seguir são detalhados os aspectos gerais que dizem respeito à API Pix.

Conceitos gerais

Para os fins deste documento, as expressões e os termos relacionados são assim definidos:

• I - client_ID: componente de acesso a API Pix que identifica um elemento de software cliente do usuário. Para acessar a API, é necessário utilizar, por exemplo, o Client_ID e um segredo, ambos fornecidos pelo PSP do usuário no processo de cadastramento. Pode existir mais de um elemento software cliente na infraestrutura do usuário e, portanto, para um usuário pode existir mais de um client_ID.
• II - Escopos: definem as autorizações associadas a cada um dos serviços da API. Por sua vez, os Client_IDs possuem acesso a um ou mais escopos, o que definirá quais serviços podem ser acessados por cada Client_ID;
• III – Payload JSON: conteúdo recuperado a partir da chamada à URL, lida a partir do QR Code dinâmico e que representa uma cobrança;
• IV - PSP Pagador: participante do Pix no qual o usuário pagador possui uma conta transacional;
• V – PSP Recebedor: participante do Pix no qual o usuário recebedor possui uma conta transacional que será usada para recebimentos de Pix. O PSP Recebedor que quiser disponibilizar a seus clientes uma solução de integração automatizada com o arranjo Pix deve fazê-lo por meio da API Pix, seguindo as especificações de negócio e técnicas definidas pelo Banco Central do Brasil neste documento e nos outros documentos trazidos na seção 2.
• VI - transactionId (txid): identificador da transação, na perspectiva do usuário recebedor. Esse número é gerado pelo usuário recebedor e repassado ao PSP recebedor na chamada da API Pix, no momento da criação da cobrança, a fim de identificar unicamente aquela cobrança66. Assim, o txid é utilizado pelo usuário recebedor, em seus processos de conciliação de pagamentos recebidos por meio de Pix. No caso das cobranças criadas por meio da API Pix, o PSP recebedor deve garantir que o txid seja único para um dado usuário recebedor (CPF/CNPJ).
• VII - usuário pagador: aquele que efetua o pagamento de uma cobrança por meio do Pix e tem a sua conta transacional debitada.
• VIII - usuário recebedor: pessoa natural ou jurídica que deseja receber cobranças – para pagamentos imediatos ou com vencimento – por meio do Pix e se vale da API Pix para automação dos seus processos de geração dessas cobranças e para conciliação de pagamentos recebidos por meio do Pix.
• IX – facilitador de serviço de saque (FSS): participante do Pix que se classifique como provedor de conta transacional e seja autorizado a funcionar pelo Banco Central do Brasil em caráter facultativo, venha a prestar o serviço de saque, diretamente, ou por meio de agente de saque, mediante estabelecimento de relação contratual para essa finalidade.
• X – Chave: O campo chave, obrigatório, determina a chave Pix registrada junto ao Banco Central que será utilizada para a cobrança, identificando o usuário recebedor, bem como os dados da conta transacional à qual a cobrança deve estar atrelada.

Funcionalidades da API Pix

Definições das entidades

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

I - 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.

II - Pix (/pix): representa um pagamento recebido por meio do arranjo de pagamentos Pix.

III - 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

• I - Uma Cobrança pode estar associada a um ou mais Pix (mesmo txid);
• II - Um Pix pode estar associado a uma única Cobrança. O Pix, no entanto, pode existir independentemente da existência de uma Cobrança;
• III - Um Pix pode ter uma ou mais Devoluções associadas a ele. Uma Devolução está sempre associada a um Pix.
• IV – 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, conforme tratado a seguir.

txid no contexto das Cobranças:

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.

Grupos de funcionalidades

Funcionalidades e respectivos endpoints

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

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

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

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.

Solicitação de credencial para desenvolvimento/integração

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

Descrição ambiente:

Produção: é 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: é o ambiente destinado à realização de testes. As operações são executadas em ambiente real, porém não produtivo.

Homologação

As credenciais para o ambiente de homologação são solicitadas diretamente em nosso Portal de Desenvolvedores

Basta selecionar as APIs abaixo:

Após a criação será possível visualizar o seu client_id e client_secret, acesse: Minhas Credenciais

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.

API Pix: 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.