Pular para o conteúdo principal

Pix Automático

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ção

Atençã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"
}
}
}

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

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

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.

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

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


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.

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

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

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

{
"status": "CANCELADA"
}

Respostas

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

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

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.

Criar cobrança de Pix Automático (com txid)

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.

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

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

{
"status": "CANCELADA"
}

Respostas

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

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

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.

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

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

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


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.

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