Criar cobrança Pix

Cria uma cobrança com QR dinâmico. O txid é seu: repetir o mesmo txid com o mesmo corpo devolve a mesma cobrança com 200 e o cabeçalho x-replayed: true.

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": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "solicitacaoPagador": "Pedido 778812",
  "pixCopiaECola": "00020126480014br.gov.bcb.pix0126...6304C057"
}

Campos do request #

Campo	Tipo	Obrigatório	Descrição
`valor.original`	string	sim	Valor com duas casas, maior que zero.
`devedor.cpf`	string	sim	CPF do pagador esperado, 11 dígitos.
`devedor.nome`	string	não	Nome do pagador.
`calendario.expiracao`	inteiro	não	Segundos até o QR expirar. Padrão 900.
`solicitacaoPagador`	string	não	Texto mostrado ao pagador.
`ex.subconta`	string	não	Id da sub-conta que recebe. Omitido, recebe a conta principal.
`ex.splitConfig`	string	não	Id de uma configuração de split. Consulte a referência interna.

Campo desconhecido dentro de ex responde 400 campo_desconhecido. A chave é preenchida por nós e não deve ser enviada. O pagador é pessoa física: devedor.cnpj é recusado.

Campos do response #

Campo	Tipo	Descrição
`status`	string	`ATIVA`, `CONCLUIDA`, `REMOVIDA_PELO_USUARIO_RECEBEDOR` ou `REMOVIDA_PELO_PSP`.
`pixCopiaECola`	string	O BR Code. Mostre como QR ou como texto para copiar.
`revisao`	inteiro	Sobe a cada alteração da cobrança.
`calendario.criacao`	string	Instante da criação.

Quando o pagador paga, você recebe o webhook pix.creditado. 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 #

Status	`title`	Quando
400	`txid_invalido`	`txid` fora de 26 a 35 caracteres alfanuméricos.
400	`valor_invalido`	Valor fora do formato `"0.00"` ou não positivo.
400	`cpf_invalido`	`devedor.cpf` fora do formato.
400	`devedor_obrigatorio`	Sem `devedor.cpf`.
400	`devedor_pj_nao_permitido`	`devedor.cnpj` informado.
400	`campo_desconhecido`	Campo que não existe dentro de `ex`.
403	`subconta_indisponivel`	`ex.subconta` existe e não está `ATIVA`.
409	`txid_duplicado`	O mesmo `txid` já existe com outro corpo.
422	`subconta_nao_encontrada`	`ex.subconta` não existe.
422	`split_config_nao_encontrada`	`ex.splitConfig` não existe.