Visão Geral

Risk Notification API foi desenvolvida pelo time de Risco da Braspag para os que clientes possam consultar alertas de fraudes, chargebacks, realizar envio de arquivos para contestação de chargebacks e acatar chargebacks.

A API é baseada em arquitetura REST, que trocam dados em formato JSON seguindo fluxos de autorização definidos pelo protocolo OAuth 2, onde todos os padrões são amplamente utilizados pelo mercado e suportado pelas comunidades técnicas.

Para saber mais sobre OAuth 2, consulte https://oauth.net/2/

Objetivo

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a Risk Notification API, descrevendo as operações disponíveis com exemplos de requisições e respostas.

Para executar uma operação, combine o endpoint base do ambiente com o endpoint da operação desejada e envie utilizando o VERBO HTTP conforme descrito na operação.

Hosts

BraspagAuth API

Risk Notification API

Autenticação

Tokens de Acesso

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, que são: Sandbox e Produção.

Esta sessão descreve o fluxo necessário para que aplicações cliente obtenham tokens de acesso válidos para uso na API.

Obtenção do token de acesso

O token de acesso é obtido através do fluxo oauth client_credentials. O diagrama abaixo, ilustra, em ordem cronológica, a comunicação que se dá entre a Aplicação Cliente, a API BraspagAuth e a Risk Notification API.

1. A Aplicação Cliente, informa à API BraspagAuth sua credencial.

2. O BraspagAuth valida a credencial recebida. Se for válida, retorna o token de acesso para a Aplicação Cliente.

3. A Aplicação Cliente informa o token de acesso no cabeçalho das requisições HTTP feitas à Risk Notification API.

4. Se o token de acesso for válido, a requisição é processada e os dados são retornados para a Aplicação Cliente.

Solicite uma credencial abrindo um ticket através da nossa ferramenta de suporte, enviando o(s) IP(s) de saída dos seus servidores de homologação e produção. Suporte Braspag

Como obter o token

Uma vez em posse da credencial, será necessário “codificá-la” em Base64, utilizando a convenção client_id:client_secret, e enviar o resultado no cabeçalho através do campo Authorization.

Exemplo:

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

Request

Parâmetros no cabeçalho (Header)

Parâmetros no corpo (Body)

Response

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

Parâmetros no corpo (Body)

Simulando Chargeback

Através desta opção será possível você criar chargeback para as transações apenas no ambiente de sandbox. Para isso, realizar um POST de acordo com as orientações abaixo.

Request

Parâmetros no cabeçalho (Header)

{
    "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"
        }]
    }]
}

Response

Aceitação

Aceitando um chargeback

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Aceitando um chargeback inexistente

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Aceitando um chargeback aceito anteriormente

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Contestação

Contestando um chargeback

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

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Parâmetros no corpo (Body)

Response

Parâmetros no cabeçalho (Header)

Contestando um chargeback inexistente

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Contestando um chargeback contestado anteriormente

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Contestando um chargeback e não enviando o arquivo de contestação

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

{
    "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)

Contestando um chargeback enviando o arquivo de contestação com extensão diferente de jpeg, pfg ou png

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

{
    "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)

Contestando um chargeback enviando arquivo(s) para contestação com tamanho maior que 7mb

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Contestando um chargeback enviando arquivos e a soma do tamanho de todos é maior que 7mb

Request

Parâmetros no cabeçalho (Header)

Parâmetros na rota

Response

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

Parâmetros no cabeçalho (Header)

Parâmetros no body (Corpo)

Consultas

Request

Parâmetros no cabeçalho (Header)

Parâmetros na querystring

Response

{
    "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",
                }
            }
        }
    ]
}

Tabelas

Tabela 1 - Chargebacks[n].NegativeValues

Possíveis valores a serem inseridos na lista negativa na Cybersource.

Tabela 2 - Result.ProcessingStatus

Possíveis retornos do chargeback enviado.

Tabela 3 - Chargebacks[n].Status

Possíveis valores do chargeback.

Tabela 4 - Chargebacks[n].Transaction.ProviderChargebackMarkingEvent.Status

Tabela 5 - Chargebacks[n].Transaction.ProviderChargebackMarkingEvent.Code

Tabela 6 - Chargebacks[n].Transaction.AntifraudSourceApplication

Tabela 7 - ReasonCode e ReasonMessage

Matriz

Matriz 1 - Documentos