Webhooks

Informações referentes ao gerenciamento de notificações por parte do PSP recebedor a pessoa usuária recebedora.

Recebendo Callbacks

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.

Pagamento imediato

// Exemplo - Pagamento imediato aceito
{
  "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 - Pagamento imediato recusado
{
  "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"
}

Pagamento agendado

// Exemplo - Pagamento agendado aceito
{
  "identificadorPagamento": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "valor": "0.01",
  "status": "agendado",
  "dataOperacao": "2025-09-03",
  "dataCriacao": "2025-09-02T18:41:27.790Z",
  "endToEndId": "E090993562022060954525a47762681g",
  "tipo": "pagamento"
}

// Exemplo - Pagamento agendado rejeitado
{
  "identificadorPagamento": "urn:efi:8356bccc-811a-40c1-b293-8ac4ec7b84fc",
  "valor": "0.01",
  "status": "rejeitado",
  "motivo": "Saldo insuficiente",
  "dataOperacao": "2024-09-03",
  "dataCriacao": "2024-09-02T18:41:27.790Z",
  "endToEndId": "E09089356202409031500c4e8090aa56",
  "tipo": "pagamento"
}

Pagamento recorrente

// Exemplo - Pagamento recorrente aceito
{
  "identificadorPagamento": "urn:efi:ae71713f-875b-4af3-9d85-0bcb43288847",
  "valor": "9.90",
  "status": "ativa",
  "dataCriacao": "2022-04-29T11:55:03.000Z",
  "recorrencia": [
    {
      "endToEndId": "E090893562024080715006f2630c3d62",
      "status": "aceito",
      "dataOperacao": "2024-08-06"
    },
    {
      "endToEndId": "E090893562024080815004f4a2ef26ef",
      "status": "agendado",
      "dataOperacao": "2024-08-08"
    }
  ],
  "tipo": "recorrencia"
}

// Exemplo - Pagamento recorrente rejeitado ou cancelado
{
  "identificadorPagamento": "urn:efi:b8ef7479-9c50-4b1b-a7c6-2ad778647bec",
  "valor": "0.01",
  "status": "concluida",
  "dataCriacao": "2024-09-02T18:42:15.119Z",
  "recorrencia": [
    {
      "endToEndId": "E0908935620241001150016e5824d268",
      "status": "rejeitado",
      "motivo": "Saldo insuficiente",
      "dataOperacao": "2024-10-01"
    },
    {
      "endToEndId": "E09089356202411011500033fddb81d6",
      "status": "cancelado",
      "motivo": "Cancelado pelo usuário na instituição bancária",
      "dataOperacao": "2024-11-01"
    },
    {
      "endToEndId": "E09089356202412011500c1d1d087313",
      "status": "cancelado",
      "motivo": "Cancelado pelo integrador",
      "dataOperacao": "2024-12-01"
    }
  ],
  "tipo": "recorrencia"
}

Devolução

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