Webhooks

Esta seção reúne endpoints para gerenciamento de notificações por parte do PSP recebedor a pessoa usuária recebedora.

Importante!

Por norma do Banco Central, será necessário a inserção de uma chave pública da Efí em seu servidor para que a comunicação obedeça o padrão mTLS, mesmo padrão utilizado na API Pix.

Para entender o padrão mTLS e configurar seu servidor, clique aqui.

Criar webhook de pagamento

Endpoint para criação do webhook de pagamento.

PUT /v1/webhook

Requer autorização para o escopo: payment.webhook.write

Requisição

Exemplo

{
  "url": "string"
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

🟢 201

{
  "url": "string"
}

🔴 400

{
  "nome": "string",
  "mensagem": "string"
}

Listar webhooks de pagamento

Endpoint para listar webhooks de pagamento através de parâmetros como dataInicio e dataFim. Os atributos são inseridos como query params.

GET /v1/webhook

Requer autorização para o escopo: payment.webhook.read

Requisição

O trecho abaixo mostra como os parâmetros dataInicio e dataFim (obrigatórios) devem ser repassados na requisição.

/v1/webhook/?dataInicio=2024-01-22T16:01:35Z&dataFim=2024-10-23T16:01:35Z

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

🟢 200

{
  "parametros": {
    "inicio": "string",
    "fim": "string",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 5
    }
  },
  "webhooks": [
    {
      "url": "string",
      "criacao": "string"
    }
  ]
}

🔴 400

{
  "nome": "string",
  "mensagem": "string"
}

Deletar webhook de pagamento

Endpoint para deleção do webhook de pagamento.

DELETE /v1/webhook

Requer autorização para o escopo: payment.webhook.write

Requisição

Exemplo

{
  "url": "string"
}

Respostas

A resposta abaixo representa Sucesso(204) do consumo.

🟢 204

Webhook deletado

🔴 400

{
  "nome": "string",
  "mensagem": "string"
}

Recebendo Callbacks

Esse serviço está protegido por uma camada de autenticação mTLS. Os callbacks são enviados pela Efí via POST url-webhook-cadastrada quando há uma alteração no status do Pagamento.

Requisição

Quando ocorre uma alteração no status de um pagamento associado a aplicação utilizada, a Efí envia uma requisição POST para a URL de webhook que você definiu. Um objeto JSON (como os exemplos abaixo) será enviado ao seu servidor. Cada requisição de callback possui um timeout de 60 segundos, ou seja, é interrompida se não houver resposta em 60 segundos.

Exemplos:

A seguir, veja alguns exemplos do objeto JSON enviado.

Em processamento

{
  "identificador": "1013",
  "status": {
      "anterior": "CRIADO",
      "atual": "EM_PROCESSAMENTO"
  },
  "valor": "150.10",
  "horario": {
      "solicitacao": "2024-02-07T14:32:54.000Z"
  },
  "efiExtras": {
      "dataExecucao": "2024-02-07",
      "codigoBarras": "23797962400000213204150060000055503009010000",
      "linhaDigitavel": "23794150096000005550330090100006796240000021320"
  }
}

Agendado

{
  "identificador": "1012",
  "status": {
      "anterior": "CRIADO",
      "atual": "AGENDADO"
  },
  "valor": "150.10",
  "horario": {
      "solicitacao": "2024-02-07T14:17:36.000Z"
  },
  "efiExtras": {
      "dataExecucao": "2024-02-08",
      "codigoBarras": "23792962400000180004150060000055567609010000",
      "linhaDigitavel": "23794150096000005556076090100009296240000018000"
  }
}

Executado

{
  "valor": "650.00",
  "status": {
    "atual": "EXECUTADO",
    "anterior": "EM_PROCESSAMENTO"
  },
  "horario": {
    "solicitacao": "2024-02-01T15:12:21"
  },
  "efiExtras": {
    "protocolo": "936879015",
    "codigoBarras": "10497962600000650008527261000100040064915871",
    "dataExecucao": "2024-02-01",
    "motivoRecusa": null,
    "linhaDigitavel": "10498527246100010004200649158714796260000065000"
  },
  "identificador": "5968942"
}

Liquidado

{
  "valor": "650.00",
  "status": {
    "atual": "LIQUIDADO",
    "anterior": "EXECUTADO"
  },
  "horario": {
    "liquidacao": "2024-02-01T15:12:33",
    "solicitacao": "2024-02-01T15:12:21"
  },
  "efiExtras": {
    "protocolo": "936879015",
    "codigoBarras": "10497962600000650008527261000100040064915871",
    "dataExecucao": "2024-02-01",
    "motivoRecusa": null,
    "linhaDigitavel": "10498527246100010004200649158714796260000065000"
  },
  "identificador": "5968942"
}

Nao realizado

{
  "valor": "582.30", 
  "status": { 
    "atual": "NAO_REALIZADO", 
    "anterior": "AGENDADO" 
  }, 
  "horario": { 
    "solicitacao": "2024-02-06T01:55:31.000Z" 
  }, 
  "efiExtras": { 
    "protocolo": "949096655", 
    "codigoBarras": "65593166800000582300000001007500004640804500", 
    "dataExecucao": "2024-02-07", 
    "motivoRecusa": "Saldo Insuficiente. Data: 07/02/2024.", 
    "linhaDigitavel": "65590000020100750000046408045006316680000058230" 
  }, 
  "identificador": "5978351"
}

Cancelado

{
  "valor": "20.00",
  "status": {
    "atual": "CANCELADO",
    "anterior": "AGENDADO"
  },
  "horario": {
    "solicitacao": "2024-01-23T10:36:07"
  },
  "efiExtras": {
    "protocolo": null,
    "codigoBarras": "36491000000000020000000700014334200000000066",
    "dataExecucao": "2024-01-24",
    "motivoRecusa": null,
    "linhaDigitavel": "36490000760001433420500000000661100000000002000"
  },
  "identificador": "5949678"
}

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° 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