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 Split de Cobrança deve ser gerado usando o Authorization Code.

É necessário incluir os seguintes escopos:

Escopo	Descrição
`brn:btg:empresas:banking:collections`	Permite emitir, consultar e alterar cobranças, além de criar, atualizar e excluir splitters
`brn:btg:empresas:banking:collections.readonly`	Permite apenas consultar cobranças e splitters

Split de Cobrança — Visão Geral da API

A API de Split de Cobrança do BTG Empresas permite que sua empresa divida automaticamente o valor recebido de um boleto entre múltiplos destinatários, chamados de splitters. Ao emitir um boleto com split, o BTG distribui os valores para cada conta configurada no momento da liquidação, sem necessidade de transferência manual.

O fluxo é organizado em dois conceitos centrais: o splitter (destinatário cadastrado, reutilizável em múltiplas cobranças) e o split (plano de divisão vinculado a um boleto específico). Antes de emitir cobranças com split, é necessário cadastrar os splitters.

📘
Restrição de tipo
Split é suportado exclusivamente para cobranças do tipo BANKSLIP. Pix, QR Code e cartão de crédito não são compatíveis.

Fluxo de Splitters

O splitter representa um destinatário fixo — uma empresa (CNPJ) que receberá uma fração dos valores cobrados. Cada splitter armazena a conta bancária de destino e a configuração de divisão: um percentual (PERCENT) ou um valor absoluto em reais (VALUE). Um splitter cadastrado pode ser reutilizado em quantos boletos desejar.

Criar Splitter

O cadastro de um splitter é o ponto de entrada do fluxo. Você informa o CNPJ do destinatário, os dados da conta BTG Pactual para crédito e a configuração de divisão padrão. A API retorna imediatamente com o identificador do splitter criado.

📘
Reativação automática
Se já existir um splitter com o mesmo taxId e ele estiver com status DELETED, o registro existente é reativado com os novos dados — o UUID permanece o mesmo e o status volta para ACTIVE. Se já existir um splitter ACTIVE com o mesmo taxId, a API retorna 409 Conflict.

Requisição — POST /{companyId}/banking/splitter

{
  "taxId": "89713903000123",
  "personType": "J",
  "name": "Empresa Exemplo LTDA",
  "nickname": "Empresa Exemplo",
  "account": {
    "number": "000548981",
    "branch": "0001",
    "bankCode": "208"
  },
  "configuration": {
    "splitType": "PERCENT",
    "divisionAmount": 0.30
  }
}

O campo taxId deve ser o CNPJ do destinatário — não pode ser igual ao companyId (auto-split não é permitido). Somente Pessoa Jurídica ("J") é aceita. O campo bankCode aceita apenas "208" (BTG Pactual); qualquer outro valor é rejeitado.

Para splitType: "PERCENT", o divisionAmount deve ser um número entre 0 (exclusivo) e 1 (exclusivo) — por exemplo, 0.30 representa 30%. Para splitType: "VALUE", deve ser um valor positivo em reais.

Resposta — 201 Created

{
  "id": "019f67b5-ef74-7cce-bfae-7629d9a2584f",
  "taxId": "89713903000123",
  "personType": "J",
  "name": "Empresa Exemplo LTDA",
  "status": "ACTIVE",
  "nickname": "Empresa Exemplo",
  "account": {
    "branch": "0001",
    "number": "000548981",
    "bankCode": "208"
  },
  "configuration": {
    "splitType": "PERCENT",
    "divisionAmount": 0.30,
    "isDefault": true
  },
  "createdAt": "2026-07-15T21:36:44.404Z",
  "updatedAt": "2026-07-15T21:36:44.404Z"
}

Guarde o campo id retornado — ele é o splitterId e será usado em todas as operações subsequentes, inclusive na emissão de boletos com split.

Listagem de Splitters

Todos os splitters cadastrados ficam disponíveis para consulta. A listagem permite que sua equipe acompanhe o estado de cada destinatário — identificando splitters ativos (ACTIVE), com conta inválida (INVALID_ACCOUNT) ou excluídos (DELETED) — e aplique filtros por nome, CNPJ, status ou tipo de divisão.

A paginação pode ser feita por número de página ou por cursor. Quando o campo _links.next estiver presente na resposta, há mais páginas disponíveis.

Resposta — GET /{companyId}/banking/splitter?pageSize=10&pageNumber=1&status=ACTIVE

{
  "data": [
    {
      "id": "019f67b5-ef74-7cce-bfae-7629d9a2584f",
      "taxId": "89713903000123",
      "personType": "J",
      "name": "Empresa Exemplo LTDA",
      "status": "ACTIVE",
      "nickname": "Empresa Exemplo",
      "account": {
        "branch": "0001",
        "number": "000548981",
        "bankCode": "208"
      },
      "configuration": {
        "splitType": "PERCENT",
        "divisionAmount": 0.30,
        "isDefault": true
      },
      "createdAt": "2026-07-15T21:36:44.404Z",
      "updatedAt": "2026-07-15T21:36:44.404Z"
    }
  ],
  "_links": {
    "next": {
      "href": "?cursor=eyJwYWdlU2l6ZSI6MTAsInBhZ2VOdW1iZXIiOiIyIn0=",
      "method": "GET",
      "type": "application/json",
      "rel": "self"
    }
  }
}

O parâmetro status aceita múltiplos valores separados por vírgula — por exemplo, status=ACTIVE,DELETED. Os parâmetros opcionais name (busca por nome ou apelido), taxId (CNPJ exato) e splitType (PERCENT ou VALUE) podem ser combinados livremente.

Buscar Splitter por CNPJ ou por ID

Para consultar um splitter específico, a API oferece duas formas de busca. A busca por CNPJ é útil quando o splitterId não está disponível ou quando você quer verificar se um determinado CNPJ já possui um splitter cadastrado — independentemente do status.

Resposta — GET /{companyId}/banking/splitter/tax-id/{taxId}

{
  "id": "019f67b5-ef74-7cce-bfae-7629d9a2584f",
  "taxId": "89713903000123",
  "personType": "J",
  "name": "Empresa Exemplo LTDA",
  "status": "ACTIVE",
  "nickname": "Empresa Exemplo",
  "account": {
    "branch": "0001",
    "number": "000548981",
    "bankCode": "208"
  },
  "configuration": {
    "splitType": "PERCENT",
    "divisionAmount": 0.30,
    "isDefault": true
  },
  "createdAt": "2026-07-15T21:36:44.404Z",
  "updatedAt": "2026-07-15T21:36:44.404Z"
}

A busca por ID — GET /{companyId}/banking/splitter/{splitterId} — retorna o mesmo schema e é igualmente independente de status: um splitter DELETED ou INVALID_ACCOUNT continua acessível pela consulta direta.

Atualizar Splitter

É possível atualizar o nome, o apelido, a conta bancária e a configuração de divisão de um splitter existente. Pelo menos um dos campos deve ser informado. Atualizações parciais são suportadas: envie apenas os campos que deseja modificar.

Para remover o apelido, envie "nickname": "" (string vazia). Se o splitter estiver com status INVALID_ACCOUNT e uma conta bancária válida for fornecida, o status volta automaticamente para ACTIVE.

Requisição — PATCH /{companyId}/banking/splitter/{splitterId}

{
  "name": "Empresa Atualizada LTDA",
  "configuration": {
    "splitType": "PERCENT",
    "divisionAmount": 0.25
  }
}

Resposta — 200 OK

{
  "id": "019f67b5-ef74-7cce-bfae-7629d9a2584f",
  "taxId": "89713903000123",
  "personType": "J",
  "name": "Empresa Atualizada LTDA",
  "status": "ACTIVE",
  "nickname": "Empresa Exemplo",
  "account": {
    "branch": "0001",
    "number": "000548981",
    "bankCode": "208"
  },
  "configuration": {
    "splitType": "PERCENT",
    "divisionAmount": 0.25,
    "isDefault": true
  },
  "createdAt": "2026-07-15T21:36:44.404Z",
  "updatedAt": "2026-07-24T16:31:53.074Z"
}

Excluir Splitter

Ao excluir um splitter, o registro é marcado logicamente como DELETED e o campo deletedAt é preenchido. O registro nunca é removido fisicamente do sistema.

Esta operação é reversível: caso o mesmo destinatário precise ser recadastrado, basta criar um novo splitter com o mesmo taxId — o sistema reutiliza o UUID existente e restaura o status para ACTIVE com os novos dados informados.

Requisição — DELETE /{companyId}/banking/splitter/{splitterId}

Resposta — 204 No Content

Sem corpo de resposta. Para verificar o estado atualizado, consulte o splitter via GET /banking/splitter/{splitterId}.

Fluxo de Cobranças com Split

Com os splitters cadastrados, o passo seguinte é emitir boletos referenciando-os. Os valores de divisão são resolvidos automaticamente a partir da configuração armazenada em cada splitter — não é necessário informá-los novamente na criação da cobrança.

Criar Cobrança com Split

O boleto é emitido com o campo split preenchido com o tipo de divisão e a lista de splitters que devem receber parte do valor. Cada item da lista contém apenas o splitterId — o sistema recupera o divisionAmount da configuração cadastrada.

📘
Parte residual do beneficiário
O valor que sobra após todas as divisões pertence automaticamente ao próprio beneficiário (payee). Esse valor residual não precisa ser declarado na requisição e não aparece na resposta de criação — ele é visível apenas na consulta do split (GET /{companyId}/banking/split/{splitId}), identificado pelo campo isBeneficiary: true.

Requisição — POST /bankinghub/api/v1/collection/

{
  "type": "BANKSLIP",
  "amount": 1000.00,
  "dueDate": "2026-08-01",
  "overDueDate": "2026-08-02",
  "account": {
    "branch": "1",
    "number": "048098719"
  },
  "payer": {
    "name": "Empresa Pagadora SA",
    "personType": "J",
    "taxId": "11222333000181"
  },
  "detail": {
    "documentNumber": "split-doc-001"
  },
  "interest":  { "type": "NOT_APPLICABLE", "value": 0 },
  "fine":      { "type": "NOT_APPLICABLE", "value": 0 },
  "discounts": [{ "type": "NOT_APPLICABLE", "value": 0 }],
  "split": {
    "type": "PERCENT",
    "parts": [
      { "splitterId": "019f67b5-ef74-7cce-bfae-7629d9a2584f" }
    ]
  }
}

O campo account é a conta do próprio beneficiário (payee), não a do splitter. O documentNumber deve ter no máximo 15 caracteres. O campo split.type deve corresponder ao splitType configurado nos splitters referenciados.

São aceitos no máximo 3 splitters por cobrança. Todos os splitters referenciados devem estar com status ACTIVE no momento da criação. O valor residual que ficará com o beneficiário deve ser de pelo menos R$ 0,01.

Resposta — 200 OK

{
  "collectionId": "019f94f8-1e0b-7447-a240-77ad653e8b12",
  "status": "PROCESSING",
  "type": "BANKSLIP",
  "amount": 1000.00,
  "dueDate": "2026-08-01",
  "payee": {
    "name": "EMPRESA BENEFICIARIA LTDA",
    "taxId": "37297902000141",
    "bankCode": "208",
    "branchCode": "1",
    "number": "048098719"
  },
  "detail": {
    "barCode": "20899152500000001000001012251829051748098710",
    "digitableLine": "20890001091225182905217480987100915250000000100",
    "ourNumber": "22518290517",
    "documentNumber": "split-doc-001"
  },
  "split": {
    "id": "019f94f8-241f-7447-a240-a07ec2693dc8",
    "type": "PERCENT",
    "status": "PENDING",
    "parts": [
      {
        "id": "019f94f8-241e-7447-a240-9184f221b4d5",
        "splitterId": "019f67b5-ef74-7cce-bfae-7629d9a2584f",
        "status": "PENDING",
        "divisionAmount": 0.25,
        "isBeneficiary": false
      }
    ]
  }
}

Guarde o campo split.id retornado — ele é o splitId e será usado para acompanhar o andamento da divisão.

Consultar Split

Uma vez emitido o boleto, é possível consultar o estado completo da divisão a qualquer momento usando o splitId. Esta consulta retorna todas as partes do split, incluindo a parte residual do beneficiário — que não aparece na resposta de criação.

O campo splitterInfo dentro de cada parte é um snapshot do splitter no momento em que o split foi criado. Atualizações posteriores no splitter (nome, conta, configuração) não afetam registros de split já existentes.

Resposta — GET /{companyId}/banking/split/{splitId}

{
  "id": "019f94f8-241f-7447-a240-a07ec2693dc8",
  "collectionId": "019f94f8-1e0b-7447-a240-77ad653e8b12",
  "type": "PERCENT",
  "status": "PENDING",
  "splitParts": [
    {
      "id": "019f94f8-241f-7447-a240-9c8378b37d0f",
      "splitterInfo": {
        "splitterId": "019f94f8-2403-7447-a240-810d8f4b859e",
        "taxId": "37297902000141",
        "personType": "J",
        "name": "EMPRESA BENEFICIARIA LTDA",
        "status": "ACTIVE",
        "account": {
          "number": "048098719",
          "branch": "1",
          "bankCode": "208"
        },
        "isBeneficiary": true
      },
      "divisionAmount": 0.75,
      "status": "PENDING",
      "createdAt": "2026-07-24T16:31:57.982Z",
      "updatedAt": "2026-07-24T16:31:57.982Z"
    },
    {
      "id": "019f94f8-241e-7447-a240-9184f221b4d5",
      "splitterInfo": {
        "splitterId": "019f67b5-ef74-7cce-bfae-7629d9a2584f",
        "taxId": "89713903000123",
        "personType": "J",
        "name": "Empresa Atualizada LTDA",
        "status": "ACTIVE",
        "account": {
          "number": "000548981",
          "branch": "0001",
          "bankCode": "208"
        },
        "isBeneficiary": false,
        "nickname": "Empresa Exemplo"
      },
      "divisionAmount": 0.25,
      "status": "PENDING",
      "createdAt": "2026-07-24T16:31:57.982Z",
      "updatedAt": "2026-07-24T16:31:57.982Z"
    }
  ],
  "createdAt": "2026-07-24T16:31:57.982Z",
  "updatedAt": "2026-07-24T16:31:57.982Z"
}

Após o pagamento do boleto, o provedor externo processa a distribuição e os status são atualizados de forma assíncrona. O status global do split evolui de PENDING para PROCESSING e, ao final, para SUCCESS. Cada parte (SplitPart) segue o mesmo caminho e, quando liquidada, recebe os campos settledAt (data de liquidação) e amountPaid (valor efetivamente transferido).

Se o boleto for cancelado enquanto o split ainda estiver PENDING, ele transita para CANCELED. Splits já em PROCESSING ou em estado terminal não são revertidos.

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-split.pending`	Split de cobrança criado e aguardando pagamento do boleto.
`collections-split.processing`	Pagamento recebido; distribuição entre os destinatários em andamento.
`collections-split.success`	Todas as partes do split foram liquidadas com sucesso.
`collections-split.failed`	Uma ou mais partes falharam durante o processamento.

📘
Identificação do tenant
O campo tenantId de cada notificação é preenchido com o taxId da parte marcada como isPrincipal: true — o próprio beneficiário (payee) da cobrança. É esse valor que o sistema de webhooks usa para rotear a notificação ao tenant correto.

collections-split.pending

{
  "createdAt": "2026-05-14T21:50:00.248Z",
  "eventType": "GLOBAL",
  "splitId": "019e2877-cc39-7cc5-9ba1-02efd9dc572f",
  "status": "PENDING",
  "splitParts": [
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc38-7cc5-9ba0-e8be08bc86a1",
      "status": "PENDING",
      "settledAt": null,
      "isPrincipal": false,
      "splitter": {
        "taxId": "15836348000190",
        "name": "EMPRESA DESTINATARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "4885263" }
      }
    },
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc39-7cc5-9ba0-fffa98eb0cec",
      "status": "PENDING",
      "settledAt": null,
      "isPrincipal": true,
      "splitter": {
        "taxId": "47328649000108",
        "name": "EMPRESA BENEFICIARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "011195302" }
      }
    }
  ]
}

collections-split.processing

{
  "createdAt": "2026-05-14T21:50:00.248Z",
  "eventType": "GLOBAL",
  "splitId": "019e2877-cc39-7cc5-9ba1-02efd9dc572f",
  "status": "PROCESSING",
  "splitParts": [
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc38-7cc5-9ba0-e8be08bc86a1",
      "status": "PROCESSING",
      "settledAt": null,
      "isPrincipal": false,
      "splitter": {
        "taxId": "15836348000190",
        "name": "EMPRESA DESTINATARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "4885263" }
      }
    },
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc39-7cc5-9ba0-fffa98eb0cec",
      "status": "PROCESSING",
      "settledAt": null,
      "isPrincipal": true,
      "splitter": {
        "taxId": "47328649000108",
        "name": "EMPRESA BENEFICIARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "011195302" }
      }
    }
  ]
}

collections-split.success

{
  "createdAt": "2026-05-14T21:50:00.248Z",
  "eventType": "GLOBAL",
  "splitId": "019e2877-cc39-7cc5-9ba1-02efd9dc572f",
  "status": "SUCCESS",
  "splitParts": [
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc38-7cc5-9ba0-e8be08bc86a1",
      "status": "SETTLED",
      "settledAt": "2026-05-14T21:53:18.968Z",
      "isPrincipal": false,
      "splitter": {
        "taxId": "15836348000190",
        "name": "EMPRESA DESTINATARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "4885263" }
      }
    },
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc39-7cc5-9ba0-fffa98eb0cec",
      "status": "SETTLED",
      "settledAt": "2026-05-14T21:53:18.967Z",
      "isPrincipal": true,
      "splitter": {
        "taxId": "47328649000108",
        "name": "EMPRESA BENEFICIARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "011195302" }
      }
    }
  ]
}

collections-split.failed

{
  "createdAt": "2026-05-14T21:50:00.248Z",
  "eventType": "GLOBAL",
  "splitId": "019e2877-cc39-7cc5-9ba1-02efd9dc572f",
  "status": "FAILED",
  "splitParts": [
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc38-7cc5-9ba0-e8be08bc86a1",
      "status": "FAILED",
      "settledAt": null,
      "isPrincipal": false,
      "splitter": {
        "taxId": "15836348000190",
        "name": "EMPRESA DESTINATARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "4885263" }
      }
    },
    {
      "createdAt": "2026-05-14T21:50:00.248Z",
      "splitPartId": "019e2877-cc39-7cc5-9ba0-fffa98eb0cec",
      "status": "FAILED",
      "settledAt": null,
      "isPrincipal": true,
      "splitter": {
        "taxId": "47328649000108",
        "name": "EMPRESA BENEFICIARIA LTDA",
        "account": { "branchCode": "50", "accountNumber": "011195302" }
      }
    }
  ]
}

📘
isPrincipal vs isBeneficiary
No payload do webhook, a parte residual do beneficiário é identificada por isPrincipal: true. Na API REST (GET /banking/split/{splitId}), o mesmo conceito é representado por isBeneficiary: true. Os dois campos são equivalentes — a diferença é apenas de nomenclatura entre as duas camadas.

Gestão de Split de cobrança

Segurança

BTG Id

Escopos necessários

Split de Cobrança — Visão Geral da API

Restrição de tipo

Fluxo de Splitters

Criar Splitter

Reativação automática

Listagem de Splitters

Buscar Splitter por CNPJ ou por ID

Atualizar Splitter

Excluir Splitter

Fluxo de Cobranças com Split

Criar Cobrança com Split

Parte residual do beneficiário

Consultar Split

Eventos de webhook

Identificação do tenant

collections-split.pending

collections-split.processing

collections-split.success

collections-split.failed

`isPrincipal` vs `isBeneficiary`

Segurança

BTG Id

Escopos necessários

Split de Cobrança — Visão Geral da API

Restrição de tipo

Fluxo de Splitters

Criar Splitter

Reativação automática

Listagem de Splitters

Buscar Splitter por CNPJ ou por ID

Atualizar Splitter

Excluir Splitter

Fluxo de Cobranças com Split

Criar Cobrança com Split

Parte residual do beneficiário

Consultar Split

Eventos de webhook

Identificação do tenant

collections-split.pending

collections-split.processing

collections-split.success

collections-split.failed

isPrincipal vs isBeneficiary

`isPrincipal` vs `isBeneficiary`