Create Pix charge

Creates a charge with a dynamic QR. The txid is yours: repeating the same txid returns the charge already created, without changing it, with 200 and the header x-replayed: true. With a different debtor document, amount, ex.subconta or ex.splitConfig, the response is 409. For another charge, use another txid.

PUT /v2/cob/{txid}

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

Request fields #

Some accounts accept a maximum expiration lower than 900 seconds. Without calendario.expiracao, or with a value above that maximum, the charge is created with the maximum of the account, and the response carries the stored number. Asking for a value below the minimum of the account responds 422 expiracao_nao_suportada_no_custodiante, with the limits in violacoes, and the charge is not created.

In some accounts the validity of the QR is set by the institution, and not by the requested expiration. In those the charge expires together with the QR, and calendario.expiracao in the response carries that validity, which may be longer or shorter than the requested one. A Pix paid within it is credited. Always use the expiration from the response.

Some accounts do not issue a charge without the name of the payer. To find out, read capacidades.cobrancaSemNome in GET /v2/ex/config: when it is false, send devedor.nome, or the charge responds 422 nome_do_pagador_obrigatorio and is not created.

Some accounts only issue charges within a range of amounts. Outside it, the charge responds 422 valor_abaixo_do_minimo or 422 valor_acima_do_maximo, with the limit in detail, and is not created. When there is more than one account for your charges, it is created in another one that accepts the amount, and the refusal only comes when none of them accepts it.

With ex.subconta, both rules are those of the sub-account: read GET /v2/ex/config?subconta={id}.

An unknown field inside ex responds 400 campo_desconhecido. The chave is filled in by us and must not be sent.

To charge a company, send devedor.cnpj instead of the cpf. This applies where capacidades.devedorPJ is true in GET /v2/ex/config; where it is false, the cnpj is rejected. Send one of the two, never both.

Where capacidades.cobrancaSemDevedor is true, the charge may be created without devedor.cpf and without devedor.cnpj, and then anyone can pay it. On these accounts, a devedor.cpf or devedor.cnpj that is not a valid document is discarded together with devedor, and the charge is created without it; a document with punctuation that is valid without it is used, without the punctuation.

The Pix only becomes balance when the payer has the same document as devedor. If another person or company pays the QR, the amount does not become balance and stays with the payer: you receive cob.pagamento_rejeitado with motivo equal to TITULARIDADE and, if the money did come in, devolucao.criada with the same reason. Send in devedor the document of the person who will actually pay.

On some accounts the institution reports the CPF of the payer only masked, such as ***456789**. Where it confirms that this is the CPF of the payer, the Pix is matched by the six visible digits and by the first and last name in devedor.nome, and the CPF of the payer also reaches you masked. On these accounts capacidades.cobrancaSemNome is false: a charge with devedor.cpf requires devedor.nome with the first name and the surname of the person who will pay, or it responds 422 nome_do_pagador_obrigatorio and is not created. On the other accounts where the CPF arrives masked, a charge with devedor responds 422 titularidade_sem_confirmacao and is not created, and so does a charge with devedor.cnpj on the accounts that match by the six digits.

Response fields #

When the payment becomes balance, you receive the webhook pix.creditado. A rejected Pix does not produce pix.creditado: it arrives as pix.recebido with situacaoFundos equal to EM_DEVOLUCAO, followed by devolucao.criada. Look up the charge in Get charge.

There is also POST /v2/cob, with the same body, in which the txid is generated by us. Prefer the PUT.

Errors #