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 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 um expiration_time.

Request

POST {cielo-api-base-url}/consent/v1/oauth/access-token

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

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.
• Quando o access_token expirar o parceiro não conseguirá mais chamas as APIs até que solicite um novo acess_token usando o 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 parceiro não consegue gerar um access_token sem o consentimento do cliente.
• O parceiro não consegue usar o authorization code, recebido no primeiro passo, mais de 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: Authorization: Bearer {access_token} Em todas as chamadas para as APIs.

O access_token foi obtido no Segundo passo.

Passo 3.1: Atualizando um Access Token

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

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

Um ponto de atenção na requisição pois agora o parceiro precisa enviar o grant_type como refresh_token e no campo refresh_token deve ser enviado um refresh_token válido (e não mais um access_token).

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.