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.

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.

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.

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.

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:

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.

PIX AUTOMÁTICO

O Pix Automático é uma funcionalidade do Pix criada para facilitar pagamentos recorrentes, permitindo que o usuário pagador autorize previamente uma cobrança periódica feita por um estabelecimento. Após o consentimento, os débitos são realizados de forma automática na conta do pagador, sem necessidade de ações manuais a cada ciclo. Esse modelo torna o processo mais simples, rápido e seguro para ambos os lados, substituindo mecanismos tradicionais como débito automático, boletos ou renovações manuais de assinatura.

Benefícios

O Pix Automático permite criar contratos de cobrança que podem ser por tempo indeterminado ou com um período definido, informando data de início e de término. Também é necessário indicar a periodicidade combinada entre pagador e recebedor, que pode ser: semanal, quinzenal, mensal, trimestral ou anual.

Esta solução preenche lacunas atualmente existentes no mercado de meios de pagamento, ao oferecer maior simplicidade para a empresa recebedora. Com ela, o recebedor pode operar utilizando apenas um único provedor de Pix Automático, o que aumenta a eficiência, reduz a carga operacional e acelera processos. Além disso, aproveita a agilidade do Pix, que possui liquidação instantânea, garantindo a identificação e baixa do pagamento de forma imediata.

Casos de uso

O Pix Automático pode ser aplicado em diversos tipos de pagamentos recorrentes, especialmente aqueles que exigem praticidade e regularidade. Entre os principais casos, destacam‑se:

• Despesas domésticas fixas: Aluguel, água, energia, gás, internet e outros serviços essenciais.
• Mensalidades: Academias, escolas e cursos diversos.
• Assinaturas digitais: Plataformas de streaming, clubes de assinatura, softwares e serviços online.
• Seguros: Cobranças periódicas de diferentes tipos de apólices.

Fluxo de integração

Para utilização do Pix Automático na visão de usuário recebedor, por meio da API Pix, é necessário seguir os seguintes passos:

1. Criação da recorrência: É o ponto de partida para habilitar o recebimento de pagamentos pelo produto. Nessa etapa, é criado um contrato de recorrência que reúne as informações do recebedor, a descrição do débito recorrente, a periodicidade e a data de início das cobranças. Após a criação, é gerado um identificador para essa recorrência (idRec).

2. Autorização do pagador: Após a criação da recorrência, é necessário que o pagador realize o consentimento para autorizar pagamentos vinculados ao contrato estabelecido. e pagamento da recorrência criada.

3. Cobranças recorrentes: Com o aceite da solicitação de recorrência, o usuário recebedor pode enviar as cobranças correspondentes ao período vigente para agendamento e liquidação. Para isso, cada cobrança deve obedecer as condições definidas no contrato de recorrência, como valor, periodicidade e data de vencimento, além de ter um Txid único por transação.

4. Cancelamento: Pode acontecer a qualquer momento do ciclo de vida do produto e pode partir tanto do usuário recebedor como do pagador.

Endpoints da API Pix

Abaixo estão listados os principais endpoints da API Pix, com foco nas funcionalidades relacionadas ao Pix Automático. A tabela a seguir resume os métodos disponíveis, sua presença na documentação da Cielo e no Swagger do Bacen.

Jornadas

As jornadas do Pix são caminhos padronizados definidos pelo Banco Central que determinam como o usuário pagador concede autorização para pagamentos recorrentes no Pix Automático.

No Pix Automático na Cielo, estão previstas algumas jornadas:

• Jornadas de adesão (autorização da recorrência)
• Jornadas de cobrança (agendamento)
• Jornadas do envio de notificações por webhook

Jornadas de adesão

Para realizar a adesão ao Pix Automático, o usuário recebedor deve primeiro criar a recorrência. Em seguida, ele solicita o aceite do usuário pagador, concluindo assim o processo de adesão ao meio de pagamento.

Jornada 1: Por meio de notificação

1.O usuário pagador seleciona o Pix Automático como forma de pagamento no ambiente da empresa recebedora e informa os dados de agência e conta.

2. Com essas informações, o recebedor solicita ao seu PSP a criação da recorrência e o envio da solicitação correspondente.

3. Quando o usuário recebedor cria a recorrência, a Cielo retorna um ID de recorrência (IdRec), que poderá ser utilizado pela empresa recebedora para consultar aquele contrato a qualquer momento.

4. É gerada uma solicitação de recorrência vinculada ao IdRec, que também possui um identificador único (IdSolicRec) para consulta. Essa solicitação permanece válida até a data de vencimento definida pelo recebedor.

Jornada 2: Leitura de QRCode

1. O usuário pagador seleciona o Pix Automático como forma de pagamento, e a empresa recebedora exibe um QR Code contendo todas as informações da recorrência.

2. Ao ler esse QR Code no aplicativo do banco onde possui conta, o pagador é direcionado diretamente para a jornada de autorização dentro do próprio aplicativo bancário.

A solicitação de uma recorrência via QR Code é realizada por meio da rota de location da recorrência, utilizando um identificador específico destinado a esse fluxo de leitura por QR Code.

O processo de criação da recorrência permanece igual ao descrito na Jornada 1, adotando o mesmo padrão de identificadores, conforme demonstrado no fluxograma a seguir:

Jornada 3: Pagamento imediato de Pix + autorização da recorrência

1. A empresa recebedora disponibiliza ao cliente um QR Code (ou código copia e cola) que reúne as informações necessárias para a autorização da recorrência e para o pagamento imediato da primeira cobrança.

2. O cliente concede a autorização ao mesmo tempo em que realiza o pagamento inicial via Pix.

3. Após o pagamento dessa primeira cobrança, a solicitação do Pix Automático é automaticamente aceita, e as próximas cobranças passam a ocorrer conforme os parâmetros definidos na recorrência.

Jornada de cobrança: Agendamento

Para agendar uma cobrança no Pix Automático, a empresa recebedora deve enviar a solicitação de acordo com a periodicidade definida no contrato de recorrência. A solicitação de agendamento deve ser enviada entre 10 e 2 dias antes da data de vencimento, conforme regra estabelecida pelo Banco Central.

O cancelamento do agendamento pode ser realizado tanto pelo pagador quanto pelo recebedor, seguindo prazos específicos para cada parte:

• Recebedor: Pode cancelar até as 22h00 do dia anterior à data prevista para liquidação.
• Pagador: Pode cancelar até as 23h59 do dia anterior à data de liquidação.
  

A consulta de agendamentos e o cancelamento devem ser realizados por meio dos endpoints específicos desse serviço, permitindo que a empresa recebedora acesse o status dos agendamentos, seja de forma individual ou em lista.

Abaixo, apresentamos um exemplo com os campos obrigatórios para criação de cobrança recorrente.

Requisição:

{ 
  "idRec": "RR1234567820240115abcdefghijk", 
  "infoAdicional": "Serviços de Streaming de Música e Filmes.", 
  "calendario": { 
    "dataDeVencimento": "2024-04-15" 
  }, 
  "valor": { 
    "original": "106.07" 
  }, 
  "ajusteDiaUtil": true, 
  "devedor": { 
    "cep": "89256-140", 
    "cidade": "Uberlândia", 
    "email": "sebastiao.tav@mail.com", 
    "logradouro": "Alameda Franco 1056", 
    "uf": "MG" 
  }, 
  "recebedor": { 
    "agencia": "9708", 
    "conta": "012682", 
    "tipoConta": "CORRENTE" 
  } 
} 

Como o cliente acessa os dados da sua conta?

Na chamada do endpoint CobR, o usuário recebedor deve informar agência e conta de pagamento da Cielo. Para encontrar essses dados, no Site Cielo, em ambiente logado, acesse a aba Pix e serão apresentados os dados da Conta de pagamento, conforme abaixo:

Fluxos de webhook

A aplicação atua como um monitor ativo de todos os eventos relacionados ao Pix Automático, independentemente de terem sido iniciados pelo pagador ou pelo recebedor. Seu objetivo é notificar o usuário recebedor sobre cada etapa do fluxo do Pix Automático, garantindo visibilidade completa do processo.

A Cielo disponibiliza esse serviço tanto para as etapas da recorrência — incluindo todos os passos que compõem esse ciclo — quanto para a jornada de agendamento, cobrindo desde a criação do agendamento até a etapa de liquidação.

QR Code composto

Nas jornadas que utilizam QR Code, existem casos em que é empregado o QR Code composto, que oferece um conjunto mais amplo de funcionalidades em comparação ao QR Code estático e ao QR Code dinâmico. A principal diferença desse tipo de QR Code é a presença de uma URL adicional, inserida em um campo específico do payload. Essa URL contém as informações associadas às configurações de recorrência de pagamentos que o usuário recebedor disponibiliza ao usuário pagador.

AS periodicidades possíveis são:

• Semanal;
• Mensal;
• Trimestral;
• Semestral;
• Anual.
  
  

Política de retentativa

Status de recorrência

Tipo de jornada

Dados de entrada

Exemplo de entrada

{
  "vinculo": {
    "contrato": "63100862",
    "devedor": {
      "cpf": "45164632481",
      "nome": "Fulano de Tal"
    },
    "objeto": "Serviço de Streamming de Música."
  },
  "calendario": {
    "dataFinal": "2025-04-01",
    "dataInicial": "2024-04-01",
    "periodicidade": "MENSAL"
  },
  "valor": {
    "valorRec": "35.00"
  },
  "politicaRetentativa": "NAO_PERMITE",
  "loc": 108,
  "ativacao": {
    "dadosJornada": {
      "txid": "33beb661beda44a8928fef47dbeb2dc5"
    }
  }
}

Dados de saída

Exemplos de saída

{
  "idRec": "RN1234567820240115abcdefghijk",
  "vinculo": {
    "contrato": "63100862",
    "devedor": {
      "cpf": "45164632481",
      "nome": "Fulano de Tal"
    },
    "objeto": "Serviço de Streamming de Música."
  },
  "calendario": {
    "dataFinal": "2025-04-01",
    "dataInicial": "2024-04-01",
    "periodicidade": "MENSAL"
  },
  "politicaRetentativa": "NAO_PERMITE",
  "recebedor": {
    "cnpj": "01602606113708",
    "nome": "Empresa de Serviços SA"
  },
  "valor": {
    "valorRec": "35.00"
  },
  "status": "CRIADA",
  "loc": {
    "criacao": "2023-12-10T07:10:05.115Z",
    "id": 108,
    "location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
    "idRec": "RN1234567820240115abcdefghijk"
  },
  "ativacao": {
    "dadosJornada": {
      "tipoJornada": "JORNADA_3",
      "txid": "33beb661beda44a8928fef47dbeb2dc5"
    }
  },
  "atualizacao": [
    {
      "data": "2023-12-19T12:28:05.230Z",
      "nome": "CRIADA"
    }
  ]
}

Códigos de retorno

Recursos

Consultar listas de recorrência

Retorna todos os contratos de recorrência de forma paginada a partir das informações do pagador.

AS periodicidades possíveis são:

• Semanal;
• Mensal;
• Trimestral;
• Semestral;
• Anual.
  
  

Política de retentativa

Status de recorrência

Tipo de jornada

Os possíveis solicitantes de cancelamento da cobrança recorrente são:

• PSP_PAGADOR
• USUARIO_PAGADOR
• PSP_RECEBEDOR
• USUARIO_RECEBEDOR
  
  

Códigos de cancelamento

SWAGGER: API PIX

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