O conjunto de endpoints a seguir é responsável pela gestão de cobranças recorrentes de Pix Automático. As cobranças, no contexto da API Pix representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.
InformaçãoAtenção: Até o dia 16/06/2025, as funcionalidades relacionadas ao Pix Automático disponíveis nesta documentação são exclusivamente para fins de teste e não refletem transações financeiras reais.
A configuração dos webhooks do Pix Automático está descrita nesta página.
Gerenciamento de recorrências de Pix Automático
Esta seção reúne endpoints destinados a lidar com gerenciamento de recorrências de Pix Automático.
Criar recorrência de Pix Automático
Endpoint para criar recorrência de Pix Automático.
Geralmente, o txid
é criado pelo usuário recebedor e está sob sua responsabilidade. No entanto, este endpoint é uma exceção a essa regra, e, nesse caso, o txid
será definido pela Efí.
POST /v2/rec
Requer autorização para o escopo: rec.write
Requisição
{
"vinculo": {
"contrato": "63100862",
"devedor": {
"cpf": "45164632481",
"nome": "Fulano de Tal"
},
"objeto": "Serviço de Streamming de Música."
},
"calendario": {
"dataFinal": "2025-04-01",
"dataInicial": "2024-04-01",
"periodicidade": "MENSAL"
},
"valor": {
"valorRec": "35.00"
},
"politicaRetentativa": "NAO_PERMITE",
"loc": 108,
"ativacao": {
"dadosJornada": {
"txid": "33beb661beda44a8928fef47dbeb2dc5"
}
}
}
{
"vinculo": {
"contrato": "998782003",
"devedor": {
"cpf": "2989131415",
"nome": "Beltrano da Silva"
},
"objeto": "Serviço de Plano de Saúde."
},
"calendario": {
"dataInicial": "2024-10-10",
"periodicidade": "ANUAL"
},
"valor": {
"valorMinimoRecebedor": "5000.00"
},
"politicaRetentativa": "PERMITE_3R_7D"
}
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"idRec": "RN1234567820240115abcdefghijk",
"vinculo": {
"contrato": "63100862",
"devedor": {
"cpf": "45164632481",
"nome": "Fulano de Tal"
},
"objeto": "Serviço de Streamming de Música."
},
"calendario": {
"dataFinal": "2025-04-01",
"dataInicial": "2024-04-01",
"periodicidade": "MENSAL"
},
"politicaRetentativa": "NAO_PERMITE",
"recebedor": {
"cnpj": 1602606113708,
"nome": "Empresa de Serviços SA"
},
"valor": {
"valorRec": "35.00"
},
"status": "CRIADA",
"loc": {
"criacao": "2023-12-10T07:10:05.115Z",
"id": 108,
"location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
"idRec": "RN1234567820240115abcdefghijk"
},
"ativacao": {
"dadosJornada": {
"tipoJornada": "JORNADA_3",
"txid": "33beb661beda44a8928fef47dbeb2dc5"
}
},
"atualizacao": [
{
"data": "2023-12-19T12:28:05.230Z",
"nome": "CRIADA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/RecOperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "A recorrência não respeita o schema.",
"violacoes": [
{
"razao": "O campo rec.calendario.dataInicial não respeita o schema.",
"propriedade": "rec.calendario.dataInicial"
}
]
}
{
"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/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."
}
Consultar recorrência de Pix Automático
Endpoint para consultar recorrência de Pix Automático.
GET /v2/rec/:idRec
Requer autorização para o escopo: rec.read
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"idRec": "RN1234567820240115abcdefghijk",
"status": "APROVADA",
"valor": {
"valorRec": "300.00"
},
"vinculo": {
"contrato": "98625023",
"devedor": {
"cpf": "87734514122",
"nome": "Fulano de Tal"
},
"objeto": "Serviços de Gestão de Imóveis"
},
"calendario": {
"dataFinal": "2028-09-01",
"dataInicial": "2024-02-01",
"periodicidade": "MENSAL"
},
"politicaRetentativa": "NAO_PERMITE",
"loc": {
"criacao": "2023-12-19T12:28:05.230Z",
"id": 5100,
"location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
"idRec": "RN1234567820240115abcdefghijk"
},
"pagador": {
"codMun": "2673833",
"cpf": "75633122216",
"ispbParticipante": "81102623"
},
"recebedor": {
"cnpj": "92221288310574",
"nome": "Imobiliária Bom Sucesso"
},
"atualizacao": [
{
"data": "2024-01-03T08:30:02.050Z",
"nome": "CRIADA"
},
{
"data": "2024-01-04T09:40:42.210Z",
"nome": "APROVADA"
}
],
"dadosQR": {
"jornada": "JORNADA_2",
"pixCopiaECola": "00020126180014br.gov.bcb.pix5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***80800014br.gov.bcb.pix2558pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002630462C9"
}
}
{
"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."
}
Revisar recorrência de Pix Automático
Endpoint para revisar recorrência de Pix Automático.
PATCH /v2/rec/:idRec
Requer autorização para o escopo: rec.write
Requisição
{
"loc": 108,
"vinculo": {
"devedor": {
"nome": "Fulano de Tal"
}
},
"calendario": {
"dataInicial": "2024-04-01"
},
"ativacao": {
"dadosJornada": {
"txid": "33beb661beda44a8928fef47dbeb2dc5"
}
}
}
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idRec": "RN1234567820240115abcdefghijk",
"vinculo": {
"contrato": "63100862",
"devedor": {
"cpf": "45164632481",
"nome": "Fulano de Tal"
},
"objeto": "Serviço de Streamming de Música."
},
"calendario": {
"dataFinal": "2025-04-01",
"dataInicial": "2024-04-01",
"periodicidade": "MENSAL"
},
"politicaRetentativa": "NAO_PERMITE",
"recebedor": {
"cnpj": 1602606113708,
"nome": "Empresa de Serviços SA"
},
"valor": {
"valorRec": "35.00"
},
"status": "CRIADA",
"loc": {
"criacao": "2023-12-10T07:10:05.115Z",
"id": 108,
"location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
"idRec": "RN1234567820240115abcdefghijk"
},
"ativacao": {
"dadosJornada": {
"tipoJornada": "JORNADA_3",
"txid": "33beb661beda44a8928fef47dbeb2dc5"
}
},
"atualizacao": [
{
"data": "2023-12-19T12:28:05.230Z",
"nome": "CRIADA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/RecOperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "A recorrência não respeita o schema.",
"violacoes": [
{
"razao": "O campo rec.calendario.dataInicial não respeita o schema.",
"propriedade": "rec.calendario.dataInicial"
}
]
}
{
"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."
}
Consultar lista de recorrências de Pix Automático
Endpoint para consultar lista de recorrências de Pix Automático.
Este endpoint possui filtros para afunilar os resultados da busca, tais como CPF/CNPJ e status. 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/rec
Requer autorização para o escopo: rec.read
Requisição
O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datas
inicio
e
fim
) e o formato em que esses parâmetros devem ser repassados.
/v2/rec?inicio=2025-01-01T16:01:35Z&fim=2025-11-30T20:10:00Z
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"parametros": {
"inicio": "2024-04-01T00:00:00Z",
"fim": "2024-04-01T23:59:59Z",
"paginacao": {
"paginaAtual": 0,
"itensPorPagina": 100,
"quantidadeDePaginas": 1,
"quantidadeTotalDeItens": 1
}
},
"recs": [
{
"idRec": "RN1234567820240115abcdefghijk",
"status": "APROVADA",
"valor": {
"valorRec": "300.00"
},
"vinculo": {
"contrato": "98625023",
"devedor": {
"cpf": "87734514122",
"nome": "Fulano de Tal"
},
"objeto": "Serviços de Gestão de Imóveis"
},
"calendario": {
"dataFinal": "2028-09-01",
"dataInicial": "2024-02-01",
"periodicidade": "MENSAL"
},
"politicaRetentativa": "NAO_PERMITE",
"loc": {
"criacao": "2023-12-19T12:28:05.230Z",
"id": 5100,
"location": "pix.example.com/qr/v2/rec/2353c790eefb11eaadc10242ac120002",
"idRec": "RN1234567820240115abcdefghijk"
},
"pagador": {
"codMun": "2673833",
"cpf": "75633122216",
"ispbParticipante": "81102623"
},
"recebedor": {
"cnpj": "92221288310574",
"nome": "Imobiliária Bom Sucesso"
},
"atualizacao": [
{
"data": "2024-01-03T08:30:02.050Z",
"nome": "CRIADA"
},
{
"data": "2024-01-04T09:40:42.210Z",
"nome": "APROVADA"
}
]
}
]
}
{
"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/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 solicitações de recorrências de Pix Automático
Esta seção reúne endpoints destinados a lidar com gerenciamento de solicitações de recorrências de Pix Automático.
Criar solicitação de confirmação de recorrência de Pix Automático
Endpoint para criar solicitação de confirmação de recorrência de Pix Automático.
POST /v2/solicrec
Requer autorização para o escopo: solicrec.write
Requisição
{
"idRec": "RN123456782024011577825445612",
"calendario": {
"dataExpiracaoSolicitacao": "2023-12-20T12:17:11.926Z"
},
"destinatario": {
"agencia": "2569",
"conta": "550689",
"cpf": "15231470190",
"ispbParticipante": "91193552"
}
}
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idSolicRec": "SC876456782024021577825445312",
"idRec": "RN123456782024011577825445612",
"calendario": {
"dataExpiracaoSolicitacao": "2023-12-20T12:17:11.926Z"
},
"status": "CRIADA",
"destinatario": {
"agencia": "2569",
"conta": "550689",
"cpf": "15231470190",
"ispbParticipante": "91193552"
},
"atualizacao": [
{
"data": "2023-12-20T12:18:18.618Z",
"status": "CRIADA"
}
],
"recPayload": {
"idRec": "RN123456782024011577825445612",
"vinculo": {
"contrato": "561238008",
"devedor": {
"cpf": "15231470190",
"nome": "Fulano de Tal"
},
"objeto": "Serviços de Telecomunicações"
},
"calendario": {
"dataFinal": "2023-12-01",
"dataInicial": "2024-04-01",
"periodicidade": "MENSAL"
},
"recebedor": {
"cnpj": "94370926517368",
"nome": "Empresa de Serviços SA"
},
"valor": {
"valorRec": "1200.09"
},
"atualizacao": [
{
"data": "2023-12-15T08:30:07.115Z",
"status": "CRIADA"
}
]
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SolicRecOperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "A solicitação de confirmação de recorrência não respeita o schema.",
"violacoes": [
{
"razao": "O objeto solicrec.destinatario não respeita o schema.",
"propriedade": "solicrec.destinatario"
}
]
}
{
"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."
}
Consultar solicitação de confirmação de recorrência de Pix Automático
Endpoint para consultar solicitação de recorrência de Pix Automático.
GET /v2/solicrec/:idSolicRec
Requer autorização para o escopo: solicrec.read
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"idSolicRec": "SC876456782024021577825445312",
"idRec": "RN123456782024011577825445612",
"calendario": {
"dataExpiracaoSolicitacao": "2023-12-20T12:17:11.926Z"
},
"status": "CRIADA",
"destinatario": {
"agencia": "2569",
"conta": "550689",
"cpf": "15231470190",
"ispbParticipante": "91193552"
},
"atualizacao": [
{
"data": "2023-12-20T12:18:18.618Z",
"status": "CRIADA"
}
],
"recPayload": {
"idRec": "RN123456782024011577825445612",
"vinculo": {
"contrato": "561238008",
"devedor": {
"cpf": "15231470190",
"nome": "Fulano de Tal"
},
"objeto": "Serviços de Telecomunicações"
},
"calendario": {
"dataFinal": "2023-12-01",
"dataInicial": "2024-04-01",
"periodicidade": "MENSAL"
},
"recebedor": {
"cnpj": "94370926517368",
"nome": "Empresa de Serviços SA"
},
"valor": {
"valorRec": "1200.09"
},
"atualizacao": [
{
"data": "2023-12-15T08:30:07.115Z",
"status": "CRIADA"
}
]
}
}
{
"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."
}
Revisar solicitação de confirmação de recorrência de Pix Automático
Endpoint para revisar solicitação de confirmação de recorrência de Pix Automático.
PATCH /v2/solicrec/:idSolicRec
Requer autorização para o escopo: solicrec.write
Requisição
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idSolicRec": "SC876456782024021577825445312",
"idRec": "RN123456782024011577825445612",
"calendario": {
"dataExpiracaoSolicitacao": "2024-06-11T07:17:11.008Z"
},
"status": "CANCELADA",
"destinatario": {
"agencia": "2569",
"conta": "550689",
"cpf": "15231470190",
"ispbParticipante": "91193552"
},
"atualizacao": [
{
"data": "2024-05-16T17:01:06.781Z",
"status": "CRIADA"
},
{
"data": "2024-05-30T10:18:18.618Z",
"status": "CANCELADA"
}
],
"recPayload": {
"idRec": "RN123456782024011577825445612",
"vinculo": {
"contrato": "Banda Larga Fibra Ótica",
"devedor": {
"cpf": "15231470190",
"nome": "Fulano de Tal"
},
"objeto": "Serviços de Telecomunicações"
},
"valor": {
"valorRec": "1200.09"
},
"calendario": {
"dataFinal": "2025-05-01",
"dataInicial": "2024-05-01",
"periodicidade": "MENSAL"
},
"recebedor": {
"cnpj": "94370926517368",
"nome": "Empresa de Serviços SA"
},
"atualizacao": [
{
"data": "2023-12-08T16:24:35.233Z",
"status": "CRIADA"
}
]
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SolicRecOperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "Não é possível cancelar uma solicitação de recorrência com o status diferente de CRIADA ou RECEBIDA."
}
DuplicatedRegisterError
{
"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."
}
DuplicatedRegisterError
{
"type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Entidade não encontrada."
}
ApplicationError
{
"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 cobranças associadas a uma recorrência de Pix Automático
Esta seção reúne endpoints destinados a lidar com gerenciamento de cobranças associadas a uma recorrência de Pix Automático.
Endpoint para criar uma cobrança de Pix Automático com um identificador de transação (txid
).
PUT /v2/cobr/:txid
Requer autorização para o escopo: cobr.write
Requisição
{
"idRec": "RR1234567820240115abcdefghijk",
"infoAdicional": "Serviços de Streamming de Música e Filmes.",
"calendario": {
"dataDeVencimento": "2024-04-15"
},
"valor": {
"original": "106.07"
},
"ajusteDiaUtil": true,
"devedor": {
"cep": "89256140",
"cidade": "Uberlândia",
"email": "[email protected]",
"logradouro": "Alameda Franco 1056",
"uf": "MG"
},
"recebedor": {
"agencia": "9708",
"conta": "12682",
"tipoConta": "CORRENTE"
}
}
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idRec": "RR1234567820240115abcdefghijk",
"txid": "3136957d93134f2184b369e8f1c0729d",
"infoAdicional": "Serviços de Streamming de Música e Filmes.",
"calendario": {
"criacao": "2024-04-01",
"dataDeVencimento": "2024-04-15"
},
"valor": {
"original": "106.07"
},
"status": "CRIADA",
"politicaRetentativa": "PERMITE_3R_7D",
"ajusteDiaUtil": true,
"devedor": {
"cep": "89256140",
"cidade": "Uberlândia",
"email": "[email protected]",
"logradouro": "Alameda Franco 1056",
"uf": "MG"
},
"recebedor": {
"agencia": "9708",
"conta": "12682",
"tipoConta": "CORRENTE"
},
"atualizacao": [
{
"data": "2024-04-01T14:47:29.470Z",
"status": "CRIADA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobROperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "A cobrança não respeita o schema.",
"violacoes": [
{
"razao": "O objeto cobr.calendario não respeita o schema.",
"propriedade": "cobr.calendario"
}
]
}
{
"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."
}
Revisar cobrança de Pix Automático
Endpoint para revisar uma cobrança de Pix Automático.
PATCH /v2/cobr/:txid
Requer autorização para o escopo: cobr.write
Requisição
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idRec": "RN985156112024071999000566354",
"txid": "517bd858b59d458a841280b0f0a60bfa",
"calendario": {
"criacao": "2024-05-20",
"dataDeVencimento": "2024-06-20"
},
"valor": {
"original": "210.00"
},
"status": "CANCELADA",
"politicaRetentativa": "NAO_PERMITE",
"ajusteDiaUtil": true,
"devedor": {
"cep": "26901-340",
"cidade": "São Luís",
"email": "[email protected]",
"logradouro": "Alameda Cardoso 1007",
"uf": "MA"
},
"recebedor": {
"cnpj": "31166575201770",
"conta": "107262",
"nome": "Empresa de Telecomunicações SA",
"tipoConta": "POUPANÇA"
},
"tentativas": [
{
"dataLiquidacao": "2024-06-20",
"tipo": "AGND",
"endToEndId": "E12345678202406201221abcdef12345",
"status": "CANCELADA"
}
],
"encerramento": {
"cancelamento": {
"solicitante": "USUARIO_RECEBEDOR",
"codigo": "SLCR",
"descricao": "Cancelamento de agendamento solicitado pelo usuário recebedor"
}
},
"atualizacao": [
{
"data": "2024-05-20T14:47:29.470Z",
"status": "CRIADA"
},
{
"data": "2024-05-21T10:18:20.120Z",
"status": "ATIVA"
},
{
"data": "2024-05-26T10:18:20.120Z",
"status": "CANCELADA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobROperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "Não é possível cancelar uma cobrança em uma data igual ou maior que a data prevista da primeira tentativa de liquidação."
}
{
"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."
}
Consultar cobrança de Pix Automático
Endpoint para consultar uma cobrança de Pix Automático através de um determinado txid
.
GET /v2/cobr/:txid
Requer autorização para o escopo: cobr.read
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
- 🟢 200
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idRec": "RR1234567820240115abcdefghijk",
"txid": "3136957d93134f2184b369e8f1c0729d",
"infoAdicional": "Serviços de Streamming de Música e Filmes.",
"calendario": {
"criacao": "2024-04-01",
"dataDeVencimento": "2024-04-15"
},
"valor": {
"original": "106.07"
},
"status": "CRIADA",
"politicaRetentativa": "PERMITE_3R_7D",
"ajusteDiaUtil": true,
"devedor": {
"cep": "89256140",
"cidade": "Uberlândia",
"email": "[email protected]",
"logradouro": "Alameda Franco 1056",
"uf": "MG"
},
"recebedor": {
"agencia": "9708",
"conta": "12682",
"tipoConta": "CORRENTE"
},
"atualizacao": [
{
"data": "2024-04-01T14:47:29.470Z",
"status": "CRIADA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobROperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "A cobrança não respeita o schema.",
"violacoes": [
{
"razao": "O objeto cobr.calendario não respeita o schema.",
"propriedade": "cobr.calendario"
}
]
}
{
"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."
}
Criar cobrança de Pix Automático (sem txid)
Endpoint para criar uma cobrança de Pix Automático, neste caso, o txid
deve ser definido pelo PSP.
Geralmente, o txid
é criado pelo usuário recebedor e está sob sua responsabilidade. No entanto, este endpoint é uma exceção a essa regra, e, nesse caso, o txid
será definido pela Efí.
POST /v2/cobr
Requer autorização para o escopo: cobr.write
Requisição
{
"idRec": "RR1234567820240115abcdefghijk",
"infoAdicional": "Serviços de Streamming de Música e Filmes.",
"calendario": {
"dataDeVencimento": "2024-04-15"
},
"valor": {
"original": "106.07"
},
"ajusteDiaUtil": true,
"devedor": {
"cep": "89256140",
"cidade": "Uberlândia",
"email": "[email protected]",
"logradouro": "Alameda Franco 1056",
"uf": "MG"
},
"recebedor": {
"agencia": "9708",
"conta": "12682",
"tipoConta": "CORRENTE"
}
}
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"idRec": "RR1234567820240115abcdefghijk",
"txid": "3136957d93134f2184b369e8f1c0729d",
"infoAdicional": "Serviços de Streamming de Música e Filmes.",
"calendario": {
"criacao": "2024-04-01",
"dataDeVencimento": "2024-04-15"
},
"status": "CRIADA",
"valor": {
"original": "106.07"
},
"politicaRetentativa": "PERMITE_3R_7D",
"ajusteDiaUtil": true,
"devedor": {
"cep": "89256140",
"cidade": "Uberlândia",
"email": "[email protected]",
"logradouro": "Alameda Franco 1056",
"uf": "MG"
},
"recebedor": {
"agencia": "9708",
"conta": "12682",
"tipoConta": "CORRENTE"
},
"atualizacao": [
{
"data": "2024-04-01T14:47:29.470Z",
"status": "CRIADA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobROperacaoInvalida",
"title": "Operação inválida.",
"status": 400,
"detail": "A cobrança não respeita o schema.",
"violacoes": [
{
"razao": "O objeto cobr.calendario não respeita o schema.",
"propriedade": "cobr.calendario"
}
]
}
{
"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/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."
}
Consultar lista de cobranças de Pix Automático
Endpoint para consultar cobranças de Pix Automático através de parâmetros como início, fim, idRec, cpf, cnpj, status e convênio.
Este endpoint possui filtros para afunilar os resultados da busca, tais como CPF/CNPJ e status. 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/cobr
Requer autorização para o escopo: cobr.read
Requisição
O trecho de código abaixo ilustra o consumo do endpoint em uma requisição com o mínimo de parâmetros possível (o intervalo de datas
inicio
e
fim
) e o formato em que esses parâmetros devem ser repassados.
/v2/cobr?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z
Respostas As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"parametros": {
"inicio": "2024-04-01T00:00:00Z",
"fim": "2024-12-01T23:59:59Z",
"paginacao": {
"paginaAtual": 0,
"itensPorPagina": 100,
"quantidadeDePaginas": 1,
"quantidadeTotalDeItens": 1
}
},
"cobsr": [
{
"idRec": "RR123456782024061999000566354",
"txid": "7f733863543b4a16b516d839bd4bc34e",
"calendario": {
"criacao": "2024-05-20",
"dataDeVencimento": "2024-06-20"
},
"valor": {
"original": "50.33"
},
"status": "ATIVA",
"ajusteDiaUtil": false,
"politicaRetentativa": "PERMITE_3R_7D",
"devedor": {
"cep": "63259-740",
"cidade": "Campinas",
"email": "[email protected]",
"logradouro": "Rua Gonçalves Dias 605",
"uf": "SP"
},
"recebedor": {
"conta": "997182",
"tipoConta": "CORRENTE"
},
"tentativas": [
{
"dataLiquidacao": "2024-06-20",
"tipo": "AGND",
"status": "AGENDADA",
"endToEndId": "E12345678202406201221abcdef12345",
"atualizacao": [
{
"data": "2024-05-21T10:40:16.730Z",
"status": "SOLICITADA"
},
{
"data": "2024-05-21T17:08:00.520Z",
"status": "AGENDADA"
}
]
}
],
"atualizacao": [
{
"data": "2024-05-20T14:47:29.470Z",
"status": "CRIADA"
},
{
"data": "2024-05-21T10:18:20.120Z",
"status": "ATIVA"
}
]
}
]
}
{
"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/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."
}
Solicitar retentativa de Pix Automático
Endpoint para solicitar retentativa de uma cobrança de Pix Automático.
POST /v2/cobr/:txid/retentativa/:data
Requer autorização para o escopo: cobr.write
Respostas As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
- 🟢 201
- 🔴 400
- 🔴 403
- 🔴 404
- 🔴 503
{
"idRec": "RR123456782024061999000566354",
"txid": "7f733863543b4a16b516d839bd4bc34e",
"calendario": {
"criacao": "2024-05-20",
"dataDeVencimento": "2024-06-20"
},
"valor": {
"original": "50.33"
},
"status": "ATIVA",
"politicaRetentativa": "PERMITE_3R_7D",
"ajusteDiaUtil": true,
"devedor": {
"cep": "63259-740",
"cidade": "Campinas",
"email": "[email protected]",
"logradouro": "Rua Gonçalves Dias 605",
"uf": "SP"
},
"recebedor": {
"cnpj": "58966551101210",
"conta": "997182",
"tipoConta": "CORRENTE"
},
"tentativas": [
{
"dataLiquidacao": "2024-06-22",
"tipo": "AGND",
"endToEndId": "E12345678202406201221abcdef12345",
"status": "EXPIRADA"
},
{
"dataLiquidacao": "2024-06-24",
"tipo": "NTAG",
"endToEndId": "E12345678202406201221abcdef12345",
"status": "AGENDADA"
}
],
"atualizacao": [
{
"data": "2024-05-20T14:47:29.470Z",
"status": "CRIADA"
},
{
"data": "2024-05-21T10:18:20.120Z",
"status": "ATIVA"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobROperacaoInvalida",
"title": "Cobrança não encontrada.",
"status": 400,
"detail": "A política configurada na recorrência não permite retentativa de cobrança."
}
{
"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."
}