Split de cobrança

A API de Split de cobrança do BTG Pactual Empresas permite dividir automaticamente o valor recebido em uma cobrança entre o beneficiário e um ou mais parceiros cadastrados. Em vez de receber o valor integral e redistribuí-lo manualmente, a divisão é configurada antecipadamente e executada no momento da liquidação.

O fluxo envolve dois recursos principais: o Splitter, que representa um beneficiário parceiro cadastrado, e o Split, que representa a divisão efetiva associada a uma cobrança específica. O Splitter é criado uma vez e reutilizado em múltiplas cobranças; o Split é gerado a cada cobrança que utiliza um Splitter configurado.

Casos de Uso

• Repasse automático de comissões a parceiros comerciais no momento da liquidação.
• Divisão de receita entre empresas participantes de um mesmo serviço ou produto.
• Centralização do recebimento com distribuição automática para fornecedores.
• Consulta de status de repasse por cobrança para conciliação financeira.

Splitter

Um Splitter é o cadastro de um parceiro que receberá parte do valor de cobranças futuras. Cada Splitter pertence a uma pessoa jurídica (CNPJ) e contém as informações bancárias do beneficiário parceiro e a regra de divisão a ser aplicada.

Status do Splitter

A exclusão de um Splitter é um soft-delete: o registro é marcado como DELETED, mas não é apagado. Caso seja criado um novo Splitter com o mesmo CNPJ (taxId) de um registro DELETED, o sistema reativa o registro existente com os novos dados, mantendo o mesmo identificador. Se o Splitter com aquele taxId já estiver ACTIVE, a criação retorna 409 Conflict.

Tipos de Divisão

Ao cadastrar um Splitter, é necessário definir a regra de divisão por meio dos campos splitType e divisionAmount na configuração.

Por percentual — PERCENT

O divisionAmount representa uma fração do valor total da cobrança. O valor deve ser entre 0 (exclusivo) e 1 (exclusivo).

• 0.30 equivale a 30% do valor da cobrança.
• O beneficiário principal (payee) recebe o valor residual — ou seja, o que restar após a soma de todos os percentuais dos Splitters.
• Indicado quando a divisão acompanha o valor variável das cobranças.

Por valor fixo — VALUE

O divisionAmount representa um valor absoluto em reais a ser repassado, independentemente do valor total da cobrança.

• 100.50 equivale a R$ 100,50 fixos por cobrança.
• O beneficiário principal recebe o valor residual após a dedução dos valores fixos.
• Indicado para repasses de valor constante, como taxas ou mensalidades fixas.

Split

O Split é o registro da divisão efetiva gerada para uma cobrança específica. Ele é consultado pelo seu identificador UUID e contém todas as partes da divisão (splitParts), incluindo a parte residual do próprio beneficiário (marcada com isBeneficiary: true).

Atenção: a resposta da criação de uma cobrança retorna apenas as partes dos Splitters. A consulta direta ao Split via GET /banking/split/{splitId} é a única forma de ver a parte residual do beneficiário principal.

Status do Split

O Split possui um status global e um status por parte (splitParts).

Status global do Split:

Status de cada parte (splitParts):

Recursos Disponíveis

Os recursos da API de Split estão disponíveis no API Reference.