创建 Pix 收款

创建一笔带动态 QR 码的收款。txid 由您生成：重复使用同一个 txid 会返回已创建的收款，不做修改，状态码为 200，并带有响应头 x-replayed: true。若债务人证件号、金额、ex.subconta 或 ex.splitConfig 不同，则返回 409。要创建另一笔收款，请使用另一个 txid。

PUT /v2/cob/{txid}

权限范围：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"
}

请求字段 #

有些账户接受的最大过期时间小于 900 秒。不带 calendario.expiracao 或其值超过该最大值时，收款以账户的最大值创建，响应中会返回实际记录的数值。请求低于账户的最小值时，返回 422 expiracao_nao_suportada_no_custodiante，限制值在 violacoes 中，收款不会创建。

在有些账户中，二维码的有效期由机构决定，而不是由请求的过期时间决定。在这些账户中，收款与二维码同时过期，响应中的 calendario.expiracao 返回该有效期，可能长于或短于请求的值。在有效期内支付的 Pix 会入账。请始终以响应中的过期时间为准。

有些账户在没有付款人姓名时不签发收款。可读取 GET /v2/ex/config 中的 capacidades.cobrancaSemNome 确认：为 false 时请发送 devedor.nome，否则收款返回 422 nome_do_pagador_obrigatorio，且不会创建。

有些账户只在一定金额范围内签发收款。超出该范围时，收款返回 422 valor_abaixo_do_minimo 或 422 valor_acima_do_maximo，限制值在 detail 中，收款不会创建。当您的收款有多个账户可用时，收款会在接受该金额的另一个账户中创建，只有在所有账户都不接受时才会被拒绝。

使用 ex.subconta 时，上述两条规则以子账户为准：请读取 GET /v2/ex/config?subconta={id}。

ex 中的未知字段返回 400 campo_desconhecido。chave 由我们填写，不应发送。

向企业收款时，请发送 devedor.cnpj 代替 cpf。这在 GET /v2/ex/config 中 capacidades.devedorPJ 为 true 时可用；为 false 时，cnpj 会被拒绝。两者只发送其一，切勿同时发送。

在 capacidades.cobrancaSemDevedor 为 true 的账户，收款可以既不带 devedor.cpf 也不带 devedor.cnpj，此时任何人都可以支付。在这些账户中，无效的 devedor.cpf 或 devedor.cnpj 会连同 devedor 一起被丢弃，收款在没有付款人的情况下创建；带标点但去掉标点后有效的证件号照常使用，去掉标点。

只有付款人的证件号与 devedor 相同时，Pix 才会计入余额。如果其他个人或企业支付了该 QR 码，款项不会计入余额，仍归付款人：您会收到 motivo 为 TITULARIDADE 的 cob.pagamento_rejeitado；如果款项已经到账，还会收到原因相同的 devolucao.criada。请在 devedor 中填写实际付款人的证件号。

有些账户中，机构只提供付款人被遮蔽的 CPF，例如 ***456789**。在机构确认这是付款人 CPF 的账户中，Pix 按六位可见数字以及 devedor.nome 的名和姓进行核对，您收到的付款人 CPF 也是遮蔽的。在这些账户中 capacidades.cobrancaSemNome 为 false：带 devedor.cpf 的收款必须在 devedor.nome 中填写付款人的名和姓，否则返回 422 nome_do_pagador_obrigatorio，且不会创建。在其他 CPF 被遮蔽的账户中，带 devedor 的收款返回 422 titularidade_sem_confirmacao，且不会创建；在按六位数字核对的账户中，带 devedor.cnpj 的收款也是如此。

响应字段 #

款项计入余额时，您会收到 webhook pix.creditado。被拒绝的 Pix 不会产生 pix.creditado：它以 situacaoFundos 为 EM_DEVOLUCAO 的 pix.recebido 到达，随后是 devolucao.criada。可在查询收款中查询收款。

另有 POST /v2/cob，正文相同，txid 由我们生成。建议使用 PUT。

错误 #