Cobranças

Sobre a migração da /v1/bank-slips para /banking/collection

Existem alguns pontos de atenção referentes ao processo migratório da API. Caso você seja um usuário que já iniciou o processo de integração na API de collections, esta seção deve ser ignorada.

Persistência de boletos

Todos os boletos gerados em /v1/bank-slips estarão disponíveis em /banking/collection dando na listagem de titulo quanto webhook. Assim, garantimos que nçao haverão perdas de títulos od nomento do desligamento do serviço

bankslipId

O campo bankslipId deixa de ser o principal identificador das cobranças realizadas. Nesta nova API, este dado é é representado por externalId.

Para boletos gerados via /v1/bank-slips antes da migração, será necessário que o monitoramento deste titulos sendo feito via consultar cujo filtro é o externalId. O mesmo é válido para webhooks

Para cobranças já criadas em /banking/collection deve-se utilizar o dado collectionId como principal dado de monitoramento via webhook e listagem.

Segurança

📘
BTG Id
O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Cobranças deve ser gerado usando o Authorization Code.

O escopo openidé obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário incluir o seguinte escopo:

Escopo	Descrição
brn:btg:empresas:banking:collections	Permite a consulta e gestão de cobrança
brn:btg:empresas:banking:collections.readonly	Permite apenas consulta de cobranças

Recursos Disponíveis

Com esta API é possível emitir cobranças em formato de boleto tradicional, boleto híbrido, ou PIX. Além disso, é possível configurar na requisição uma série de parametros como juros, multa datas de vencimento e limite de pagamento e mais.

Verifique os payloads de criação em Criar Cobrança.

Boleto tradicional

A criação de um boleto tradicional é definido pela propriedade type e ocorre quando esta assume o valor BANKSLIP.

{
  "type":"BANKSLIP",
  "amount":10,
  
//Restante do boleto...
}

Boleto híbrido

A criação de um boleto híbrido é definido pela propriedade type e ocorre quando esta assume o valor BANKSLIP_QRCODE. O boleto híbrido possui toda a estrutura de um boleto tradicional, porém é acompanhado de um QR Code para pagamento via PIX

Esta modalidade permite a utilização da jornada 4 do PIX Automático, caso o objeto.

{
  "type":"BANKSLIP_QRCODE",
  "amount":10,
  
//Restante do boleto híbrido...
}

PIX Cobrança QR Code com data de vencimento

A criação de um PIX Cobrança com data de vencimento é definido pela propriedade type e ocorre quando esta assume o valor DUE_DATE_QRCODE

{
  "type":"DUE_DATE_QRCODE",
  "amount":10,
  
//Restante do PIX Cobrança...
}

Especificidades

Utilização da jornada 4 do PIX Automático

❗️
Importante
A criação da autorização e, consequentemente, a inicio da jornada 4 ocorrerá SOMENTE SE o pagamento do boleto for realizado por meio do QR Code. Outros métodos de pagamento do boleto não iniciaram a jornada de PIX Automático.

A jornada 4 do PIX Automático pode ser utilizada somente na emissão de boletos híbridos.

Para ativar a jornada, é necessário que seja criado um boleto híbrido e adicionamente seja passado um objeto automaticPixDetails conforme exemplo:

{
  "type": "BANKSLIP_QRCODE",
  "automaticPixDetails": {
    "period": "ANNUALLY",
    "retryPolicy": "ACCEPT_3R_7D",
    "contract": "54872120205AASS12",
    "initialDate": "2025-04-18"
  }
	//Restante do payload do boleto...
}

Juros pencentuais

O campo de juros na opção percentual é cobrado diariamente após o vencimento da cobrança, mas o valor percentual deve ser configurado em relação ao quanto se deseja cobrar mensalmente.

Por exemplo, se você deseja cobrar 0.03% de juros ao dia, deve-se realizar o post com o valor pencentual de 1%.

Vale ressaltar que o juros é cobrado por dias corridos, então seriam acrescidos 0,03% de juros mesmo em fins de semana e feriados.

Status da cobrança

Uma cobrança pode ter diversos status:

Status	Descrição
CREATED	Cobrança emitida
PAID	Cobrança pago
CANCELED	Cobrança cancelada
EXPIRED	Cobrança vencida
PROCESSING	Cobrança em processamento
FAILED	Falha na emissão da cobrança
UPDATED	Cobrança atualizada
UPDATING	Cobrança em atualização
UPDATE_FAILED	Falha na atualização da cobrança
CANCEL_FAILED	Falha no cancelamento da cobrança
RETURNED	Cobrança estornada
CANCELING	Cobrança em cancelamento

Eventos de webhook

Os payloads disponíveis abaixo representam o conteúdo do campo data, seguindo o formato do envio descrito em Eventos.

Evento	Descrição
`collections.created`	Cobrança criada.
`collections.processing`	Cobrança em processamento
`collections.paid`	Cobrança paga.
`collections.expired`	Cobrança expirada.
`colections.cancelled`	Cobrança cancelada.
`collections.failed`	Falha na emissão da cobrança
`collections.updated`	Cobrança atualizada
`collections.update_failed`	Falha na atualização da cobrança

collections.created

{
    "amount": 4620,
    "origin": "APP",
    "dueDate": "2025-10-07",
    "overDueDate": "2026-02-04",
    "type": "BANKSLIP",
    "payer": {
        "address": {
            "number": "11111",
            "zipCode": "111111111",
            "city": "VOLTA REDONDA",
            "street": "RUA",
            "state": "RJ",
        },
        "taxId": "21342341243234",
        "name": "NOME",
        "personType": "J"
    },
    "floatingInDays": 1,
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "12342134234",
        "taxId": "2123421400103",
        "name": "NOME",
        "personType": "J"
    },
    "installmentNumber": 1,
    "createdAt": "2025-08-08T18:35:25.000Z",
    "totalInstallments": 1,
    "timelineException": false,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "interest": {
        "type": "NOT_APPLICABLE",
        "value": 0
    },
    "fine": {
        "type": "NOT_APPLICABLE",
        "value": 0
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "isAnticipated": false
    },
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "5269/3",
        "externalId": "5edb5555-54c1-4ab7-960e-f54055555d212",
        "ourNumber": "13752155718125475",
        "barCode": "555555543213400000500155755555505224880",
        "digitableLine": "20812555555555806112270000462000"
    },
    "collectionId": "555555-7dcd-4ab9-bdd1-555555b4",
    "updatedAt": "2025-08-08T18:35:25.000Z",
    "status": "CREATED"
}

collections.paid

{
    "amount": 9200,
    "origin": "WEB",
    "dueDate": "2025-08-12",
    "overDueDate": "2025-12-10",
    "type": "BANKSLIP_QRCODE",
    "payer": {
        "address": {
            "number": "11111",
            "zipCode": "521341240",
            "city": "Recife",
            "street": "RUA",
            "state": "PE",
        },
        "taxId": "01324124321464",
        "name": "NOME",
        "personType": "J"
    },
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "123421424",
        "taxId": "1234214214",
        "name": "NOME",
        "personType": "J"
    },
    "createdAt": "2025-06-13T21:36:06.000Z",
    "timelineException": false,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "amountPaid": 9200,
    "interest": {
        "type": "PERCENTAGE_PER_MONTH",
        "value": 8,
        "startDate": "2025-08-13"
    },
    "fine": {
        "type": "NOT_APPLICABLE",
        "value": 0
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "anticipationDate": "2025-06-16",
        "isAnticipated": true
    },
    "settledAt": "2025-08-08",
    "paidAt": "2025-08-08",
    "paymentMethod": "QRCODE",
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "28045",
        "externalId": "644444ce2-4444-40e4-8e4f-144444444",
        "ourNumber": "84306546310566684",
        "barCode": "2012342142148405378560",
        "digitableLine": "201234124124124124920000",
        "emv": "00020101021226960014br.gov.bcb.pix2574api.developer.btgpactual.com/v1/p/v2/cobv/4444447a95fc5442ca144444830664479d524444449865802BR5925DMH - TESTE6009SAO PAULO61080453813362070503***630426B7"
    },
    "collectionId": "444444e81-6cef-4bf7-44444-4240309f67d5",
    "updatedAt": "2025-08-08T18:34:32.000Z",
    "status": "PAID"
}

collections.expired

{
  "collectionId": "be9ed6e9-4444-4f8a-8c8a-ef4441ad44b6",
  "createdAt": "2025-03-08T06:20:49.341Z",
  "amount": 487.25,
  "batchId": "444444ce8-1611-4284-a541-7af4444444a",
  "deliveryMediums": [],
  "type": "BANKSLIP",
  "payee": {
    "name": "NAME",
    "bankCode": "208",
    "branchCode": "1",
    "number": "004444445",
    "personType": "J",
    "taxId": "52664444444435"
  },
  "updatedAt": "2025-03-08T06:20:53.000Z",
  "origin": "CNAB",
  "payer": {
    "taxId": "4444446153",
    "name": "NAME",
    "personType": "F",
    "address": {
      "city": "S.CAETANO SUL",
      "number": "83",
      "state": "SP",
      "street": "RUA SAMUEL KLEIN",
      "zipCode": "09510125",
    }
  },
  "status": "EXPIRED",
  "correlationId": "54444444140049350804",
  "badCredit": {},
  "anticipation": { "isAnticipated": false },
  "detail": {
    "externalId": "e44444-62ab-46c8-8b5b-4444443fe61",
    "barCode": "208941144444410000058465444444090",
    "digitableLine": "208444444444071090441135044444425",
    "ourNumber": "00000444444",
    "documentNumber": "000000000000000"
  },
  "interest": {
    "startDate": "2025-07-08",
    "type": "PERCENTAGE_PER_MONTH",
    "value": 9.96
  },
  "fine": { "startDate": "2025-07-08", "type": "PERCENTAGE", "value": 4 },
  "discounts": [ { "limitDate": "2025-07-02", "type": "PERCENTAGE", "value": 1.5 } ],
  "overDueDate": "2025-08-06",
  "dueDate": "2025-07-07",
  "installmentNumber": 1,
  "totalInstallments": 1,
  "automaticBadCreditException": false,
  "timelineException": false
}

collections.cancelled

{
    "amount": 2.97,
    "origin": "WEB",
    "dueDate": "2025-12-13",
    "description": "DESCRIÇÃO",
    "overDueDate": "2026-12-13",
    "type": "BANKSLIP_QRCODE",
    "payer": {
        "taxId": "17584193773",
        "name": "Carlos Caliman",
        "personType": "F"
    },
    "floatingInDays": 1,
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "0107444444",
        "taxId": "474444444108",
        "name": "NOME",
        "personType": "J"
    },
    "installmentNumber": 1,
    "createdAt": "2025-07-28T21:05:50.000Z",
    "totalInstallments": 1,
    "timelineException": false,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "canceledAt": "2025-08-08",
    "interest": {
        "type": "FIXED_VALUE_PER_DAY",
        "value": 2,
        "startDate": "2025-12-14"
    },
    "fine": {
        "type": "PERCENTAGE",
        "value": 1,
        "startDate": "2025-12-14"
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "isAnticipated": false
    },
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "teste",
        "externalId": "3444470-a44e-48bc-8b19-6aa244444e32",
        "ourNumber": "74198196346750084",
        "barCode": "2089444444444440001050050014444444410773460",
        "digitableLine": "20890050091963444444444604112940000000105",
        "emv": "00020101021226980014br.gov.bcb.pix2576api-h.developer.btgpactual.com/pc/p/v2/cobv/5b3969415dca40758c8bad8ae849dd64520444444445802BR5925TESTEsao paulo62070503***63044F03"
    },
    "collectionId": "4444bf8b-f0e7-4444-9cd7-c6ef444f2af5",
    "updatedAt": "2025-08-08T19:15:06.000Z",
    "status": "CANCELED"
}

collections.failed

{
    "amount": 15121.76,
    "origin": "DEVELOPERS",
    "dueDate": "2026-02-02",
    "overDueDate": "2026-06-02",
    "type": "BANKSLIP_QRCODE",
    "payer": {
        "address": {
            "number": "11",
            "zipCode": "010353333",
            "city": "São Paulo",
            "street": "Rua teste",
            "state": "SP",
        },
        "taxId": "11111111111",
        "name": "EMPRESA PAGADORA TESTE",
        "personType": "J",
        "ispb": "9999999"
    },
    "floatingInDays": 1,
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "12341234",
        "taxId": "11111111111",
        "name": "EMPRESA RECEBEDORA TESTE",
        "personType": "J"
    },
    "installmentNumber": 1,
    "createdAt": "2026-01-23T15:01:38.352Z",
    "totalInstallments": 1,
    "discounts": [
        {
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "amountPaid": 15121.76,
    "interest": {
        "type": "PERCENTAGE_PER_MONTH",
        "value": 1,
        "startDate": "2026-02-03"
    },
    "fine": {
        "type": "PERCENTAGE",
        "value": 2,
        "startDate": "2026-02-03"
    },
    "automaticBadCreditException": false,
    "anticipation": {
        "isAnticipated": false
    },
    "paidAt": "2026-02-02",
    "paymentMethod": "BARCODE",
    "correlationId": "new-bill",
    "detail": {
        "documentNumber": "190",
        "externalId": "111111111111111",
        "ourNumber": "11111111111111111",
        "barCode": "11111111111111111111111",
        "digitableLine": "111111111111111111",
        "emv": "new-emv"
    },
    "collectionId": "b6496e1e-8af4-4624-acc5-25d55d36355f",
    "updatedAt": "2026-02-02T10:21:36.000Z",
    "status": "FAILED"
}

collections.processing

{
    "amount": 608.41,
    "origin": "DEVELOPERS",
    "dueDate": "2026-02-05",
    "description": "TESTE",
    "overDueDate": "2026-06-05",
    "type": "BANKSLIP",
    "payer": {
        "taxId": "12342134",
        "name": "TESTE",
        "personType": "F"
    },
    "floatingInDays": 1,
    "payee": {
        "branchCode": "50",
        "bankCode": "208",
        "number": "111111111",
        "taxId": "1111111111111",
        "name": "TESTE RECEBEDOR",
        "personType": "J"
    },
    "createdAt": "2026-02-02T13:20:44.588Z",
    "discounts": [
        {
            "limitDate": "2026-02-05",
            "type": "NOT_APPLICABLE",
            "value": 0
        }
    ],
    "interest": {
        "type": "PERCENTAGE_PER_MONTH",
        "value": 1,
        "startDate": "2026-02-06"
    },
    "fine": {
        "type": "PERCENTAGE",
        "value": 10,
        "startDate": "2026-02-06"
    },
    "anticipation": {
        "isAnticipated": false
    },
    "correlationId": "new-bill",
    "deliveryMediums": [
        "Email"
    ],
    "detail": {
        "documentNumber": "02-2026",
        "externalId": "222222222222222",
        "ourNumber": "04330594848444588",
        "barCode": "1111111111111111111",
        "digitableLine": "1111111111111111111"
    },
    "collectionId": "cafa8b63-ad7c-41db-8d72-a3d703420547",
    "updatedAt": "2026-02-02T13:20:44.588Z",
    "status": "PROCESSING"
}

collections.updated

{
  "collectionId": "019d8d6a-7099-7668-94e6-d9a95a681df5",
  "createdAt": "2026-04-14T19:14:16.344Z",
  "amount": 1,
  "deliveryMediums": [],
  "type": "BANKSLIP_QRCODE",
  "description": "Boleto",
  "payee": {
    "name": "Teste",
    "bankCode": "208",
    "branchCode": "50",
    "number": "001111111",
    "personType": "J",
    "taxId": "14101441000101"
  },
  "updatedAt": "2026-05-08T14:20:46.000Z",
  "origin": "DEVELOPERS",
  "payer": {
    "taxId": "05555555000505",
    "phoneNumber": "+5511955555555",
    "name": "AB COMERCIO DE VEICULOS LTDA",
    "personType": "J",
    "email": "[email protected]",
    "address": {
      "city": "teste",
      "number": "44444",
      "state": "SP",
      "street": "AV BRIGADEIRO FARIA LIMA",
      "zipCode": "33303333",
    }
  },
  "status": "UPDATED",
  "correlationId": "125940",
  "badCredit": {},
  "anticipation": {
    "isAnticipated": false
  },
  "detail": {
    "externalId": "019d8d6a-7098-7668-94e6-bc05bad4d4d8",
    "barCode": "20891555700006555710050010000009555505554555",
    "digitableLine": "20850050055000000955459083240206114550000655551",
    "ourNumber": "95559",
    "documentNumber": "95559",
    "emv": "00020501055556960014br.gov.bcb.pix2574api.developer.btgpactual.com/pc/p/v2/cobv/7c0606dbbcab449e80f4d736b009563f5255000053035565552BR5925TESTE DE6009SAO PAULO61080453813355075503***80950014br.gov.bcb.pix2573api.developer.btgpactual.com/pc/p/v2/rec/b6876218d9104320b4165152128e009f630428D7"
  },
  "interest": {
    "startDate": "2026-05-09",
    "type": "PERCENTAGE_PER_MONTH",
    "value": 10
  },
  "fine": {
    "startDate": "2026-05-09",
    "type": "FIXED_VALUE",
    "value": 1
  },
  "discounts": [
    {
      "type": "NOT_APPLICABLE",
      "value": 0
    }
  ],
  "overDueDate": "2026-09-05",
  "dueDate": "2026-05-08",
  "installmentNumber": 1,
  "totalInstallments": 1,
  "automaticBadCreditException": false,
  "floatingInDays": 1
}

collections.update_failed

{
  "collectionId": "019d8d6a-7099-7668-94e6-d9a95a681df5",
  "createdAt": "2026-04-14T19:14:16.344Z",
  "amount": 1,
  "deliveryMediums": [],
  "type": "BANKSLIP_QRCODE",
  "description": "Boleto",
  "payee": {
    "name": "Teste",
    "bankCode": "208",
    "branchCode": "50",
    "number": "001111111",
    "personType": "J",
    "taxId": "14101441000101"
  },
  "updatedAt": "2026-05-08T14:20:46.000Z",
  "origin": "DEVELOPERS",
  "payer": {
    "taxId": "05555555000505",
    "phoneNumber": "+5511955555555",
    "name": "AB COMERCIO DE VEICULOS LTDA",
    "personType": "J",
    "email": "[email protected]",
    "address": {
      "city": "teste",
      "number": "44444",
      "state": "SP",
      "street": "AV BRIGADEIRO FARIA LIMA",
      "zipCode": "33303333",
    }
  },
  "status": "UPDATE_FAILED",
  "correlationId": "125940",
  "badCredit": {},
  "anticipation": {
    "isAnticipated": false
  },
  "detail": {
    "externalId": "019d8d6a-7098-7668-94e6-bc05bad4d4d8",
    "barCode": "20891555700006555710050010000009555505554555",
    "digitableLine": "20850050055000000955459083240206114550000655551",
    "ourNumber": "95559",
    "documentNumber": "95559",
    "emv": "00020501055556960014br.gov.bcb.pix2574api.developer.btgpactual.com/pc/p/v2/cobv/7c0606dbbcab449e80f4d736b009563f5255000053035565552BR5925TESTE DE6009SAO PAULO61080453813355075503***80950014br.gov.bcb.pix2573api.developer.btgpactual.com/pc/p/v2/rec/b6876218d9104320b4165152128e009f630428D7"
  },
  "interest": {
    "startDate": "2026-05-09",
    "type": "PERCENTAGE_PER_MONTH",
    "value": 10
  },
  "fine": {
    "startDate": "2026-05-09",
    "type": "FIXED_VALUE",
    "value": 1
  },
  "discounts": [
    {
      "type": "NOT_APPLICABLE",
      "value": 0
    }
  ],
  "overDueDate": "2026-09-05",
  "dueDate": "2026-05-08",
  "installmentNumber": 1,
  "totalInstallments": 1,
  "automaticBadCreditException": false,
  "floatingInDays": 1
}