Crear cobro Pix

Crea un cobro con QR dinámico. El txid es suyo: repetir el mismo txid devuelve el cobro ya creado, sin modificarlo, con 200 y la cabecera x-replayed: true. Con otro documento del deudor, valor, ex.subconta o ex.splitConfig, la respuesta es 409. Para otro cobro, use otro txid.

PUT /v2/cob/{txid}

Alcance: 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 del request #

Algunas cuentas aceptan una expiración máxima menor que 900 segundos. Sin calendario.expiracao, o con un valor por encima de ese máximo, el cobro se crea con el máximo de la cuenta, y la respuesta trae el número registrado. Solicitar por debajo del mínimo de la cuenta responde 422 expiracao_nao_suportada_no_custodiante, con los límites en violacoes, y el cobro no se crea.

En algunas cuentas la validez del QR la define la institución, y no la expiración solicitada. En ellas el cobro vence junto con el QR, y calendario.expiracao en la respuesta trae esa validez, que puede ser mayor o menor que la solicitada. El Pix pagado dentro de ella se acredita. Use siempre la expiración de la respuesta.

Algunas cuentas no emiten cobros sin el nombre del pagador. Para saberlo, lea capacidades.cobrancaSemNome en GET /v2/ex/config: cuando es false, envíe devedor.nome, o el cobro responde 422 nome_do_pagador_obrigatorio y no se crea.

Algunas cuentas solo emiten cobros dentro de un rango de valores. Fuera de él, el cobro responde 422 valor_abaixo_do_minimo o 422 valor_acima_do_maximo, con el límite en detail, y no se crea. Cuando hay más de una cuenta para sus cobros, se crea en otra que acepte el valor, y el rechazo solo llega cuando ninguna lo acepta.

Con ex.subconta, las dos reglas son las de la subcuenta: lea GET /v2/ex/config?subconta={id}.

Un campo desconocido dentro de ex responde 400 campo_desconhecido. La chave la completamos nosotros y no debe enviarse.

Para cobrar a una empresa, envíe devedor.cnpj en lugar del cpf. Esto vale donde capacidades.devedorPJ es true en GET /v2/ex/config; donde es false, el cnpj se rechaza. Envíe uno de los dos, nunca los dos.

Donde capacidades.cobrancaSemDevedor es true, el cobro puede emitirse sin devedor.cpf y sin devedor.cnpj, y entonces cualquier persona puede pagarlo. En esas cuentas, un devedor.cpf o devedor.cnpj que no es un documento válido se descarta junto con devedor, y el cobro se crea sin él; el documento con puntuación que es válido sin ella vale, sin la puntuación.

El Pix solo se convierte en saldo cuando quien paga tiene el mismo documento de devedor. Si otra persona o empresa paga el QR, el valor no se convierte en saldo y queda con el pagador: usted recibe cob.pagamento_rejeitado con motivo igual a TITULARIDADE y, si el dinero llegó a entrar, devolucao.criada con el mismo motivo. Envíe en devedor el documento de quien de hecho va a pagar.

En algunas cuentas la institución solo informa el CPF de quien pagó enmascarado, como ***456789**. Donde ella confirma que es el de quien pagó, el Pix se confiere por los seis dígitos visibles y por el primer y el último nombre de devedor.nome, y el CPF de quien pagó también le llega enmascarado. En esas cuentas capacidades.cobrancaSemNome es false: el cobro con devedor.cpf exige devedor.nome con el nombre y el apellido de quien va a pagar, o responde 422 nome_do_pagador_obrigatorio y no se crea. En las otras en que el CPF llega enmascarado, el cobro con devedor responde 422 titularidade_sem_confirmacao y no se crea, y también el cobro con devedor.cnpj en las que confieren por los seis dígitos.

Campos del response #

Cuando el pago se convierte en saldo, usted recibe el webhook pix.creditado. Un Pix rechazado no genera pix.creditado: llega como pix.recebido con situacaoFundos igual a EM_DEVOLUCAO, seguido de devolucao.criada. Consulte el cobro en Consultar cobro.

También existe POST /v2/cob, con el mismo cuerpo, en el que el txid lo generamos nosotros. Prefiera el PUT.

Errores #