Introdução

Desenvolvimento da API Pix (Application Programming Interface) pela Cielo na qualidade de detentora de contatransacional e participante direto do Pix, considerando os padrões definidos pelo Banco Central no regulamento do Pix e demais documentos correlatos.

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.

• 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 deprodutos, 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 derecursos. Uma solução digital mais completa.Seu negócio sempre disponível, Blindagem antifraude, mais conversão, Simples, modular e flexível, Data intelligence.

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.
• 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 – prestador de serviço de saque (pss): participante do Pix, que se enquadre na modalidade provedor de conta transacional e que seja autorizado a funcionar pelo Banco Central do Brasil, que, em caráter facultativo, venha a prestar serviço de saque, diretamente, ou por meio de agente de saque, mediante estabelecimento de relação contratual para essa finalidade.

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: um pagamento foi recebido via Pix.

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.

Ambientes Disponíveis

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.

Para solicitar credenciais, entre em contato com o ponto focal do time comercial da Cielo e informe para quais ambientes são necessárias credenciais. Será necessário informar os seguintes dados:

a. Nome da empresa b. Nome do proprietário responsável em receber a(s) credencial(s) c. E-mail do proprietário responsável em receber a(s) credencial(s) d. Telefone do proprietário responsável e. Nome da Software House do cliente = Nem todos os clientes terão parceria com uma Software House f. Número do Cadastro na Cielo g. Informar o(s) nº(s) lógico(s) do Cadastro na Cielo: Será criada uma credencial para cada nº lógico h. Cidade do EC.

Para o acesso à API, esse mesmo e-mail do proprietário (responsável por receber a credencial) deverá ser utilizado para a criação de uma nova conta no Portal de Desenvolvedores Cielo. Para verificar qual foi a credencial gerada, acesse a conta criada e verifique o Client-Id.

Após aprovação das credenciais, receberá um e-mail informando que a(s) credencial(is) gerada(s) já estão disponíveis no Portal dos Desenvolvedores Cielo e também com a orientação de como deverá realizar o cadastro no portal de Desenvolvedores Cielo. para ter acesso as credenciais geradas para cada nº lógico;

Além disso, receberá um contato telefônico para informa ló sobre a criação das credenciais e orientar a fazer o cadastro no Portal do Desenvolvedor para ter acesso às credenciais;

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.

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.

Recomendações de segurança

É recomendado ao PSP:

1. Implementar múltiplos fatores de autenticação para o processo de cadastro/onboarding na API.
2. Desenvolver e implementar a API seguindo boas práticas de segurança, de forma a eliminar/reduzir ao máximo os riscos de segurança conforme última versão dos guias OWASP API Security Top Ten e CWE Top 25 Software Weaknesses.
3. Possuir processo periódico de análise de vulnerabilidades, tanto estática como dinâmica da API.
4. Assegurar a segurança do desenvolvimento do software cliente da API, mesmo que desenvolvido por terceiros. Sugere-se que o PSP institua e mantenha processo de homologação dos softwares clientes, estabelecendo critérios mínimos de segurança para que eles sejam autorizados a interagir com a API. Nesse caso, a API deve negar tentativas de comunicação de clientes não homologados.
5. Os usuários recebedores, como clientes da API, são um elo importante na segurança do sistema, e, portanto, recomenda-se que o PSP tome ações para mitigar os riscos do ambiente computacional dos seus usuários, uma vez que caso um risco se materialize em um incidente, o próprio PSP poderá ser afetado. Ações recomendadas (sem prejuízo para outras ações que o PSP julgar importantes):
   • a. Instituir e acompanhar programa de melhoria contínua da segurança dos usuários recebedores que utilizam a API;
   • b. Realizar campanhas de conscientização e compartilhamento de informações de segurança junto aos usuários;
   • c. Definir uma política de troca periódica do certificado, senha e outras credenciais utilizadas no acesso à API;
   • d. Validar a segurança do ambiente computacional dos usuários nos aspectos de infraestrutura, implementação e configuração do software cliente da API.
   • e. Exigir que as empresas e instituições que utilizem a API tenham uma Política de Segurança da Informação formalmente instituída.

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.

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. Cada PSP terá autonomia para definir a jornada de Adesão para os seus clientes, utilizando os canais que julgar mais adequados.

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 quecumpram requisitos adicionais de segurança estipulados por cada PSP.

API Pix: Documentação Técnica

Acesse o nosso Portal de Desenvolvedores Cielopara visualizar as especificações técnicas de cada recurso da API PIX.