Obter resultado da transação via webhook

Na seção Obter resultado da transação é descrita uma maneira de obter o status de uma transação através de uma chamada a um endpoint. Dessa forma, o cliente realiza um polling para receber informações sobre as transações criadas, isto é, o endpoint pode ser chamado diversas vezes para uma mesma transação para que se obtenha o seu status mais recente. Porém, através do uso de webhooks, é possível o IDPay notificar um endpoint específico do cliente toda vez que o status de uma transação for alterado.

O que é um webhook?

Webhook é um serviço de notificação sistêmica, que permite a integração assíncrona entre sistemas, notificando o outro sistema através de um gatilho. Assim, os webhooks podem manter sistemas atualizados com informações mais recentes sem que seja necessária a verificação constante por atualizações através de polling.

Informações necessárias para a configuração do webhook

Para configurar o webhook, são necessárias as seguintes informações:

• URL de notificação: O endpoint em que o IDPay irá notificar sobre as atualizações de status.
• Tipo de autenticação: Método de autenticação utilizado para invocar o endpoint, que deverá estar entre as opções:
  • Basic Authorization;
  • API Key;
  • Sem autenticação.
• Secret: Secret utilizada para a autenticação, somente necessário no Basic Authorization e APIKEY
  • Para o Basic Authentication é necessário enviar no seguinte formato: user:pass
  • Para API Key, é possível enviar em dois formatos:
    • header:value, quando é desejado que o header tenha um nome especifico;
    • value: quando o header desejado é o Authorization
• Configurações de retentativas: Configurações de retentativas para o caso de falha na chamada ao endpoint:
  • Número máximo de tentativas;
  • Intervalo entre tentativas (em segundos);
  • Rate limit: Limite máximo de envios simultâneos (máximo: 500).
• Status a serem notificados: É possível se inscrever em status específicos para receber as notificações. São eles:
  • approved: Transação aprovada;
  • processing: Transação em processamento;
  • inconclusive: Não conseguimos realizar uma validação conclusiva;
  • shared: Transação compartilhada, aguardando envio;
  • skiped: A pessoa pulou a captura biométrica no fluxo;
  • unknown-share: A pessoa marcou que não reconhece aquela compra;
  • absent-holder: O titular do cartão não está presente para realizar a captura;
  • expired: A pessoa não realizou a captura dentro do tempo estabelecido e a transação foi expirada;

Integração com o IDPay

Ao configurar um webhook no IDPay, o cliente poderá obter informações sobre as transações através de notificações enviadas para um endpoint da API desenvolvida pelo cliente para receber essas atualizações.

As informações enviadas pelo IDPay para a API do cliente serão duas:

• ID: ID da transação;
• status: Status da transação;

Note que é possível escolher os status que o cliente deseja ser notificado, através da configuração do webhook. Após o envio dessas informações, a resposta esperada deverá ser síncrona.

Autenticação

A API poderá ser protegida por um método de autenticação, seja ele um Basic Authentication ou uma API Key. Uma lista de IPs válidos para acesso também pode ser definida, para proteção complementar.

Requisição

A requisição deve ser um método POST em uma API REST, sendo assim mais fácil e seguro o envio das informações. Todos os campos devem ser obrigatórios. O corpo da requisição deve aceitar o ID da transação e o status, tal como o exemplo abaixo:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved"
}

Resposta

A resposta deve vir de forma síncrona. O status para requisições bem sucedidas deverá estar no intervalo de 200 a 299. Qualquer outro status será considerado como falha e o IDPay irá realizar novas tentativas de notificações (com exponential backoff entre elas), até receber uma resposta 2xx ou até atingir o número máximo de tentativas.

Status da Resposta

Atualmente temos um conjunto de status, porém esse conjunto pode variar no futuro. Então é recomendado deixar configurável os status que o cliente tem interesse para tomar alguma ação. Por exemplo, se há o desejo de tomar uma ação toda vez que uma captura é realizada com sucesso, atualmente isso ocorre com o status processing, porém como isso pode ser modificado no futuro, é recomendado que o status que indica que a captura foi realizada com sucesso seja uma configuração no sistema, de modo que uma alteração no futuro para o status de captured seja facilmente realizada.

Além disso, recomendamos ter ações específicas para status específicos, e uma ação geral caso o status não seja reconhecido (por exemplo assumir que tudo que for diferente de processing e approved é inconclusivo). isso é importante, pois novos status podem surgir no futuro e não é esperado que o webhook quebre em função disso.

Considerações importantes

Atente-se aos seguintes aspectos ao desenvolver API que o IDPay irá utilizar para notificar as mudanças de status:

Rate Limit

Com intuito de não sobrecarregar os recursos do cliente em situações onde temos muitas transações, é possível especificar um limite superior de vezes em que o endpoint poderá ser invocado.

Taxa de erros

A taxa de erros (respostas fora do intervalo de [200, 299]) deve ser sempre baixa. Caso contrário, o throughput do webhook será automaticamente reduzido, e essa redução junto ao mecanismo do retry pode implicar no aumento do tempo de execução de novos webhooks.

Idempotência

A atual implementação de webhook possui a garantia de at-least once delivery, portanto podemos notificar o mesmo status mais de uma vez. A implementação do endpoint deve ter isso em mente e ser implementada de maneira idempotente.

Fallback

Em caso de alguma indisponibilidade no serviço do webhook, é recomendado que exista um método de fallback para que o cliente possa continuar obtendo os status das transações dentro do tempo de resposta estabelecido. A consulta ao endpoint descrita na seção Obter resultado da transação pode ser utilizada para esse fim.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.