Cobrancas com Vencimento

Gerencie cobrancas Pix com data de vencimento (cobv), incluindo multas, juros e descontos.

A diferenca entre cob (cobranca imediata) e cobv (cobranca com vencimento) e que a cobv permite definir uma data de vencimento, multas, juros e descontos. A cobranca imediata (cob) expira apos o tempo definido em calendario.expiracao, enquanto a cobv permanece valida ate a data de vencimento mais o periodo de validade apos vencimento.

Criar Cobrança com Vencimento

PUT/cobv/{txid}

Cria uma cobranca Pix com vencimento (cobv). O txid deve ser definido pelo cliente e ser unico.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo do conteudo da requisicao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`txid`	string	Identificador da transacao (26-35 caracteres alfanumericos)

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`calendario.dataDeVencimento`	string	Obrigatorio	Data de vencimento da cobranca (formato YYYY-MM-DD)
`calendario.validadeAposVencimento`	integer	Opcional	Quantidade de dias que a cobranca permanece valida apos o vencimento
`devedor.cpf`	string	Opcional	CPF do devedor (usar cpf OU cnpj, nao ambos)
`devedor.cnpj`	string	Opcional	CNPJ do devedor (usar cpf OU cnpj, nao ambos)
`devedor.nome`	string	Obrigatorio	Nome do devedor
`valor.original`	string	Obrigatorio	Valor original da cobranca em BRL (ex: "100.00")
`valor.multa.modalidade`	integer	Opcional	Modalidade da multa: 1 = valor fixo, 2 = percentual
`valor.multa.valorPerc`	string	Opcional	Valor ou percentual da multa (ex: "2.00")
`valor.juros.modalidade`	integer	Opcional	Modalidade dos juros: 1 = valor por dia, 2 = percentual por dia, 3 = percentual por mes, etc.
`valor.juros.valorPerc`	string	Opcional	Valor ou percentual dos juros (ex: "0.033")
`valor.desconto.modalidade`	integer	Opcional	Modalidade do desconto: 1 = valor fixo por data, 2 = percentual por data
`valor.desconto.descontoDataFixa`	array	Opcional	Array de descontos por data [{data, valorPerc}]
`chave`	string	Obrigatorio	Chave Pix cadastrada na conta
`solicitacaoPagador`	string	Opcional	Descricao do pagamento visivel para o pagador (max 140 caracteres)

Exemplo de Request

{
  "calendario": {
    "dataDeVencimento": "2025-02-15",
    "validadeAposVencimento": 30
  },
  "devedor": {
    "cpf": "12345678909",
    "nome": "Fulano de Tal"
  },
  "valor": {
    "original": "100.00",
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2025-02-10",
          "valorPerc": "5.00"
        }
      ]
    }
  },
  "chave": "sua-chave-pix@example.com",
  "solicitacaoPagador": "Fatura #98765"
}

Exemplo de Response

{
  "calendario": {
    "criacao": "2025-01-15T10: 30: 00.000Z",
    "dataDeVencimento": "2025-02-15",
    "validadeAposVencimento": 30
  },
  "txid": "abcdefghijklmnopqrstuvwxyz12",
  "revisao": 0,
  "loc": {
    "id": 5678,
    "location": "pix.example.com/qr/v2/cobv123abc",
    "tipoCob": "cobv"
  },
  "location": "pix.example.com/qr/v2/cobv123abc",
  "status": "ATIVA",
  "devedor": {
    "cpf": "12345678909",
    "nome": "Fulano de Tal"
  },
  "valor": {
    "original": "100.00",
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2025-02-10",
          "valorPerc": "5.00"
        }
      ]
    }
  },
  "chave": "sua-chave-pix@example.com",
  "solicitacaoPagador": "Fatura #98765",
  "pixCopiaECola": "00020126580014br.gov.bcb.pix..."
}

Exemplos de Codigo

curl -X PUT https://api.pix.basspago.com.br/cobv/abcdefghijklmnopqrstuvwxyz12 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "calendario": {
      "dataDeVencimento": "2025-02-15",
      "validadeAposVencimento": 30
    },
    "devedor": {
      "cpf": "12345678909",
      "nome": "Fulano de Tal"
    },
    "valor": {
      "original": "100.00",
      "multa": {
        "modalidade": 2,
        "valorPerc": "2.00"
      },
      "juros": {
        "modalidade": 2,
        "valorPerc": "0.033"
      }
    },
    "chave": "sua-chave-pix@example.com",
    "solicitacaoPagador": "Fatura #98765"
  }'

Atualizar Cobrança com Vencimento

PATCH/cobv/{txid}

Atualiza parcialmente uma cobranca com vencimento existente. Apenas os campos enviados serao alterados.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo do conteudo da requisicao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`txid`	string	Identificador da transacao a ser atualizada

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`calendario.dataDeVencimento`	string	Opcional	Nova data de vencimento (formato YYYY-MM-DD)
`valor.original`	string	Opcional	Novo valor da cobranca em BRL
`solicitacaoPagador`	string	Opcional	Nova descricao do pagamento

Exemplo de Request

{
  "calendario": {
    "dataDeVencimento": "2025-03-01"
  },
  "valor": {
    "original": "150.00"
  }
}

Exemplo de Response

{
  "calendario": {
    "criacao": "2025-01-15T10: 30: 00.000Z",
    "dataDeVencimento": "2025-03-01",
    "validadeAposVencimento": 30
  },
  "txid": "abcdefghijklmnopqrstuvwxyz12",
  "revisao": 1,
  "status": "ATIVA",
  "valor": {
    "original": "150.00"
  }
}

Exemplos de Codigo

curl -X PATCH https://api.pix.basspago.com.br/cobv/abcdefghijklmnopqrstuvwxyz12 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "calendario": {
      "dataDeVencimento": "2025-03-01"
    },
    "valor": {
      "original": "150.00"
    }
  }'

Consultar Cobrança com Vencimento

GET/cobv/{txid}

Consulta uma cobranca com vencimento especifica pelo txid.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`txid`	string	Identificador da transacao a ser consultada

Exemplo de Response

{
  "calendario": {
    "criacao": "2025-01-15T10: 30: 00.000Z",
    "dataDeVencimento": "2025-02-15",
    "validadeAposVencimento": 30
  },
  "txid": "abcdefghijklmnopqrstuvwxyz12",
  "revisao": 0,
  "loc": {
    "id": 5678,
    "location": "pix.example.com/qr/v2/cobv123abc",
    "tipoCob": "cobv"
  },
  "status": "ATIVA",
  "devedor": {
    "cpf": "12345678909",
    "nome": "Fulano de Tal"
  },
  "valor": {
    "original": "100.00",
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    }
  },
  "chave": "sua-chave-pix@example.com",
  "solicitacaoPagador": "Fatura #98765",
  "pixCopiaECola": "00020126580014br.gov.bcb.pix..."
}

Exemplos de Codigo

curl -X GET https://api.pix.basspago.com.br/cobv/abcdefghijklmnopqrstuvwxyz12 \
  -H "Authorization: Bearer {access_token}"

Listar Cobranças com Vencimento

GET/cobv

Lista cobrancas com vencimento, com suporte a paginacao e filtro por periodo.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Query

Nome	Tipo	Obrigatorio	Descricao
`inicio`	string	Obrigatorio	Data/hora inicial do periodo de consulta (formato RFC 3339, ex: 2025-01-01T00:00:00Z)
`fim`	string	Obrigatorio	Data/hora final do periodo de consulta (formato RFC 3339, ex: 2025-01-31T23:59:59Z)
`paginacao.paginaAtual`	integer	Opcional	Numero da pagina atual para paginacao (inicia em 0)
`paginacao.itensPorPagina`	integer	Opcional	Quantidade de itens por pagina (1 a 1000)

Exemplo de Response

{
  "parametros": {
    "inicio": "2025-01-01T00: 00:00Z",
    "fim": "2025-01-31T23: 59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "cobs": [
    {
      "calendario": {
        "criacao": "2025-01-15T10: 30: 00.000Z",
        "dataDeVencimento": "2025-02-15",
        "validadeAposVencimento": 30
      },
      "txid": "abcdefghijklmnopqrstuvwxyz12",
      "status": "ATIVA",
      "valor": {
        "original": "100.00"
      },
      "chave": "sua-chave-pix@example.com"
    }
  ]
}

Exemplos de Codigo

curl -X GET "https://api.pix.basspago.com.br/cobv?inicio=2025-01-01T00:00:00Z&fim=2025-01-31T23:59:59Z&paginacao.paginaAtual=0&paginacao.itensPorPagina=100" \
  -H "Authorization: Bearer {access_token}"