API de Chargeback

Introdução

Objetivo

Esse manual foi feito para garantir uma melhor integração a você, cliente Cielo, na API de Chargeback.

Através dela, você pode aceitar ou recusar contestações, além de consultar contestações pendentes e tratadas, ciclo de vida e todas as informações importantes no processo de contestação.

Integração na API

Fluxo para integração com API de Chargeback

Integração com API de Chargeback

1. Envie o número do estabelecimento matriz (EC que representa a raiz de CNPJ) da companhia para Technical Support Chargeback no e-mail techsupportchargeback@cielo.com.br.

2. Efetue o pré-cadastro no Portal de Desenvolvedores.

• Acesse o Portal dos Desenvolvedores. Deve ser criado apenas um único login por cliente;
• Clique em “Sign Up” e cadastre Nome, Sobrenome e E-mail;
• Após esse cadastro, envie um e-mail para Technical Support Chargeback informando os dados cadastrados.

3. Crie uma chave pública e privada para criptografia

a. É necessário gerar o arquivo da chave pública no formato .csr.

Dica: as chaves podem ser geradas via ferramenta openssl.
Exemplo: openssl req -out nome_chave_publica.csr -new -newkey rsa:2048 -nodes - keyout chave_privada.key

• Gere o.csr da chave pública conforme padrão abaixo:

  1. emailAddress: informar o mesmo e-mail cadastrado no Portal dos Desenvolvedores
  2. Common Name (CN): nome da empresa
  3. Organizational Unit (OU): deve ser cadastrado como “Cielo – chargeback”
  4. Organization (O): nome da empresa
  5. Locality (L): cidade
  6. State (ST): estado
  7. Country (C): BR

  • Exemplo de preenchimento:

    > emailAddress: **adm@cliente1.com.br**<br>
    > Common Name (CN): **Cliente 1**<br>
    > Organizational Unit (OU): **Cielo – chargeback**<br>
    > Organization (O): **Cliente 1**<br>
    > Locality (L): **Campinas**<br>
    > State (ST): **Sao Paulo**<br>
    > Country (C): **BR**
    

b. Compacte o arquivo .csr contendo a chave pública em um arquivo .zip e envie para Technical Support Chargeback para realizar a assinatura.

c. Aguarde retorno do time Cielo com o certificado MTLS assinado.

4. Acesse o Portal dos Desenvolvedores e efetue o cadastro definitivo

Após o cadastro definitivo, faça o login no Portal dos Desenvolvedores e colete as chaves disponíveis do ambiente desejado;

Ao finalizar esse processo, você poderá acessar o sandbox da API de Chargeback e iniciar os testes conosco.

5. Liberação de acesso para os endpoints da Cielo:

Instruções para uso do Sandbox

Para utilizar o sandbox, passe os cenários abaixo para simular retornos de sucesso (código iniciando com 1) ou erro (código iniciando com 9).

Proposta de validação para prosseguirmos com a integração em produção:

• Validar sucesso (código 103) no serviço de Consulta de contestação pendente
• Validar falha (código 901) no serviço de Consulta de contestação pendente
• Validar sucesso (código 103) no serviço de Consulta de contestação tratada
• Validar falha (código 901) no serviço de Consulta de contestação tratada
• Validar sucesso (código 101) no serviço de Acate de contestação
• Validar falha (código 901) no serviço de Acate de contestação
• Validar sucesso (código 102) no serviço de Recusa de contestação
• Validar falha (código 901) no serviço de Recusa de contestação
• Validar sucesso (código 104) no serviço de Consulta de documento
• Validar falha (código 901) no serviço de Consulta de documento
• Validar falha (código 901) no serviço de Pesquisa do ciclo de vida

Utilização

Obtenção do Token

Para fazer a chamada, é preciso obter um token utilizando seu client_id e client_secret. Confira um exemplo de requisição:

Sandbox:

curl --location --request POST
https://apihml-internet.cielo.com.br/cielo-security-sys-web-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-internet.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'

Extraia o campo access_token do retorno da requisição e passe como header em Authorization:

Serviços da API

Fluxo de tratamento de contestações pendentes

Com a API de Chargeback, você consegue tratar suas contestações a partir de dois serviços: o de aceite e o de recusa. Veja como o fluxo funciona:

Fluxo de tratamento de contestações tratadas

Depois da tratativa, você pode acompanhar todo o processo consultando o ciclo de vida da disputa. E caso tenha recusado a contestação, você também pode consultar o documento de defesa anexado. Além disso, é possível realizar chamadas obtendo o código e descrição das razões e suas respectivas classificações.

Lista dos serviços disponíveis

Detalhamento dos serviços

Consulta de contestações pendentes ou tratadas

Com esse serviço, você consegue filtrar contestações para visualizar ou tratar por diversos parâmetros, como período, número do EC, entre outros.

Requisição

Parâmetros e Path Variables:

Corpo da requisição:

{
    "startNotificationPeriod": "2022-01-01",
    "endNotificationPeriod": "2022-01-01",
    "cardAssociationCode": null,
    "process":null,
    "reason": null,
    "establishmentNumber": ["2012457511"],
    “mainCustomer”: “”,
    “hierarchyType”: 4,
    "idCase": null,
    "tid": null,
    "nsu": null,
}

*Obrigatório para status DONE.

Domínios

Status

CardAssociationCode

Processo

Tipo de hierarquia

Resposta

A seguir, apresentamos exemplos de retornos da requisição para o ststus pendente e tratadas, respectivamente:**

• Exemplo de requisição do status pendente:

 {
    "content": [
        {
            "treatmentDeadline": "2023-09-27",
            "idCase": 5434398,
            "idChargeback": 58410,
            "establishmentNumber": 2012457538,
            "process": "PRIMEIRO_CHARGEBACK",
            "lifecycle": {},
            "transactionAmount": 211,
            "transactionDetails": {
                "transactionDate": "2023-09-13",
                "authorization": "588557",
                "cardAssociation": 1,
                "cardAssociationName": "VISA",
                "productCode": 43,
                "productDescription": "VISA PARCELADO LOJA",
                "issuerSenderCode": "0237",
                "issuerSenderDescription": "BRADESCO S/A",
                "truncatedCard": "409603******0034",
                "currency": "REAL",
                "referenceNumber": "24487683256432000000944",
                "nsu": 344221,
                "ro": "4230913",
                "terminal": "00068773",
                "establishmentName": "LEITE EM PO SA"
            },
    "chargebackDetails": {
                "reasonCode": "105",
                "reasonDescription": "Chargeback Credito",
                "tpReason": 1,
                "receptionDate": "2023-09-26",
                "rapidDisputeResolution": "false"
            },
            "remainingDaysToTreat": 1
        }
    ]
 }

• Exemplo de requisição do status tratado:

 [
  {
    "treatmentDeadline": "2022-10-14",
    "idCase": 0,
    "idChargeback": 0,
    "establishmentNumber": 0,
    "process": "PRIMEIRO_CHARGEBACK",
    "remainingDaysToTreat": 3,
    "lifecycle": {
      "action": "string",
      "actionDate": "2022-10-14"
    },
    "transactionAmount": 0,
    "actionTakenCode": "ACATAR",
    "transactionDetails": {
      "transactionDate": "2022-10-14",
      "authorization": "string",
      "cardAssociation": 1
      "cardAssociationName": "Mastercard",   
      "productCode": 0,
      "productDescription": "string",
      "issuerSenderCode": "string",
      "issuerSenderDescription": "string",
      "truncatedCard": "string",
      "currency": "REAL",
      "referenceNumber": "string",
      "ro": "string",
      "terminal": "string",
      "tid": "string",
      "establishmentName": "string"
    },
    "chargebackDetails": {
      "reasonCode": "104",
      "reasonDescription": "Outras Fraudes - Cartao Ausente",
      "tpReason": 1,
      "reasonMessage": "CMD CHARGEBACK TC15",
      "chargebackMessage": "CMD CHARGEBACK TC15",
      "receptionDate": "2023-09-14",
      "replyDate": "2023-09-15",
      "rapidDisputeResolution": "false"
            },
    "remainingDaysToTreat": 1
        }
    ]

Status de retorno:

Pesquisa de ciclo de vida

Esse serviço permite consultar o ciclo de vida de uma contestação tratada, isto é, as ações ocorridas na contestação após a tratativa.

Requisição

Parâmetros e Path Variables:

{
    "code": "string",
    "message": "string",
    "details": [
    {
    "code": "string",
    "message": "string"
    }
  ]
}

Retorno da requisição:

[
    {
    "code": "string",
    "message": "string",
    }
]

Status de retorno:

• Status Ciclo de Vida
  • Intermediários:
    • Em análise com o Cliente
    • Em análise com o Emissor
    • Em análise com a Cielo
  • Finais:
    • A favor do Estabelecimento
    • A favor do Emissor

Aceite de contestação

Serviço de realização do aceite de uma contestação, considerando a venda como inválida e concordando com o estorno pela credenciadora, a Cielo.

Requisição

Parâmetros e Path Variables:

{
    "updateChargeback": [
    {
    "establishmentNumber": " string ",
    "idChargeback": " string "
    },
     {
    "establishmentNumber": " string ",
    "idChargeback": " string "
    }
  ],
    "userName": "user"
}

*Todos os campos são obrigatórios.

Retorno da requisição:

 [
    {
    "establishmentNumber": "string",
    "idChargeback": "string",
    "code": "string",
    "message": "string"
   },
   {
    "establishmentNumber": "string",
    "idChargeback": "string",
    "code": "string",
    "message": "string"
    }
]

Status de retorno:

Recusa de contestação

Com esse serviço, você pode se defender de uma contestação apresentando uma evidência na forma de imagem ou documento, além de um breve texto justificando a posição.

Requisição

Parâmetros e Path Variables:

{
    "establishmentNumber": " string ",
    "idChargeback": " string",
    "reasonToRefuse": " string ",
     “file”: “multipart/form-data”,
     “userName”: “user”
}

*Todos os campos são obrigatórios.

Resposta

{
   "code":"string",
   "message":"string"
}

Status de retorno:

Pesquisa de razão

Serviço que provê a lista de todas as razões, por cada bandeira, para ser utilizada no filtro do serviço “Consulta de contestação pendentes e tratadas”.

Requisição

Parâmetros e Path Variables:

Resposta

{
    "cdReason": "string",
    "dcReason": "string",
     “tpReason”: “string”
}

Consulta de documento

No caso de recusa da contestação, esse serviço retorna o documento de defesa anexado para consulta.

Requisição

Parâmetros e Path Variables:

*Todos os campos são obrigatórios.

Resposta

[
  {
  "dateInclusion": "2023-01-20",
  "nameFile": "string",
  "codigo": 0,
  "mensagem": "string",
  "file": [
      "string"
    ]
  }
]

Lista de documentos do emissor

Esse serviço retorna os nomes e os códigos dos documentos enviados pelo emissor para apoio na tratativa de contestação.

Obs.: É necessário primeiro listar o documento, para após isso, realizar o download.

Requisição

Parâmetros e Path Variables:

*Todos os campos são obrigatórios.

Resposta

[
    {
        "idDocumento": 1571,
        "nameFile": "5219062.tif"
    }
]

Download de documentos do emissor

Este serviço disponibiliza o documento enviado pelo emissor para download.

Requisição

Parâmetros e Path Variables:

*Todos os campos são obrigatórios.

Resposta

{
    "dateInclusion": "2023-06-07",
    "nameFile": "string",
    "codigo": 0,
    "mensagem": "string!",
    "file": "string”
}

Tabela de descrição de campos

Tabela dos status de retorno

Dúvidas frequentes

1. O que é uma contestação?

É quando a pessoa titular do cartão identifica algum problema na transação, como suspeita de fraude ou desacordo com a loja. Então, a pessoa titular do cartão entra em contato com o banco emissor do cartão para relatar o ocorrido e é iniciado o processo de disputa. Além de contestação, esse processo também é chamado de chargeback. E todo o fluxo de disputa é regulamentado pelas bandeiras dos cartões, que determinam as regras de disputa, como quem ganha e quem perde, por exemplo.

2. Como eu posso me defender dessas contestações?

Quando uma compra é contestada, você tem duas opções:

• Aceitar e permitir o estorno do valor da venda;
• Se defender e evitar que o valor seja estornado.

Suas ações durante o processo de chargeback são chamadas de tratativas. A tratativa pode ser realizada dentro do App Cielo Gestão, Site Cielo ou através da API de Chargeback Cielo, que é o tema deste documento.

3. Para dar início ao processo de integração com a API de Chargeback, quais informações devo passar e para quem devo solicitar o cadastro?

Siga o passo a passo descrito no item Integração com API de Chargeback.

4. Caso eu esteja integrado com a API Risk Notification (Braspag), posso migrar para API de Chargeback da Cielo?

Sim, nós recomendamos que essa migração ocorra, justamente porque a API de Chargeback da Cielo oferece benefícios em relação a API Risk Notification. Entre eles, podemos listar:

• Um aumento de prazo no tratamento das contestações em 3 dias. Ou seja, a API Risk Notification tem 7 dias e a Cielo 10 dias;
• Um leque maior de formatos de documentos aceitos. A API Risk Notification aceita apenas TIFF, enquanto a Cielo aceita PDF e JPEG também;
• A consulta do status da contestação (serviço ciclo de vida), dando maior visibilidade e capacidade de gestão das contestações tratadas;
• A consulta do documento adicionado na defesa (serviço consulta de documento);
• A consulta do documento enviado pelo emissor.

Para realizar a migração, solicite ao seu Gerente de Negócios o descadastramento da API Risk Notification Braspag e a integração com a API de Chargeback Cielo. Durante o período de integração com API de Chargeback Cielo (desde o momento do descadastro da API Braspag até o momento da integração com a nova API), você deverá administrar seus chargebacks pelo site Cielo.

5. Como consultar uma contestação na API?

No serviço Consultar contestações pendentes ou tratadas, você consegue visualizar tanto as contestações que estão pendentes (status PENDING) quanto as que já foram tratadas (status DONE).

Para visualizar as contestações que estão pendentes de tratamento, basta informar o número do estabelecimento que deseja consultar, e para as já tratadas, você também deve especificar um período.

6. Posso realizar uma consulta para todos os estabelecimentos abaixo da minha matriz?

Sim, nós recomendamos que você consulte sempre pelo seu estabelecimento matriz, pois dessa forma você visualiza todas as contestações dos demais estabelecimentos abaixo daquela matriz selecionada. Na API, o número do estabelecimento individual que recebeu a contestação é representado pelo campo establishmentNumber e o número do estabelecimento matriz é o mainCustomer. Então, no serviço de consulta, você só precisa preencher o campo mainCustomer, assim você vai obter todas as contestações abaixo da sua hierarquia de Raiz de CNPJ. Caso queira visualizar as contestações abaixo de um outro tipo de hierarquia, como por exemplo um Grupo de Pagamento, você deverá preencher também o campo hierarchyType para especificar o tipo de matriz a ser consultada.

7. Como realizar uma tratativa na API?

No serviço Aceite de contestação, você realiza o aceite informando o número do estabelecimento que recebeu a contestação e o ID do Chargeback.

No serviço Recusa de contestação, você realiza a recusa informando, além do número do estabelecimento que recebeu a contestação e do ID do Chargeback, uma breve descrição da razão de recusa (máximo 100 caracteres) e um documento que comprove que a venda foi legítima, isto é, que foi feita pela pessoa titular do cartão ou com o consentimento dela e que ambos cumpriram suas obrigações no momento da compra.

8. Enviei a documentação solicitada, como saber qual o status do meu caso. Eu ganhei ou perdi esta contestação?

Você pode consultar o andamento da sua contestação no serviço Pesquisa Ciclo de Vida da API, informando o número do case que deseja visualizar.

9. Com que frequência devo consultar as contestações?

As bandeiras atualizam as contestações uma vez por dia, por isso, você pode verificar suas contestações diariamente.

Mais informações

Para mais informações, acesse o blog da Cielo.

Suporte

Em caso de dúvidas, envie um e-mail para techsupportchargeback@cielo.com.br

Caso precise de alguma ajuda, você pode entrar em contato diretamente com seu Gerente de Negócios, que estará pronto para te atender da melhor forma.