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.

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

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

Fluxo 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:

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:

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:

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:

Cardinalidade entre as entidades

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:

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:

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:

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.

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

O software de automação do usuário recebedor aciona a API Pix para verificar se a devolução foi liquidada:

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.

Ambiente URL
Produção https://api2.cielo.com.br/

Homologação: é o ambiente destinado à realização de testes. As operações são executadas em ambiente real, porém não produtivo.

Ambiente URL
Homologação https://api2.cielo.com.br/

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.