Ficha técnica

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%.

{
 //restante do payload do boleto
	"interests": {
    "arrears": {
      "type": "PERCENTAGE",
      "value": 1
    }
	},
	//restante do payload do boleto
}

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 atualizado
UPDATING	Cobrança em atualização
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.

Evento	Descrição
`collections.created`	Cobrança criada.
`collections.paid`	Cobrança paga.
`collections.expired`	Cobrança expirada.
`colections.cancelled`	Cobrança cancelada.

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",
            "neighborhood": "JARDIM AMÁLIA"
        },
        "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",
            "neighborhood": "Tamarineira",
            "complement": "até 3514/3515"
        },
        "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",
      "neighborhood": "CENTRO"
    }
  },
  "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"
}

Escopos necessários​

Recursos Disponíveis​

Boleto tradicional​

Boleto híbrido​

PIX Cobrança QR Code com data de vencimento​

Especificidades​

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

Juros pencentuais​

Status da cobrança​

Eventos de webhook​

collections.created​

collections.paid​

collections.expired​

collections.cancelled​