Gestão de Pix
Consultar Pix
Endpoint para consultar um Pix através de um e2eId
.
Este endpoint retorna apenas informações sobre Pix recebidos.
GET /v2/pix/:e2eId
pix.read
Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🟢 200
- 🔴 400
- 🔴 500
{
"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"
}
]
}
{
"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."
}
{
"endToEndId": "E12345678202009091221ghijk78901234",
"txid": "5b933948f3224266b1050ac54319e775",
"valor": "200.00",
"horario": "2020-09-10T13:03:33.902Z",
"infoPagador": "Revisão do carro"
}
{
"nome": "pix_nao_encontrado",
"mensagem": "Nenhum pix encontrado para o identificador informado"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao buscar o pix"
}
Consultar Pix Recebidos
Endpoint para consultar vários Pix recebidos.
GET /v2/pix
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.
- 🟢 200
- 🔴 400
- 🔴 500
{
"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"
}
]
}
]
}
{
"nome": "valor_invalido",
"mensagem": "Campo de data fim deve ser maior ou igual ao campo de data inicio"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao buscar pix recebidos"
}
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.
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.
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
pix.send
Requisição
- Exemplo 1
- Exemplo 2
- Exemplo 3
{
"valor": "12.34",
"pagador": {
"chave": "19974764017",
"infoPagador": "Segue o pagamento da conta"
},
"favorecido": {
"chave": "joã[email protected]"
}
}
{
"valor": "12.34",
"pagador": {
"chave": "19974764017",
"infoPagador": "Segue o pagamento da conta"
},
"favorecido": {
"contaBanco": {
"nome": "JOSE CARVALHO",
"cpf": "10519952057",
"codigoBanco": "09089356",
"agencia": "1",
"conta": "123453",
"tipoConta": "cacc"
}
}
}
//Exemplo validando o titular da chave
{
"valor": "12.34",
"pagador": {
"chave": "19974764017"
},
"favorecido": {
"chave": "joã[email protected]",
"cpf": "58629188090"
}
}
Respostas
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 409
- 🔴 422
- 🔴 500
{
"idEnvio": "12453567890123456789",
"e2eId": "E09089356202011251226APIff82f2e5",
"valor": "12.31",
"horario": {
"solicitacao": "2021-11-25T12:26:42.905Z"
},
"status":"EM_PROCESSAMENTO"
}
{
"nome": "documento_bloqueado",
"mensagem": "O documento desta conta tem bloqueios que impedem a emissão"
}
Ou
{
"nome": "chave_invalida",
"mensagem": "A chave informada não faz referência à conta Efíautenticada"
}
InvalidValueError
{
"nome": "valor_invalido",
"mensagem": "Campo valor.original deve ser maior que zero"
}
Ou
{
"nome": "valor_invalido",
"mensagem": "Campo calendario.expiracao deve ser maior que zero"
}
Ou
{
"nome": "valor_invalido",
"mensagem": "Documento CPF em devedor.cpf é inválido"
}
{
"nome": "valor_invalido",
"mensagem": "Documento CNPJ em devedor.cnpj é inválido"
}
{
"nome": "id_envio_duplicado",
"mensagem": "O id de envio informado já foi utilizado em outro pagamento"
}
{
"nome": "pagamento_negado",
"mensagem": "Pagamento negado por análises"
}
ApplicationError
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao validar a chave"
}
Consultar Pix enviado através do endToEndId
Endpoint para consultar um Pix enviado através de seu e2eId
.
GET /v2/gn/pix/enviados/:e2eId
gn.pix.send.read
Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🟢 200
- 🔴 404
{ // 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-**"
}
}
}
{ // Pix enviado através endpoint da API Pix via dados bancários
"endToEndId": "E09089356202210262021APIbh1457fa",
"idEnvio": "4",
"valor": "0.01",
"chave": "19974764017",
"status": "REALIZADO",
"infoPagador": "Segue o pagamento da conta (pix.sent dados bancarios)",
"horario": {
"solicitacao": "2022-10-26T17:21:19.000Z",
"liquidacao": "2022-10-26T17:21:18.000Z"
},
"favorecido": {
"contaBanco": {
"nome": "Francisco da Silva",
"cpf": "***.456.789-**",
"agencia": "1",
"conta": "12345678",
"tipoConta": "corrente"
}
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/PixEnviadoNaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Pix enviado não encontrado para o e2eId informado."
}
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
gn.pix.send.read
Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🟢 200
- 🔴 404
{ // 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-**"
}
}
}
{ // Pix enviado através endpoint da API Pix via dados bancários
"endToEndId": "E09089356202210262021APIbh1457fa",
"idEnvio": "4",
"valor": "0.01",
"chave": "19974764017",
"status": "REALIZADO",
"infoPagador": "Segue o pagamento da conta (pix.sent dados bancarios)",
"horario": {
"solicitacao": "2022-10-26T17:21:19.000Z",
"liquidacao": "2022-10-26T17:21:18.000Z"
},
"favorecido": {
"contaBanco": {
"nome": "Francisco da Silva",
"cpf": "***.456.789-**",
"agencia": "1",
"conta": "12345678",
"tipoConta": "corrente"
}
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/PixEnviadoNaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Pix enviado não encontrado para o idEnvio informado."
}
Consultar lista de Pix enviados
Endpoint para consultar um Pix enviado através de seu e2eId
.
GET /v2/gn/pix/enviados
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.
- 🟢 200
- 🟢 200
- 🔴 404
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-**"
}
}
}
Pix enviado através endpoint da API Pix via dados bancários
{
"endToEndId": "E09089356202210262021APIbh1457fa",
"idEnvio": "4",
"valor": "0.01",
"chave": "19974764017",
"status": "REALIZADO",
"infoPagador": "Segue o pagamento da conta (pix.sent dados bancarios)",
"horario": {
"solicitacao": "2022-10-26T17:21:19.000Z",
"liquidacao": "2022-10-26T17:21:18.000Z"
},
"favorecido": {
"contaBanco": {
"nome": "Francisco da Silva",
"cpf": "***.456.789-**",
"agencia": "1",
"conta": "12345678",
"tipoConta": "corrente"
}
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/PixEnviadoNaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Pix enviado não encontrado para o e2eId informado."
}
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
pix.write
Respostas
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 409
- 🔴 500
{
"id": "123456",
"rtrId": "D12345678202009091000abcde123456",
"valor": "7.89",
"horario": {
"solicitacao": "2020-09-11T15:25:59.411Z"
},
"status": "EM_PROCESSAMENTO"
}
{
"nome": "pix_nao_encontrado",
"mensagem": "Nenhum pix encontrado para o identificador informado"
}
{
"nome": "devolucao_id_duplicado",
"mensagem": "O id informado já foi utilizado em outra devolução"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao solicitar devolução"
}
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
pix.read
Respostas
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🟢 200
- 🔴 400
- 🔴 500
{
"id": "123456",
"rtrId": "D12345678202009091000abcde123456",
"valor": "7.89",
"horario": {
"solicitacao": "2020-09-11T15:25:59.411Z"
},
"status": "EM_PROCESSAMENTO"
}
{
"id": "502",
"rtrId": "D12345678202011111000fghij789012",
"valor": "20.00",
"horario": {
"solicitacao": "2020-09-11T15:25:59.411Z"
},
"status": "NAO_REALIZADO",
"motivo": "Negado por timeout"
}
{
"nome": "devolucao_nao_encontrada",
"mensagem": "Nenhuma devolução encontrada para o identificador informado"
}
OU
{
"nome": "pix_nao_encontrado",
"mensagem": "Nenhum pix encontrado para o identificador informado"
}
{
"nome": "erro_aplicacao",
"mensagem": "Ocorreu um erro ao buscar devolução"
}
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.