Recebendo Callbacks

Informações referentes aos recebimentos de callbacks da API Open Finance Efí.

Esse serviço possui duas formas de proteção à segurança:

• Autenticação mTLS: No domínio que representa o seu servidor, você deverá configurar a exigência da chave pública (mTLS) que estamos disponibilizando, para que ocorra a autenticação mútua. É necessário que o seu servidor tenha a versão mínima do TLS 1.2.
  

  Para configurar seu servidor, você pode seguir os exemplos citados na API Pix.

  Os callbacks são enviados pela Efí via POST url-webhook-cadastrada quando há uma alteração no status.

• Validação por hash cadastrada no webhook: Um hmac (uma identificação própria) será acrescentado ao final da URL no momento do envio do callback. Essa hash cadastrada no webhook será utilizada para validar a origem da notificação. Assim, todos os webhooks enviados ao seu servidor terão essa identificação final e sua aplicação deve confirmar a presença da mesma.

  Os callbacks são enviados pela Efí via POST url-webhook-cadastrada?hmac=hash-cadastrada quando há uma alteração no status.

Informação

Caso você precise testar os endpoints de Pagamentos do Open Finance, temos um ambiente de homologação funcional que permite simular todos os status retornados pela nossa API e webhook.

Se o valor do pagamento for de R$ 0.11:
O pagamento será rejeitado, e a informação será enviada via webhook.
Se o valor do pagamento for diferente de R$ 0.11:
O pagamento será aceito, e a informação será enviada via webhook.

Requisição

Uma requisição POST é enviada pela Efí para a URL que você cadastrou como webhook. É importante mencionar que cada requisição de callback (envio do objeto JSON) possui um limite de tempo de resposta de 25 segundos. Caso seu servidor não responda dentro desse prazo, a requisição será interrompida.

Exemplos:

A seguir, veja alguns exemplos do objeto JSON enviado.

Exemplo 1 - Iniciação de Pagamento

// Exemplo - 200 (Notificação enviada com sucesso)
{
  "identificadorPagamento": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "valor": "9.90",
  "status": "aceito",
  "dataCriacao": "2024-09-20T18:37:23.000Z",
  "endToEndId": "E090993562022060954525a47762681g",
  "idProprio": "6236574863254",
  "tipo": "pagamento" 
}

Exemplo 2 - Iniciação de Pagamento

// Exemplo - 200 (Notificação enviada com sucesso)
{
  "identificadorPagamento": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "valor": "9.90",
  "status": "expirado",
  "dataCriacao": "2024-09-20T18:37:23.000Z",
  "endToEndId": "E090993562022060954525a47762681g",
  "idProprio": "6236574863254",
  "tipo": "pagamento",
  "motivo": "Pagamento recusado no destino"
}

Devolução

// Exemplo - 200 (Notificação enviada com sucesso)
{
  "identificadorPagamento": "urn:nubank:eb164079-dbc3-37ec-80bd-1f5d5ea46cec",
  "identificadorDevolucao": "D09089356202211301744509406dc544",
  "endToEndId": "E09089356202211301744e53afc1c1c0",
  "idProprio": "4ad0394de750cd22dcbed11882a9a775",
  "valor": "0.01",
  "status": "aceito",
  "dataCriacao": "2022-11-30T17:44:35.000Z",
  "tipo": "devolucao"
}

Respostas

As requisições de callback aguardam uma resposta com status HTTP 2XX. Caso o servidor do cliente retorne um status diferente, a Efí fará até 10 novas tentativas de notificação. A primeira nova tentativa será feita 5 minutos após a falha do envio do callback. Persistindo o erro, as tentativas subsequentes serão enviadas em intervalos de tempo cada vez maiores, conforme mostra a tabela abaixo.

Importante!

Em casos onde o servidor do cliente retorna o status HTTP 429 (too many requests), os servidores da Efí tentarão enviar a notificação até 10 vezes também de acordo com a tabela abaixo.

Número da tentativa	Tempo (em minutos)
1	5
2	10
3	20
4	40
5	80
6	160
7	320
8	640
9	1280
10	52560