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.

Instruções para testes em Produção

Se você precisa testar 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.

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

Detalhar QR Code Pix​

Endpoint que permite detalhar as informações associadas a um QR Code Pix.

Atenção!

Atualmente, o escopo gn.qrcodes.read está desativado para manutenção, portanto este endpoint está temporariamente indisponível. Em breve, essa funcionalidade será restabelecida.


POST /v2/gn/qrcodes/detalhar
Requer autorização para o escopo: gn.qrcodes.read


Requisição

{
  "pixCopiaECola": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2 41e0badf811a4ce6ad8a80b306821fce5204000053000065802BR5905EFISA6008SAOPAULO60070503***61040000"
}

Respostas

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

{
  "tipoCob": "cob",
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "calendario": {
      "criacao": "2024-07-03T12:34:27.000Z",
      "apresentacao": "2024-07-03T12:34:40.238Z",
      "expiracao": 3600
  },
  "status": "ATIVA",
  "devedor": {
      "nome": "Francisco da Silva",
      "cpf": "***.456.789-**"
  },
  "recebedor": {
      "nome": "Empresa de Serviços SA",
      "cpf": "***.456.789-**"
  },
  "valor": {
      "final": "567.89"
  },
  "chave": "a1f4102e-a446-4a57-bcce-6fa48899c1d1",
  "solicitacaoPagador": "Cobrança dos serviços prestados."
}

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