Pular para o conteúdo principal

Envio e Pagamento Pix

Os endpoints a seguir trazem as funcionalidades disponíveis para a gestão do Envio de Pix e do Pagamento de QR Codes Pix.


Requisitar envio de Pix​

Endpoint destinado a realizar o envio direto de um Pix para uma chave Pix cadastrada em um PSP seja da Efí ou outro. Esse endpoint poderá sofrer alterações quando entrar no escopo de padronização do BACEN. Neste caso, os clientes habilitados serão avisados com antecedência.

Para utilização do endpoint de Requisitar envio de Pix, além da liberação do escopo pix.send na conta, é necessário que a chave Pix do pagador tenha um webhook associado a ela. Por meio do webhook a Efí irá informar a você se o envio do Pix foi realizado com sucesso ou não.

Caso a sua aplicação tenha sido criada anterior à data 29/07/2024, será necessário alterar os escopos (?), desativando e ativando novamente o escopo pix.send, dentro de API Pix, para utilizar o recurso.

Idempotência

O endpoint PUT /v3/gn/pix/:idEnvio é idempotente.

Isso significa que, se uma transação não for concluída com sucesso (por exemplo, devido a falha de comunicação ou tempo de resposta excedido), você deve reenviar a requisição utilizando o mesmo identificador (idEnvio). Dessa forma, o sistema reconhecerá que se trata da mesma operação e garantirá que nenhum valor seja debitado mais de uma vez, evitando o envio de múltiplos Pix. Por outro lado, se a transação anterior for concluída com sucesso, qualquer novo envio deve utilizar um novo identificador (idEnvio), garantindo que uma nova transação seja criada.

A idempotência, portanto, assegura que cada idEnvio represente exatamente uma transação, independentemente do número de tentativas de envio.

Importante!

Durante o processo de envio de um Pix, pode ocorrer uma falha na faixa 5XX (erros internos do servidor). Nesses casos, existe a possibilidade de a transação ter sido processada com sucesso, mesmo que a resposta da API indique erro.

Por isso, não é recomendado realizar uma nova tentativa de envio imediatamente após receber uma resposta 5XX.

Recomendações:

  • Aguarde o retorno do webhook de notificação de status do Pix enviado.
  • Caso o webhook não seja recebido dentro do tempo esperado, antes de tentar um novo envio você pode:
    • Consultar o endpoint: GET /v2/gn/pix/enviados/id-envio/:idEnvio para verificar o status do envio original.
    • Realizar uma nova tentativa com o mesmo idEnvio. Dessa forma, mesmo que o envio anterior tenha sido processado com sucesso, o valor não será debitado novamente, garantindo que não ocorram envios duplicados e reforçando a confiabilidade e segurança no processo de envio de Pix.
  • Só realize uma nova solicitação de envio (com idEnvio diferente) se for confirmado que a transação anterior não foi concluída.

Instruções para o ambiente de Produção

Ao consumir o endpoint de envio de Pix, em produção, fique atento aos seguintes limites diários pré-aprovados de cada conta:

  • Contas Efí Pro: R$ 0,30 - Para você mesmo ou contatos seguros.
  • Contas Efi Empresas: R$ 1,00 - Para você mesmo ou contatos seguros.

É um requisito do endpoint, que tenha conta do tipo Efi Empresas para realizar alterações nos limites de envio.


Instruções para testes em Homologação

Se você precisa testar o endpoint de envio de Pix, temos um ambiente funcional de homologação onde é possível simular todos os status retornados pela nossa API e pelo webhook.

  • Se o valor do Pix está entre R$ 0.01 à R$ 10.00:
    Pix é confirmado, informação virá via Webhook.
  • Se o valor do Pix está entre R$ 10.01 à R$ 20.00:
    Pix é rejeitado, informação virá via Webhook
  • Se o valor do Pix é acima de R$ 20.00:
    Pix é rejeitado já na requisição, informação não virá via Webhook.
  • Os pagamentos enviados com valor de R$ 4,00 irão gerar duas devoluções recebidas no valor de R$ 2,00.
  • Os pagamentos enviados com valor de R$ 5,00 irão gerar uma devolução recebida no valor de R$ 5,00.
  • Ao solicitar o envio de pix com os valores que geram devoluções (R$4,00 e R$5,00), um webhook de devolução será disparado, contendo o campo natureza: ORIGINAL.
  • Os pagamentos enviados via chave só serão confirmados ou rejeitados se for utilizada a chave de homologação: [email protected]. Caso contrário, um erro de chave inválida será informado.
  • Os pagamentos enviados via dados bancários não sofrem alterações.

Atenção!

Para melhorar o desempenho do serviço e evitar conflitos de saldo, recomendamos que o envio de Pix por API seja condicionado à conclusão da transação anterior, que é notificada por meio do webhook. Se essa prática não for seguida e várias requisições de envio forem feitas ao mesmo tempo, o integrador pode enfrentar problemas no envio.

Gostaríamos de ressaltar que essa rota será identificado como v3, mas quem utiliza a rota /v2/gn/pix/:idEnvio não precisa se preocupar, pois ela continuará funcionando normalmente. Essa nova versão traz uma melhoria importante, incluindo a sinalização do número de fichas disponíveis no balde (Bucket-Size), que será retornado no header da resposta. Por isso sugerimos que utilize a nova versão.


PUT /v3/gn/pix/:idEnvio
Requer autorização para o escopo: pix.send


Requisição

//Exemplo de transferência para chave Pix
{
  "valor": "12.34",
  "pagador": {
    "chave": "19974764017",
    "infoPagador": "Segue o pagamento da conta"
  },
  "favorecido": {
    "chave": "joã[email protected]"
  }
}

Respostas

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

{
  "idEnvio": "12453567890123456789",
  "e2eId": "E09089356202011251226APIff82f2e5",
  "valor": "12.31",
  "horario": {
    "solicitacao": "2021-11-25T12:26:42.905Z"
  },
  "status":"EM_PROCESSAMENTO"
}

Cabeçalhos da resposta (Headers)
Caso 1: Balde de fichas vazio
  • Bucket-Size = número inteiro que representa o tamanho do balde de fichas do usuário. Esse caso ilustra um cenário onde o usuário está com o balde de fichas vazio e, consequentemente, este cabeçalho terá o valor 0 (zero); e
  • Retry-After = número inteiro que representa a quantidade de tempo em segundos para o usuário tentar novamente.
Caso 2: Tamanho do Balde de fichas
  • Bucket-Size = número inteiro que representa o tamanho do balde de fichas do usuário. Esse caso ilustra um cenário onde o usuário possui fichas no balde, logo o cabeçalho terá um valor maior que zero. Por exemplo: 80, que representa 80 fichas restantes no balde de fichas.

Requisitar envio de Pix para contas de mesma titularidade​

Endpoint utilizado para realizar transferências via Pix exclusivamente entre contas de mesma titularidade, podendo ser outras contas que o cliente tenha no Efí ou em outras instituições financeiras.

Para utilização do endpoint de Requisitar envio de Pix para mesma titularidade, além da liberação do escopo gn.pix.sameownership.send na conta, é necessário que a chave Pix do pagador tenha um webhook associado a ela. Por meio do webhook a Efí irá informar a você se o envio do Pix foi realizado com sucesso ou não.

Idempotência

O endpoint PUT /v3/gn/pix/:idEnvio é idempotente.

Isso significa que, se uma transação não for concluída com sucesso (por exemplo, devido a falha de comunicação ou tempo de resposta excedido), você deve reenviar a requisição utilizando o mesmo identificador (idEnvio). Dessa forma, o sistema reconhecerá que se trata da mesma operação e garantirá que nenhum valor seja debitado mais de uma vez, evitando o envio de múltiplos Pix. Por outro lado, se a transação anterior for concluída com sucesso, qualquer novo envio deve utilizar um novo identificador (idEnvio), garantindo que uma nova transação seja criada.

A idempotência, portanto, assegura que cada idEnvio represente exatamente uma transação, independentemente do número de tentativas de envio.

Atenção!

Este endpoint está disponível apenas no ambiente de Produção.


Importante!

Durante o processo de envio de um Pix, pode ocorrer uma falha na faixa 5XX (erros internos do servidor). Nesses casos, existe a possibilidade de a transação ter sido processada com sucesso, mesmo que a resposta da API indique erro.

Por isso, não é recomendado realizar uma nova tentativa de envio imediatamente após receber uma resposta 5XX.

Recomendações:

  • Aguarde o retorno do webhook de notificação de status do Pix enviado.
  • Caso o webhook não seja recebido dentro do tempo esperado, antes de tentar um novo envio você pode:
    • Consultar o endpoint: GET /v2/gn/pix/enviados/id-envio/:idEnvio para verificar o status do envio original.
    • Realizar uma nova tentativa com o mesmo idEnvio. Dessa forma, mesmo que o envio anterior tenha sido processado com sucesso, o valor não será debitado novamente, garantindo que não ocorram envios duplicados e reforçando a confiabilidade e segurança no processo de envio de Pix.
  • Só realize uma nova solicitação de envio (com idEnvio diferente) se for confirmado que a transação anterior não foi concluída.

Instruções para o ambiente de Produção

Ao consumir o endpoint de envio de Pix, em produção, fique atento aos seguintes limites diários pré-aprovados de cada conta:

  • Contas Efí Pro: R$ 0,30 - Para você mesmo ou contatos seguros.
  • Contas Efi Empresas: R$ 1,00 - Para você mesmo ou contatos seguros.

É um requisito do endpoint, que tenha conta do tipo Efi Empresas para realizar alterações nos limites de envio.


Atenção!

Para melhorar o desempenho do serviço e evitar conflitos de saldo, recomendamos que o envio de Pix por API seja condicionado à conclusão da transação anterior, que é notificada por meio do webhook. Se essa prática não for seguida e várias requisições de envio forem feitas ao mesmo tempo, o integrador pode enfrentar problemas no envio.


PUT /v2/gn/pix/:idEnvio/mesma-titularidade
Requer autorização para o escopo: gn.pix.sameownership.send


Requisição

{
  "valor": "12.34",
  "pagador": {
    "chave": "19974764017",
    "infoPagador": "Segue o pagamento da conta"
  },
  "favorecido": {
    "chave": "joã[email protected]"
  }
}

Respostas

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

{
  "idEnvio": "d41d8de10f11b114e3910998ecdb8553",
  "e2eId": "E09089356202508131830API4a875212",
  "valor": "12.34",
  "horario": {
    "solicitacao": "2025-08-13T18:30:17.848Z"
  },
  "status": "EM_PROCESSAMENTO"
}

Cabeçalhos da resposta (Headers)
Caso 1: Balde de fichas vazio
  • Bucket-Size = número inteiro que representa o tamanho do balde de fichas do usuário. Esse caso ilustra um cenário onde o usuário está com o balde de fichas vazio e, consequentemente, este cabeçalho terá o valor 0 (zero); e
  • Retry-After = número inteiro que representa a quantidade de tempo em segundos para o usuário tentar novamente.
Caso 2: Tamanho do Balde de fichas
  • Bucket-Size = número inteiro que representa o tamanho do balde de fichas do usuário. Esse caso ilustra um cenário onde o usuário possui fichas no balde, logo o cabeçalho terá um valor maior que zero. Por exemplo: 80, que representa 80 fichas restantes no balde de fichas.

Consultar Pix enviado através do endToEndId​

Endpoint para consultar um Pix enviado através de seu e2eId.

GET /v2/gn/pix/enviados/:e2eId
Requer autorização para o escopo: gn.pix.send.read


Respostas

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

{ // Pix enviado através endpoint da API Pix para uma chave pix
  "endToEndId": "E09089356202210251208APIcdbe38b4",
  "idEnvio": "identificadoEnvio123456789",
  "valor": "0.01",
  "chave": "19974764017",
  "status": "REALIZADO",
  "infoPagador": "Segue o pagamento da conta (endpoint pix sent)",
  "horario": {
    "solicitacao": "2022-10-26T09:05:32.000Z",
    "liquidacao": "2022-10-26T09:05:31.000Z"
  },
  "favorecido": {
    "chave": "[email protected]",
    "identificacao": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
    },
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  }
}

Consultar Pix enviado através do Identificador da transação​

Endpoint para consultar um Pix enviado através do idEnvio.

GET /v2/gn/pix/enviados/id-envio/:idEnvio
Requer autorização para o escopo: gn.pix.send.read


Respostas

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

{ // Pix enviado através endpoint da API Pix para uma chave pix
  "endToEndId": "E09089356202210251208APIcdbe38b4",
  "idEnvio": "identificadoEnvio123456789",
  "valor": "0.01",
  "chave": "19974764017",
  "status": "REALIZADO",
  "infoPagador": "Segue o pagamento da conta (endpoint pix sent)",
  "horario": {
    "solicitacao": "2022-10-26T09:05:32.000Z",
    "liquidacao": "2022-10-26T09:05:31.000Z"
  },
  "favorecido": {
    "chave": "[email protected]",
    "identificacao": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
    },
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  }
}

Consultar lista de Pix enviados​

Endpoint para consultar vários Pix enviados.

Este endpoint possui filtros para afunilar os resultados da busca. Dentre todos os filtros disponíveis, os filtros inicio e fim são obrigatórios e representam o intervalo de datas em que as cobranças consultadas devem estar compreendidas.

GET /v2/gn/pix/enviados
Requer autorização para o escopo: gn.pix.send.read


Requisição

Para obter o resultado da consulta é necessário informar os parâmetros inicio e fim, como exibido no trecho de código abaixo. Esses parâmetros restringem os resultados para os Pix enviados compreendidos nesse intervalo de datas.

/v2/gn/pix/enviados?inicio=2022-01-01T00:00:00.000Z&fim=2022-12-31T23:59:59.000Z

Respostas

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

 Pix enviado através endpoint da API Pix para uma chave pix
{ 
  "endToEndId": "E09089356202210251208APIcdbe38b4",
  "idEnvio": "identificadoEnvio123456789",
  "valor": "0.01",
  "chave": "19974764017",
  "status": "REALIZADO",
  "infoPagador": "Segue o pagamento da conta (endpoint pix sent)",
  "horario": {
    "solicitacao": "2022-10-26T09:05:32.000Z",
    "liquidacao": "2022-10-26T09:05:31.000Z"
  },
  "favorecido": {
    "chave": "[email protected]",
    "identificacao": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
    },
    "contaBanco": {
      "codigoBanco": "09089356"
    }
  }
}

Pagar QR Code Pix​

Endpoint que permite pagar um QR Code Pix via API.

O endpoint de pagar um QR Code Pix via API é semelhante ao de enviar Pix, pois o envio em questão será destinado a pagar a cobrança especificada no campo pixCopiaECola. Esse endpoint poderá sofrer alterações quando entrar no escopo de padronização do BACEN. Neste caso, os clientes habilitados serão avisados com antecedência.

Para utilização do endpoint Pagar QR Code Pix, além da liberação do escopo gn.qrcodes.pay, é necessário que a chave Pix do pagador tenha um webhook associado a ela. Por meio do webhook a Efí irá informar a você se o pagamento foi realizado com sucesso ou não.

Importante!

Para pagar uma cobrança via API é necessário informar o idEnvio, assim como acontece no envio comum. Este identificador deve ser único tanto para envios comuns quanto para envios de pagamentos de QR Code;

Para consumir o endpoint de pagamento de QR Code Pix não é necessário um prévio consumo do endpoint de detalhar QR Code Pix. O endpoint de detalhar é complementar ao de pagamento, ou seja, o integrador pode consumir o endpoint de detalhamento, conferir as informações e, posteriormente, consumir o endpoint de pagamento. Entretanto, o integrador tem liberdade de consumir o endpoint de pagamento diretamente;


PUT /v2/gn/pix/:idEnvio/qrcode
Requer autorização para o escopo: gn.qrcodes.pay


Requisição

{
  "pagador": {
    "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
    "infoPagador": "Pagamento de QR Code via API Pix"
  },
  "pixCopiaECola": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2 41e0badf811a4ce6ad8a80b306821fce5204000053000065802BR5905EFISA6008SAOPAULO60070503***61040000"
}

Respostas

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

{
  "idEnvio": "12453567890123456789",
  "e2eId": "E09089356202011251226APIff82f2e5",
  "valor": "12.31",
  "horario": {
    "solicitacao": "2021-11-25T12:26:42.905Z"
  },
  "status":"EM_PROCESSAMENTO"
}

Última atualização em