Essa API (exclusiva para Conciliadoras) possibilita o registro de grupos e mantém seu registro para receber arquivos EDI (Electronic Data Interchange).

Passo 1: Login

1 - O parceiro redireciona o cliente para {cielo-login-url}.

2 - O cliente entra com suas credenciais e clica em Entrar.

3 - A Cielo mostra os termos de autorização e o cliente aprova este acesso clicando em Permitir Acesso.

4 - A Cielo redireciona o cliente para o parceiro novamente em {partner-call-back-url}.

O cliente deve selecionar quais ECs os conciliadores devem receber e clicar em permitir. Feito isso, ele é redirecionado para uma segunda etapa no processo, em que realiza o login novamente e é solicitado um consentimento para que o conciliador possa seguir com o processo de manutenção no cadastro EDI do cliente:

Feito o processo, seguirá para o redirect_uri do parceiro, onde pode ser resgatado o code para geração do Access token.

O que é base-login-url?

https://{base-login-url}?response_type=code &client_id={client_id} &redirect_uri={redirect_uri} &scope={scope} &state={state}

• base-login-url: URL base que muda por ambiente
• response_type: O valor deve ser fixo "code"
• client_id: Identificador do cliente, será enviado pela Cielo em tempo de projeto
• redirect_uri: URL do parceiro para a Cielo redirecionar o usuário quando o processo de login terminar, ou se der algum erro no processo
• scope: Uma lista separada por vírgula das APIs que o parceiro deseja acessar, os possiveis escopos serão enviados por API.
• state: Um valor que o cliente deseja receber no retorno para manter o estado entre a requisição e o retorno

O que é partner-callback-url?

https://{partner-callback-url}?code={code}&state={state}

• partner-callback-url: A URL do parceiro que será redirecionado quando o processo de login terminar.
• code: O authorization code gerado pela Cielo. Com esse código o parceiro vai poder trocar por um access_token para fazer chamadas em nome do cliente.
• state: O mesmo valor que o parceiro enviou na requisição.

Passo 2: Requisitando um Access Token

• O serviço do parceiro solicita um access_token.
• A Cielo retorna um acess_token, um refresh_token e o tempo de expiração do token.

Request

Há dois fluxos:

• Fluxo vigente: Pode ser utilizado até 1 de outubro de 2026;
• Fluxo novo: Vigente a partir de 9 de setembro de 2026 em homologação e 1 de outubro em produção.

Fluxo vigente

curl --location --request POST 'https://{cielo-api-base-url}/consent/v1/oauth/access-token' \ 
--header 'Authorization: Basic {Base64(client_id:client_secret)}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
  "grant_type": "authorization_code", 
  "code": "{authorization_code}" 
}' \ 
--verbose 

Fluxo novo

curl --location 'https://{cielo-api-base-url}/realms/digital-idp/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'code={authorization_code}' \
--data-urlencode 'redirect_uri={redirect_uri}'

Parâmetros obrigatórios:

Response

{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"token_type": "access_token",
"expires_in": {expiration_time}
}

Observações:

• O authorization_code precisa ser trocado por um access_token em menos de 10 minutos.
• Este tipo de access_token é mandatório para chamar as APIs que retornam dados sensíveis dos clientes.
• O parceiro precisa armazenar o access_token e o refresh_token em um lugar seguro.
• Após a expiração, solicite um novo token pelo fluxo de refresh_token.
• O acess_token gerado nesse fluxo será único por cliente da Cielo, pois precisa obrigatoriamente a aprovação do cliente.
• O access_token é único por cliente Cielo e depende do consentimento do cliente.
• O authorization_code só pode ser utilizado uma vez.

Passo 3: Chamando as APIs

Neste momento parceiro vai conseguir chamar as APIs da Cielo sem a necessidade da aprovação do cliente, pois esta já foi concedida.

A única exigência para chamar as APIs da Cielo é enviar o seguinte header HTTP em todas as chamadas para as APIs.

Authorization: Bearer {access_token}

Passo 3.1: Atualizando um Access Token

1. O serviço do parceiro chama o serviço de refresh_token.

2. A Cielo retorna um access_token novo, um refresh_token novo e um novo expiration_time.

   O dados de resposta serão os mesmos do passo 2 quando o parceiro solicita um acess_token, porém todos os dados retornados são novos e precisam ser armazenados no lugar dos antigos.

Request

Há dois fluxos:

• Fluxo vigente: endpoint atual, autenticação Basic e corpo JSON;
• Fluxo novo: novo endpoint e Content-Type application/x-www-form-urlencoded.

Fluxo vigente

curl --location --request POST 'https://{cielo-api-base-url}/consent/v1/oauth/access-token' \ 
--header 'Authorization: Basic {Base64(client_id:client_secret)}' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
  "grant_type": "refresh_token", 
  "refresh_token": "{refresh_token}" 
}' \ 
--verbose 

Fluxo novo

curl --location 'https://{cielo-api-base-url}/realms/digital-idp/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'refresh_token={refresh_token}'

Parâmetros obrigatórios:

Response

{
"access_token": "{access_token}",
"refresh_token": "{refresh_token}",
"token_type": "access_token",
"expires_in": {expiration_time}
}

Erros

Caso ocorra algum erro do lado Cielo o cliente será redirecionado para a URL de call-back do parceiro com o parâmetro error na URL, por exemplo https://{partner-callback-url}?error={error}.

Possíveis valores para {error}:

• lid_request: A requisição está faltando algum parâmetro obrigatório, ou esta com algum parâmetro inválido, ou qualquer outra possibilidade que faça a URL ficar incorreta.
• unauthorized_client: O parceiro não está autorizado a fazer uma requisição usando este método.
• access_denied: O dono do recurso ou o servidor de autorização negou a requisição.
• unsupported_response_type: O servidor de autorização não suporta obter um authorization code usando este método.
• invalid_scope: O escopo é invalido, desconhecido ou malformado.
• server_error: O servidor de autorização encontrou uma condição inesperada e não consegue concluir esta requisição. ( Este erro é necessário porque não é possível retornar um HTTP status code 500 Internal Server Error via redirecionamento HTTP)
• temporarily_unavailable: O servidor de autorização não consegue tratar a requisição devido a uma sobrecarga temporária ou está em manutenção. (Este erro é necessário pois não é possível retornar um HTTP Status 503 Service Unavailable para o parceiro via redirecionamento HTTP)

Opcionalmente pode ser retornado um outro parâmetros error_description com um detalhe do erro, apenas um texto simples.

Observações

• Todos os tokens (access_token e refresh_token) devem ser armazenados em um local seguro.
• O parceiro precisam iniciar um novo fluxo de concessão se perderem os tokens ou ambos expirarem (O refresh_token tem expiração de 90 dias a partir da geração).
• Caso gere um novo refresh_token este tem mais 90 dias a partir da geração para expirar.
• O parceiro precisa iniciar um novo fluxo de concessão para cada cliente da Cielo que o parceiro deseja consultar os dados.