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.

Atenção!

Para utilizar as funcionalidades do Pix Automático, é necessário ter uma Conta Digital Efí Empresas.

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

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

Exemplo 2

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

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

🔴 400

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

🔴 403

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

🔴 503

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

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

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

🔴 400

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

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

🔴 403

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

🔴 503

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

Atenção!

Embora o campo agencia seja opcional, recomendamos fortemente seu preenchimento em todas as solicitações de recorrência. Algumas instituições financeiras exigem essa informação para identificar corretamente a conta do pagador. A ausência desse dado pode impedir o recebimento da solicitação de autorização do 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

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

🔴 400

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

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

🔴 400

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

🔴 403

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

🔴 404

DuplicatedRegisterError
{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

Respostas

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

🟢 201

{
  "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": "PAGAMENTO"
  },
  "atualizacao": [
    {
      "data": "2024-04-01T14:47:29.470Z",
      "status": "CRIADA"
    }
  ]
}

🔴 400

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

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

🔴 400

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

{
  "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": "PAGAMENTO"
  },
  "atualizacao": [
    {
      "data": "2024-04-01T14:47:29.470Z",
      "status": "CRIADA"
    }
  ]
}

🔴 400

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

Respostas

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

🟢 201

{
  "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": "PAGAMENTO"
  },
  "atualizacao": [
    {
      "data": "2024-04-01T14:47:29.470Z",
      "status": "CRIADA"
    }
  ]
}

🔴 400

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

🔴 403

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

🔴 503

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

🟢 200

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

🔴 403

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

🔴 503

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

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

🔴 400

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

🔴 403

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

🔴 404

{
  "type": "https://pix.bcb.gov.br/api/v2/error/NaoEncontrado",
  "title": "Não Encontrado",
  "status": 404,
  "detail": "Entidade não encontrada."
}

🔴 503

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

Jornadas de contratação

A adesão ao Pix Automático pode ser feita por meio de quatro jornadas diferentes. Veja a seguir como funciona a emissão em cada uma delas:

Jornadas de contratação

Jornada 1 - via notificação push

Essa jornada foi pensada para negociações iniciadas fora do ambiente do Pix — pelo WhatsApp, por exemplo.

Passos para emitir:

1. Criar a recorrência: POST /v2/rec.

O location não deve ser enviado no body da requisição.

2. Criar a solicitação da recorrência: POST /v2/solicrec.

Informe o idRec obtido no Passo 1.

3. Criar a cobrança recorrente associada à recorrência aceita: PUT /v2/cobr/:txid ou POST /v2/cobr.

Jornada 2 - com QR Code para cobranças recorrentes futuras

Essa jornada foi pensada para empresas que não precisam receber o pagamento imediatamente, mas desejam cobrar de forma automática e periódica a partir do mês seguinte.

Passos para emitir:

1. Criar o location: POST /v2/locrec.

2. Criar a recorrência: POST /v2/rec.

Informe o location obtido no Passo 1.

3. Consultar a recorrência para obter o copia e cola: GET /v2/rec/:idRec.

Informe o idRec obtido no passo 2, como parâmetro.

4. Criar a cobrança recorrente associada à recorrência aceita: PUT /v2/cobr/:txid ou POST /v2/cobr.

Jornada 3 - com QR Code para pagamento imediato + recorrência em uma única autorização

Essa jornada foi pensada para quando o cliente deseja começar a usar o serviço imediatamente e a empresa precisa receber o primeiro pagamento à vista.

Passos para emitir:

1. Criar o location: POST /v2/locrec.

2. Criar a cobrança imediata: POST /v2/cob ou PUT /v2/cob/:txid.

3. Criar a recorrência: POST /v2/rec.

Informe o location obtido no Passo 1 e o txid da cobrança obtido no passo 2.

4. Consultar a recorrência para obter o copia e cola: GET /v2/rec/:idRec.

Informe o idRec obtido no passo 3, como parâmetro e o txid da cobrança imediata obtido no passo 2, como query params.

5. Criar a cobrança recorrente associada à recorrência aceita: PUT /v2/cobr/:txid ou POST /v2/cobr.

Jornada 4 - via fatura com QR Code

Essa jornada foi pensada para quando uma empresa já envia faturas mensais com QR Code para seus clientes e quer oferecer a proposta de ativação do Pix Automático, simplificando os pagamentos futuros.

Passos para emitir:

1. Criar o location: POST /v2/locrec.

2. Criar a cobrança com vencimento: PUT /v2/cobv/:txid.

3. Criar a recorrência: POST /v2/rec.

Informe o location obtido no Passo 1.

4. Consultar a recorrência para obter o copia e cola: GET /v2/rec/:idRec.

Informe o idRec obtido no passo 3, como parâmetro e o txid da cobrança com vencimento obtido no passo 2, como query params.

5. Criar a cobrança recorrente associada à recorrência aceita: PUT /v2/cobr/:txid ou POST /v2/cobr.