Criar cobrança Pix

Cria uma cobrança com QR dinâmico. O txid é seu: repetir o mesmo txid devolve a cobrança já criada, sem alterá-la, com 200 e o cabeçalho x-replayed: true. Com outro documento do devedor, valor, ex.subconta ou ex.splitConfig, a resposta é 409. Para outra cobrança, use outro txid.

PUT /v2/cob/{txid}

Escopo: cob.write.

PUT /v2/cob/COB01J1ZK7M9QW3ERT5TY6UI8O
{
  "calendario": { "expiracao": 900 },
  "devedor": { "cpf": "12345678909", "nome": "Fulano de Tal" },
  "valor": { "original": "150.00" },
  "solicitacaoPagador": "Pedido 778812"
}
→ 201
{
  "txid": "COB01J1ZK7M9QW3ERT5TY6UI8O",
  "revisao": 0,
  "status": "ATIVA",
  "calendario": { "criacao": "2026-09-18T12:00:00.767Z", "expiracao": 900 },
  "devedor": { "cpf": "12345678909", "nome": "Fulano de Tal" },
  "valor": { "original": "150.00" },
  "chave": "01J8Z3QK5W7R2N4M6P8T0V2X4Y",
  "solicitacaoPagador": "Pedido 778812",
  "pixCopiaECola": "00020126480014br.gov.bcb.pix0126...6304C057"
}

Campos do request #

Algumas contas aceitam uma expiração máxima menor que 900 segundos. Sem calendario.expiracao, ou com um valor acima desse máximo, a cobrança nasce com o máximo da conta, e a resposta traz o número gravado. Pedir abaixo do mínimo da conta responde 422 expiracao_nao_suportada_no_custodiante, com os limites em violacoes, e a cobrança não é criada.

Em algumas contas a validade do QR é definida pela instituição, e não pela expiração pedida. Nelas a cobrança vence junto com o QR, e calendario.expiracao na resposta traz essa validade, que pode ser maior ou menor que a pedida. O Pix pago dentro dela é creditado. Use sempre a expiração da resposta.

Algumas contas não emitem cobrança sem o nome do pagador. Para saber, leia capacidades.cobrancaSemNome em GET /v2/ex/config: quando é false, mande devedor.nome, ou a cobrança responde 422 nome_do_pagador_obrigatorio e não é criada.

Algumas contas só emitem cobrança dentro de uma faixa de valor. Fora dela, a cobrança responde 422 valor_abaixo_do_minimo ou 422 valor_acima_do_maximo, com o limite em detail, e não é criada. Quando há mais de uma conta para as suas cobranças, ela nasce em outra que aceite o valor, e a recusa só vem quando nenhuma aceita.

Com ex.subconta, as duas regras são as da sub-conta: leia GET /v2/ex/config?subconta={id}.

Campo desconhecido dentro de ex responde 400 campo_desconhecido. A chave é preenchida por nós e não deve ser enviada.

Para cobrar uma empresa, mande devedor.cnpj no lugar do cpf. Isso vale onde capacidades.devedorPJ é true em GET /v2/ex/config; onde é false, o cnpj é recusado. Mande um dos dois, nunca os dois.

Onde capacidades.cobrancaSemDevedor é true, a cobrança pode sair sem devedor.cpf e sem devedor.cnpj, e então qualquer pessoa pode pagá-la. Nessas contas, um devedor.cpf ou devedor.cnpj que não é um documento válido é descartado junto com o devedor, e a cobrança é criada sem ele; o documento com pontuação que é válido sem ela vale, sem a pontuação.

O Pix só vira saldo quando quem paga tem o mesmo documento de devedor. Se outra pessoa ou empresa pagar o QR, o valor não vira saldo e fica com o pagador: você recebe cob.pagamento_rejeitado com motivo igual a TITULARIDADE e, se o dinheiro chegou a entrar, devolucao.criada com o mesmo motivo. Mande em devedor o documento de quem de fato vai pagar.

Em algumas contas a instituição só informa o CPF de quem pagou mascarado, como ***456789**. Onde ela confirma que é o de quem pagou, o Pix confere pelos seis dígitos visíveis e pelo primeiro e o último nome de devedor.nome, e o CPF de quem pagou chega mascarado também para você. Nessas contas capacidades.cobrancaSemNome é false: a cobrança com devedor.cpf exige devedor.nome com o nome e o sobrenome de quem vai pagar, ou responde 422 nome_do_pagador_obrigatorio e não é criada. Nas outras em que o CPF chega mascarado, a cobrança com devedor responde 422 titularidade_sem_confirmacao e não é criada, e também a com devedor.cnpj nas que conferem pelos seis dígitos.

Campos do response #

Quando o pagamento vira saldo, você recebe o webhook pix.creditado. Um Pix recusado não gera pix.creditado: ele chega como pix.recebido com situacaoFundos igual a EM_DEVOLUCAO, seguido de devolucao.criada. Consulte a cobrança em Consultar cobrança.

Existe também POST /v2/cob, com o mesmo corpo, em que o txid é gerado por nós. Prefira o PUT.

Erros #