Skip to main content

Due Charges

The following set of endpoints is responsible for managing due charges. Charges, in the context of the Pix API, represent a financial transaction between a payer and a payee, with Pix being the payment method.


Information

To test the Pix CobV charge endpoints in the sandbox environment, it's possible to simulate all the statuses returned by our API and webhook.

Charges with values between R$ 0.01 to R$ 10.00 are confirmed, and you will receive the information via Webhook.
Charges with values above R$ 10.00 remain active without confirmation, and there is no webhook in these cases.


Create Due Charge​

Endpoint to register a due charge with a transaction identifier (txid).

PUT /v2/cobv/:txid
Requires authorization for the scope: cobv.write


Request

{
  "calendario": {
    "dataDeVencimento": "2022-12-01",
    "validadeAposVencimento": 30
  },
  "devedor": {
    "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
    "cidade": "Recife",
    "uf": "PE",
    "cep": "70011750",
    "cpf": "12345678909",
    "nome": "Francisco da Silva"
  },
  "valor": {
    "original": "123.45",
    "multa": {
      "modalidade": 2,
      "valorPerc": "15.00"
    },
    "juros": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2022-11-30",
          "valorPerc": "30.00"
        }
      ]
    }
  },
  "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  "solicitacaoPagador": "Cobrança dos serviços prestados."
}

Responses

The responses below represent Success(201) and consumption failures/errors.

{
  "calendario": {
    "criacao": "2020-09-09T20:15:00.358Z",
    "dataDeVencimento": "2020-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cobv"
  },
  "status": "ATIVA",
  "devedor": {
    "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
    "cidade": "Recife",
    "uf": "PE",
    "cep": "70011750",
    "cpf": "12345678909",
    "nome": "Francisco da Silva"
  },
  "recebedor": {
    "logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "70800100",
    "cnpj": "56989000019533",
    "nome": "Empresa de Logística SA"
  },
  "valor": {
    "original": "123.45"
  },
  "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  "solicitacaoPagador": "Cobrança dos serviços prestados.",
  "pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}

Review Due Charge​

Endpoint to review (modify) a due charge based on its txid.

PATCH /v2/cobv/:txid
Requires authorization for the scope: cobv.write


Request

{
  "loc": {
    "id": 789
  },
  "devedor": {
    "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
    "cidade": "Recife",
    "uf": "PE",
    "cep": "70011750",
    "cpf": "12345678909",
    "nome": "Francisco da Silva"
  },
  "valor": {
    "original": "123.45"
  },
  "solicitacaoPagador": "Cobrança dos serviços prestados."
}

Respostas

The responses below represent Success(200) and consumption failures/errors.

{
  "calendario": {
    "criacao": "2020-09-09T20:15:00.358Z",
    "dataDeVencimento": "2020-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cobv"
  },
  "status": "ATIVA",
  "devedor": {
    "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
    "cidade": "Recife",
    "uf": "PE",
    "cep": "70011750",
    "cpf": "12345678909",
    "nome": "Francisco da Silva"
  },
  "recebedor": {
    "logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "70800100",
    "cnpj": "56989000019533",
    "nome": "Empresa de Logística SA"
  },
  "valor": {
    "original": "123.45"
  },
  "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  "solicitacaoPagador": "Cobrança dos serviços prestados.",
  "pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}

Get Due Charge​

Endpoint to retrieve information about a due charge based on its txid.****

GET /v2/cobv/:txid
Requires authorization for the scope: cobv.read


Request

It's also possible to retrieve information about a specific revision of a charge. To do this, you need to provide the query param revisao. Example: /v2/cobv/:txid/?revisao=1. When the parameter is not provided, the most recent revision is returned by default.

Responses

The responses below represent Success(200) and consumption failures/errors.

{
  "calendario": {
    "criacao": "2020-09-09T20:15:00.358Z",
    "dataDeVencimento": "2020-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "cobv"
  },
  "status": "ATIVA",
  "devedor": {
    "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
    "cidade": "Recife",
    "uf": "PE",
    "cep": "70011750",
    "cpf": "12345678909",
    "nome": "Francisco da Silva"
  },
  "recebedor": {
    "logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "70800100",
    "cnpj": "56989000019533",
    "nome": "Empresa de Logística SA"
  },
  "valor": {
    "original": "123.45"
  },
  "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  "solicitacaoPagador": "Cobrança dos serviços prestados.",
  "pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}

Get Due Charges List​

Endpoint to retrieve a list of due charges using parameters such as inicio, fim, CPF, CNPJ, and status.

GET /v2/cobv
Requires authorization for the scope: cobv.read


Request

The code snippet below illustrates how to consume the endpoint with the minimum possible parameters (the date interval inicio and fim) and the format in which these parameters should be passed.

/v2/cobv?inicio=2020-10-22T16:01:35Z&fim=2020-11-30T20:10:00Z

Responses

The responses below represent Success(200) and consumption failures/errors.

{
  "parametros": {
    "inicio": "2022-01-01T23:59:59.000Z",
    "fim": "2022-12-31T23:59:59.000Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 13
    }
  },
  "cobs": [
    {
      "calendario": {
        "criacao": "2022-11-12T18:32:10.000Z",
        "dataDeVencimento": "2090-12-31",
        "validadeAposVencimento": 90
      },
      "txid": "31a0baG77448041d64352h4523459",
      "revisao": 1,
      "status": "ATIVA",
      "devedor": {
        "nome": "Empreendimentos",
        "cnpj": "53747188000100"
      },
      "recebedor": {
        "logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "70800100",
        "cnpj": "56989000019533",
        "nome": "Empresa de Logística SA"
      },
      "valor": {
        "original": "123.45",
        "juros": {
          "modalidade": 2,
          "valorPerc": "0.30"
        },
        "multa": {
          "modalidade": 2,
          "valorPerc": "2.00"
        },
        "desconto": {
          "modalidade": 1,
          "descontoDataFixa": [
            {
              "data": "2022-10-15",
              "valorPerc": "30.00"
            }
          ]
        }
      },
      "chave": "5f84a6c5-c5cb-4569-9f13-7eb4d410dacc",
      "solicitacaoPagador": "Cobrança dos serviços prestados.",
      "infoAdicionais": [
        {
          "nome": "Campo 1",
          "valor": "Informação Adicional1"
        },
        {
          "nome": "Campo 2",
          "valor": "Informação Adicional2"
        }
      ],
      "loc": {
        "id": 220,
        "location": "qrcodes-pix.gerencianet.com.br/v2/cobv/ba942520ab0746cfae2858d9afe485fd0",
        "tipoCob": "cobv",
        "criacao": "2022-11-12T18:32:10.000Z"
      },
      "pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C2"
    },
    {
      "calendario": {
        "criacao": "2022-10-27T17:30:59.000Z",
        "dataDeVencimento": "2022-12-31",
        "validadeAposVencimento": 30
      },
      "txid": "7976c0c97ea847578e8845634473c1f2",
      "revisao": 0,
      "status": "ATIVA",
      "devedor": {
        "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
        "cidade": "Recife",
        "uf": "PE",
        "cep": "70011750",
        "cpf": "12345678909",
        "nome": "Francisco da Silva"
      },
      "recebedor": {
        "logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "70800100",
        "cnpj": "56989000019533",
        "nome": "Empresa de Logística SA"
      },
      "valor": {
        "original": "100.00",
        "juros": {
            "modalidade": 1,
            "valorPerc": "0.25"
        },
        "multa": {
            "modalidade": 2,
            "valorPerc": "2.00"
        },
        "abatimento": {
            "modalidade": 1,
            "valorPerc": "5.00"
        },
        "desconto": {
            "modalidade": 3,
            "valorPerc": "1.00"
        }
      },
      "chave": "5f84a6c5-c5cb-4569-9f13-7eb4d410dacc",
      "solicitacaoPagador": "Informe o número ou identificador do pedido.",
      "loc": {
        "id": 215,
        "location": "qrcodes-pix.gerencianet.com.br/v2/cobv/68ae6f11868040ce980d6803ff6d904d",
        "tipoCob": "cobv",
        "criacao": "2022-10-27T17:30:59.000Z"
      },
      "pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C2",
    }
  ]
}
Last updated on