O datahub usa um webhook para notificar determinados eventos que ocorrem com os portadores, como quando uma transação de compra é autorizada.

O webhook permite que o emissor crie ou configure integrações a partir das notificações dos eventos. Quando um destes for disparado, será enviada uma requisição HTTP POST para a URL configurada, tornando desnecessária a busca do emissor por informações em uma API, pois os webhooks enviam as notificações de eventos para a URL de seu endpoint.


Aplicabilidade do webhook

O webhook de eventos pode ser utilizado por emissores para construção de dashboards, métricas, análises preditivas, envio de push, e-mail, SMS ou qualquer aplicação semelhante.

🚧

Atenção

Não é indicado o uso dessa opção para persistência de dados, construção de repositórios como datalake ou em aplicações críticas.


Funcionamento do webhook de eventos do datahub

Todos os eventos são capturados no ecossistema da Dock que se mantém em constante transmissão. Uma camada de comunicação por API é disponibilizada para que os usuários possam configurar a maneira como desejam receber esses eventos, os quais, após capturados, são enviados de forma criptografada provendo ainda mais segurança. A entrega dos eventos se dá através de webhooks, ou seja, a requisição HTTP é enviada para qualquer URL informada e gerenciada pelo próprio emissor.

📘

Nota

Caso haja qualquer modificação que possa causar algum impacto no formato do evento, seja um campo ou conteúdo do campo, o emissor será comunicado.


Fluxo do webhook de eventos do datahub

Testando os webhooks (sandbox)

É possível ter ideia do que os eventos são capazes de fazer e entender como seriam os próximos passos para começar a utilizar em ambiente produtivo, sem dependência de configuração por terceiros e utilizando dados fictícios.

Setup dos webhooks

1- Autenticação;
2- Criptografia;
3- Escolha dos eventos: por ser uma aplicação flexível e que possibilita a escolha de quais eventos estarão habilitados para serem enviados aos emissores, é necessário que o emissor possua uma lista de eventos que deseja receber, o que proporcionará um controle maior sobre o negócio e evitará custos desnecessários com eventos não utilizados.

Para mais detalhes sobre os passos que são necessários para realizar o setup, é só utilizar o link: Setup.

Cadastro dos webhooks

Após a realização do setup, é possível cadastrar o webhook, associando o evento à URL em que deseja receber os dados, de duas maneiras: através do Culr e do Postman. Para os detalhes técnicos sobre como utilizar, é só acessar: Cadastro de webhooks.

Manutenção dos webhooks

  • Para consultar uma lista com todos os webhooks cadastrados, é só utilizar o endpoint: Listar webhooks.

  • Para adicionar um novo webhook, é só utilizar o endpoint: Adicionar webhook.

  • Para consultar um webhook de evento, é só utilizar o endpoint: Consultar webhook.

  • Para alterar os webhooks cadastrados na API, é só utilizar o endpoint: Alterar webhook.


Retentativas

O webhook possui funcionalidades que objetivam reduzir a perda desses eventos na última camada de integração, a integração com a API do emissor. Uma delas é a possibilidade de retentativas com atraso exponencial.

Quando acontece uma retentativa?

Ao realizar a chamada HTTP à API do emissor, o webhook espera receber um código HTTP de resposta válido e, assim, interpretar o que houve com o evento entregue. O webhook não usa qualquer outra resposta além do código HTTP.

Retentativas com atraso exponencial

Essa funcionalidade garante até 10 tentativas de envio de um evento antes de descartá-lo, ou seja, o webhook vai esperar no máximo 4h30min até que a API do emissor volte a funcionar antes de descartar o evento.

Identificação da tentativa atual

A tentativa atual pode ser identificada dentro de um parâmetro do cabeçalho do evento.

Para mais informações e detalhes consultar Retentativas.

📘

Nota

A plataforma de envio de eventos poderá passar por manutenções programadas. Estas serão previamente comunicadas, informando o impacto e período. Em caso de manutenções que gerem indisponibilidade no serviço, os eventos serão represados e, entregues assim que a plataforma for reestabelecida.


Eventos contemplados no webhook do datahub

A seguir está uma breve descrição sobre cada evento contemplado. Para conhecer os detalhes técnicos e de campos dos eventos mencionados, é só acessar o link: Eventos do webhook.

Pessoa

  • Pessoa: criado sempre que uma pessoa física ou jurídica, sendo titular ou adicional, é cadastrada ou alterada na base.

  • Endereço: criado sempre quando ocorrer qualquer alteração na base de endereços.

  • Telefone: criado sempre que ocorrer qualquer alteração na base de telefones.

  • Análise de crédito: criado quando ocorre o cadastro ou alteração de proposta em análise de crédito.

Conta

  • Conta: responsável pelo envio de informações de conta do portador, esta é gerada sempre que um novo portador é aprovado para utilização de uma conta.

  • Limite de crédito: criado sempre que ocorrer qualquer alteração no limite global ou disponível do portador, geralmente, ocasionada por disponibilização de limite, pagamento, compra ou ajuste.

  • Ajustes: ajustes de fatura que são enviados para a Dock que afetam o saldo do portador ou saldo contábil, neste caso é gerado todo o ciclo de vida do ajuste, desde a inclusão até o processamento.

  • Fatura: criado sempre com informações que compõem uma fatura de cada conta, como os valores de saldo, vencimento, valor de encargos.

  • Boletos: todo boleto gerado, encaminhado e processado na base da Dock é criado.
    Geralmente, as informações de boleto referem-se a boleto de fatura ou recarga de saldo.

  • Transações: todas as transações geradas para uma fatura, tanto as transações de débito como as de crédito; todo evento de compra, pagamento e ajuste, quando processado, se torna uma transação e é enviado. Esse evento não mostra transações contábeis, somente transações que impactam a fatura.

Cartão

  • Cartão: criado sempre que qualquer mudança ocorrer em nossa base de cartão, desde um cartão criado até um cartão desbloqueado ou enviado para embossing.

Token

  • Token: gerado quando há criação de um token ou quando o seu status é atualizado.

Autorização

Para as mensagens vindas do evento Compra, existem várias possibilidades de tratamento a serem feitas pelo lado do emissor. Verificando o valor da propriedade status, é possível identificar que, ao receber os tipos Normal ou Pendente, trata-se de uma transação autorizada. Caso seja do tipo Processada, denota a liquidação de uma transação. Os demais status indicam que houve um Cancelamento na transação. A imagem a seguir ilustra o fluxo dos eventos de autorização.

FIG: Fluxo de eventos de autorizaçãoFIG: Fluxo de eventos de autorização

FIG: Fluxo de eventos de autorização

Toda autorização que realiza alteração nos limites de um cliente irá enviar eventos do tipo Transaction e Limit, assim os emissores podem fazer relações entre eles utilizando as datas de atualização de cada evento e id_conta.

Segue abaixo exemplos de mensagens com os principais tipos de status do fluxo de autorização:

  • Compra - status normal: trata-se de uma compra já processada pelo nosso autorizador e conciliada pela bandeira (caso seja uma compra bandeirada), ficando apenas pendente o processamento pela Dock para a fatura do portador gerando um evento do tipo Transaction.

  • Compra - status processada: trata-se de uma compra no qual já foi processada pelo nosso autorizador, conciliado com a bandeira (caso seja uma compra bandeirada) e processada para a etapa de fatura do portador no qual será gerado um evento do tipo Transaction.

  • Compra - status cancelada: trata-se de uma compra na qual foi inicialmente processada por nosso autorizador e recebeu uma solicitação de Cancelamento, com isso é alterado o status dessa compra e enviado um novo evento com status Cancelada.

  • Compra - baixada por prazo: trata-se de uma compra bandeirada no qual foi processado pelo nosso autorizador e ficou pendente para conciliação com a bandeira, no entanto, não foi identificado o envio pela bandeira e com isso após determinado prazo que é especificado por MCC (código de categoria do comerciante) a compra é baixada por prazo e com isso é devolvido o crédito ao portador.

  • Compra - pendente: trata-se de uma compra bandeirada já processada pelo nosso autorizador está em “espera” da conciliação com a bandeira.

  • Compra - estornada: trata-se de uma compra no qual recebeu uma solicitação de estorno no processo de conciliação, desta forma é alterado o status e enviado um novo evento com status Estornada.

Os eventos do tipo Compra foram divididos em 5 novos:

  • Compra - aprovada: trata-se de um evento que foram aprovados pelo processo de autorização.

  • Compra - processada: trata-se de todas as compras que foram totalmente aprovadas e já se encontram na fatura do portador, portanto são compras que foram aprovadas pelo fluxo de autorização e conciliadas com a bandeira.

  • Compra - liberada: trata-se de todos os eventos de compra que foram conciliados pela bandeira.

  • Compra - cancelada: trata-se de todos os eventos de compra na qual não houve a autorização ou conciliação pela bandeira, por tanto se trata de compras canceladas, estornadas, desfeitas ou baixadas por prazo.

  • Compra - tokenizada: representa todas as compras que passaram pelo autorizador e foram feitas via token em carteiras digitais. Esse evento apresenta as informações do token associado à compra e é enviado toda vez que uma nova compra via token for feita.

Eventos de pagamentos

Quando é recebida alguma informação relacionada a pagamentos, sua relação com a fatura do portador não é dada imediatamente. A maior parte dos emissores depende do processamento diário para que os valores sejam liquidados da fatura. Sendo assim, apenas com os dados dos eventos do tipo Payment não é possível validar se uma fatura foi baixada parcial ou total. Para realizar a validação da situação de uma fatura, recomenda-se validar via APIs, ou ainda relacionar o evento Payment com o histórico de eventos Limit e Statement.

Eventos de transações negadas

Ao negar uma transação, é possível verificar a interação entre os eventos Declined e Card. Esse cenário ocorre apenas quando a propriedade response_code é correspondente à senha incorreta. A interação depende de uma das propriedades do cartão, que indica a quantidade de tentativas de senha incorreta; caso excedida a quantidade limite, que é configurada por emissor, o status do cartão é atualizado, gerando assim um evento Card, conforme mostrado no fluxo a seguir.

FIG: Fluxo de eventos de transações negadasFIG: Fluxo de eventos de transações negadas

FIG: Fluxo de eventos de transações negadas

🚧

Atenção

Nem todos os eventos são enviados em tempo real, na plataforma da Dock existe o Batch, um sistema que executa uma série de rotinas ordenadas em um horário específico.

Essas rotinas representam um grande volume de processamento de dados. Por isso, são executadas durante a madrugada (offline), já que é um momento em que há baixo volume de processamento de outros serviços.


Did this page help you?