Powered by Redocly

SECHUB (v9.0)

Download OpenAPI specification:Download

Versão: 9.0

Contato: Centro de Excelência Clientes

O responsável deve ser contatado nos casos de:

  • Dúvidas sobre as informações tratadas neste documento;
  • Falhas ou vulnerabilidades encontradas no processo;
  • Necessidade de adequação identificada internamente, apresentada por auditoria, por órgão regulador ou por cliente.

Vigência: 02/06/2023 a 02/06/2025

Este manual deverá ser revisto periodicamente, quando do vencimento de sua vigência, ou quando necessário.

Histórico de atualização

Clique aqui para acessar o histórico de atualização deste documento

Ciclo de revisão

Este documento será revisto e atualizado quando:

  • Houver solicitação de atendimento, correção ou adição de informações;
  • Existir a necessidade de atender requisitos legais, boas práticas ou recomendações de auditoria;
  • Existir mudança na organização que tenha impacto relevante na atividade abordada neste documento;
  • No vencimento, conforme item HISTÓRICO DE ATUALIZAÇÃO deste documento.

Guarda e retenção

As versões deste documento deverão ser armazenadas por cinco anos, após o vencimento de seu prazo de validade.

Classificação da Segurança

Este documento é de livre acesso para consulta e só há garantias da integridade de seu conteúdo quando obtido da NUCLEA, a qual, como proprietária do documento, possui todos os direitos de elaboração, reprodução e distribuição em caráter exclusivo. A NUCLEA não se responsabiliza por versões desatualizadas, modificadas por qualquer circunstância ou provenientes de outras fontes que não a fonte oficial designada para fornecer este material.

SECHUB - Antifraude para Pagamentos Instantâneos

Introdução

O objetivo deste documento é apresentar as especificações técnicas e homologatórias do SECHUB - Antifraude para Pagamentos Instantâneos, solução desenvolvida e operada pela NUCLEA que tem o objetivo de auxiliar na avaliação, pelos Participantes, da confiabilidade de informações relacionadas aos usuários finais do PIX, buscando mitigar o risco de fraude em transações no âmbito do PIX.

A plataforma foi elaborada para ser utilizada pelo ecossistema de pagamentos instantâneos brasileiro como um todo, utilizando um conceito de base compartilhada. Quanto mais participantes estiverem integrados à solução, mais seguro será o sistema. Ao mesmo tempo, permite autonomia e controle total dos participantes terem sua própria gestão de risco, recebendo os melhores insumos para tomada de decisão.

Descrição do Produto

O SECHUB - Antifraude para Pagamentos Instantâneos foi desenvolvido exclusivamente para auxiliar os Participantes na avaliação, por eles, da confiabilidade de informações relacionadas aos processos de validação de cadastro no DICT, análise transacional e retroalimentação de fraude.

Nos fluxos de validação de cadastro no DICT e transação no PIX, o participante deve incorporar os retornos das chamadas de API às suas próprias regras internas de validação. Com isso terá todos os insumos e informações mais recentes para tomada de decisão, podendo tomar ações diferentes para níveis de riscos baixo, médio e alto.

Considerando o conjunto de dados recebidos, e também, as informações de Behavior Analytics (Device Fingerprint), garante velocidade de resposta e celeridade do processo para entregar pouca fricção na avaliação da identidade no momento do cadastro/ manutenção de chaves no DICT e avaliação do risco no processo transacional do Pix, tanto na transferência entre contas pix como nos pagamentos usando QR Codes.

Os serviços de Informação de risco de cadastro no DICT e transações PIX retornam em tempo real o nível de risco, força do vínculo de todas as duplas de dados recebidos e Insights que auxiliam a tomada de decisão, possibilitando que as instituições/ participantes do Arranjo Pix utilizem as informações adicionais em seus scores próprios ou criem regras no motor de decisão.

Os serviços de retroalimentação alimentam o nosso Data Lake, sendo que o nosso serviço está em constante ajuste para enriquecer o retorno de forma que gere mais insumos para a tomada de decisão do Participante, considerando as novas fraudes identificadas.

A funcionalidade adicional 2FA auxilia nas chamadas em que há necessidade de uma camada adicional de segurança para prevenção de fraudes tanto no cadastro das chaves no DICT como transações PIX dos usuários.

Fluxo de Utilização

Abaixo segue o Fluxo de Utilização onde o SECHUB - Antifraude para Pagamentos Instantâneos é utilizado pela Instituição Pagadora na análise antes da confirmação para envio ao Banco Central.

Fluxo de Utilização

O SECHUB - Antifraude para Pagamentos Instantâneos também poderá ser utilizado pela Instituição Recebedora, de modo que assim que receba a transação ou uma notificação de infração chamará a solução para auxiliar na decisão se será feito o crédito em conta ou o bloqueio, conforme fluxo abaixo.

Fluxo de Utilização

Segurança

Autenticação

Todas as requisições submetidas à nossa API devem ser realizadas através de um token gerado através de um usuário, senha e id da entidade que devem ser fornecidos pela NUCLEA.

Na autenticação, além do token retornamos seu tempo de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração. Só gere um novo token após a expiração do seu token atual.

O acesso aos serviços é feito através de API REST, usando padrões de mercado seguros.

Evolução do Produto

O produto está em constante evolução e está sujeito às mudanças relacionadas abaixo:

  • Inclusão de novos insights;
  • Inclusão de novos parâmetros opcionais;
  • Inclusão de novos campos no retorno da API;
  • Inclusão de novos valores nos campos de domínio.

Estas mudanças serão comunicadas pela nossa equipe de Soluções e Apoio ao Participante, mas é importante que estejam preparados para estas mudanças de forma que não gerem erros nas suas aplicações.

Componentes da Solução

Behavior Analytics

É uma ferramenta de identificação de dispositivos (também conhecida como Device Fingerprint e Behavior Analytics). Através desse recurso é possível identificar se o dispositivo utilizado no momento da transação já é conhecido pela ClearSale e qual o seu histórico de ações.

Para completa utilização da solução, é necessário que o Behavior Analytics esteja integrado no ato da captura dos dados.

O Behavior Analytics não é obrigatório, mas recomendamos a utilização para a contribuição ao enriquecimento das informações retornadas pelo produto.

Para maiores informações sobre as configurações do Behavior Analytics como também o acesso à documentação técnica para cada plataforma, clique aqui.

Funcionalidades Disponíveis

Abaixo seguem as funcionalidades disponíveis para utilização no Serviço Antifraude para Pagamentos Instantâneos:

  • API001: Informação de risco para cadastros no DICT
  • API002: Informação de risco para transações PIX - Instituição Pagadora
  • API003: Retroalimentação de cadastros no DICT
  • API004: Retroalimentação de transações PIX - Instituição Pagadora
  • API005: Retroalimentação de indicadores de fraude
  • API009: Informação de risco para transações PIX - Instituição Recebedora

Fluxo das Funcionalidades

API001 – Informação de risco para cadastros no DICT

Serviço destinado a retornar insumos para o Participante para auxiliar na tomada de decisão com relação às chaves do DICT.

Recebe como entrada um conjunto de dados composto de CPF, e-mail, celular, CEP e o dispositivo capturado por meio do Behavior Analytics (Device Fingerprint), realiza a análise na base de dados e retorna em tempo real:

  • Id: Identificador da consulta, podendo ser utilizado para posterior consulta dos dados retornados.
  • Score: nível de risco que varia de 0,00 a 100,00% e se refere à propensão do pedido em questão ser uma tentativa de fraude. Quanto menor o Nível de risco, menos chance de fraude, possuindo precisão de duas casas decimais
  • Ratings: classificação sobre a força do vínculo de todas as duplas de dados recebidos, podendo ser 0-Inexistente 1-Baixo, 2-Médio ou 3-Alto (ex: CPF com celular, CPF com email, etc);
  • Insights: informações adicionais sobre os dados informados, como por exemplo alertas sobre os dados recebidos (CPF, celular, Email e device).

Os campos relacionados ao telefone, e-mail e EVP serão obrigatórios somente se forem o tipo de chave da transação DICT informada (keyType), mas é importante salientar que a precisão nos dados retornados será maior se todos os campos forem informados.

API002 – Informação de risco para transações PIX

Serviço destinado a retornar insumos para o Participante para auxiliar na tomada de decisão com relação às transações do PIX.

Recebe como entrada um conjunto de dados como canal utilizado, QR Code, URL link, dados do remetente, dados do recebedor, moeda e valor, realiza a análise na base de dados e retorna em tempo real:

  • Id: Identificador da consulta, podendo ser utilizado para posterior consulta dos dados retornados.
  • Score: nível de risco que varia de 0,00 a 100,00% e se refere à propensão do pedido em questão ser uma tentativa de fraude. Quanto menor o Nível de risco, menos chance de fraude, possuindo precisão de duas casas decimais
  • Ratings: classificação sobre a força do vínculo de todas as duplas de dados recebidos, podendo ser 0-Inexistente 1-Baixo, 2-Médio ou 3-Alto (ex: CPF com celular, CPF com email, etc);
  • Insights: informações adicionais sobre os dados informados, como por exemplo vínculo entre o remetente e recebedor e alertas de fraude.

API003 – Retroalimentação de cadastros no DICT

Serviço destinado ao Participante para somente enviar dados de cadastro no DICT sem consultar, esta requisição não será tarifada.

Caso seja processada com sucesso será retornado o campo Id da transação, esta informação é importante pois identificará o registro efetuado.

API004 – Retroalimentação de transações PIX

Serviço destinado ao Participante para somente enviar dados de transações PIX sem consultar, esta requisição não será tarifada.

Caso seja processada com sucesso será retornado o campo Id da transação, esta informação é importante pois identificará o registro efetuado.

API005 – Retroalimentação de indicadores de fraude

Serviço destinado ao Participante para somente enviar dados de fraude sem consultar, esta requisição não será tarifada.

Caso seja processada com sucesso será retornado o campo Id da transação, esta informação é importante pois identificará o registro efetuado.

API009 – Informação de risco para transações PIX - Instituição Recebedora

Serviço destinado a retornar insumos para o Participante atuando como Instituição Recebedora para auxiliar na tomada de decisão com relação às transações do PIX.

Recebe como entrada um conjunto de dados como dados do pagador, dados do recebedor, moeda e valor, realiza a análise na base de dados e retorna em tempo real:

  • Id: Identificador da consulta, podendo ser utilizado para posterior consulta dos dados retornados.
  • Score: nível de risco que varia de 0,00 a 100,00% e se refere à propensão do pedido em questão ser uma tentativa de fraude. Quanto menor o Nível de risco, menos chance de fraude, possuindo precisão de duas casas decimais
  • Ratings: classificação sobre a força do vínculo de todas as duplas de dados recebidos, podendo ser 0-Inexistente 1-Baixo, 2-Médio ou 3-Alto (ex: CPF com celular, CPF com email, etc);
  • Insights: informações adicionais sobre os dados informados, como por exemplo vínculo entre o remetente e recebedor e alertas de fraude.

Lista de insights

API001 - Clique aqui para baixar a lista completa de insights

API002 e API009 - Clique aqui para baixar a lista completa de insights

Adicionais da Solução

API006 - 2FA

O 2FA é uma camada extra de segurança onde é enviado um SMS para o principal telefone da pessoa para confirmar o cadastro ou transação realizada.

Esta funcionalidade contempla o envio do SMS somente para pessoa física através do CPF informado e desde que o telefone principal desta pessoa esteja cadastrado nas nossas bases.

Após o envio da solicitação é retornado o Id Transação que pode ser utilizado para consulta do status da mesma.

Fluxo 2FA

Quando a mensagem for respondida pelo usuário ou não foi encontrado o principal telefone da pessoa (HotPhone), o webhook enviará uma notificação com o Id Transação para uma URL que deverá ser implementada no lado do Participante.

Os dados da resposta não serão informadas na notificação do webhook, ficará a cargo do Participante o consumo da consulta através do Id Transação informado.

Webhook

Durante a fase de configuração (setup) da solução do 2FA, o participante poderá nos informar uma URL de API para realizar um requisição POST, para informá-lo no momento em que houver a resposta do SMS ou caso não seja encontrado o HotPhone do usuário.

A utilização do webhook é um facilitador, pois o participante não precisa ficar pesquisando pela resposta a todo momento.

  • Para fins de segurança, a chamada POST deve ser feita em protocolo HTTPS;

  • É possível realizar o cadastro de um BEARER TOKEN para ser enviado no Header da requisição no caso de ambientes protegidos. Esta opção é opcional no cadastro do webhook, porém por questão de segurança recomendamos que o token seja informado e que também seja utilizado o protocolo HTTPS. Segue abaixo exemplo de header:

    {

    "content-length": "34",

    "authorization": "Bearer mock-token-secret",

    "request-context": "appId=cid-v1:3c97b085-04de-446f-bcf6-4a43f63b4f49",

    "request-id": "|75f4777f5533df41996547cda1523b09.b140cabc7f4cde40.",

    "traceparent": "00-75f4777f5533df41996547cda1523b09-b140cabc7f4cde40-00",

    "accept-encoding": "gzip, deflate",

    "content-type": "application/json; charset=UTF-8"

    }

Texto SMS

  • O texto compartilhado com o usuário final deve conter no máximo 160 caracteres;

  • Para ambos os fluxos de onboarding e transacional, é possível cadastrar uma única pergunta. Segue exemplo abaixo:

    Olá, {nome}. Você cadastrou uma chave ou realizou alguma transação PIX no {nome-do-participante}. Responda grátis:

    1 para sim

    2 para não

    3 para não sou {primeiro-nome}

    Chave Descrição Obrigatoriedade Tamanho Máximo
    {nome} Primeiro e último nome do usuário Opcional 20 caracteres
    {primeiro-nome} Primeiro nome do usuário Opcional 10 caracteres
    {nome-do-participante} Nome do Participante Opcional 30 caracteres

Fluxo para Integração

Fluxo para Integração

Homologação

Pré-requisitos

  • Adesão aos serviços;
  • Envio dos documentos de Matriz de Funcionalidades, Cadastro de Contatos e Cadastro Técnico para o e-mail homologacao@nuclea.com.br;
  • Após os requisitos acima devidamente atendidos e validados, a NUCLEA enviará o usuário e senha para acesso.

Hostname Homologação

https://afpi-hmg.sec-hub.com.br

Cenários de homologação

Recomendamos não enviar dados produtivos nos testes do ambiente de homologação. Os dados retornados no ambiente de homologação são aleatórios e fictícios.

API001 – Informação de risco para cadastros no DICT - Clique aqui para baixar a lista sugerida de cenários para teste. Nos cenários serão modificados apenas os campos que constam na lista. Se não houver erro, a resposta dessa requisição retornará o código 201 com os campos Score, Ratings e Insight conforme definido na planiha de cenários.

Produção

Hostname Produção

https://afpi.sec-hub.com.br

Tratamento de erros

401 - Não autorizado

Possíveis problemas: erro ao autenticar a requisição. Consulte o valor do token.

400 - BadRequest

Possíveis problemas: verifique se algum campo no corpo da requisição não está preenchido.

500 Internal Server Error

Possíveis problemas: algum tipo de problema está afetando o desempenho do servidor que você está tentando acessar.

SLA

Disponibilidade

A NUCLEA garante uma disponibilidade do Software Antifraude para Pagamentos Instantâneos (AFPI) de 98% (noventa e oito por cento) ao mês.

AFPI - Tempo de Resposta (apuração mensal)

Entende-se por tempo de resposta: Tempo dispendido entre o recebimento de uma requisição e envio da resposta.

Inicia-se assim que a mensagem é recebida pelo sistema na internet e é cessada assim que a mensagem de resposta deixa a plataforma.

98% das respostas até 2 segundos.

Adicional 2FA

Envio da mensagem SMS em até 60 segundos após a solicitação, desde que o telefone principal da pessoa esteja cadastrado na nossa base. Inicia-se assim que a solicitação é recebida pelo sistema na internet e é cessada assim que a mensagem de SMS deixa a plataforma.

Notificação via webhook da resposta do usuário em até 60 segundos após recebimento do SMS. Inicia-se assim que a resposta do usuário é recebida pelo sistema na internet e é cessada assim que a notificação via webhook deixa a plataforma.

Obs.: No SLA não está sendo computado manutenções preventivas programadas e informadas previamente.

Authentication

Bearer

Enter 'Bearer' [space] and then your token in the text input below.

Example: "Bearer abcd1234"

Security Scheme Type API Key
Header parameter name: Authorization

Autenticação

Todas as requisições submetidas à nossa API devém ser realizadas através de um token gerado através de um usuário, senha e id da entidade que devem ser fornecidos pela NUCLEA.

Requisição para geração de token

Na autenticação, além do token retornamos seu tempo de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração.

Request Body schema:
application/json
application/json
text/json
application/*+json
username
required
string [ 1 .. 100 ] characters

Usuário para autenticação da API.

password
required
string [ 1 .. 100 ] characters

Senha para autenticação da API.

Responses

Request samples

Content type
application/json
application/json
text/json
application/*+json
{
  • "username": "******",
  • "password": "******"
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "token": "8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD8sgbian0ii1TfP7GDrJVJtMAu0TdtdJD",
  "expiresInMinutes": 1440
}

API001 - Informação de risco para cadastros no DICT

A solução SECHUB mensura o nível de risco durante a inclusão, portabilidade ou reivindicação de um registro no DICT.

Informação de risco para cadastros no DICT

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
reason
required
string non-empty

Razões para entrada, é o mesmo campo enviado para a transaçao DICT pelo participante, valores válidos: [USER_REQUESTED,ACCOUNT_CLOSURE,BRANCH_TRANSFER,ENTRY_INACTIVITY,RECONCILIATION].

Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "ENTRY_INACTIVITY" "RECONCILIATION"
requestId
string 36 characters

Esse campo é um UUID versão 4 e deve ser único no contexto de um mesmo participante, é o mesmo campo enviado para a transaçao DICT pelo participante

name
required
string [ 1 .. 200 ] characters

Nome da pessoa ou da organização. Deve ser o mesmo valor utilizado nas transações da DICT no objeto de Proprietário.

document
required
string [ 11 .. 14 ] characters ^([0-9]{11}|[0-9]{14})$

Número do documento, somente números, padrões: [CPF]: "^[0-9]{11}$" | [CNPJ]: "^[0-9]{14}$".

documentType
required
string non-empty

Tipo do documento, opções disponíveis: [CPF,CNPJ].

Enum: "CPF" "CNPJ"
object (PhoneDto)

Objeto telefone.

email
string <= 77 characters Nullable ^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9...

Conta de e-mail.

verifiedEmail
required
boolean

Conta de e-mail foi verificada. Valor default é false.

object (AddressDto)

Address object.

evp
string Nullable

EVP gerado e utilizado para transações DICT.

keyType
required
string non-empty

Tipo da chave da transação DICT, opções disponíveis: [CPF,CNPJ,PHONE,EMAIL,EVP].

Enum: "CPF" "CNPJ" "PHONE" "EMAIL" "EVP"
required
object (AccountDto)

Informações do objeto de Conta bancária.

referenceDate
required
string <date-time>

Data e hora da transação UTC.

sessionId
string Nullable

Valor de SessionId usado na integração de análise de comportamento, valor entre 5 e 128 caracteres.

fingerprintVariables
any Nullable

Fingerprint variables information key-value json object.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "reason": "USER_REQUESTED",
  • "requestId": "1a2bdcb0-c8a8-464e-929d-6c93f8a2a143",
  • "name": "Fulano de Tal",
  • "document": "18356615801",
  • "documentType": "CPF",
  • "phone": {
    },
  • "email": "fulano.tal@email.com.br",
  • "verifiedEmail": false,
  • "address": {
    },
  • "evp": "",
  • "keyType": "EMAIL",
  • "account": {
    },
  • "referenceDate": "2021-05-07T19:52:11.772736Z",
  • "sessionId": "mysessionid-4-d3v1c3",
  • "fingerprintVariables": ""
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "ab979ac2c7a24c6eb11ad10f61f39438",
  "score": {
    "value": 90.23,
    "date": "2020-10-29T18:25:59.9019747Z"
  },
  "ratings": [
    {
      "value": 3,
      "relatedTo": [
        "Document",
        "Phone"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Document",
        "Email"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Device"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Phone",
        "Email"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Phone",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Phone",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Email",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Email",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "ZipCode",
        "Device"
      ]
    }
  ],
  "insights": [
    {
      "code": "2134",
      "description": "O CPF informado foi visto pela última vez entre 3 e 6 meses."
    },
    {
      "code": "2015",
      "description": "O Telefone informado foi visto pela primeira vez entre 6 meses e 1 ano."
    },
    {
      "code": "109",
      "description": "A dupla CPF + Telefone informada foi vista pela última vez há menos de 1 mês."
    }
  ]
}

Retorna informação de risco para cadastros no DICT por id

Authorizations:
Bearer
path Parameters
id
required
string Nullable

Responses

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "ab979ac2c7a24c6eb11ad10f61f39438",
  "score": {
    "value": 90.23,
    "date": "2021-05-07T19:52:11.8032355Z"
  },
  "ratings": [
    {
      "value": 3,
      "relatedTo": [
        "Document",
        "Phone"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Document",
        "Email"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Device"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Phone",
        "Email"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Phone",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Phone",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Email",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Email",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "ZipCode",
        "Device"
      ]
    }
  ],
  "insights": [
    {
      "code": "2134",
      "description": "O CPF informado foi visto pela última vez entre 3 e 6 meses."
    },
    {
      "code": "2015",
      "description": "O Telefone informado foi visto pela primeira vez entre 6 meses e 1 ano."
    },
    {
      "code": "109",
      "description": "A dupla CPF + Telefone informada foi vista pela última vez há menos de 1 mês."
    }
  ]
}

API002 – Informação de risco para transações PIX

A solução SECHUB mensura o nível de risco de uma transação PIX. Esta requisição deve ser feita antes de se incluir a transação no SPI, de modo que viabilize uma ação do participante

Informação de risco para transação PIX

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
transactionType
string Nullable

Tipo da mensagem usada na transação SPI, e.g.: "PACS.008", "PACS.004".

Enum: "PACS.008" "PACS.004"
endToEndId
string <= 50 characters Nullable

Identificação única atribuída pela parte iniciadora a identificar inequivocamente a transação, mesmo valor usado no nas mensagens PACS.008 e PACS.004

txId
string <= 50 characters Nullable

Identificação de transação usada em mensagens PACS para SPI nas transações PIX por QRCode ou Link.

channel
required
string non-empty

Canal de origem da transação, opções disponíveis: "WEB", "MOBILE" and "AGENCY".

Enum: "WEB" "MOBILE" "AGENCY"
object (QrCodeDto)
object (UrlLinkDto)
required
object (RecipientDto)
required
object (SenderDto)
currency
required
string [ 1 .. 50 ] characters

Moeda usada na transferência.

amount
required
number <double> non-empty > 0

Valor da transferência.

referenceDate
required
string <date-time>

Data e hora da transação.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "transactionType": "PACS.008",
  • "endToEndId": "E9999901012341234123412345678900",
  • "txId": "90000",
  • "channel": "WEB",
  • "qrCode": {},
  • "urlLink": {},
  • "recipient": {
    },
  • "sender": {
    },
  • "currency": "BRL",
  • "amount": 110.55,
  • "referenceDate": "2021-11-17T22:32:08.1319258Z"
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "e08bbca0-024f-4b61-8849-112e72c404de",
  "score": {
    "value": 44.76,
    "date": "2021-11-17T22:32:08.132322Z"
  },
  "ratings": [
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Phone"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Document",
        "ZipCode"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Email"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Device"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Phone",
        "Email"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Phone",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Phone",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Email",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Email",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "ZipCode",
        "Device"
      ]
    }
  ],
  "insights": [
    {
      "code": "117",
      "description": "Dupla CPF + Telefone vista em diversos segmentos"
    },
    {
      "code": "316",
      "description": "Dupla CPF + CEP com alta frequência de utilização em transações positivas"
    },
    {
      "code": "117",
      "description": "Dupla CPF + Telefone vista em diversos segmentos"
    }
  ]
}

Retorna informação de transação por id

Authorizations:
Bearer
path Parameters
id
required
string Nullable

Responses

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "79ac2c7a2fc44c6eb11ad10f61f39438",
  "score": {
    "value": 85.5,
    "date": "2021-11-17T22:32:08.140732+00:00"
  },
  "ratings": [
    {
      "value": 3,
      "relatedTo": [
        "Document",
        "Phone"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Document",
        "Email"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Device"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Phone",
        "Email"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Phone",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Phone",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Email",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Email",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "ZipCode",
        "Device"
      ]
    }
  ],
  "insights": [
    {
      "code": "2134",
      "description": "O CPF informado foi visto pela última vez entre 3 e 6 meses."
    },
    {
      "code": "2015",
      "description": "O Telefone informado foi visto pela primeira vez entre 6 meses e 1 ano."
    },
    {
      "code": "109",
      "description": "A dupla CPF + Telefone informada foi vista pela última vez há menos de 1 mês."
    }
  ]
}

API009 – Informação de risco para transações PIX - Instituição Recebedora

A solução SECHUB mensura o nível de risco de uma transação PIX. Esta requisição deve ser feita quando do recebimento de uma transação do SPI, de modo que viabilize uma ação do participante atuando como Instituição Recebedora.

Informação de risco para transação PIX - Instituição Recebedora

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
transactionType
required
string non-empty

Tipo da mensagem usada na transação SPI, e.g.: "PACS.008", "PACS.004".

Enum: "PACS.008" "PACS.004"
endToEndId
required
string [ 1 .. 50 ] characters

Identificação única atribuída pela parte iniciadora a identificar inequivocamente a transação, mesmo valor usado no nas mensagens PACS.008 e PACS.004.

txId
string <= 50 characters Nullable

Identificação de transação usada em mensagens PACS para SPI nas transações PIX por QRCode ou Link.

required
object (RecipientReceiverDto)
required
object (SenderReceiverDto)
currency
required
string [ 1 .. 50 ] characters

Moeda usada na transação.

amount
required
number <double> non-empty > 0

Valor da transação.

referenceDate
required
string <date-time>

Data e hora da transação.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "transactionType": "PACS.008",
  • "endToEndId": "E9999901012341234123412345678900",
  • "txId": "90000",
  • "recipient": {
    },
  • "sender": {
    },
  • "currency": "BRL",
  • "amount": 110.55,
  • "referenceDate": "2021-12-29T18:34:03.3621786Z"
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "e08bbca0024f4b618849112e72c404de",
  "score": {
    "value": 44.76,
    "date": "2021-12-29T18:34:03.3625827Z"
  },
  "ratings": [
    {
      "value": 3,
      "relatedTo": [
        "Document",
        "Phone"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Document",
        "Email"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Device"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Phone",
        "Email"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Phone",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Phone",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Email",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Email",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "ZipCode",
        "Device"
      ]
    }
  ],
  "insights": [
    {
      "code": "117",
      "description": "Dupla CPF + Telefone vista em diversos segmentos"
    },
    {
      "code": "316",
      "description": "Dupla CPF + CEP com alta frequência de utilização em transações positivas"
    }
  ]
}

Retorna Informação de risco para transações PIX por id - Instituição Recebedora.

Authorizations:
Bearer
path Parameters
id
required
string Nullable

Responses

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "e08bbca0024f4b618849112e72c404de",
  "score": {
    "value": 44.76,
    "date": "2021-12-29T18:34:03.3702842Z"
  },
  "ratings": [
    {
      "value": 3,
      "relatedTo": [
        "Document",
        "Phone"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Document",
        "Email"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Document",
        "Device"
      ]
    },
    {
      "value": 1,
      "relatedTo": [
        "Phone",
        "Email"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Phone",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Phone",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "Email",
        "ZipCode"
      ]
    },
    {
      "value": 2,
      "relatedTo": [
        "Email",
        "Device"
      ]
    },
    {
      "value": 3,
      "relatedTo": [
        "ZipCode",
        "Device"
      ]
    }
  ],
  "insights": [
    {
      "code": "117",
      "description": "Dupla CPF + Telefone vista em diversos segmentos"
    },
    {
      "code": "316",
      "description": "Dupla CPF + CEP com alta frequência de utilização em transações positivas"
    }
  ]
}

Retroalimentação

A retroalimentação possibilita ao participante contribuir com informações para enriquecer os dados de suas próprias análises futuras. De modo geral sempre que uma consulta for feita, seja de vínculo ou transacional, esta será incluída na base de dados e utilizada em correções futuras. No entanto, um participante pode optar por não fazer uma consulta de dados a fim de otimizar seus custos. Neste cenário, a retroalimentação irá apenas incluir os dados da requisição na base de dados para correlação futura.

API003 – Retroalimentação de cadastros na DICT

Este método difere de uma requisição normal por não retornar uma análise de risco e também não gera custo ao participante.

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
reason
required
string non-empty

Razão para FeedbackEntry, é o mesmo campo enviado para transação DICT pelo participante, opções disponíveis: [USER_REQUESTED,ACCOUNT_CLOSURE,BRANCH_TRANSFER,ENTRY_INACTIVITY,RECONCILIATION].

Enum: "USER_REQUESTED" "ACCOUNT_CLOSURE" "BRANCH_TRANSFER" "ENTRY_INACTIVITY" "RECONCILIATION"
requestId
string 36 characters

UUID versão 4 e deve ser único no contexto de um mesmo participante, é o mesmo campo enviado para a transaçao DICT pelo participante

name
required
string [ 1 .. 200 ] characters

Nome da pessoa ou da organização. Deve ser o mesmo valor utilizado nas transações da DICT no objeto de Proprietário.

document
required
string non-empty ^([0-9]{11}|[0-9]{14})$

Número do documento, somente números, padrões: [CPF]: "^[0-9]{11}$" | [CNPJ]: "^[0-9]{14}$".

documentType
required
string non-empty

Tipo do documento, opções disponíveis: [CPF,CNPJ].

Enum: "CPF" "CNPJ"
object (PhoneDto)

Objeto telefone.

email
string Nullable

Conta de e-mail.

verifiedEmail
required
boolean

Conta de e-mail foi verificada. Valor default é false.

object (AddressDto)

Address object.

evp
string Nullable

EVP gerado e utilizado para transações DICT.

keyType
required
string non-empty

Tipo da chave da transação DICT, opções disponíveis: [CPF,CNPJ,PHONE,EMAIL,EVP].

Enum: "CPF" "CNPJ" "PHONE" "EMAIL" "EVP"
required
object (FeedbackAccountDto)

Informações do objeto de Conta bancária.

referenceDate
required
string <date-time>

Data e hora da transação UTC.

object (FraudEventStatisticDto)
fingerprintVariables
any Nullable

Fingerprint variables information key-value json object.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "reason": "USER_REQUESTED",
  • "requestId": "1a2bdcb0-c8a8-464e-929d-6c93f8a2a143",
  • "name": "Fulano de Tal",
  • "document": "18356615801",
  • "documentType": "CPF",
  • "phone": {
    },
  • "email": "fulano.tal@email.com.br",
  • "verifiedEmail": false,
  • "address": {
    },
  • "evp": "123e4567-e89b-12d3-a456-426655440000",
  • "keyType": "EVP",
  • "account": {
    },
  • "referenceDate": "2021-05-07T19:52:12.1344294Z",
  • "fingerprintVariables": ""
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "ab979ac2c7a24c6eb11ad10f61f39438"
}

API004 – Retroalimentação de transações PIX

Este método difere de uma requisição normal por não retornar uma análise de risco e também não gera custo ao participante.

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
transactionType
string Nullable

Tipo da mensagem usada na transação SPI, e.g.: "PACS.008", "PACS.004".

Enum: "PACS.008" "PACS.004"
endToEndId
string <= 50 characters Nullable

Identificação única atribuída pela parte iniciadora a identificar inequivocamente a transação, mesmo valor usado no nas mensagens PACS.008 e PACS.004

txId
string <= 50 characters Nullable

Identificação de transação usada em mensagens PACS para SPI nas transações PIX por QRCode ou Link.

channel
required
string non-empty

Canal de origem da transação, opções disponíveis: "WEB", "MOBILE" and "AGENCY".

Enum: "WEB" "MOBILE" "AGENCY"
object (QrCodeDto)
object (UrlLinkDto)
required
object (FeedbackRecipientDto)
required
object (FeedbackTransferSenderDto)
currency
required
string [ 1 .. 50 ] characters

Moeda usada na transferência.

amount
required
number <double> non-empty > 0

Valor da transferência.

referenceDate
required
string <date-time>

Data e hora da transação.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "transactionType": "PACS.008",
  • "endToEndId": "E9999901012341234123412345678900",
  • "txId": "90000",
  • "channel": "WEB",
  • "qrCode": {},
  • "urlLink": {},
  • "recipient": {
    },
  • "sender": {
    },
  • "currency": "BRL",
  • "amount": 110.55,
  • "referenceDate": "2021-11-17T22:32:08.2012386Z"
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "ab979ac2c7a24c6eb11ad10f61f39438"
}

API005 – Retroalimentação de indicadores de fraude

O participante pode também auxiliar na retroalimentação da base de dados para incluir ou atualizar uma marcação de fraude na plataforma.

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
participant
required
string non-empty

Número do banco.

summary
required
string non-empty

Resumo do evento de fraude da retroalimentação.

description
required
string non-empty

Descrição do evento de fraude da retroalimentação.

visibility
required
integer <int32> non-empty [ 0 .. 1 ]

Valor Visibilidade, mark: 0 - Só você pode ver; 1 - Você vai colaborar com outros.

referenceDate
required
string <date-time>

Valor de data / hora UTC do evento de fraude da retroalimentação.

status
required
integer <int32> non-empty [ 0 .. 3 ]

Feedback Fraud status: 0 - Suspeita de fraude; 1 - Fraude confirmada; 2 - Suspeita de fraude descartada; 3 - Fraude arquivada;

Array of objects (EntryDto) Nullable

Lista de dados de entrada relacionados a evento de fraude da retroalimentação

Array of objects (TransferDto) Nullable

Lista de dados de transferência relacionados a evento de fraude da retroalimentação

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "participant": "87654321",
  • "summary": "Fraude de roubo de whatsapp",
  • "description": "Fraude de roubo de whatsapp relatada pelo cliente em XX/YY/ZZZZ, nos ligou informando o modo de operação, o cliente recebeu uma mensagem...",
  • "visibility": 1,
  • "referenceDate": "2020-11-09T11:53:26.721+00:00",
  • "status": 2,
  • "relatedEntries": [
    ],
  • "relatedTransfers": [
    ]
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "ab979ac2b7a24c6ebf1ad10f61f39438"
}

Funcionalidades Adicionais

As funcionalidades Adicionais auxiliam os Participantes nas chamadas onde necessitar uma camada adicional de segurança no intuito de combater a fraude, tanto no momento do cadastro de chaves na DICT como nas transações entre usuários.

API006 - 2FA - Gerar um ID da transação 2FA

A funcionalidade 2FA envia um SMS para o principal telefone da pessoa para confirmar o cadastro ou transação realizada.

Authorizations:
Bearer
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
documentType
required
string [ 1 .. 3 ] characters

Document type, options available: [CPF].

document
required
string non-empty ^[0-9]{11}$

Document value, only numbers, patterns: [CPF]: "^[0-9]{11}$".

email
string <email> [ 3 .. 200 ] characters ^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9...

Email account.

verifiedEmail
boolean

Email account has been verified. Default value is false.

sessionId
string Nullable

SessionId value used in behavior analytics integration, value between 5 and 128 chars.

object (AddressDto)

Address object.

object (PhoneDto)

Objeto telefone.

referenceDate
string <date-time>

Transaction UTC datetime value.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
text/json
application/*+json
{
  • "documentType": "cpf",
  • "document": "48592970083",
  • "email": "teste@teste.com",
  • "verifiedEmail": true,
  • "sessionId": "mysessionid-4-d3v1c3",
  • "address": {
    },
  • "phone": {
    },
  • "referenceDate": "2021-05-07T19:52:12.3546884Z"
}

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "id": "2f67b00a53784298a659cc3d89d6789b"
}

API006 - 2FA - Retorna resultado do 2FA por id

A funcionalidade 2FA retorna os dados do SMS enviado e resposta, bem como o status da requisição.

Authorizations:
Bearer
path Parameters
id
required
string Nullable

Responses

Response samples

Content type
text/plain
text/plain
application/json
text/json
{
  "request": {
    "text": "Olá, Fulano de Tal. Você cadastrou um chave Pix ou realizou alguma transação? Responda gratis:\n1 para sim\n2 para nao\n3 para nao sou Fulano de Tal",
    "type": "Sms",
    "status": "Sent",
    "createdAt": "2021 - 01 - 18T17:57:00.3741639Z"
  },
  "result": {
    "text": "1",
    "type": "Sms",
    "status": "Replied",
    "createdAt": "2021 - 01 - 18T17:57:33.450434Z"
  },
  "id": "b8b6a622658844e1a4446760287d3d11",
  "status": "success"
}