Pular para o conteúdo principal

Gestão de Pix

Os endpoints a seguir trazem as funcionalidades disponíveis para a gestão das transações Pix, isto é, a manutenção dos recebimentos e envios de valores através do arranjo de pagamentos Pix.


Consultar Pix​

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

Atenção!

Este endpoint retorna apenas informações sobre Pix recebidos.


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


Respostas

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

{
  "endToEndId": "E12345678202009091221abcdef12345",
  "txid": "cd1fe328c875481285a6f233ae41b662",
  "valor": "100.00",
  "horario": "2020-09-10T13:03:33.902Z",
  "infoPagador": "Reforma da casa",
  "devolucoes": [
    {
      "id": "000AAA111",
      "rtrId": "D12345678202009091000abcde123456",
      "valor": "11.00",
      "horario": {
        "solicitacao": "2020-09-10T13:03:33.902Z"
      },
      "status": "EM_PROCESSAMENTO"
    }
  ]
}

Consultar Pix Recebidos​

Endpoint para consultar vários Pix recebidos.

GET /v2/pix
Requer autorização para o escopo: cobv.read


Requisição

Este endpoint dispõe de filtros para afunilar os resultados. Todos os filtros são do tipo query params, portanto devem ser enviados pela URL, como exemplificado no trecho de código abaixo.

/v2/pix?inicio=2020-04-01T00:00:00Z&fim=2020-04-01T23:59:59Z

Os filtros inicio e fim definem um intervalo de datas em que os Pix devem estar compreendidos para serem retornados. Esses filtros são obrigatórios.

Respostas

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

{
  "parametros": {
    "inicio": "2022-01-01T00:00:00.000Z",
    "fim": "2022-12-31T23:00:00.000Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 2,
      "quantidadeTotalDeItens": 150
    }
  },
  "pix": [
    {
      "endToEndId": "E182361232022110114206014506ed00",
      "txid": "465669b3847d4a30ae14848c5d4d1683",
      "valor": "0.01",
      "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
      "horario": "2022-11-01T14:20:41.425Z"
    },
    {
      "endToEndId": "E18236129202210311159s01f572d8b1",
      "txid": "0002712070000000000000209BONAE2",
      "valor": "5.00",
      "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
      "horario": "2022-10-31T11:59:13.220Z"
    },
    {
      "endToEndId": "E18236126202210091755s13093ea838",
      "txid": "fc9a4386fefdh964b5dbc6c91a8722d5",
      "valor": "0.02",
      "chave": "5f84a4c5-c5cb-4590-9f13-7eb4d419dacc",
      "horario": "2022-10-19T17:56:09.173Z",
      "devolucoes": [
        {
          "id": "fc9a4386fefdh964b5dbc6c91a8722d5",
          "rtrId": "D09089556202210191757eeb3cf6972c",
          "valor": "0.01",
          "horario": {
            "solicitacao": "2022-10-19T17:57:02.000Z",
            "liquidacao": "2022-10-19T17:57:03.000Z"
          },
          "status": "DEVOLVIDO"
        },
        {
          "id": "fc9a4386fefdh964b5dbc6c91a8722d6",
          "rtrId": "D09089356002210191757c95a3620972",
          "valor": "0.01",
          "horario": {
            "solicitacao": "2022-10-19T17:57:33.000Z",
            "liquidacao": "2022-10-19T17:57:35.000Z"
          },
          "status": "DEVOLVIDO"
        }
      ]
    }
  ]
}

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 habilitar o endpoint pix/enviar em produção, é necessário preencher este formulário. Após o preenchimento, basta aguardar que entraremos em contato.

Para utilização do endpoint de Requisitar envio de Pix, além da liberação do escopo pix.send é 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.

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



PUT /v2/gn/pix/:idEnvio
Requer autorização para o escopo: pix.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": "12453567890123456789",
  "e2eId": "E09089356202011251226APIff82f2e5",
  "valor": "12.31",
  "horario": {
    "solicitacao": "2021-11-25T12:26:42.905Z"
  },
  "status":"EM_PROCESSAMENTO"
}

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

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

Consultar lista de Pix enviados​

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

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

Solicitar devolução​

Este é o endpoint usado para solicitar uma devolução usando o e2eId do Pix e o ID da devolução. O motivo atribuído à PACS.004 será “Devolução solicitada pelo usuário recebedor do pagamento original”, com a sigla “MD06”, conforme consta na aba RTReason da PACS.004 no Catálogo de Mensagens do Pix.

PUT /v2/pix/:e2eId/devolucao/:id
Requer autorização para o escopo: pix.write


Respostas

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

{
  "id": "123456",
  "rtrId": "D12345678202009091000abcde123456",
  "valor": "7.89",
  "horario": {
    "solicitacao": "2020-09-11T15:25:59.411Z"
  },
  "status": "EM_PROCESSAMENTO"
}
Instruções

Envio da Devolução pelo id através do endpoint PUT/v2/pix/:e2eId/devolucao/:id .

Você pode simular a rejeição da devolução usando o valor de R$ 0,01. Essas devoluções serão rejeitadas e notificadas para simular o fluxo de produção. Devoluções com valores diferentes de R$ 0,01, seguirão o fluxo normal de devolução com várias outras validações. Se estiverem em conformidade, serão confirmadas e notificadas, simulando o fluxo de produção.



Consultar devolução​

Endpoint para consultar uma devolução através de um e2eId do Pix e do ID da devolução.

GET /v2/pix/:e2eId/devolucao/:id
Requer autorização para o escopo: pix.read


Respostas

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

{
  "id": "123456",
  "rtrId": "D12345678202009091000abcde123456",
  "valor": "7.89",
  "horario": {
    "solicitacao": "2020-09-11T15:25:59.411Z"
  },
  "status": "EM_PROCESSAMENTO"
}
Instruções

Consulta da Devolução Enviada pelo id através do endpoint GET/v2/pix/:e2eId/devolucao/:id .

É possível consultar informações de uma devolução simulada pelo endpoint de Envio de Devolução no ambiente de homologação.

A funcionalidade ocorre exatamente como no ambiente de produção.


Última atualização em