Skip to main content

Automatic Pix

The following set of endpoints is responsible for managing recurrence charges. In the context of the Pix API, charges represent a financial transaction between a payer and a receiver, where the payment method is Pix.


Information

The configuration of Pix Automatico webhooks is described on this page.


Automatic Pix recurrence Management

Contains endpoints for handling Automatic Pix recurrence management.

Create Automatic Pix recurrence

Endpoint to create an Automatic Pix recurrence.

Usually, the txid is created by the receiving user and is under their responsibility. However, this endpoint is an exception to this rule, and in this case, the txid will be defined by Efí.

POST /v2/rec
Requires authorization for the scope: rec.write


Request

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

Responses

The Responses below represent Success(201) and consumption failures/errors.

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

Get Automatic Pix recurrence

Endpoint to retrieve Automatic Pix recurrence.

GET /v2/rec/:idRec
Requires authorization for the scope: rec.read


Responses

The Responses below represent Success(200) and consumption failures/errors.

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

Review Automatic Pix recurrence

Endpoint to review Automatic Pix recurrence.

PATCH /v2/rec/:idRec
Requires authorization for the scope: rec.write


Request

{
"loc": 108,
"vinculo": {
"devedor": {
"nome": "Fulano de Tal"
}
},
"calendario": {
"dataInicial": "2024-04-01"
},
"ativacao": {
"dadosJornada": {
"txid": "33beb661beda44a8928fef47dbeb2dc5"
}
}
}

Responses

The Responses below represent Success(200) and consumption failures/errors.

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

Get Automatic Pix recurrences List

Endpoint to retrieve the list of Automatic Pix recurrences.

This endpoint has filters to narrow down the search results, such as CPF/CNPJ and status. Among all available filters, the inicio and fim filters are mandatory and represent the date range in which the queried charges must be included.

GET /v2/rec
Requires authorization for the scope: rec.read


Request

The code snippet below illustrates the consumption of the endpoint in a request with the minimum possible parameters (the date range inicio and fim) and the format in which these parameters should be passed.

/v2/rec?inicio=2025-01-01T16:01:35Z&fim=2025-11-30T20:10:00Z

Responses

The Responses below represent Success(200) and consumption failures/errors.

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


Automatic Pix recurrence requests Management

Contains endpoints designed to handle management of Automatic Pix recurrence requests.

Create Automatic Pix recurrence Confirmation Request

Endpoint to create an Automatic Pix recurrence confirmation request.

POST /v2/solicrec
Requires authorization for the scope: solicrec.write


Request

{
"idRec": "RN123456782024011577825445612",
"calendario": {
"dataExpiracaoSolicitacao": "2023-12-20T12:17:11.926Z"
},
"destinatario": {
"agencia": "2569",
"conta": "550689",
"cpf": "15231470190",
"ispbParticipante": "91193552"
}
}

Responses

The Responses below represent Success(201) and consumption failures/errors.

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

Get Automatic Pix recurrence Confirmation Request

Endpoint to retrieve an Automatic Pix recurrence confirmation request.

GET /v2/solicrec/:idSolicRec
Requires authorization for the scope: solicrec.read


Responses

The Responses below represent Success(200) and consumption failures/errors.

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

Review Automatic Pix recurrence Confirmation Request

Endpoint to review Automatic Pix recurrence confirmation request.

PATCH /v2/solicrec/:idSolicRec
Requires authorization for the scope: solicrec.write


Request

{
"status": "CANCELADA"
}

Responses

The Responses below represent Success(201) and consumption failures/errors.

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

Management of charges associated with an Automatic Pix recurrence

Brings together endpoints designed to handle collection management associated with an Automatic Pix recurrence.

Create Automatic Pix charge (with txid)

Endpoint for creating an Automatic Pix charge with a transaction identifier (txid).

PUT /v2/cobr/:txid
Requires authorization for the scope: cobr.write


Request

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

Responses

The Responses below represent Success(201) and consumption failures/errors.

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

Review Automatic Pix charge

Endpoint for reviewing an Automatic Pix charge.

PATCH /v2/cobr/:txid
Requires authorization for the scope: cobr.write


Request

{
"status": "CANCELADA"
}

Responses

The Responses below represent Success(200) and consumption failures/errors.

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

Get Automatic Pix charge

Endpoint to retrieve an Automatic Pix charge through a specific txid.

GET /v2/cobr/:txid
Requires authorization for the scope: cobr.read


Responses

The Responses below represent Success(200) and consumption failures/errors.

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

Create Automatic Pix charge (without txid)

Endpoint to create an Automatic Pix charge, in this case, the txid must be defined by the PSP.

Usually, the txid is created by the receiving user and is under their responsibility. However, this endpoint is an exception to this rule, and in this case, the txid will be defined by Efí.

POST /v2/cobr
Requires authorization for the scope: cobr.write


Request

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

Responses

The Responses below represent Success(201) and consumption failures/errors.

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

Get list of Automatic Pix charges

Endpoint to retrieve Automatic Pix charges through parameters such as start, end, idRec, cpf, cnpj, status and agreement.

This endpoint has filters to narrow down the search results, such as CPF/CNPJ and status. Among all available filters, the inicio and fim filters are mandatory and represent the date range in which the queried charges must be included.

GET /v2/cobr
Requires authorization for the scope: cobr.read


Request

The code snippet below illustrates the consumption of the endpoint in a request with the minimum possible parameters (the date range inicio and fim) and the format in which these parameters should be passed.

/v2/cobr?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z

Responses

The Responses below represent Success(200) and consumption failures/errors.

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


Request Automatic Pix

Endpoint to request retry of an Automatic Pix charge.

POST /v2/cobr/:txid/retentativa/:data
Requires authorization for the scope: cobr.write


Responses

The Responses below represent Success(201) and consumption failures/errors.

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