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.
  

Arquitetura

Na implementação da API, a Cielo é responsável por gerar o QR Code para pagamentos via Pix, garantindo conformidade com os requisitos de segurança do Banco Central. Durante a transação, são identificadas informações importantes, como:

• Data e hora da operação;
• Nome do pagador;
• Nome do recebedor;
• Valor da transação.

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.

Requisitos de segurança

Para garantir a conformidade e a proteção das informações, devem ser adotadas as seguintes medidas:

Comunicação e autenticação

A Cielo utiliza seu próprio Resource Server, que implementa o OAuth 2.0 (RFC 6749) com TLS mútuo (mTLS – RFC 8705), conforme regulamentações do Banco Central. Assim, o processo de comunicação e autenticação deve seguir os seguintes critérios:

• Toda conexão com a API deve ser criptografada utilizando TLS versão 1.2 ou superior, permitindo apenas cipher suites que ofereçam forward secrecy.
• 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.
• 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.
• A API Pix exige autenticação mútua por certificados. Isso significa que tanto o cliente quanto o servidor apresentam seus certificados, que são validados pelo outro lado. Durante a requisição, o cliente envia seu certificado para validação pela Cielo. A Cielo, por sua vez, também apresenta seu certificado para validação pelo cliente. A autenticação só é concluída mediante validação bem-sucedida dos dois certificados.
• Os certificados digitais dos clientes podem ser emitidos por ACs externas ou pela própria Cielo, que atua como autoridade certificadora. Certificados autoassinados não são aceitos.
• Cada PSP deve possuir seu próprio Authorization Server e Resource Server associado à API Pix, e ambos devem implementar TLS mútuo.
• 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).
• A Cielo utiliza Client Certificate-Bound Access Tokens, vinculando o certificado do cliente ao access token emitido, conforme seção 3 da RFC 8705.
• O Resource Server da Cielo valida se o thumbprint do certificado associado ao access token corresponde ao certificado utilizado na autenticação TLS (proof-of-possession).
• O fluxo OAuth utilizado é o Client Credentials Flow.

Confidencialidade e integridade

• O processo de cadastro dos clientes para acesso à API ocorre em ambiente autenticado da Cielo com duplo fator de autenticação conforme determinado pelo Bacen. Além disso, utilizamos um canal seguro para envio das credenciais, o que garante rastreabilidade completa de todas as ações realizadas.
• A API assegura a confidencialidade e a integridade dos dados dos usuários e de suas transações, tanto em trânsito quanto em repouso.
• A Cielo mantém logs de auditoria de acesso à API por, no mínimo, 1 ano.
• O client_id utilizado na autenticação é vinculado ao CNPJ ou CPF do estabelecimento recebedor, e somente permite acesso aos recursos relacionados às contas transacionais de titularidade desse mesmo CNPJ ou CPF.
• A API da Cielo é projetada para atender com alta disponibilidade.

Habilitando o Pix

Para que seja possível efetivar transações Pix, é necessário habilitar este tipo de pagamento. Para realizar essa ação, siga as instruções abaixo.

1. Entre no site Cielo com seu login e senha.

2. Clique em Meu cadastro.

3. Clique em Autorizações e selecione a opção Pix.

4. Clique em Iniciar habilitação.

5. Na opção Habilitação simplificada, clique em Selecionar.

6. Marque a caixa de aceite , e clique em Enviar solicitação.

Após essa habilitação via site Cielo, o estabelecimento estará apto a trabalhar com a modalidade Pix!

RECEBIMENTOS PIX

Com o Pix na Cielo, todo cliente tem uma conta de pagamento gratuita e pode optar como deseja receber as suas vendas: pela Transferência automática ou pela Conta Cielo.

Modalidades de recebimento

Caso escolha transferência automática, há duas opções:

• Transferência automática por venda: Cada venda é transferida de forma automática e instantânea, via Pix, diretamente da conta de pagamento para domicílio bancário escolhido pelo cliente.
• Transferência programada: As vendas via Pix são acumuladas na Conta Cielo e transferidas automaticamente para o banco do cliente, também via Pix, em até 4 períodos diários em horários pré-definidos.

Ao optar pela Conta Cielo, suas vendas são direcionadas para essa conta, permitindo que você utilize todas as funcionalidades do Pix diretamente pelo App Cielo Gestão. O saldo das vendas realizadas via Pix pode ser usado para fazer transferências e pagamentos por Pix. Nessa modalidade, o valor das vendas não é transferido automaticamente para um domicílio bancário escolhido pelo cliente.

Como alterar a modalidade de recebimento Pix?

A modalidade de recebimento Pix pode ser alterada via site Cielo ou via app Cielo Gestão.

Antes de aprender como alterar a modalidade de recebimento, confira as regras para alteração:

Aderindo a transferência programada

Via app Cielo Gestão

Siga o passo-a-passo abaixo para alterar a modalidade de recebimento para transferência programada via app Cielo Gestão:

1. Na área logada do Pix no app Cielo Gestão, selecione a opção Recebimentos Pix.

2. Clique em Transferência programada.

4. Clique em Configurar.

5. Selecione o horário da transferência.

6. Marque o opt-in e clique em Ativar modalidade.

7. Seu token de segurança será validado.

Pronto! Seu modelo de recebimento foi alterado.

Via site Cielo

Siga o passo-a-passo abaixo para alterar a modalidade de recebimento para transferência programada via site Cielo:

1. Na área logada do site Cielo, no menu superior clique em Pix > Configurações.

2. Clique em Recebimentos.

3. Selecione a opção Transferência programada.

4. Selecione o horário da transferência.

5. Marque o opt-in e clique em Ativar.

6. Para prosseguir, insira o token de segurança Cielo Gestão e clique em Verificar.

Pronto. Seu modelo de recebimento foi alterado!

Aderindo a transferência por venda

Via app Cielo Gestão

Siga o passo-a-passo abaixo para alterar a modalidade de recebimento para transferência por venda via app Cielo Gestão:

1. Na área logada do Pix no app Cielo Gestão, selecione a opção Recebimentos Pix.

2. Clique em Transferência por venda.

3. Marque o opt-in e clique em Ativar modalidade.

4. Seu token de segurança será validado.

Pronto! Seu modelo de recebimento foi alterado.

Via site Cielo

Siga o passo-a-passo abaixo para alterar a modalidade de recebimento para transferência por venda via site Cielo:

1. Na área logada do site Cielo, no menu superior clique em Pix > Configurações.

2. Clique em Recebimentos.

3. Selecione a opção Transferência por venda.

4. Marque o opt-in e clique em Ativar.

5. Para prosseguir, insira o token de segurança Cielo Gestão e clique em Verificar.

Pronto. Seu modelo de recebimento foi alterado!

Aderindo a Conta Cielo

A adesão a Conta Cielo pode acontecer somente via app.

Siga o passo-a-passo abaixo para alterar a modalidade de recebimento para transferência por venda:

1. Na área logada do Pix no app Cielo Gestão, selecione a opção Recebimentos Pix.

2. Clique em Conta Cielo.

3. Marque o opt-in e clique em Ativar modalidade.

4. Seu token de segurança será validado.

Pronto! Seu modelo de recebimento foi alterado.

INTEGRAÇÃO COM A API

Aqui, você encontra todas as informações necessárias sobre endpoints e recursos disponíveis na API Pix.

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

Ambientes

• Sandbox: É o ambiente destinado à realização de testes. As operações são executadas em ambiente real, porém não produtivo.
• 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	Base da URL
Sandbox	https://api2.cielo.com.br/sandbox/cielo-pix/v1
Produção	https://api-mtls.cielo.com.br/cielo-pix/v1

Todas as chamadas devem ser executadas utilizando as respectivas credenciais dos ambientes de Sandbox e Produção.

Arquitetura da API

A API Pix está detalhada no formato OpenAPI 3.077 e o formato de dados utilizados é o JSON.

A automação do usuário recebedor interage com a API utilizando web services baseados em REST sobre HTTPS.

O modelo empregado na integração das APIs é simples. Para executar uma operação:

1. Combine a base da URL do ambiente com o endpoint da operação desejada. Ex.: https://api-mtls.cielo.com.br/cielo-pix/v1/

2. Envie a requisição para a URL utilizando o método HTTP adequado à operação.

Método HTTP	Descrição
GET	Retorna recursos já existentes, ex.: consulta de cobrança.
POST	Cria um novo recurso, ex.: criação de cobrança.
PUT	Atualiza um recurso existente, ex.: realizar devolução.
DELETE	Exclui um recurso, ex.: exclui um webhook.
PATCH	Revisa um recurso, ex.: revisa uma cobrança.

Cada envio de requisição irá retornar um código de Status HTTP, indicando se ela foi realizada com sucesso ou não.

Código de status HTTP

Os códigos do padrão HTTP, retornados como resposta à requisição feita para a API, informam se as informações enviadas à API estão obtendo sucesso ao atingir nossos endpoints.

Código	Status	Descrição	Exemplo de situações em que pode ocorrer
200	OK	Operação realizada com sucesso	Cobrança recorrente revisada Dados da cobrança recorrente Lista de cobranças recorrentes Lista de cobranças imediatas Lista dos Pix recebidos de acordo com o critério de busca Lista dos locations cadastrados de acordo com o critério de busca Dados da location do Payload Entidade representada pelo recurso informado desvinculada com sucesso Dados da recorrência Recorrência revisada Dados da solicitação da recorrência Cobrança imediata revisada. A revisão deve ser incrementada em 1. Dados da cobrança imediata. Dados da devolução Webhook para notificações acerca de Pix recebidos associados a um txid. Dados do webhook. Webhook para notificações.
201	Created	A solicitação foi realizada, resultando na criação de um novo recurso	Access Token Criado Cobrança imediata recorrente Cobrança recorrente criada Cobrança recorrente Dados da location do Payload Recorrência criada Dados da solicitação da recorrência Solicitação de recorrência atualizada Cobrança imediata criada Dados da devolução
204	Empty	Operação realizada com sucesso, mas nenhuma resposta foi retornada	Webhook para notificações foi cancelado.
400	Bad Request	A requisição possui parâmetro(s) inválido(s)	Requisição com formato inválido
401	Unauthorized	O token de acesso não foi informado ou não possui acesso às APIs	Erro credencial inválida
403	Forbidden	O acesso ao rescurso foi negado	Requisição de participante autenticado que viola alguma regra de autorização
404	Not Found	O recurso informado no request não foi encontrado	Recurso solicitado não foi encontrado
503	Service unavailable	Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento	Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.

Credenciais e autenticação

Abaixo, você aprende como solicitar credenciais Sandbox e, em seguida, credenciais Produção.

Solicitação de credenciais Sandbox

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

No ambiente Sandbox, após gerar o QR Code, envie-o por e-mail apipix.suporte@cielo.com.br para que a Cielo efetue o pagamento. Configure um tempo de expiração maior para o QR Code.

Solicitação de credenciais Produção

Para transacionar em nome dos clientes da Cielo, os parceiros devem ter as seguintes chaves do cliente:

• Client ID
• Client Secret
• Chave Pix

Siga o passo-a-passo abaixo para gerar credenciais de Produção:

1. No site da Cielo, acesse o portal Minha Conta e clique em Meu Cadastro.

2. Na aba Autorizações, clique em Pix.

3. Selecione a opção Novo acesso.

4. Clique em Criar credencial.

5. Selecione o parceiro.

6. Clique em Criar.

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

8. Clique no botão Autenticar e continuar.

9 Insira o token de segurança.

A ativação do token deve ser realizada através do Cielo Gestão.

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.

Geração de certificado mTLS

Com mTLS, seu sistema precisa provar sua identidade usando um certificado cliente. Sem esse certificado, a API Pix não permite conexões. O mTLS adiciona uma camada extra de criptografia e validação. Isso evita interceptação de dados e acesso indevido à API.

Nesse contexto, o arquivo .csr (Certificate Signing Request) é o pedido de certificado contendo sua chave pública e os dados da sua empresa. Você gera o .csr localmente, envia para a Cielo e nós devolvemos um certificado assinado que sua aplicação deve usar.

Para obter o certificado assinado pela Cielo, gere um arquivo .csr com o seguinte comando no terminal (CMD):

openssl req -new -newkey rsa:2048 -nodes -keyout chave_privada.key -out certificado.csr

Você deve passar as seguintes informações:

Certificado do tipo MTLS
E-mail: sustentacaopix@cielo.com.br
Common Name (CN) = api-insiraaquionomedoparceiro-mtls
Organizational Unit (OU) = PIX
Organization (O) = CIELO S.A.
Locality (L) = Barueri
State (ST) = SP
Country (C)C= BR

Envie o .csr para: apipix.suporte@cielo.com.br.

Ao preencher os campos obrigatórios listados acima, lembre-se:

• Caracteres especiais (como símbolos e acentos) não são aceitos.
• No campo Common Name (CN), onde aparece “api-insiraaquionomedoparceiro-mtls”, substitua o trecho insiraaquionomedoparceiro pelo nome do parceiro.   

Entidades

As entidades representam os principais objetos de dados utilizados na comunicação com a API Pix. Elas definem a estrutura das informações que são enviadas e recebidas durante as operações de pedidos e pagamentos.

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:

• ATIVA: indica que a cobrança foi gerada e pronta para ser paga;
• CONCLUÍDA:: indica que a cobrança já foi paga e, por conseguinte, não pode acolher outro pagamento67;
• REMOVIDO_PELO_USUARIO_RECEBEDOR: indica que o usuário recebedor solicitou a remoção da cobrança; e
• 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:

• EM_PROCESSAMENTO: indica que a devolução foi solicitada, mas ainda está em processamento no SPI;
• DEVOLVIDO: indica que a devolução foi liquidada pelo SPI; e
• 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.

SWAGGER: API PIX

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