Visão Geral O endpoint PUT /cob/:txid cria uma cobrança imediata (cob) associada ao identificador de transação (txid) informado. Este endpoint segue a especificação oficial do Banco Central do Brasil para cobranças PIX.
O txid é um identificador único gerado pelo seu sistema. Deve ter entre 26 e 35 caracteres alfanuméricos.
Endpoint Autenticação Token Bearer obtido via /oauth/token. Exemplo: Bearer eyJhbGciOiJSUzI1NiIs...
Parâmetros de URL Identificador da transação. Deve ser único e conter entre 26 e 35 caracteres alfanuméricos [a-zA-Z0-9]. Exemplo: 7978c0c97ea847e78e8849634473c1f1
Request Body Informações de controle de tempo da cobrança. Tempo de vida da cobrança em segundos. Padrão: 86400 (24 horas).
Dados do devedor (pagador). Pode ser Pessoa Física (CPF) ou Jurídica (CNPJ). CPF do devedor. Apenas números, 11 dígitos.
Nome completo do devedor. Máximo 200 caracteres.
CNPJ do devedor. Apenas números, 14 dígitos.
Razão social do devedor. Máximo 200 caracteres.
Valores monetários da cobrança. Valor original da cobrança. String no formato decimal com 2 casas. Exemplo: "123.45"
Modalidade de alteração do valor:
0: Valor fixo (não pode ser alterado pelo pagador)1: Valor alterável (pagador pode modificar) Chave PIX do recebedor. Pode ser telefone, e-mail, CPF/CNPJ ou EVP (chave aleatória). Máximo 77 caracteres.
Texto livre para o pagador. Máximo 140 caracteres.
Lista de informações adicionais ao pagador. Nome do campo. Máximo 50 caracteres.
Valor do campo. Máximo 200 caracteres.
Request curl -X PUT https://api.avista.global/cob/7978c0c97ea847e78e8849634473c1f1 \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "calendario": { "expiracao": 3600 }, "devedor": { "cpf": "12345678909", "nome": "Carlos Oliveira" }, "valor": { "original": "123.45", "modalidadeAlteracao": 0 }, "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906", "solicitacaoPagador": "Serviço realizado.", "infoAdicionais": [ { "nome": "Pedido", "valor": "#12345" } ] }'
Response 201 Created
400 Bad Request
409 Conflict
{ "calendario" : { "criacao" : "2024-01-15T10:30:00.358Z" , "expiracao" : 3600 }, "txid" : "7978c0c97ea847e78e8849634473c1f1" , "revisao" : 0 , "loc" : { "id" : 12345 , "location" : "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD" , "tipoCob" : "cob" }, "location" : "00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1bbff817b5a8520400005303986540512.345802BR5916Tech Solutions Ltda6009Sao Paulo62070503***6304ABCD" , "status" : "ATIVA" , "devedor" : { "cpf" : "12345678909" , "nome" : "Carlos Oliveira" }, "valor" : { "original" : "123.45" , "modalidadeAlteracao" : 0 }, "chave" : "7d9f0335-8dcc-4054-9bf9-0dbd61d36906" , "solicitacaoPagador" : "Serviço realizado." , "infoAdicionais" : [ { "nome" : "Pedido" , "valor" : "#12345" } ] }
{ "statusCode" : 400 , "message" : "CPF deve conter exatamente 11 dígitos numéricos" , "error" : "Bad Request" }
{ "statusCode" : 409 , "message" : "Cobrança com este txid já existe" , "error" : "Conflict" }
Campos da Resposta Data e hora de criação da cobrança (ISO 8601).
Tempo de expiração em segundos.
Identificador da transação informado na requisição.
Número da revisão da cobrança. Sempre 0 na criação.
Informações do payload PIX. Identificador da transação.
Código PIX copia-e-cola (EMV). Use este valor para gerar o QR Code ou permitir que o pagador copie e cole no aplicativo do banco.
Tipo de cobrança. Sempre "cob" para cobranças imediatas.
Código PIX copia-e-cola (mesmo valor de loc.location). String no formato EMV que pode ser usada para pagamento.
Status da cobrança:
ATIVA: Cobrança ativa, aguardando pagamentoCONCLUIDA: Pagamento recebidoREMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelada pelo recebedorREMOVIDA_PELO_PSP: Removida pelo PSP Status da Cobrança Webhook de Pagamento Quando o pagamento for confirmado, você receberá um webhook V2 do tipo RECEIVE:
{ "type" : "RECEIVE" , "data" : { "id" : 123 , "txId" : "7978c0c97ea847e78e8849634473c1f1" , "status" : "LIQUIDATED" , "payment" : { "amount" : "123.45" , "currency" : "BRL" }, "endToEndId" : "E12345678901234567890123456789012" , "debtorAccount" : { "name" : "Carlos Oliveira" , "document" : "123.xxx.xxx-xx" } } }
Webhooks V2 Veja a documentação completa do webhook RECEIVE
Erros Comuns Código Erro Solução 400 txid fora do padrão Use 26-35 caracteres alfanuméricos 400 CPF/CNPJ inválido Verifique formato (apenas números) 400 Valor inválido Use formato “123.45” (string com 2 decimais) 401 Token inválido Renove o token de acesso 409 txid já existe Use um txid diferente
Próximos Passos 
