Objetivo

O objetivo desta documentação é orientar sobre a integração com a API Única de Cancelamento de vendas Cielo, descrevendo funcionalidade, informações técnicas e etapas para solicitação de acesso.

Sobre a API Única de Cancelamento

A API Única de Cancelamento é mais uma opção de canal de cancelamento de vendas disponibilizado pela Cielo aos clientes.

Com a API Única de cancelamento, é possível centralizar cancelamentos de vendas de diversas soluções de captura em uma única integração (POS, LIO, TEF e E-commerce) além de permitir consulta de cancelamentos e geração de Cartas de Cancelamentos efetivados.

A integração com a API exige credenciais de acesso que são concedidas por Raiz de CNPJ. Ou seja, todos os Estabelecimentos (ECs) que fazem parte dessa raiz podem ter cancelamentos de vendas solicitados usando uma mesma credencial de acesso em uma única integração.

Principais benefícios da solução da API de Cancelamento

• Solicitação de cancelamento direta para o Sistema de Cancelamento Cielo.
• Consulta de Status de Cancelamento com descrição complementar de motivo em caso de rejeição de cancelamento.
• Centralização de solicitações de cancelamento de vendas feitas por variadas soluções de captura usadas pelo cliente (POS, TEF, LIO, E-commerce).
• Geração de Carta de Cancelamento no mesmo dia da efetivação do cancelamento, de forma unitária ou em lote.
• Autonomia e autosserviço no processo de solicitação de cancelamento de vendas.
• Simplicidade: o protocolo utilizado é puramente HTTPS, tecnologia REST, que é padrão de mercado.
• Facilidade de testes: disponibilizamos credenciais de ambiente de homologação e massa de vendas para teste em ambiente de homologação.

Produtos e Bandeiras suportadas

A versão atual da API Cancelamento Cielo possui suporte de cancelamento a todos os produtos e bandeiras capturados pela Cielo com exceção de PIX, transações de Voucher e Pré-autorização.

Fluxo para acesso API de Cancelamento

O fluxo abaixo mostra a integração do cliente na API Única de Cancelamento desde o recebimento das credenciais de Homologação produção até o acesso à API em Produção

Solicitação de Credenciais para Produção (client_id e client_secret)

Envio de informações para solicitação de credencial

Para obter acesso à API de Cancelamento em Produção, envie os dados abaixo para: api.cancelamento@cielo.com.br

• Nome: nome do ponto focal do estabelecimento que fará o gerenciamento das credenciais para acessar a API de Cancelamento.
• E-mail: e-mail do ponto focal do estabelecimento que fará o gerenciamento das credenciais para acessar a API de Cancelamento.
• Raiz de CNPJ: raiz do CNPJ que deseja integrar na API. Caso tenha mais de uma raiz de CNPJ a ser integrada, envie todas.

Nota: Todos os estabelecimentos que compõem essa raiz de CNPJ poderão ter os cancelamentos de vendas solicitados pela API Única de Cancelamento.

Com esses dados, nosso time Cielo vai solicitar criação de credenciais de acesso para integração em Produção.

Mesmo que a integração do Estabelecimento com a API seja feita através de um terceiro, o e-mail que deve ser enviado deve ser do ponto focal do estabelecimento.

Cadastro no Portal de Desenvolvedores Cielo 

Após a aprovação da solicitação, um e-mail será enviado ao ponto focal estabelecimento solicitante. 

Acesse o Portal de Desenvolvedores Cielo  https://desenvolvedores.cielo.com.br/api-portal/ e realize seu cadastro.

Importante: O cadastro deve ser realizado com o mesmo e-mail do ponto focal do Estabelecimento enviado no passo 1.

Preencha o e-mail de quem fará o gerenciamento das credenciais para acessar a API de cancelamento e demais dados do Estabelecimento.

Ao concluir o cadastro, um e-mail de confirmação será enviado.

Acesse o e-mail utilizado no cadastro e acesse o link para validar o primeiro acesso.

Altere a senha inicial e salve as alterações.

Para ter mais segurança no acesso às credenciais, clique no botão “Configurar Aplicativo” e instale em seu dispositivo móvel ou desktop aplicativo de duplo fator de autenticação que desejar /preferir.

• Google Authenticator (Android/iPhone/BlackBerry)
• Authy (Android/iPhone)
• Authenticator (Windows Phone)
• FreeOTP (Android)
• GAuth Authenticator (Firefox OS, desktop, outros)

O aplicativo de autenticação de dois fatores será usado durante esta configuração e para gerar códigos durante a autenticação regular. Se o aplicativo for compatível, realize a leitura do código QR Code para obter o código de configuração, caso contrário você poderá inserir manualmente o código de texto.

Link para instalação do app: https://www.microsoft.com/pt-br/security/mobile-authenticator-app

Forneça a senha atual e confirme.

O aplicativo de autenticação de dois fatores será usado durante esta configuração e para gerar códigos durante a autenticação regular. Se o aplicativo for compatível, realize a leitura do código QR Code para obter o código de configuração, caso contrário você poderá inserir manualmente o código de texto.

Valide o código fornecido no aplicativo Microsoft Authenticator (é obrigatório).

Após concluída a autenticação, a mensagem “Configuração do TFA concluída” será exibida e poderá ter acesso a sua conta conforme dados enviados por e-mail.

Acesse Cliente-Ids Cadastrados acessando no menu item “Perfil” > “Client-Ids Cadastrados” ou acessando Client-Ids Cadastrados no rodapé.

Criação de uma chave pública e privada para criptografia (Certificado MTLS)

Para conferir maior segurança no uso da API Única de Cancelamento, é necessário uso de certificado assinado pela Cielo.

Este certificado não tem custo adicional e todas as chamadas aos serviços da API em homologação e produção devem ser feitas com certificado MTLS assinado pela Cielo.

Gere o arquivo da chave pública no formato .csr executando o comando abaixo em um terminal como gitbash ou via ferramenta openssl.

Exemplo:

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

Ao executar este comando, preencha as informações solicitadas conforme exemplo abaixo e substituindo os dados sinalizadas na cor azul em negrito com o nome da sua empresa:

Exemplo:

Serão gerados dois arquivos no caminho de diretório em que for executado o comando, um deles .csr e outr .key

• O arquivo “.key” é de uso exclusivo do estabelecimento
• Já o arquivo “.csr” deve ser encaminhado para assinatura da Cielo, sendo utilizado o mesmo certificado nos ambientes de Sandbox e Produção.

O cliente deve enviar o arquivo .csr por e-mail para geração do certificado assinado.

Envie o arquivo para: api.cancelamento@cielo.com.br e aguarde retorno do time Cielo com o certificado MTLS assinado.

Configurações para utilização da API

Adicionar certificado MTLS no Postman

Nesse tópico serão fornecidas informações sobre como anexar o certificado assinado pela Cielo na API Única de Cancelamentos.

Na ferramenta do Postman, vá para o ícone de “ferramentas” > Configurações > Certificados > Anexe o arquivo .crt assinado pela Cielo e o .key.

Observação: Este passo deve ser feito tanto para o ambiente de produção quanto para o de homologação, mas você pode usar o mesmo certificado, apenas alterando o campo “Host”.

Acesso aos endpoints da Cielo:

Homologação: https://apihml-corp.cielo.com.br/cielo-refunds-exp-hml/refunds/v1/refunds

Produção: https://api-corp.cielo.com.br/cielo-refunds-exp/refunds/v1/refunds

Fluxo de Autenticação de Credenciais do Cliente (Client Credencials flow)

Obtenção do Token

Para realizar uma solicitação de cancelamento ou consulta na API, é necessário obter o token utilizando seu cliente_id e Cliente_secret

Homologação

curl --location --request POST
https://apihml-corp.cielo.com.br/cielo-security-sys-hml/oauth/v2/MulesoftHML/protocol/openid-connect/token\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client\_id={ **clientId** }' \
--data-urlencode 'client\_secret={ **secret** }' \
--data-urlencode 'grant\_type=client\_credentials'

Produção

curl --location --request POST
https://api-corp.cielo.com.br/cielo-security-sys-web/oauth/v2/MulesoftPRD/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client\_id={ **clientId** }' \
--data-urlencode 'client\_secret={ **secret** }' \
--data-urlencode 'grant\_type=client\_credentials'

Exemplo no Postman:

Header:

Body:

(enviar o client_id e o client secret disponibilizado pela Cielo)

Enviando uma requisição com token

Extraia o campo access_token do retorno da requisição apresentada no passo anterior e passe como header em “Authorization” quando for realizar requisição.

Exemplo: header (“Authorization”, “Bearer “ + token)

Serviços disponíveis API Única de Cancelamento

Solicitação de Cancelamento

Com esse serviço, é possível realizar solicitações de cancelamento individuais ou em lote através de dados da venda como número do EC, data da venda, código de autorização, valor da venda, entre outros.

Headers:

No campo “key” digite: Authorization e no campo “value” digite: Bearer + espaço + {access_token}

Em seguida no campo “key digite: Content-Type e no campo “value” digite: application/json.

Corpo da Requisição (Body):

Enviando uma solicitação de cancelamento.

transactionID = identificador de transação E-commerce.
Nsu = Número sequencial único
cardNumberLast4Digits = os 4 últimos dígitos do cartão
merchantID* = número do EC (estabelecimento comercial)
authorizationCode* = Código de autorização da venda
refundAmount: {
        currency*= tipo de moeda para cancelamento utilizar somente BRL
        value*= Valor para cancelar, pode ser o valor parcial ou total.
      }
saleAmount: {
        currency*= tipo de moeda para cancelamento utilizar somente BRL. 
        value*= valor da venda 
      }
transactionDate* = passar no formato DD-MM-YYYY HH24:MI:SS data da venda (Não é necessário passar a hora exata da venda)

*Campos obrigatórios

Response da requisição de cancelamento

  "merchantID": número do EC (estabelecimento comercial)
      "authorizationCode": Código de autorização da venda
      "refundAmount": {
        "currency":  tipo de moeda para cancelamento utilizar somente BRL.
        "value": Valor para cancelar, pode ser o valor parcial ou total
      },
      "saleAmount": {
        "currency":  tipo de moeda para cancelamento utilizar somente BRL.
        "value": Valor da venda
      },
      "transactionDate": formato DD-MM-YYYY HH24:MI:SS data da venda
      "controlID": identificador do cancelamento
      "status": {
        "type": Status da solicitação 
      }
    }
  ],
  "refundID": Identificador do lote de cancelamento
  "refundDate": Data da solicitação do cancelamento, formato exemplo: 2019-12-27T19:38:30.547Z

Consultar Cancelamento

Neste serviço, é possível consultar solicitações de cancelamento e visualizar status de cada requisição através de diversos parâmetros como lote de cancelamento, ID de cancelamento, data ou status.

Headers: (*mesmos headers utilizados na requisição de cancelamento)

No campo “key” digite: Authorization e no campo “value” digite: Bearer + espaço + {access_token} Em seguida no campo “key digite: Content-Type e no campo “value” digite: application/json.

Exemplo de requisição em homologação:

https://apihml-corp.cielo.com.br/cielo-refunds-exp-hml/refunds/v1/refunds/140426/2005157770

Request:

/{refundID}/{merchantID}?limit={limit} &offset={offset}
refundID = identificador devolvido no response da solicitação de cancelamento.
merchantID = número do EC (estabelecimento comercial)
limit = quantidade de solicitações dentro do json
offset = paginação

Response:

{
    "refundID": 140426,
    "refundDate": "2024-10-09T15:31:19.000-0300",
    "transactions": [
        {
            "transactionID": "20051577703PPIQIJ7FB",
            "nsu": 515027,
            "cardNumberLast4Digits": "0034",
            "merchantID": 2005157770,
            "authorizationCode": "546441",
            "refundAmount": {
                "currency": "BRL",
                "value": 0.01
            },
            "saleAmount": {
                "currency": "BRL",
                "value": 70000.0
            },
            "transactionDate": "2024-07-03T18:13:40.000-0300",
            "controlID": 3506674,
            "status": {
                "type": "done",
                "detail": {
                    "code": 0,
                    "message": "Cancelamento aprovado com sucesso."
                }
            }
        }
    ]
}

Descrição dos campos:

{
**"refundID":** Identificador do lote de cancelamento
**"refundDate":** Data da solicitação do cancelamento, formato exemplo: 2019-12-27T19:38:30.547Z
 **"transactions":** [
        {
**transactionID**= identificador de transação E-commerce.
**Nsu** = Número sequencial único.
**cardNumberLast4Digits** = os 4 últimos dígitos do cartão.
**merchantID** = número do EC (estabelecimento comercial).
**authorizationCode** = Código de autorização da venda.
**refundAmount**: {
        **currency** = tipo de moeda para cancelamento utilizar somente **BRL**.
        **value** = Valor para cancelar, pode ser o valor parcial ou total.
      }
**saleAmount**: {
        **currency** = tipo de moeda para cancelamento utilizar somente **BRL**.
        **value** = Valor da venda.
      }
**transactionDate** = no formato DD-MM-YYYY HH24:MI:SS data da venda. "**controlID**": identificador do cancelamento
      "**status**": {
        "**type**": Status da solicitação 
      }


**Caso o status for rejected:**
"**detail**": {
          "**code**" = Código da rejeição de cancelamento
          "**message**" = Motivo da rejeição de cancelamento
        }

O status pending e approved não tem detail no json.

Os retornos do tipo rejeição:

Consultar Cancelamento por timeout na requisição

Essa consulta deve ser executada somente quando houver problemas na comunicação durante a solicitação de cancelamento.

Exemplo Request:

https://apihml-corp.cielo.com.br/cielo-refunds-exp-hml/refunds/v1/refunds?cancelStartDate=09-10-2024&cancelEndDate=10-10-2024&rows=25&page=1&merchantId=2005157770&authorizationCode=546441

Request:

?cancelStartDate= {Data inicial}&cancelEndDate={Data final}&rows={linha}&page={pagina}&merchantId={Estabelecimento}&authorizationCode={código de autorização}
**cancelStartDate** = Data inicial da solicitação de cancelamento (formato dd-MM-yyyy)
**cancelEndDate** = Data final da solicitação de cancelamento (formato dd-MM-yyyy)
**rows** = Quantidade de linhas
**page** = Paginação
**merchantId** = número do EC (estabelecimento comercial)
**authorizationCode** = Código de autorização da venda.

Respose:

Descrição dos campos:

{
"**refundID**": Identificador do lote de cancelamento
 "**refundDate**": Data da solicitação do cancelamento, formato exemplo: 2019-12-27T19:38:30.547Z
 "**transactions**": [
        {
**transactionID** = identificador de transação E-commerce.
**Nsu** = Número sequencial único.
**cardNumberLast4Digits** = os 4 últimos dígitos do cartão.
**merchantID** = número do EC (estabelecimento comercial).
**authorizationCode** = Código de autorização da venda.
**refundAmount**: {
        **currency** = tipo de moeda para cancelamento utilizar somente **BRL**.
        **value** = Valor para cancelar, pode ser o valor parcial ou total.
      }
**saleAmount**: {
        **currency** = tipo de moeda para cancelamento utilizar somente **BRL**.
        **value** = Valor da venda.
      }
**transactionDate** = no formato DD-MM-YYYY HH24:MI:SS data da venda. "**controlID**": identificador do cancelamento
      "**status**": {
        "**type**": Status da solicitação 
      }

**Observações**:
O status pending e approved não tem detail no json.

Caso o status for rejected (Rejeição):
"**detail**": {
          "**code**" = Código da rejeição de cancelamento
          "**message**" = Motivo da rejeição de cancelamento
        }

Fluxo de Cancelamento

Efetivação de Cancelamento

A efetivação dos cancelamentos solicitados pela API é feita de forma assíncrona em processo batch com corte às 18h30 da tarde. O que significa que cancelamentos solicitados antes deste horário e que forem aprovados na validação de regras de negócio de cancelamento serão enviados para efetivação e terão seus status finais retornados na manhã do dia seguinte a partir das 8h (D1).

Status, Códigos e Mensagens de Retorno

Status

A API de Cancelamento possui 4 tipos de status de cancelamento retornados.

Códigos e Mensagens de Retorno

Nos cancelamentos com Status Rejected e Failed, temos informações de retorno no campo details. Os retornos possíveis são:

Retorno do tipo Failed:

Neste caso é só fazer uma nova requisição:

Retorno do tipo Done:

Carta de Cancelamento

Validações para geração

Só será possível gerar a carta de cancelamento quando o status type for igual a done. Ou seja, só será possível gerar a carta de cancelamento quando a solicitação estiver efetivada.

É possível solicitar a geração e carta por unidade ou lote.

A geração de carta pode ser gerada no idioma português ou inglês.

Não é possível gerar cartas em lote mesclados nos idiomas português e inglês.

Nas requisições de carta por lote, o limite é de 10 cartas por requisição.

Não é possível gerar um lote de cartas para ECs diferentes, na mesma requisição.

Solicitação de Carta por unidade

{
  "merchantId": 0,
  "cancellationId": 0,
  "language": "PT_BR"
}

No campo merchantId é necessário informar o número do estabelecimento (EC), do tipo number, este campo é obrigatório.

O Campo cancellationId é necessário informar o controlId, do tipo number, este campo é obrigatório.

O campo language é opcional, mantendo como default o idioma português, podendo também usar como o PT_BR para português ou EN_US para inglês.

Response em caso de erro:

{
  "errorCode": 999,
  "errorMessage": "You don't have sufficient credentials to perform this operation",
  "date": "2012-04-23T18:25:43.511Z"
}

Solicitação de Carta por lote

{
  "merchantId": 0,
  "cancellations": [
    0,1,2,3
  ],
  "language": "PT_BR"
}

No campo merchantId é necessário informar o número do estabelecimento (EC), do tipo number, este campo é obrigatório.

O Campo cancellationId é necessário informar uma lista de controlId, separado por virgula (“,”), do tipo number, este campo é obrigatório.

O campo language é opcional, mantendo como default o idioma português, podendo também usar como o PT_BR para português ou EN_US para inglês.

Suporte Cielo

Caso tenha dúvidas, envie um e-mail para: api.cancelamento@cielo.com.br

FAQ - Perguntas Frequentes

O que fazer se o token expirar?

Obtenha um novo token JWT repetindo o processo de autenticação descrito no passo (Fluxo de Autenticação de Credenciais do Cliente)

Como testar sem impactar o ambiente de produção?

Use a URL de homologação fornecida no passo (Acesso aos endpoints da Cielo).

Posso reutilizar o mesmo token para múltiplas requisições?

Sim, desde que ele ainda esteja válido (duração: 5 minutos). Caso expire, gere um novo token.

Ao integrar na API de Cancelamento, ainda poderei solicitar cancelamento por outros Canais?

Sim. A API é mais uma opção de canal para solicitar cancelamento de vendas. Os demais canais continuarão disponíveis para solicitação de cancelamento (POS, TEF, e-commerce, Central de Atendimento, Site/APP).

Atente-se para envio de cancelamentos parciais por 2 canais diferentes. Havendo saldo disponível na transação, as duas solicitações podem ser efetivadas.

É possível enviar cancelamentos parciais pela API de Cancelamento?

Sim. É possível enviar um ou mais cancelamentos parciais de uma mesma transação pela API. As solicitações serão efetivadas respeitando o saldo disponível na transação e as regras de cancelamento de cada Bandeira.

Débito Mastercard só permite um cancelamento parcial por transação. Em caso de 2ª solicitação de cancelamento, ela será rejeitada por regra da bandeira.

Qual o prazo de efetivação de cancelamento solicitado via API de Cancelamento?

Cancelamentos solicitados no mesmo dia da venda terão o status final disponível a partir das 8h da manhã de D2.

Cancelamentos solicitados após a data da venda, caso solicitados até as 18h30 terão seu status final disponível a partir das 8h da manhã de D1.

Qual a diferença entre API Única de Cancelamento e a API E-Commerce?

API Única de Cancelamento e a API E-commerce são soluções diferentes com propósitos e integrações diferentes.

A API E-commerce é uma solução de captura que também permite solicitação de cancelamentos de vendas e-commerce. Só é permitido cancelar vendas e-commerce do EC integrado

A API Única de cancelamento é uma solução cujo objetivo é permitir clientes centralizarem cancelamentos de diversas soluções de captura oferecidas pelas Cielo (TEF, POS, E-commerce, LIO). A integração é por Raiz de CNPJ e é possível cancelar vendas de todos os ECs que compõem essa Raiz.