Due Charges

The following set of endpoints is responsible for managing due charges.

Create due charge (cobv)

Endpoint to create a due charge (cobv) with a specific TxId provided by the PSP.

Features of due charge (Cobv):

• Mandatory due date: Defines when the payment is due
• Flexible payment: Can be paid before, on, or after the due date
• Interest and fines: Configurable for late payments
• Discount: Configurable for early payments
• Reduction: Reduction on the original amount
• Full address: Debtor and receiver with mandatory address

Differences between Cob and Cobv:

Feature	Cob (Immediate)	Cobv (With Due Date)
Due date	❌ None	✅ Mandatory
Payment	Immediate	Can be future
Interest/Fine	❌ Not allowed	✅ Configurable
Reduction	❌ Not allowed	✅ Configurable
Discount	❌ Not allowed	✅ Configurable
Debtor address	❌ Basic optional	✅ Complete mandatory

Interest/Fine/Reduction Types:

• 1: Fixed value
• 2: Percentage

Discount Types:

• 1: Fixed value until a specific date
• 2: Percentage until a specific date
• 3: Fixed value per day of anticipation
• 4: Percentage per day of anticipation
• 5: Fixed value per business day of anticipation
• 6: Percentage per business day of anticipation

Validations:

• Due date: Must be in the future
• Addresses: Debtor and receiver mandatory and complete
• CPF/CNPJ: Must be valid and not blocked
• Values: Interest, fines, discount must be positive

PUT /v1/cobv/:txid

Requires authorization for the scope: cobv.write

Request

Simple due charge

{
  "calendario": {
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "logradouro": "Rua das Flores, 123",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "logradouro": "Av. Paulista, 1000",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "100.50"
  },
  "chave": "+5561988887777"
}

Complete payment with interest and discount

{
  "calendario": {
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "email": "[email protected]",
    "logradouro": "Rua das Flores, 123, Apto 45",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "email": "[email protected]",
    "logradouro": "Av. Paulista, 1000, Sala 100",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "500.00",
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    },
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2023-12-25",
          "valorPerc": "25.00"
        },
        {
          "data": "2023-12-28",
          "valorPerc": "10.00"
        }
      ]
    }
  },
  "chave": "[email protected]",
  "solicitacaoPagador": "Fatura #123 - Desconto até 25/12",
  "infoAdicionais": [
    {
      "nome": "Fatura",
      "valor": "#123"
    },
    {
      "nome": "Referência",
      "valor": "DEZ/2023"
    }
  ]
}

Responses

The responses below represent Success (201) and Failure/Error cases.

🟢 201

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv"
  },
  "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "logradouro": "Rua das Flores, 123",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "logradouro": "Av. Paulista, 1000",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "100.50"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de vencimento deve ser no futuro"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Get due charge

Endpoint to retrieve detailed information of a specific due charge using its txid.

Value Calculation:

The system returns the configured values (interest, fine, discount) but does not calculate the final amount. The calculation of the amount to be paid is performed at the time of payment based on the date.

Use Cases:

• Check due date: Verify if the payment is overdue
• Get QR Code: To make it available to the payer
• Audit: Track modification history
• Validate configurations: Check interest, fines, and discounts

GET /v1/cobv/:txid

Requires authorization for the scope: cobv.read

Request

The request sent to this endpoint does not require a body, only OAuth authorization headers, parameters, and the account certificate.

Responses

The responses below represent Success (200) and Failure/Error cases.

🟢 200

//Active charge with due date
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "email": "[email protected]",
    "logradouro": "Rua das Flores, 123, Apto 45",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "email": "[email protected]",
    "logradouro": "Av. Paulista, 1000, Sala 100",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "500.00",
    "juros": {
      "modalidade": 2,
      "valorPerc": "0.033"
    },
    "multa": {
      "modalidade": 2,
      "valorPerc": "2.00"
    },
    "desconto": {
      "modalidade": 1,
      "descontoDataFixa": [
        {
          "data": "2023-12-25",
          "valorPerc": "25.00"
        },
        {
          "data": "2023-12-28",
          "valorPerc": "10.00"
        }
      ]
    }
  },
  "chave": "+5561988887777",
  "solicitacaoPagador": "Fatura #123 - Desconto até 25/12",
  "infoAdicionais": [
    {
      "nome": "Fatura",
      "valor": "#123"
    },
    {
      "nome": "Referência",
      "valor": "DEZ/2023"
    }
  ],
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🟢 200

//Charge completed
{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv",
    "criacao": "2023-10-15T14:30:00Z"
  },
  "status": "CONCLUIDA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "logradouro": "Rua das Flores, 123",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "logradouro": "Av. Paulista, 1000",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "500.00"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "TxId deve ter entre 26 e 35 caracteres alfanuméricos"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 404

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Cobrança com vencimento com o txid informado não foi encontrada"
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

Update due charge

Endpoint to update information of an existing due charge (cobv).

Restrictions:

• Status: Only payments with ACTIVE status can be updated
• Due date: Cannot be changed after creation
• Key: Cannot be changed after creation
• TxId: Cannot be changed

Special Validations:

• Addresses: Debtor and receiver must have complete addresses
• Due date: If in the past, the payment may be overdue but still updatable
• Values: Interest, fine, discount must follow the correct modalities
• CPF/CNPJ: If changed, must be valid and not blocked

Behaviors:

• Revision: Automatically increments with each update
• QR Code: Regenerated with new information
• Modalities: Changes to interest/fine/discount modalities are allowed

Important!

After the update, a new QR Code will be generated. Previous QR Codes may not work.

PATCH /v1/cobv/:txid

Requires authorization for the scope: cobv.write

Request

Update values and interest

{
  "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."
}

Update debtor data

{
  "valor": {
    "original": "567.89"
  },
  "solicitacaoPagador": "Informar cartão fidelidade"
}

Full update

{
  "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}

Responses

The responses below represent Success (200) and Failure/Error cases.

🟢 200

{
  "calendario": {
    "criacao": "2023-10-15T14:30:00Z",
    "dataDeVencimento": "2023-12-31",
    "validadeAposVencimento": 30
  },
  "txid": "fb2761260e054c7a94fb7b7b",
  "revisao": 0,
  "loc": {
    "id": 789,
    "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
    "tipoCob": "cobv"
  },
  "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
  "status": "ATIVA",
  "devedor": {
    "nome": "João Silva Santos",
    "cpf": "12345678901",
    "logradouro": "Rua das Flores, 123",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01234567"
  },
  "recebedor": {
    "nome": "Empresa XYZ Ltda",
    "cnpj": "98765432000123",
    "logradouro": "Av. Paulista, 1000",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100"
  },
  "valor": {
    "original": "100.50"
  },
  "chave": "+5561988887777",
  "pixCopiaECola": "00020101021226580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426655440000520400005303986540510.005802BR5913Fulano de Tal6008BRASILIA62070503***630445CC"
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de vencimento deve ser no futuro"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}

List due charges

Endpoint to retrieve a paginated list of due charges (cobv) created by the PSP.

GET /v1/cobv

Requires authorization for the scope: cobv.read

Request

The code snippet below illustrates calling the endpoint with the minimum required parameters (the date range inicio and fim) and the format in which these parameters should be passed.

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

Responses

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

🟢 200

{
  "parametros": {
    "inicio": "2023-10-01T00:00:00Z",
    "fim": "2023-10-31T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "cobvs": [
    {
      "calendario": {
        "criacao": "2023-10-15T14:30:00Z",
        "dataDeVencimento": "2023-12-31",
        "validadeAposVencimento": 30
      },
      "txid": "fb2761260e054c7a94fb7b7b",
      "revisao": 0,
      "loc": {
        "id": 789,
        "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
        "tipoCob": "cobv"
      },
      "location": "pix.example.com/qr/v2/cobv/fb2761260e054c7a94fb7b7b",
      "status": "ATIVA",
      "devedor": {
        "nome": "João Silva Santos",
        "cpf": "12345678901",
        "logradouro": "Rua das Flores, 123",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01234567"
      },
      "recebedor": {
        "nome": "Empresa XYZ Ltda",
        "cnpj": "98765432000123",
        "logradouro": "Av. Paulista, 1000",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01310100"
      },
      "valor": {
        "original": "500.00",
        "juros": {
          "modalidade": 2,
          "valorPerc": "0.033"
        },
        "multa": {
          "modalidade": 2,
          "valorPerc": "2.00"
        },
        "desconto": {
          "modalidade": 1,
          "descontoDataFixa": [
            {
              "data": "2023-12-25",
              "valorPerc": "25.00"
            }
          ]
        }
      },
      "chave": "+5561988887777",
      "solicitacaoPagador": "Fatura #123 - Desconto até 25/12",
      "infoAdicionais": [
        {
          "nome": "Fatura",
          "valor": "#123"
        }
      ]
    },
    {
      "calendario": {
        "criacao": "2023-10-16T09:15:00Z",
        "dataDeVencimento": "2024-01-15",
        "validadeAposVencimento": 15
      },
      "txid": "ac3849f6b2d54e8a95fb1b2c",
      "revisao": 0,
      "loc": {
        "id": 790,
        "location": "pix.example.com/qr/v2/cobv/ac3849f6b2d54e8a95fb1b2c",
        "tipoCob": "cobv"
      },
      "status": "CONCLUIDA",
      "devedor": {
        "nome": "Maria Silva",
        "cpf": "98765432100",
        "logradouro": "Av. Brasil, 456",
        "cidade": "Rio de Janeiro",
        "uf": "RJ",
        "cep": "20040020"
      },
      "recebedor": {
        "nome": "Loja ABC Ltda",
        "cnpj": "11223344000156",
        "logradouro": "Rua Comercial, 789",
        "cidade": "Rio de Janeiro",
        "uf": "RJ",
        "cep": "20050030"
      },
      "valor": {
        "original": "250.00"
      },
      "chave": "[email protected]"
    }
  ]
}

🔴 400

{
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "error": {
    "status": 400,
    "title": "Bad Request",
    "detail": "Data de início deve ser anterior à data de fim"
  }
}

🔴 401

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Unauthorized",
    "detail": "Token de acesso inválido ou expirado",
    "status": 401
  }
}

🔴 403

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "Forbidden",
    "detail": "Acesso negado",
    "status": 403
  }
}

🔴 500

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "InternalServerError",
    "detail": "Erro interno do servidor",
    "status": 500
  }
}

🔴 503

{
  "correlationId": "abcdef01-2345-6789-0123-456789012345",
  "error": {
    "title": "ServiceUnavailable",
    "detail": "Serviço temporariamente indisponível",
    "status": 503
  }
}