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

Authorization

string

obrigatório

Token Bearer obtido via /oauth/token.Exemplo: Bearer eyJhbGciOiJSUzI1NiIs...

Parâmetros de URL

txid

string

obrigatório

Identificador da transação. Deve ser único e conter entre 26 e 35 caracteres alfanuméricos [a-zA-Z0-9].Exemplo: 7978c0c97ea847e78e8849634473c1f1

Request Body

calendario

object

obrigatório

Informações de controle de tempo da cobrança.

Mostrar Propriedades

expiracao

number

padrão:86400

Tempo de vida da cobrança em segundos. Padrão: 86400 (24 horas).

devedor

object

Dados do devedor (pagador). Pode ser Pessoa Física (CPF) ou Jurídica (CNPJ).

Mostrar Pessoa Física

cpf

string

obrigatório

CPF do devedor. Apenas números, 11 dígitos.

nome

string

obrigatório

Nome completo do devedor. Máximo 200 caracteres.

Mostrar Pessoa Jurídica

cnpj

string

obrigatório

CNPJ do devedor. Apenas números, 14 dígitos.

nome

string

obrigatório

Razão social do devedor. Máximo 200 caracteres.

valor

object

obrigatório

Valores monetários da cobrança.

Mostrar Propriedades

original

string

obrigatório

Valor original da cobrança. String no formato decimal com 2 casas.Exemplo: "123.45"

modalidadeAlteracao

number

padrão:0

Modalidade de alteração do valor:

0: Valor fixo (não pode ser alterado pelo pagador)
1: Valor alterável (pagador pode modificar)

chave

string

Chave PIX do recebedor. Pode ser telefone, e-mail, CPF/CNPJ ou EVP (chave aleatória). Máximo 77 caracteres.

solicitacaoPagador

string

Texto livre para o pagador. Máximo 140 caracteres.

infoAdicionais

array

Lista de informações adicionais ao pagador.

Mostrar Item

nome

string

obrigatório

Nome do campo. Máximo 50 caracteres.

valor

string

obrigatório

Valor do campo. Máximo 200 caracteres.

Request

curl -X PUT https://api.public.firebanking.com.br/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"
      }
    ]
  }'

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: {
        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' },
      ],
    }),
  }
);

const cobranca = 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': {
            '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'},
        ],
    }
)

cobranca = response.json()

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

calendario

object

Mostrar Propriedades

criacao

string

Data e hora de criação da cobrança (ISO 8601).

expiracao

number

Tempo de expiração em segundos.

txid

string

Identificador da transação informado na requisição.

revisao

number

Número da revisão da cobrança. Sempre 0 na criação.

loc

object

Informações do payload PIX.

Mostrar Propriedades

number

Identificador da transação.

location

string

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.

tipoCob

string

Tipo de cobrança. Sempre "cob" para cobranças imediatas.

location

string

Código PIX copia-e-cola (mesmo valor de loc.location). String no formato EMV que pode ser usada para pagamento.

status

string

Status da cobrança:

ATIVA: Cobrança ativa, aguardando pagamento
CONCLUIDA: Pagamento recebido
REMOVIDA_PELO_USUARIO_RECEBEDOR: Cancelada pelo recebedor
REMOVIDA_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

Visão Geral

Endpoint

Autenticação

Parâmetros de URL

Request Body

Request

Response

Campos da Resposta

Status da Cobrança

Webhook de Pagamento

Webhooks V2

Erros Comuns

Próximos Passos

Solicitar Devolução

Webhook RECEIVE

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de URL

​Request Body

​Request

​Response

​Campos da Resposta

​Status da Cobrança

​Webhook de Pagamento

Webhooks V2

​Erros Comuns

​Próximos Passos

Solicitar Devolução

Webhook RECEIVE

Visão Geral

Endpoint

Autenticação

Parâmetros de URL

Request Body

Request

Response

Campos da Resposta

Status da Cobrança

Webhook de Pagamento

Erros Comuns

Próximos Passos