Webhooks

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

Entendendo o padrão mTLS

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

A Efí irá fazer 2 requisições para o seu domínio (servidor):

Primeira Requisição: Vamos certificar que seu servidor esteja exigindo uma chave pública da Efí. Para isso, enviaremos uma requisição sem certificado e seu servidor não deverá aceitar a requisição. Caso seu servidor responda com recusa, enviaremos a 2ª requisição.
Segunda Requisição: Seu servidor, que deve conter a chave pública disponibilizada, deverá realizar o "Hand-Shake" para que a comunicação seja estabelecida.

É necessário que o seu servidor tenha a versão mínima do TLS 1.2.

Em seu servidor, configure uma rota 'POST' com uma resposta padrão como uma string "200". Inclua o nosso certificado de produção ou homologação em seu servidor, a seguir temos alguns exemplos.

Servidores dedicados

Recomenda-se que você tenha um servidor dedicado para conseguir realizar as configurações do webhook, pois é necessário ter acesso a alguns arquivos para realizar as configurações, como nos exemplos abaixo.

Exemplos de configurações de servidor

Para configurar seu servidor, você precisará das chaves públicas da Efí. Abaixo estão os endereços das chaves para os ambientes de Produção e Homologação. Essas chaves devem ser baixadas e dispostas em seu servidor.

Atributo	URL da chave pública
Produção	`https://certificados.efipay.com.br/webhooks/certificate-chain-prod.crt`
Homologação	`https://certificados.efipay.com.br/webhooks/certificate-chain-homolog.crt`

Os trechos de código abaixo buscam exemplificar as configurações necessárias em seu servidor para que seja possível realizar o hand-shake com nossos servidores.

Python
Nginx
Node
Apache
PHP

from flask import Flask, jsonify, request
import ssl
import json
app = Flask(__name__)

@app.route("/", methods=["POST"])
def imprimir():
  response = {"status": 200}
  return jsonify(response)


@app.route("/pix", methods=["POST"])
def imprimirPix():
  imprime = print(request.json)
  data = request.json
  with open('data.txt', 'a') as outfile:
      outfile.write("\n")
      json.dump(data, outfile)
  return jsonify(imprime)

if __name__ == "__main__":
  context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
  context.verify_mode = ssl.CERT_REQUIRED
  context.load_verify_locations('caminho-certificados/certificado-público.crt')
  context.load_cert_chain(
      'caminho-certificados/server_ssl.crt.pem',
      'caminho-certificados/server_ssl.key.pem')
  app.run(ssl_context=context, host='0.0.0.0')
#Desenvolvido pela Consultoria Técnica da Efí

server {
  #
  # ...
  #
  listen [::]:443 ssl ipv6only=on;
  listen 443 ssl;
  ssl_certificate server_ssl.crt.pem;
  ssl_certificate_key server_ssl.key.pem;
  ssl_client_certificate /root/chain-pix-webhooks-prod.crt;
  ssl_verify_client optional;
  ssl_verify_depth 3;
  #
  # ...
  #
  location /webhook {
    if ($ssl_client_verify != SUCCESS) {
      return 403;
    }
    proxy_pass /webhook;
  }
}
#Desenvolvido pela Consultoria Técnica da Efí

const express = require("express");
const fs = require("fs");
const https = require("https");
var logger = require("morgan");

const httpsOptions = {
  cert: fs.readFileSync(""), // Certificado fullchain do dominio
  key: fs.readFileSync("/"), // Chave privada do domínio
  ca: fs.readFileSync(""), // Certificado público da Efí
  minVersion: "TLSv1.2",
  requestCert: true,
  rejectUnauthorized: true, //Caso precise que os demais endpoints não rejeitem requisições sem mTLS, você pode alterar para false
};

const app = express();
const httpsServer = https.createServer(httpsOptions, app);
const PORT = 443;

app.use(logger("dev")); // Comente essa linha caso não queira que seja exibido o log do servidor no seu console
app.use(express.json());
app.use(express.urlencoded({ extended: false }));

// Endpoint para configuração do webhook, você precisa cadastrar https://SEUDOMINIO.com/webhook
app.post("/webhook", (request, response) => {
  // Verifica se a requisição que chegou nesse endpoint foi autorizada
  if (request.socket.authorized) {
    response.status(200).end();
  } else {
    response.status(401).end();
  }
});

// Endpoind para recepção do webhook tratando o /pix
app.post("/webhook/pix", (request, response) => {
  if (request.socket.authorized) {
    //Seu código tratando a callback
    /* EXEMPLO:
    var body = request.body;
    filePath = __dirname + "/data.json";
    fs.appendFile(filePath, JSON.stringify(body) + "\n", function (err) {
        if (err) {
            console.log(err);
        } else {
            response.status(200).end();
        }
    })*/
    response.status(200).end();
  } else {
    response.status(401).end();
  }
});

httpsServer.listen(PORT, () =>
  console.log(`Express server currently running on port ${PORT}`)
);
//Desenvolvido pela Consultoria Técnica da Efí

# ********************************************************************************* #
# Utilize o primeiro exemplo, caso queira requerir o certificado para autenticação  #
# mútua em qualquer rota do domínio indicado no VirtualHost.                        #
# Funciona bem para sub-domínios. Exemplo: https://www.webhook.seu_dominio.com.br   #
# ********************************************************************************* #

<IfModule mod_ssl.c>
<VirtualHost *:443> # Porta HTTPS
  #
  # ...
  #

  SSLCertificateFile /caminho_certificado/fullchain_ssl.pem #fullchain associado ao seu certificado SSL do domínio
  SSLCertificateKeyFile /caminho_certificado/privkey_ssl.pem #privkey associada ao seu certificado SSL do domínio

  #Chave pública da Efí
  SSLCACertificateFile /caminho_certificado/chain-pix-prod.crt

  # mTLS Efí
  SSLVerifyClient require
  SSLVerifyDepth 3

  # Tratando o /pix, redirecionando as requisições sempre para /webhook
  Alias "/pix/" "/var/www/webhook/index.php"
  Alias "/pix" "/var/www/webhook/index.php"

  #
  # ...
  #
</VirtualHost>
</IfModule>


# ******************************************************************************** #
# Utilize o segundo exemplo, caso queira requerir o certificado para autenticação  #
# mútua em apenas uma rota do domínio indicado no VirtualHost.                     #
# Exemplo: https://www.seu_dominio.com.br/webhook/                                 #
# ******************************************************************************** #

<IfModule mod_ssl.c>
<VirtualHost *:443> # Porta HTTPS
  #
  # ...
  #

  SSLCertificateFile /caminho_certificado/fullchain_ssl.pem #fullchain associado ao seu certificado SSL do domínio
  SSLCertificateKeyFile /caminho_certificado/privkey_ssl.pem #privkey associada ao seu certificado SSL do domínio

  #Chave pública da Efí
  SSLCACertificateFile /caminho_certificado/chain-pix-prod.crt

  # mTLS Efí
  SSLVerifyClient none
  SSLProtocol TLSv1.2

  <Location "/webhook">
      SSLVerifyClient require
      SSLVerifyDepth 3
  </Location>

  # Tratando o /pix, redirecionando as requisições sempre para /webhook
  Alias "/webhook/pix/" "/var/www/webhook/index.php"
  Alias "/webhook/pix" "/var/www/webhook/index.php"

  #
  # ...
  #
</VirtualHost>
</IfModule>

# ********************************************************************************** #
# Para o funcionamento deste exemplo é necessário que seu servidor tenha configurado #
# o certificado do mTLS, com o direcionamento para este arquivo, e também com a      #
# tratativa do /pix. Assim como é feito em nosso exemplo de servidores Apache.       #
# ********************************************************************************** #

<?php

function resposta($status, $mensagem, $dados)
{
  $resposta['status'] = $status;
  $resposta['mensagem'] = $mensagem;
  $resposta['dados'] = $dados;
  $json_resposta = '<pre>' . json_encode($resposta, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . '</pre>';

  header("HTTP/1.1 " . $status);
  echo $json_resposta;
}

function salvar($dados)
{
  // Crie um arquivo .;json para salvar as informações
  $nomeArquivo = './dados.json';
  $dadosGravados = json_decode(file_get_contents($nomeArquivo), true);
  $arquivo = fopen($nomeArquivo, 'w');

  // Incrementa as informações enviadas com o que já havia gravado
  array_push($dadosGravados, $dados);

  if (fwrite($arquivo, json_encode($dadosGravados))) {
    resposta(200, "Requisição realizada com sucesso!", $dados);
  } else {
    resposta(300, "Falha ao salvar os dados da requisição.", $dados);
  }

  fclose($arquivo);
}

function requisicao($metodo, $body, $parametros)
{
  switch ($metodo) {
    case 'POST':
      salvar($body);
      break;
    case 'GET':
      resposta(200, "Requisição realizada com sucesso!", $body);
      break;
  }
}

// Obtém o método HTTP, body e parâmetros da requisição
$metodo = $_SERVER['REQUEST_METHOD'];
$parametros = explode('/', trim($_SERVER['REQUEST_URI'], '/'));
$body = json_decode(file_get_contents('php://input'), true);

try {
  requisicao($metodo, $body, $parametros);
} catch (Exception $e) {
  resposta(400, $e->getMessage(), $e);
}

Para ter um ter um SSL válido, você deve entrar em contato com uma Autoridade Certificadora e gerar a chave privada server_ssl.key.pem e uma pública server_ssl.crt.pem, assim você valida a integridade da conexão. Você consegue realizar isso de forma gratuita utilizando um utilitário como o Certbot por exemplo.

Skip-mTLS

Para hospedagem em servidores compartilhados, pode haver restrições em relação à inserção de certificados gerados por outra entidade, como o nosso CA, por exemplo. Por isso, disponibilizamos a opção skip mTLS, que permite o cadastro do webhook sem a necessidade de validação mTLS.

Atenção!

É importante destacar que sempre enviaremos o certificado nos webhooks, seja no cadastro ou na notificação de Pix. No entanto, quando o skip-mTLS é utilizado, você, pessoa integradora, fica responsável por validar o nosso certificado.

Caso opte por utilizar o atributo skip mTLS, ou seja, sem a validação mTLS no seu servidor, você deverá implementar medidas para garantir que quem está enviando os webhooks ao seu servidor é, de fato, a Efí.

Sugerimos as duas formas de validação a seguir, mas recomendamos fortemente que as utilize em conjunto:

Verifique o IP de comunicação: Você pode restringir a comunicação ao domínio do webhhook cadastrado para aceitar apenas mensagens do IP utilizado pela Efí.

IP utilizado atualmente em nossas comunicações: '34.193.116.226'.

Adicione uma hash à URL cadastrada no webhook: Crie um hmac (uma identificação própria) que será acrescentado ao final da URL no momento do cadastro do webhook. Essa hash 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 validar a presença da mesma.
Exemplo:
URL de notificação original: https://seu_dominio.com.br/webhook
Como deverá ser cadastrada com a hash: https://seu_dominio.com.br/webhook?hmac=xyz&ignorar=. O termo ignorar= servirá para tratar a adição do /pix no final da URL.

Como cadastrar o skip-mTLS:

Para configurar o webhook Pix, você deve utilizar o endpoint específico e passar no cabeçalho da requisição o parâmetro x-skip-mtls-checking com o valor true ou false dependendo se deseja habilitar ou desabilitar essa funcionalidade.

A imagem abaixo mostra como este parâmetro deve ser informado:

Gerenciamento de notificações

Esta seção reúne endpoints para gerenciamento de notificações por parte do PSP recebedor ao usuário recebedor.

Configurar o webhook Pix

Endpoint para configuração do serviço de notificações acerca de Pix recebidos. Pix oriundos de cobranças estáticas só serão notificados se estiverem associados a um txid.

Lembrete

Uma URL de webhook pode estar associada a várias chaves Pix.

Por outro lado, uma chave Pix só pode estar vinculada a uma única URL de webhook.

Informação

Ao cadastrar seu webhook, enviaremos uma notificação de teste para a URL cadastrada, porém quando de fato uma notificação for enviada, o caminho /pix será acrescentado ao final da URL cadastrada. Para não precisar de duas rotas distintas, você poder adicionar um parâmetro ?ignorar= ao final da URL cadastrada, para que o /pix não seja acrescentado na rota da sua URL.

PUT /v2/webhook/:chave

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

Requisição

Exemplo 1
Exemplo 2

{
  "webhookUrl": "https://exemplo-pix/webhook"
}

{
  "webhookUrl": "https://exemplo-pix/webhook?ignorar="
}

Respostas

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

🟢 201
🔴 400

Webhook para notificações acerca de Pix recebidos associados a um txid.

InvalidValueError
{
  "nome": "valor_invalido",
  "mensagem": "URL inválida"
}

OU

{
  "nome": "valor_invalido",
  "mensagem": "A URL do webhook deve usar o protocolo HTTPS"
}

OU

{
  "nome": "webhook_invalido",
  "mensagem": "A autenticação de TLS mútuo não está configurada na URL informada"
}

OU

{
  "nome": "webhook_invalido",
  "mensagem": "A URL informada está inacessível"
}

OU

{
  "nome": "webhook_invalido",
  "mensagem": "A URL informada atingiu o tempo limite de resposta"
}

OU

{
  "nome": "webhook_invalido",
  "mensagem": "A requisição na URL informada falhou com o erro: {{errno}}" //{{errno}} representa um código de erro do linux: https://man7.org/linux/man-pages/man3/errno.3.html Ex: ECONNRESET, EPIPE
}

OU

{
  "nome": "webhook_invalido",
  "mensagem": "A URL informada respondeu com o código HTTP {{httpStatus}}" // {{httpStatus}} representa o status HTTP que a url respondeu. Ex: 400, 403, 500.
}

OU

{
  "nome": "webhook_invalido",
  "mensagem": "Não foi possível receber uma resposta da URL informada"
}

Exibir informações do webhook Pix

Endpoint para recuperação de informações sobre o webhook pix.

GET /v2/webhook/:chave

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

Respostas

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

🟢 200

{
  "webhookUrl": "https://gn-pix-webhook.gerencianet.com.br/webhook/",
  "chave": "40a0932d-1918-4eee-845d-35a2da1690dc",
  "criacao": "2020-11-11T10:15:00.358Z"
}

Consultar lista de webhooks

Endpoint para consultar webhooks associados a chaves através de parâmetros como início e fim. Os atributos são inseridos como query params.

GET /v2/webhook

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

Requisição

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

/v2/webhook/?inicio=2020-10-22T16:01:35Z&fim=2020-10-23T16:01:35Z

Respostas

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

🟢 200
🔴 400

{
  "parametros": {
    "inicio": "2021-01-22T16:01:35.000Z",
    "fim": "2022-12-30T16:01:35.000Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 5
    }
  },
  "webhooks": [
    {
      "webhookUrl": "https://seudominio.com.br/gn/webhook/",
      "chave": "40a0932d-1618-4eee-845d-35a2da1590dc",
      "criacao": "2021-05-05T19:52:13.000Z"
    },
    {
      "webhookUrl": "https://.projetosseudominio.seudominio.com.br/gn/webhook/",
      "chave": "40a0932d-1918-0eee-845d-35a2da1690dc",
      "criacao": "2021-10-18T14:42:41.000Z"
    },
    {
      "webhookUrl": "https://seudominio.com.br/webhook/?ignorar=",
      "chave": "40a0032d-1918-45ee-845d-3562da1690dc",
      "criacao": "2021-11-03T12:25:15.000Z"
    }
  ]
}

{
  "nome": "valor_invalido",
  "mensagem": "Campo de data fim deve ser maior ou igual ao campo de data inicio"
}

Cancelar o webhook Pix

Endpoint para cancelamento do webhook pix.

DELETE /v2/webhook/:chave

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

Respostas

A resposta abaixo representa Sucesso(204) do consumo.

🟢 204

Webhook para notificações Pix foi cancelado.

Gerenciamento de notificações de recorrências de Pix Automático

Esta seção reúne endpoints para gerenciamento de notificações de de recorrências de Pix Automático por parte do PSP recebedor ao usuário recebedor.

Configurar o webhook de recorrência de Pix Automático

Endpoint para configuração do serviço de notificações acerca de recorrências de Pix Automático. Somente recorrências associadas a chave e conta serão notificadas.

Informação

PUT /v2/webhookrec

Requer autorização para o escopo: webhookrec.write

Requisição

Exemplo

{
  "webhookUrl": "https://usuario.recebedor.com/api/webhookrec/"
}

Respostas

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

🟢 200
🔴 400
🔴 403
🔴 404
🔴 503

Webhook para notificações acerca de Pix recebidos associados a um txid.

{
  "type": "https://pix.bcb.gov.br/api/v2/error/WebhookOperacaoInvalida",
  "title": "Webhook inválido.",
  "status": 400,
  "detail": "A presente requisição busca criar um webhook sem respeitar o _schema_ ou, ainda, com sentido semanticamente inválido."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Exibir informações do webhook de recorrência de Pix Automático

Endpoint para recuperação de informações sobre o webhook de recorrência de Pix Automático.

GET /v2/webhookrec

Requer autorização para o escopo: webhookrec.read

Respostas

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

🟢 200
🔴 403
🔴 404
🔴 503

{
  "webhookUrl": "https://usuario.recebedor.com/api/webhookrec/",
  "criacao": "2023-12-20T12:51:16.485Z"
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Cancelar o webhook de recorrência de Pix Automático

Endpoint para cancelamento do webhook de recorrência de Pix Automático.

DELETE /v2/webhookrec

Requer autorização para o escopo: webhookrec.write

Respostas

A resposta abaixo representa Sucesso(200) do consumo.

🟢 204
🔴 403
🔴 404
🔴 503

Webhook para notificações Pix foi cancelado.

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Gerenciamento de notificações de cobranças de Pix Automático

Esta seção reúne endpoints para gerenciamento de notificações de cobranças recorrentes de Pix Automático por parte do PSP recebedor ao usuário recebedor.

Configurar o webhook de cobrança de Pix Automático

Endpoint para configuração do serviço de notificações acerca de cobranças recorrentes de Pix Automático. Somente cobranças recorrentes de Pix Automático associadas ao usuário recebedor serão notificadas.

PUT /v2/webhookcobr

Requer autorização para o escopo: webhookcobr.write

Requisição

Exemplo

{
  "webhookUrl": "https://usuario.recebedor.com/api/webhookcobr/"
}

Respostas

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

🟢 200
🔴 400
🔴 403
🔴 404
🔴 503

Webhook para notificações acerca de Pix recebidos associados a um txid.

{
  "type": "https://pix.bcb.gov.br/api/v2/error/WebhookOperacaoInvalida",
  "title": "Webhook inválido.",
  "status": 400,
  "detail": "A presente requisição busca criar um webhook sem respeitar o _schema_ ou, ainda, com sentido semanticamente inválido."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Exibir informações do webhook de cobrança de Pix Automático

Endpoint para recuperação de informações sobre o webhook de cobrança de Pix Automático.

GET /v2/webhookcobr

Requer autorização para o escopo: webhookcobr.read

Respostas

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

🟢 200
🔴 403
🔴 404
🔴 503

{
  "webhookUrl": "https://usuario.recebedor.com/api/webhookcobr/",
  "criacao": "2023-12-20T12:51:16.485Z"
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Cancelar o webhook de cobrança de Pix Automático

Endpoint para cancelamento do webhook de cobrança de Pix Automático.

DELETE /v2/webhookcobr

Requer autorização para o escopo: webhookcobr.write

Respostas

A resposta abaixo representa Sucesso(200) do consumo.

🟢 204
🔴 403
🔴 404
🔴 503

Webhook para notificações Pix foi cancelado.

{
  "type": "https://pix.bcb.gov.br/api/v2/error/AcessoNegado",
  "title": "Acesso Negado",
  "status": 403,
  "detail": "Requisição de participante autenticado que viola alguma regra de autorização."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/ServicoIndisponivel",
  "title": "Serviço Indisponível",
  "status": 503,
  "detail": "Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."
}

Reenviar webhook Pix

Endpoint que permite reenviar webhook pix.

Atenção!

O endpoint de reenvio de webhook Pix não se aplica aos webhooks do Pix Automático.

Atenção!

É possível solicitar o reenvio de Webhooks para transações que ocorreram a partir do dia 27/12 às 10:00 da manhã.

O reenvio de webhook para uma transação fica disponível por um prazo máximo de 30 dias.

A tentativa de reenvio ocorre uma vez para cada webhook, NÃO existe reagendamentos como ocorre no envio normal. Caso o servidor do cliente esteja inoperante, o cliente terá que solicitar novamente o reenvio.

Nos casos de webhooks de devoluções (recebimento e envio) ocorre o reenvio de um webhook com todo o array de devolução ao invés de um webhook por devolução. Por exemplo, se você realizar duas devoluções relacionadas a um mesmo endToEndId, no envio, você receberá dois webhooks distintos. Porém, ao solicitar o reenvio, receberá apenas um webhook.

POST /v2/gn/webhook/reenviar

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

Requisição

Exemplo

{
  "tipo": "PIX_RECEBIDO",
  "e2eids": [
    "E09089356202412261300API229e5352",
    "E09089356202412261300API3149af57"
  ]
}

Respostas

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

🟢 202
🔴 400
🔴 422
🔴 500

Webhook enviado

{
  "type": "https://pix.bcb.gov.br/api/v2/error/Desconhecido",
  "title": "Operação Inválida",
  "status": 400,
  "detail": "A requisição que busca reenviar os webhooks não respeita o schema ou está semanticamente errada.",
  "violacoes": [
      {
          "razao": "O campo reenviarWebhook.tipo deve ser um dos seguintes valores: PIX_RECEBIDO, PIX_ENVIADO, DEVOLUCAO_RECEBIDA, DEVOLUCAO_ENVIADA.",
          "propriedade": "reenviarWebhook.body.tipo"
      }
  ]

  Ou

  {
      "razao": "O array reenviarWebhook.e2eids deve conter pelo menos 1 e2eid.",
      "propriedade": "reenviarWebhook.body.e2eids"
  }

  Ou

  {
      "razao": "O array reenviarWebhook.e2eids contém itens duplicados.",
      "propriedade": "reenviarWebhook.body.e2eids"
  }

  Ou

  {
      "razao": "O array reenviarWebhook.e2eids deve conter no máximo 1000 e2eids.",
      "propriedade": "reenviarWebhook.body.e2eids"
  }

  Ou

  {
      "razao": "O objeto reenviarWebhook.body deve conter o campo tipo.",
      "propriedade": "reenviarWebhook.body"
  }

  Ou

  {
      "razao": "O objeto reenviarWebhook.body deve conter o campo e2eids.",
      "propriedade": "reenviarWebhook.body"
  }

  Ou

  {
      "razao": "O objeto reenviarWebhook.body não respeita o schema.",
      "propriedade": "reenviarWebhook.body"
  }
} 

{
  "type": "https://pix.bcb.gov.br/api/v2/error/WebhooksOperacaoInvalida",
  "title": "Operação Inválida",
  "status": 422,
  "detail": "A requisição que busca solicitar o reenvios de webhooks não respeita o schema ou está semanticamente errada.",
  "violacoes": [
      {
          "razao": "Nenhuma devolução foi encontrada para os e2eids informados.",
          "propriedade": "body.e2eIds"
      }
  ]
}

{
  "type": "https://pix.bcb.gov.br/api/v2/error/WebhooksErroInterno",
  "title": "Erro Interno",
  "status": 500,
  "detail": "Funcionalidade desabilitada em ambiente de homologação."
}

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/pix quando há uma alteração no status do Pix.

Informação

Para testar os endpoints de cobrança Pix Cob e Pix CobV em ambiente de homologação, é possível simular todos os status retornados pela nossa API e webhook.

Cobranças com valor entre R$ 0.01 à R$ 10.00 são confirmadas, e você receberá a informação via Webhook.
Cobranças com valor acima de R$ 10.00 permanecem ativas, sem confirmação, e não há webhook nesses casos.

Requisição

Quando ocorre uma alteração no status de uma transação Pix associada à chave cadastrada, 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.

Recebido
Devolução
Envio

// Pix recebido
{
  "pix": [
    {
      "endToEndId": "E1803615022211340s08793XPJ",
      "txid": "fc9a43k6ff384ryP5f41719",
      "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
      "valor": "0.01",
      "horario": "2020-12-21T13:40:34.000Z",
      "infoPagador": "pagando o pix"
    }
  ]
}

// Pix recebido com dados do pagador CPF
{
  "pix": [
    {
      "endToEndId": "E1803615022211340s08793XPJ",
      "txid": "fc9a43k6ff384ryP5f41719",
      "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
      "valor": "0.01",
      "horario": "2020-12-21T13:40:34.000Z",
      "infoPagador": "pagando o pix",
      "gnExtras": {
        "pagador": {
          "nome": "GORBADOCK OLDBUCK",
          "cpf": "***.123.456-**",
          "codigoBanco":"00416968"
        }
      }
    }
  ]
}
// Pix recebido com dados do pagador CNPJ
{
  "pix": [
    {
      "endToEndId": "E090893562024101648554e991d24ccb",
      "txid": "c547f5f498c0420a9d1db5970a0d34c3",
      "chave": "ca179e79-df8a-4717-b915-549f1de4d31d",
      "valor": "0.01",
      "horario": "2024-10-16T18:56:36.000Z",
      "gnExtras": {
        "pagador": {
          "nome": "EFI SA - INSTITUICAO DE PAGAMENTO",
          "cnpj": "09089356000118",
          "codigoBanco": "09089356"
        }
      }
    }
  ]
}
// Pix recebido com Split
{
  "pix": [
    {
      "endToEndId": "E1803615022211340s08793XPJ",
      "txid": "fc9a43k6ff384ryP5f41719",
      "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
      "valor": "0.01",
      "horario": "2020-12-21T13:40:34.000Z",
      "infoPagador": "Teste",
      "gnExtras": {
        "split": {
          "id": "f659e882b00440ef9f07538fb697a6b2",
          "revisao": 0
        }
      }
    }
  ]
}
// Pix recebido com tarifa informada
{
  "pix": [
    {
      "endToEndId": "E1803615022211340s08793XPJ",
      "txid": "fc9a43k6ff384ryP5f41719",
      "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
      "valor": "0.10",
      "horario": "2020-12-21T13:40:34.000Z",
      "infoPagador": "pagando o pix",
      "gnExtras": {
        "tarifa": "0.01"
      }
    }
  ]
}

// Devolução enviada
{
  "pix": [
    {
      "endToEndId": "E12345678202009091221syhgfgufg",
      "txid": "c3e0e7a4e7f1469a9f782d3d4999343c",
      "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
      "valor": "110.00",
      "horario": "2020-09-09T20:15:00.358Z",
      "infoPagador": "0123456789",
      "devolucoes": [
        {
          "id": "123ABC",
          "rtrId": "D12345678202009091221abcdf098765",
          "valor": "110.00",
          "natureza": "MED_FRAUDE",
          "horario": {
            "solicitacao": "2020-09-09T20:15:00.358Z"
          },
          "status": "DEVOLVIDO"
        }
      ]
    }
  ]
}

// Devolução rejeitada
{
  ...
      "devolucoes": [
        {
          ...,
          "status": "NAO_REALIZADO",
          "motivo": "Saldo insuficiente para realizar a devolução."
        }
      ]
  ...
}

// Pix enviado
{
  "pix": [
    {
      "endToEndId": "E090893562021030PIf25a7868",
      "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
      "tipo": "SOLICITACAO",
      "status": "REALIZADO",
      "valor": "0.01",
      "horario": "2021-03-04T20:39:47.000Z",
      "gnExtras": {
        "idEnvio": "123ABC"
      }
    }
  ]
}

// Pix enviado com dados do favorecido
{
  "pix": [
    {
      "endToEndId": "E09089356202501031120API37548077",
      "chave": "[email protected]",
      "tipo": "SOLICITACAO",
      "status": "REALIZADO",
      "valor": "0.01",
      "horario": "2025-01-03T11:20:41.000Z",
      "infoPagador": "Envio de Pix Id: t9tKDtGL7SYrp4j8NypgfnKPeIx5v",
      "gnExtras": {
        "favorecido": {
          "nome": "NOME DO FAVORECIDO",
          "cpf": "***.123.456-**",
          "contaBanco": {
            "codigoBanco": "60746948",
            "agencia": "1234",
            "conta": "1234567",
            "tipoConta": "cacc"
          }
        },
        "idEnvio": "t9tKDtGL7SYrp4j8NypgfnKPeIx5v"
      }
    }
  ]
}

// Pix rejeitado
{
  "pix": [
      {
          "endToEndId": "E090893562021030PIf25a7868",
          "chave": "2c3c7441-b91e-4982-3c25-6105581e18ae",
          "tipo": "SOLICITACAO",
          "status": "NAO_REALIZADO",
          "valor": "0.01",
          "horario": null,
          "infoPagador": "0123456789",
          "gnExtras": {
              "idEnvio": "123ABC",
              "erro": {
                  "codigo": "AC03",
                  "origem": "PSP do usuário recebedor",
                  "motivo": "Número da agência e/ou conta transacional do usuário recebedor inexistente ou inválido"
              }
          }
      }
  ]
}

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é 9 novas tentativas de notificação. A primeira tentativa ocorre imediatamente. O tempo de reagendamento inicia a partir da segunda tentativa, seguindo uma escala progressiva. Após a nona tentativa, nenhum novo reenvio será realizado, conforme mostra a tabela abaixo.

N° da tentativa	Tempo (em minutos)	Tempo (em segundos)
1	Imediata	0
2	5	300
3	5	300
4	5	300
5	10	600
6	20	1200
7	40	2400
8	80	4800
9	160	9600

Dica

Após a nona tentativa, como não haverá mais reenvios automáticos, você poderá utilizar o endpoint de reenviar webhook Pix, caso seja necessário.

Webhooks

Entendendo o padrão mTLS​

Exemplos de configurações de servidor​

Skip-mTLS

Como cadastrar o skip-mTLS:

Gerenciamento de notificações​

Configurar o webhook Pix​

Exibir informações do webhook Pix​

Consultar lista de webhooks​

Cancelar o webhook Pix​

Gerenciamento de notificações de recorrências de Pix Automático​

Configurar o webhook de recorrência de Pix Automático​

Exibir informações do webhook de recorrência de Pix Automático​

Cancelar o webhook de recorrência de Pix Automático​

Gerenciamento de notificações de cobranças de Pix Automático​

Configurar o webhook de cobrança de Pix Automático​

Exibir informações do webhook de cobrança de Pix Automático​

Cancelar o webhook de cobrança de Pix Automático​

Reenviar webhook Pix​

Recebendo Callbacks​

Requisição​

Entendendo o padrão mTLS

Exemplos de configurações de servidor

Gerenciamento de notificações

Configurar o webhook Pix

Exibir informações do webhook Pix

Consultar lista de webhooks

Cancelar o webhook Pix

Gerenciamento de notificações de recorrências de Pix Automático

Configurar o webhook de recorrência de Pix Automático

Exibir informações do webhook de recorrência de Pix Automático

Cancelar o webhook de recorrência de Pix Automático

Gerenciamento de notificações de cobranças de Pix Automático

Configurar o webhook de cobrança de Pix Automático

Exibir informações do webhook de cobrança de Pix Automático

Cancelar o webhook de cobrança de Pix Automático

Reenviar webhook Pix

Recebendo Callbacks

Requisição