Criar Cobrança
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
PUT /cob/{txid}Autenticação
Token Bearer obtido via /oauth/token.
Exemplo: Bearer eyJhbGciOiJSUzI1NiIs...
Parâmetros de URL
txidstringobrigatorioIdentificador 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.
Dados do devedor (pagador). Pode ser Pessoa Física (CPF) ou Jurídica (CNPJ).
Valores monetários da cobrança.
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.
Request
curl -X PUT https://api.public.firebanking.com.br/cob/7978c0c97ea847e78e8849634473c1f1 \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"calendario": {
"expiração": 3600
},
"devedor": {
"cpf": "12345678909",
"nome": "Carlos Oliveira"
},
"valor": {
"original": "123.45",
"modalidadeAlteração": 0
},
"chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
"solicitaçãoPagador": "Serviço realizado.",
"infoAdicionais": [
{
"nome": "Pedido",
"valor": "#12345"
}
]
}'const response = await fetch(
'https://api.public.firebanking.com.br/cob/7978c0c97ea847e78e8849634473c1f1',
{
method: 'PUT',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
calendario: {
expiração: 3600,
},
devedor: {
cpf: '12345678909',
nome: 'Carlos Oliveira',
},
valor: {
original: '123.45',
modalidadeAlteração: 0,
},
chave: '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
solicitaçãoPagador: 'Serviço realizado.',
infoAdicionais: [
{ nome: 'Pedido', valor: '#12345' },
],
}),
}
);
const cobrança = await response.json();import requests
response = requests.put(
'https://api.public.firebanking.com.br/cob/7978c0c97ea847e78e8849634473c1f1',
headers={
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
},
json={
'calendario': {
'expiração': 3600,
},
'devedor': {
'cpf': '12345678909',
'nome': 'Carlos Oliveira',
},
'valor': {
'original': '123.45',
'modalidadeAlteração': 0,
},
'chave': '7d9f0335-8dcc-4054-9bf9-0dbd61d36906',
'solicitaçãoPagador': 'Serviço realizado.',
'infoAdicionais': [
{'nome': 'Pedido', 'valor': '#12345'},
],
}
)
cobrança = response.json()Response
{
"calendario": {
"criação": "2024-01-15T10:30:00.358Z",
"expiração": 3600
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisão": 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",
"modalidadeAlteração": 0
},
"chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
"solicitaçãoPagador": "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
calendarioobjecttxidstringIdentificador da transação informado na requisição.
revisãonumberNúmero da revisão da cobrança. Sempre 0 na criação.
locobjectInformações do payload PIX.
locationstringCódigo PIX copia-e-cola (mesmo valor de loc.location). String no formato EMV que pode ser usada para pagamento.
statusstringStatus 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
stateDiagram-v2
[*] --> ATIVA: Cobrança criada
ATIVA --> CONCLUIDA: Pagamento recebido
ATIVA --> REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelada
ATIVA --> REMOVIDA_PELO_PSP: Expirada/Removida
CONCLUIDA --> [*]
REMOVIDA_PELO_USUARIO_RECEBEDOR --> [*]
REMOVIDA_PELO_PSP --> [*]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 |