Skip to main content

Batch charges

The following set of endpoints is responsible for managing batch payments. Payments, in the context of the Pix API, represent a financial transaction between a payer and a payee, with Pix as the payment method.


Due charges in Batch​

Brings together endpoints designed to handle the management of batch payments with due dates.

Create/Update batch of due charges​

Endpoint used to create or update a batch of due charges.

Information

A request for creating a payment with status "IN_PROCESS" or "DENIED" is associated with a payment that does not actually exist, therefore it will not be listed in GET /cobv or GET /cobv/:txid.

A charge, once created via PUT /cobv/:txid, cannot be associated with a batch later.

A charge, once created via PUT /lotecobv/:id, cannot be associated with a new batch later.

The batch creation must contain at least 1 payment and at most 1000.


Dica

After generating the batch payment, you can use the endpoint to retrieve list of due charges, providing the loteCobvId parameter to return information about the batch.


PUT /v2/lotecobv/:id
Requires authorization for the scope: lotecobv.read


For the use case of changing payments, the array to be assigned in the request must be composed of the exact creation requests of payments that appeared in the array assigned in the original request.

You cannot use this endpoint to change a batch of payments by adding or removing existing payments within the set of payments originally created in the batch request.

In other words, if a batch was originally created with payments [a, b, and c], you cannot change this original set of payments represented by the batch to [a, b, c, d], or to [a, b]. However, you can change, in batch, the payments [a, b, c], as originally listed in the batch request.


Request

{
  "descricao": "Cobranças dos alunos do turno vespertino",
  "cobsv": [
    {
      "calendario": {
          "dataDeVencimento": "2020-12-31",
          "validadeAposVencimento": 30
      },
      "txid": "fb2761260e554ad593c7226beb5cb650",
      "devedor": {
          "cpf": "08577095428",
          "nome": "João Souza"
      },
      "valor": {
          "original": "100.00"
      },
      "chave": "7c084cd4-54af-4172-a516-a7d1a12b75cc",
      "solicitacaoPagador": "Informar matrícula"
      },
      {
      "calendario": {
          "dataDeVencimento": "2020-12-31",
          "validadeAposVencimento": 30
      },
      "txid": "7978c0c97ea847e78e8849634473c1f1",
      "devedor": {
          "cpf": "15311295449",
          "nome": "Manoel Silva"
      },
      "valor": {
          "original": "100.00"
      },
      "chave": "7c084cd4-54af-4172-a516-a7d1a12b75cc",
      "solicitacaoPagador": "Informar matrícula"
    }
  ]
}

Responses

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

Lote de cobranças com vencimento solicitado para criação.

Review batch specific charges​

Endpoint used to review specific charges within a batch of due charges.

Information

The difference between this endpoint and the related PUT endpoint is that this endpoint supports a cobsv array with fewer requests to create or change charges than the array assigned in the original batch request.

You cannot, however, use this endpoint to add or remove requests for changes or creation of charges as contained in the original batch request.


PATCH /v2/lotecobv/:id
Requires authorization for the scope: lotecobv.read


Request

{
  "cobsv": [
    {
      "calendario": {
        "dataDeVencimento": "2020-01-10"
      },
      "txid": "fb2761260e554ad593c7226beb5cb650",
      "valor": {
        "original": "110.00"
      }
    },
    {
      "calendario": {
        "dataDeVencimento": "2020-01-10"
      },
      "txid": "7978c0c97ea847e78e8849634473c1f1",
      "valor": {
        "original": "110.00"
      }
    }
  ]
}


Responses

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

Solicitação de revisão do Lote de cobranças encaminhada para processamento.

GET batch of due charges​

Endpoint to retrieve a specific batch of due charges.

GET /v2/lotecobv/:id
Requires authorization for the scope: lotecobv.write


Responses

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

{
  "descricao": "Cobranças dos alunos do turno vespertino",
  "criacao": "2020-11-01T20:15:00.358Z",
  "cobsv": [
    {
      "criacao": "2020-11-01T20:15:00.358Z",
      "txid": "fb2761260e554ad593c7226beb5cb650",
      "status": "CRIADA"
    },
    {
      "txid": "7978c0c97ea847e78e8849634473c1f1",
      "status": "NEGADA",
      "problema": {
        "type": "https://pix.bcb.gov.br/api/v2/error/CobVOperacaoInvalida",
        "title": "Cobrança inválida.",
        "status": 400,
        "detail": "A requisição que busca alterar ou criar uma cobrança com vencimento não respeita o _schema_ ou está semanticamente errada.",
        "violacoes": [
          {
            "razao": "O objeto cobv.devedor não respeita o _schema_.",
            "propriedade": "cobv.devedor"
          }
        ]
      }
    }
  ]
}

Get list of batch of due charges​

Endpoint to retrieve due charges using parameters such as inicio, fim, cpf, cnpj and status.

GET /v2/lotecobv
Requires authorization for the scope: lotecobv.write


Request

The code snippet below illustrates the consumption of the endpoint in a request with the minimum possible parameters (the date range inicio and fim) and the format in which these parameters should be passed.

/v2/lotecobv?inicio=2023-01-01T16:01:35Z&fim=2023-12-30T16:01:35Z

Responses

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

{
  "parametros": {
    "inicio": "2020-01-01T00:00:00Z",
    "fim": "2020-12-01T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "lotes": [
    {
      "$ref": "openapi.yaml#/components/examples/loteCobVResponse1/value"
    },
    {
      "$ref": "openapi.yaml#/components/examples/loteCobVResponse2/value"
    }
  ]
}
Last updated on