Webhooks

Information on the endpoints for managing notifications by the receiving PSP to the receiving end user.

Receiving Callbacks

This service has two security protection methods:

• mTLS Authentication: In your server's domain representing, you should configure the requirement of the public key (mTLS) that we are providing, for mutual authentication to occur. It is necessary for your server to have a minimum TLS version of 1.2.
  

  To configure your server, you can follow the examples mentioned in the Pix API.

  Callbacks are sent by Efí via POST url-webhook-registered when there is a change in status.

• Validation by hash registered in webhook: An HMAC (a unique identifier) will be appended to the end of the URL when sending the callback. This hash registered in the webhook will be used to validate the notification's origin. Thus, all webhooks sent to your server will have this final identification, and your application must confirm its presence.

  Callbacks are sent by Efí via POST url-registered-webhook?hmac=registered-hash when there is a change in status.

Information

If you need to test the Payment endpoints of the Open Finance, we have a functional testing environment that allows simulating all the statuses returned by our API and webhook.

If the payment amount is R$ 0.11:
The payment will be rejected, and the information will be sent via webhook.
If the payment amount is different from R$ 0.11:
The payment will be accepted, and the information will be sent via webhook.

Request

An HTTP POST request is sent by Efí to the URL you registered as a webhook. It is important to mention that each callback request (sending of the JSON object) has a response time limit of 25 seconds. If your server does not respond within this time frame, the request will be interrupted.

Examples:

Below are some examples of the JSON object sent for payments.

Immediate

// Example - Immediate payment accepted
{
  "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" 
}

// Example - Immediate payment refused
{
  "identificadorPagamento": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "valor": "9.90",
  "status": "rejeitado",
  "dataCriacao": "2024-09-20T18:37:23.000Z",
  "endToEndId": "E090993562022060954525a47762681g",
  "idProprio": "6236574863254",
  "tipo": "pagamento",
  "motivo": "Pagamento recusado no destino"
}

Scheduled

// Examplo - Scheduled payments accepted
{
  "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"
}

// Examplo - Scheduled payments rejected
{
  "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"
}

Recurrent

// Examplo - Recurrent payment accepted
{
  "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"
}

// Examplo - Recurrent payment rejected or canceled
{
  "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"
}

Biometric

// Example - Authorized enrollment webhook
{
  "identificadorVinculo": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "status": "autorizado",
  "tipo": "vinculo" 
}

// Example - Rejected Registration Webhook
{
  "identificadorVinculo": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "status": "rejeitado",
  "tipo": "vinculo",
  "motivo": "Usuário rejeitou o vinculo"
}

// Example - Accepted Payments webhook
{
  "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" 
}

// Example - Rejected Payments webhook
{
  "identificadorPagamento": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "valor": "9.90",
  "status": "rejeitado",
  "dataCriacao": "2024-09-20T18:37:23.000Z",
  "endToEndId": "E090993562022060954525a47762681g",
  "idProprio": "6236574863254",
  "tipo": "pagamento",
  "motivo": "Pagamento recusado no destino"
}

Automatic

// Example - Successful enrollment webhook
{
  "identificadorAdesao": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "idProprio": "6236574863254",
  "status": "aceito",
  "dataCriacao": "2025-09-20T18:37:23.000Z",
  "tipo": "adesao" 
}

// Example - Rejected enrollment webhook
{
  "identificadorAdesao": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "idProprio": "6236574863254",
  "status": "rejeitado",
  "dataCriacao": "2025-09-20T18:37:23.000Z",
  "motivo": "A autorização foi recusada pelo usuário",
  "tipo": "adesao" 
}

// Example - Accepted Payments webhook
{
  "identificadorAdesao": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "idProprio": "6236574863254",
  "endToEndId": "E090993562022060954525a47762681g",
  "valor": "9.90",
  "status": "aceito",
  "dataCriacao": "2025-09-20T18:37:23.000Z",
  "dataOperacao": "2025-09-20",
  "infoPagador": "Primeiro pagamento da adesão",
  "tipo": "pagamento" 
}

// Example - Scheduled Payments Webhook
{
  "identificadorAdesao": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "idProprio": "6236574863254",
  "endToEndId": "E090993562022060954525a47762681g",
  "valor": "9.90",
  "status": "agendado",
  "dataCriacao": "2025-09-20T18:37:23.000Z",
  "dataOperacao": "2025-09-25",
  "infoPagador": "Primeiro pagamento da adesão",
  "tipo": "pagamento" 
}

// Example - Canceled or Rejected Payments Webhook
{
  "identificadorAdesao": "urn:instituicaoDetentoraDeConta:fd2be7c4-604c-4493-9236-78fe66f40597",
  "idProprio": "6236574863254",
  "endToEndId": "E090993562022060954525a47762681g",
  "valor": "9.90",
  "status": "cancelado/rejeitado",
  "dataCriacao": "2025-09-20T18:37:23.000Z",
  "dataOperacao": "2025-09-21",
  "infoPagador": "Primeiro pagamento da adesão",
  "motivo": "O pagamento agendado foi cancelado antes da data prevista de processamento",
  "tipo": "pagamento" 
}

Refund

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

Response

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