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

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

Exemplo 1
Exemplo 2

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

🟢 201
🔴 400
🔴 403
🔴 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/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.

🟢 200
🔴 403
🔴 404
🔴 503

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

Exemplo

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

🟢 200
🔴 403
🔴 503

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

Exemplo

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

🟢 200
🔴 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/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

Exemplo

{
  "status": "CANCELADA"
}

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.

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

Exemplo

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

Exemplo

{
  "status": "CANCELADA"
}

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

Exemplo

{
  "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
🔴 503

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

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.

🟢 200
🔴 403
🔴 503

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

Pix Automático

Gerenciamento de recorrências de Pix Automático​

Criar recorrência de Pix Automático​

Consultar recorrência de Pix Automático​

Revisar recorrência de Pix Automático​

Consultar lista de recorrências de Pix Automático​

Gerenciamento de solicitações de recorrências de Pix Automático​

Criar solicitação de confirmação de recorrência de Pix Automático​

Consultar solicitação de confirmação de recorrência de Pix Automático​

Revisar solicitação de confirmação de recorrência de Pix Automático​

Gerenciamento de cobranças associadas a uma recorrência de Pix Automático​

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

Revisar cobrança de Pix Automático​

Consultar cobrança de Pix Automático​

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

Consultar lista de cobranças de Pix Automático​

Solicitar retentativa de Pix Automático​

Gerenciamento de recorrências de Pix Automático

Criar recorrência de Pix Automático

Consultar recorrência de Pix Automático

Revisar recorrência de Pix Automático

Consultar lista de recorrências de Pix Automático

Gerenciamento de solicitações de recorrências de Pix Automático

Criar solicitação de confirmação de recorrência de Pix Automático

Consultar solicitação de confirmação de recorrência de Pix Automático

Revisar solicitação de confirmação de recorrência de Pix Automático

Gerenciamento de cobranças associadas a uma recorrência de Pix Automático

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

Revisar cobrança de Pix Automático

Consultar cobrança de Pix Automático

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

Consultar lista de cobranças de Pix Automático

Solicitar retentativa de Pix Automático