Webhooks

This section brings together endpoints for managing notifications from the receiving PSP to the receiving user

Important!

By Banco Central regulations, it will be necessary to insert a public key from Efí into your server so that communication follows the mTLS standard, the same standard used in the Pix API.

To understand the mTLS standard and configure your server, click here.

Create payment webhook

Endpoint for creating the payment webhook.

PUT /v1/webhook

Requires authorization for the scope: payment.webhook.write

Request

Example

{
  "url": "string"
}

Responses

The responses below represent Success(201) and consumption failures/errors.

🟢 201

{
  "url": "string"
}

🔴 400

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

List payment webhooks

Endpoint for listing payment webhooks using parameters such as dataInicio and dataFim. The attributes are inserted as query parameters.

GET /v1/webhook

Requires authorization for the scope: payment.webhook.read

Request

The snippet below shows how the dataInicio and dataFim parameters (required) should be passed in the request.

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

Responses

The responses below represent Success(200) and consumption failures/errors.

🟢 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"
}

Delete payment webhook

Endpoint for deleting the payment webhook.

DELETE /v1/webhook

Requires authorization for the scope: payment.webhook.write

Request

Example

{
  "url": "string"
}

Responses
The responses below represents Consumer Success(204).

🟢 204

Webhook deleted

🔴 400

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

Receiving Callbacks

This service is protected by a layer of mTLS authentication. Callbacks are sent by Efí via POST url-registered-webhook when there is a change in the Payment status.

Request

When there is a change in the status of a payment associated with the used application, Efí sends a POST request to the webhook URL you defined. A JSON object (like the examples below) will be sent to your server. Each callback request has a timeout of 60 seconds, meaning it is interrupted if there is no response in 60 seconds.

Examples:

Below, see some examples of the JSON object sent.

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

Responses

Callback requests wait for a response with HTTP status 2XX. If the client's server returns a different status, Efí will make up to 10 new notification attempts. The first new attempt will be made 5 minutes after the failure to send the callback. If the error persists, subsequent attempts will be sent at increasingly longer intervals, as shown in the table below.

N° of attempts	Time (in minutes)
1	5
2	10
3	20
4	40
5	80
6	160
7	320
8	640
9	1280
10	52560