Manual de Integração - Risk Notification

Redirecionando para https://docs.cielo.com.br/risco/page/api-risk-notification-deprecated ...

Sobre essa documentação

Esta documentação apresenta a integração com a Risk Notification API, trazendo exemplos de requisições e respostas sobre a notificação, consulta, aceitação e disputa de chargebacks.

Se você tem interesse na ferramenta de análise de fraude da Braspag, acesse a documentação do Antifraude Gateway.

Visão geral

Os chargebacks são comuns em qualquer operação de e-commerce e geram impactos na agenda financeira de uma loja. A Risk Notification API oferece uma forma fácil e simplificada de saber quando um chargeback ocorreu e por qual motivo; assim, a loja pode decidir se irá aceitar ou disputar o chargeback.

Requisitos

Você pode integrar a Risk Notification API se a sua loja cria transações usando a API do Pagador  (tendo a Cielo como adquirente) ou a API E-commerce Cielo.

Para contratar a Risk Notification API, fale com o time Comercial da Braspag.

Clientes da API Cielo E-commerce que desejam usar a Risk Notification API precisam contratar este serviço com a Braspag. Para isso, solicite para o canal de chargeback do seu segmento (por e-mail) ou para seu gestor comercial.

Benefícios da Risk Notification API

A Risk Notification API permite:

• Notificação da ocorrência de chargeback na API Transacional (Pagador ou API E-commerce Cielo);
• Consulta de detalhes sobre o chargeback;
• Automatização do processo de notificação, aceitação e disputa;
• Retroalimentação das ocorrências de chargeback para a análise de fraude na Cybersource. **Exclusivo para lojas integradas ao Antifraude Gateway Braspag com o provedor Cybersource.

Glossário

Confira a seguir alguns conceitos básicos sobre chargebacks.

O que é chargeback?

É o processo no qual o portador do cartão contesta uma compra com o emissor do cartão. Essa contestação pode ser feita pelo portador do cartão até 180 dias depois da data da compra.

O chargeback pode ocorrer em transações de e-commerce ou mundo físico, e a loja tem o direito de disputar o chargeback em um fluxo regulamentado pelas bandeiras.

Conheça as orientações da Cielo para Prevenção de Fraudes e Chargeback.

Por que ocorre um chargeback?

Os motivos da ocorrência de chargeback são:

• Fraude: o portador do cartão não reconhece a compra;
• Desacordo comercial: o portador do cartão reconhece a compra, porém alega que algum termo da venda não foi cumprido (mercadoria não entregue ou com defeito, por exemplo);
• Erro de processamento: o portador do cartão identifica algum erro na cobrança (duplicidade, valor cobrado incorretamente, pagamento por outros meios etc.).
  
  

  As transações que passam por autenticação 3DS são de responsabilidade do emissor e, por isso, não podem receber chargeback de fraude.

Notificação de chargeback

Ao integrar o seu e-commerce à Risk Notification API, você pode optar por receber a notificação de chargeback pelo Post de Notificação.

O Post de Notificação é o webhook configurado na API que você usa para as suas transações (Pagador ou API E-commerce Cielo).

Para receber as notificações, você deve informar uma URL de Notificação à nossa equipe de Suporte {:target=”_blank”}. Saiba mais no manual do Pagador ou no manual da API E-commerce Cielo.

• A ativação do Post de Notificação é opcional, mas recomendamos o uso dessa funcionalidade;
  
• O endereço (URL) deve ser HTTPS;
  
• É possível adicionar chaves nos cabeçalhos (headers) como medida de segurança.

Estrutura da notificação do webhook

Enviaremos uma notificação em JSON contendo o PaymentId e o ChangeType com o valor “7”, que indica a ocorrência de chargeback.

{ 
   "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
   "ChangeType": "7" 
}

A notificação de chargeback informa apenas que um chargeback ocorreu e envia o PaymentId da transação. Para saber mais detalhes como valor e motivo do chargeback, faça uma Consulta na Risk Notification API.

Após a consulta, você deve decidir por aceitar ou disputar o chargeback, conforme ilustrado no diagrama a seguir:

Integração

Ambientes

Sandbox

Produção

Para simular um chargeback, você deverá criar uma transação no ambiente sandbox da API do Pagador ou da API E-commerce Cielo; saiba mais em Simulando um Chargeback.

Autenticação

A Risk Notification API utiliza o protocolo padrão de mercado OAuth 2.0 para autorização de acesso a seus recursos específicos por ambientes, Sandbox e Produção.

Obtendo o token de acesso

Durante o onboarding, você receberá as credenciais ClientId e ClientSecret. Caso não tenha recebido a credencial, solicite ao Suporte Braspag.

1. Concatene as credenciais no formato ClientId:ClientSecret;
2. Converta o resultado em base 64, gerando uma string;

Exemplo:

• client_id: braspagtestes
  
• client_secret: 1q2w3e4r5t6y7u8i9o0p0q9w8e7r6t5y4u3i2o1p
  
• String a ser codificada em Base64: braspagtestes:1q2w3e4r5t6y7u8i9o0p0q9w8e7r6t5y4u3i2o1p
  
• Resultado após a codificação: YnJhc3BhZ3Rlc3RlczoxcTJ3M2U0cg==
  

3. Envie a string em base 64 na requisição de Autenticação (POST);
4. A API de Autenticação irá validar a string e retornará o access_token (token de acesso).

O token retornado (access_token) deverá ser utilizado em toda requisição à Risk Notification API como uma chave de autorização. O access_token possui uma validade de 20 minutos e é necessário gerar um novo toda vez que a validade expirar.

Requisição

Parâmetros no Cabeçalho (header)

Parâmetros no Corpo (body)

Resposta

{
  "access_token": "faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw",
  "token_type": "bearer",
  "expires_in": 599
}

Parâmetros no corpo (body)

Simulando um chargeback

Você pode simular um chargeback para testar a consulta, aceitação e disputa de chargebacks.

Para simular chargeback, o primeiro passo é criar uma transação de teste; em seguida, você poderá enviar a requisição de simulação de chargeback. Depois disso, o fluxo segue conforme um chargeback real:

1. Crie uma transação de teste no ambiente sandbox da API transacional usada pela sua loja (API do Pagador ou API E-commerce Cielo);
2. Crie uma simulação de chargeback na Risk Notification API, conforme requisição de simulação;
3. A Risk Notification API informará a ocorrência de chargeback para a API transacional;
4. A API transacional enviará um Post de Notificação com o ChangeType igual a “7”, informando o PaymentId da transação;
5. Faça uma consulta na Risk Notification API usando o PaymentId. A consulta vai retornar o CaseNumber;
6. Você pode decidir se irá testar o fluxo de aceitação ou disputa, seguindo as requisições padrões dessa documentação, em ambiente sandbox. Tanto para a requisição de aceitação quanto de disputa, você deverá informar o CaseNumber recebido na etapa 5.

Requisição

Depois de criar uma transação de teste na API do Pagador ou API E-commerce Cielo, envie a requisição de simulação para criar um chargeback em ambiente sandbox.

Confira a correspondência entre os parâmetros das APIs transacionais e da Risk Notification API:

Importante:

• Para a simulação, você precisa criar um valor fictício para o CaseNumber no parâmetro ChargebackBrandGroups[n].Details[n].AcquirerCaseNumber;
  
• Na simulação de chargeback, use a data da transação em ChargebackBrandGroups[n].Details[n].SaleDate.

{
    "ChargebackBrandGroups": [{
        "Brand": "Visa",
        "Details": [{
            "Acquirer": "Cielo",
            "AcquirerCaseNumber": "2020052301",
            "AcquirerTransactionId": "0523103051968",
            "Amount": 100,
            "AuthorizationCode": "433946",
            "CardHolder": "Teste Holder",
            "EstablishmentCode": "TestAffiliation",
            "MaskedCardNumber": "402400******2931",
            "ReasonCode": "101",
            "ReasonMessage": "Responsabilidade EMV - Falsifcação",
            "SaleDate": "2020-05-23",
            "TransactionAmount": 100,
            "ProofOfSale": "3051968"
        }]
    },
    {
        "Brand": "Master",
        "Details": [{
            "Acquirer": "Cielo",
            "AcquirerCaseNumber": "2020052302",
            "AcquirerTransactionId": "0523103114691",
            "Amount": 100,
            "AuthorizationCode": "722134",
            "CardHolder": "Teste Holder",
            "EstablishmentCode": "TestAffiliation",
            "MaskedCardNumber": "402400******2931",
            "ReasonCode": "101",
            "ReasonMessage": "Responsabilidade EMV - Falsifcação",
            "SaleDate": "2020-05-23",
            "TransactionAmount": 100,
            "ProofOfSale": "3114691"
        }]
    }]
}

Parâmetros no cabeçalho (Header)

Parâmetros no corpo (Body)

Resposta

Consultando um chargeback

Após receber a notificação de chargeback, use o PaymentId para consultar mais detalhes do chargeback, como motivo e valor.

Há dois tipos de consultas:

• Consulta por PaymentId: você deve inserir o PaymentId recebido na notificação;
• Consulta por data ou página: você deve buscar um intervalo de datas ou de páginas e localizar o PaymentId de interesse na lista de resultados.

Consulta por PaymentId

Requisição

Parâmetros no cabeçalho (Header)

Resposta

{
    "Id": "fd14e3fb-cf2a-4228-b690-1338660afc54",
    "CreatedDate": "2022-06-24T20:45:55.2",
    "Date": "2022-06-24T00:00:00",
    "CaseNumber": "000001",
    "Amount": 10000,
    "ReasonCode": "28",
    "ReasonMessage": "Consumidor nao reconhece a compra",
    "Status": "Received",
    "IsFraud": true,
    "Transaction": {
        "AcquirerType": "Cielo",
        "EstablishmentCode": "1234567890",
        "MerchantOrderId": "abc123efg",
        "Tid": "1234567890BA2018XPTO",
        "Nsu": "258654",
        "AuthorizationCode": "T85245",
        "SaleDate": "2022-06-06T00:00:00",
        "PagadorMerchantId": "a1052460-92b2-49c3-a929-fc985df0ba2f",
        "BraspagTransactionId": "bb33b5c5-82fe-4254-9f1d-b9c97297b0d5",
        "Amount": 10000,
        "RawData": "JOAO D SOUZA",
        "MaskedCardNumber": "453906******8385",
        "Brand": "Visa",
        "AntifraudSourceApplication": "Gateway"
    }
}

Consulta por data ou página

Requisição

Parâmetros no cabeçalho (Header)

Parâmetros na querystring

Resposta

{
    "PageIndex": 1,
    "PageSize": 250,
    "Total": 500,
    "Chargebacks":
    [
        {
            "Id": "fd14e3fb-cf2a-4228-b690-1338660afc54",
            "CreatedDate": "2018-09-01 09:51:25",
            "Date": "2018-08-30",
            "CaseNumber": "000001",
            "Amount": 10000,
            "ReasonCode": "28",
            "ReasonMessage": "Consumidor nao reconhece a compra",
            "Status": "Received",
            "Comment": "Cliente enviou documentos inválidos",
            "IsFraud": true,
            "Transaction":
            {
                "AcquirerType": "Cielo",
                "EstablishmentCode": "1234567890",
                "MerchantOrderId": "abc123efg",
                "Tid": "1234567890BA2018XPTO",
                "Nsu": "258654",
                "AuthorizationCode": "T85245",
                "SaleDate": "2018-08-15",
                "PagadorMerchantId": "a1052460-92b2-49c3-a929-fc985df0ba2f",
                "BraspagTransactionId": "bb33b5c5-82fe-4254-9f1d-b9c97297b0d5",
                "Amount": 10000,
                "RawData": "JOAO D COUVES",
                "MaskedCardNumber": "453906******8385",
                "Brand": "Visa",
                "AntifraudMerchantId": "4b1b017a-a8b5-4e83-ae36-19c69f11845e",
                "AntifraudTransactionId": "9f6ec028-b55d-4605-b655-164ce62aeaef",
                "AntifraudSourceApplication": "Gateway",
                "ProviderTransactionId": "5446494501496896403073",
                "NegativeValues": [
                    "CustomerDocumentNumber",
                    "ShippingStreet"
                ], 
                "ProviderChargebackMarkingEvent": {
                    "Id": "5446495589216876903021",
                    "Status": "ACCEPT",
                    "Code": "100",
                }
            }
        }
    ]
}

Aceitando um chargeback

A funcionalidade de aceitar um chargeback está disponível para lojas que desejam:

• Sinalizar para a Cielo que não disputarão o chargeback e, assim, antecipar em alguns dias o débito do chargeback;
• Criar regras para aceitação automática de determinados tipos de chargeback, conforme ReasonCode e valor, por exemplo.

Confira no diagrama a seguir o fluxo da aceitação de um chargeback:

Requisição

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Resposta

{
    "CaseNumber": "000001",
    "Status": 2,
    "StatusDescription": "AcceptedByMerchant"
}

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Disputando um chargeback

Para disputar um chargeback via API, você deve enviar os documentos de defesa em até 7 dias corridos a partir da data do chargeback.

Quais documentos são enviados para disputa?

Depende do segmento de mercado e do motivo do chargeback. É possível enviar contratos e comprovantes de entrega assinados, comprovante de cancelamento ou reembolso da venda e cartões de embarque, entre outros.

Confira nos anexos a lista completa de documentos de defesa por segmento.

Como enviar os documentos de disputa via API?

Você deve converter os arquivos dos documentos em imagem ou PDF para base64 e enviar o código base64 na requisição de Disputa.

Qual o tipo e tamanho máximo dos arquivos?

• As extensões permitidas são .pdf, .png, .jpg ou .jpeg convertidos em base64 (encoded);
• A soma de todos os arquivos deve ter no máximo 7MB de tamanho. A Risk Notification API encaminhará a documentação para a Cielo, que submeterá a disputa para análise da bandeira e do emissor.

Importante:

• O envio da documentação para disputa não garante que não ocorrerá débito do chargeback na agenda financeira. Os documentos são o requisito mínimo estipulado pelas bandeiras para negociação;
  
• Quando o prazo para envio da disputa expira o chargeback é automaticamente considerado aceito.

Consulte sua agenda financeira para acompanhar o resultado da disputa.

Confira no diagrama a seguir o fluxo da disputa de um chargeback:

Requisição

{
    "Files":
    [{
        "FileName": "file1.png",
        "Content": "asdfghjkle ********** lkjhgfdsa"
    },
    {
        "FileName": "file2.jpg",
        "Content": "zxcvbnmasd ********** qwertyuio"
    },
    {
        "FileName": "file3.jpg",
        "Content": "qwertyuiop ********** asdfghjkl"
    }]
}

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Parâmetros no corpo (Body)

Resposta

Parâmetros no cabeçalho (Header)

Erros de integração

Erros na aceitação ou disputa de chargeback

Confira as respostas possíveis para os seguintes cenários de erros no envio da requisição de aceitação ou disputa:

• Chargeback inexistente: o CaseNumber não existe;
• Chargeback repetido: o CaseNumber já foi aceito ou disputado anteriormente.

Chargeback inexistente

Ocorre quando o CaseNumber informado não existe.

{
    "Code": "ChargebackNotFounded",
    "Message": "Chargeback not found"
}

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Chargeback repetido

Ocorre quando o CaseNumber informado já foi aceito ou disputado anteriormente.

{
    "Code": "ChargebackAlreadyUpdated",
    "Message": "Chargeback already updated"
}

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Erros na disputa de chargeback

Arquivo de disputa não enviado

Ocorre quando a requisição de disputa é enviada sem o nome e/ou conteúdo do arquivo.

{
    "Message": "The request is invalid.",
    "ModelState": {
        "contestationRequest.Files[0].FileName": [
        "FileName can not be null or empty."
    ],
    "contestationRequest.Files[0].Content": [
        "Content can not be null or empty."
    ]}
}

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Arquivo com extensão inválida

O arquivo de contestação deve ter extensão .jpeg, .jpg, .png ou .pdf. Caso a extensão do arquivo enviado seja diferente das mencionadas, o retorno será o erro a seguir:

{
    "Message": "The request is invalid.",
    "ModelState": {
    "contestationRequest.Files[0].FileName": [
        "The file extension must be sent. The accepted extensions are: '.png', '.jpg', '.jpeg'"
    ]}
}

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Arquivo com tamanho acima do permitido

Ocorre quando o arquivo enviado ou a soma dos arquivos enviados for superior à 7MB.

Mensagem para arquivo superior à 7MB

{
    "Message": "File(s) file1.png, file2.png has length bigger than the size limit of 7MB."
}

Mensagem para soma de arquivos superior à 7MB

{
    "Message": "Files has length bigger than the size limit of 7MB.",
}

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Tabelas

Tabela 1 - Lista Negativa da Cybersource

Valores que podem ser retornados na lista negativa da Cybersource para retroalimentação de chargeback. Esses valores são retornados na resposta da consulta, no campo Chargebacks.Transaction.NegativeValues.

Válidos apenas para clientes integrados à API Antifraude Gateway com a Cybersource como provedor do Antifraude.

Tabela 2 - Status do chargeback

Possíveis valores do chargeback retornados no campo Chargebacks.Status na Consulta.

Tabela 3 - Marcação de chargeback no provedor de Antifraude

Quando há tentativa de retroalimentação de chargeback na Cybersource, este provedor de Antifraude retorna se a marcação de chargeback foi aceita ou não.

O resultado da marcação retorna na resposta da Consulta, no campo Chargebacks[n].Transaction.ProviderChargebackMarkingEvent.Status.

Tabela 4 - API de Antifraude

Indica qual é a API de Antifraude usada pela loja. Os valores são retornados na resposta da Consulta, no campo Chargebacks[n].Transaction.AntifraudSourceApplication.

Tabela 5 - Motivo do chargeback

A tabela a seguir apresenta o ReasonCode e o ReasonMessage retornados na resposta da Consulta de Chargeback, e que compõem o motivo do chargeback.

Documentos para disputa