Ficha técnica

Alcances necesarios

El token para consumir la API de Split de Cobranza debe generarse utilizando el Authorization Code.

Es necesario incluir los siguientes alcances:

Alcance	Descripción
`brn:btg:empresas:banking:collections`	Permite emitir, consultar y modificar cobros, además de crear, actualizar y eliminar splitters
`brn:btg:empresas:banking:collections.readonly`	Permite únicamente consultar cobros y splitters

Split de Cobranza — Visión General de la API

La API de Split de Cobranza de BTG Empresas permite que su empresa divida automáticamente el valor recibido de un boleto entre múltiples destinatarios, denominados splitters. Al emitir un boleto con split, el BTG distribuye los montos a cada cuenta configurada en el momento de la liquidación, sin necesidad de transferencia manual.

El flujo está organizado en dos conceptos centrales: el splitter (destinatario registrado, reutilizable en múltiples cobros) y el split (plan de división vinculado a un boleto específico). Antes de emitir cobros con split, es necesario registrar los splitters.

📘

Restricción de tipo

El split es compatible exclusivamente con cobros del tipo BANKSLIP. Pix, QR Code y tarjeta de crédito no son compatibles.

Flujo de Splitters

El splitter representa un destinatario fijo — una empresa (CNPJ) que recibirá una fracción de los valores cobrados. Cada splitter almacena la cuenta bancaria de destino y la configuración de división: un porcentaje (PERCENT) o un valor absoluto en reales (VALUE). Un splitter registrado puede reutilizarse en tantos boletos como se desee.

Crear Splitter

El registro de un splitter es el punto de entrada del flujo. Usted informa el CNPJ del destinatario, los datos de la cuenta BTG Pactual para crédito y la configuración de división predeterminada. La API responde de inmediato con el identificador del splitter creado.

📘

Reactivación automática

Si ya existe un splitter con el mismo taxId y su estado es DELETED, el registro existente es reactivado con los nuevos datos — el UUID permanece igual y el estado vuelve a ACTIVE. Si ya existe un splitter ACTIVE con el mismo taxId, la API retorna 409 Conflict.

Solicitud — 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
  }
}

El campo taxId debe ser el CNPJ del destinatario — no puede ser igual al companyId (el auto-split no está permitido). Solo se acepta Persona Jurídica ("J"). El campo bankCode acepta únicamente "208" (BTG Pactual); cualquier otro valor es rechazado.

Para splitType: "PERCENT", el divisionAmount debe ser un número entre 0 (exclusivo) y 1 (exclusivo) — por ejemplo, 0.30 representa el 30%. Para splitType: "VALUE", debe ser un valor positivo en reales.

Respuesta — 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 el campo id retornado — es el splitterId y se utilizará en todas las operaciones posteriores, incluida la emisión de boletos con split.

Listado de Splitters

Todos los splitters registrados están disponibles para consulta. El listado permite que su equipo monitoree el estado de cada destinatario — identificando splitters activos (ACTIVE), con cuenta inválida (INVALID_ACCOUNT) o eliminados (DELETED) — y aplique filtros por nombre, CNPJ, estado o tipo de división.

La paginación puede realizarse por número de página o por cursor. Cuando el campo _links.next esté presente en la respuesta, hay más páginas disponibles.

Respuesta — 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"
    }
  }
}

El parámetro status acepta múltiples valores separados por coma — por ejemplo, status=ACTIVE,DELETED. Los parámetros opcionales name (búsqueda por nombre o apodo), taxId (CNPJ exacto) y splitType (PERCENT o VALUE) pueden combinarse libremente.

Buscar Splitter por CNPJ o por ID

Para consultar un splitter específico, la API ofrece dos formas de búsqueda. La búsqueda por CNPJ es útil cuando el splitterId no está disponible o cuando desea verificar si un determinado CNPJ ya tiene un splitter registrado — independientemente del estado.

Respuesta — 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"
}

La búsqueda por ID — GET /{companyId}/banking/splitter/{splitterId} — retorna el mismo esquema y es igualmente independiente del estado: un splitter DELETED o INVALID_ACCOUNT sigue siendo accesible mediante consulta directa.

Actualizar Splitter

Es posible actualizar el nombre, el apodo, la cuenta bancaria y la configuración de división de un splitter existente. Al menos uno de los campos debe ser informado. Se admiten actualizaciones parciales: envíe únicamente los campos que desea modificar.

Para eliminar el apodo, envíe "nickname": "" (cadena vacía). Si el splitter está con estado INVALID_ACCOUNT y se proporciona una cuenta bancaria válida, el estado vuelve automáticamente a ACTIVE.

Solicitud — PATCH /{companyId}/banking/splitter/{splitterId}

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

Respuesta — 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"
}

Eliminar Splitter

Al eliminar un splitter, el registro es marcado lógicamente como DELETED y el campo deletedAt es completado. El registro nunca es eliminado físicamente del sistema.

Esta operación es reversible: si el mismo destinatario necesita ser registrado nuevamente, basta con crear un nuevo splitter con el mismo taxId — el sistema reutiliza el UUID existente y restaura el estado a ACTIVE con los nuevos datos informados.

Solicitud — DELETE /{companyId}/banking/splitter/{splitterId}

Respuesta — 204 No Content

Sin cuerpo de respuesta. Para verificar el estado actualizado, consulte el splitter mediante GET /banking/splitter/{splitterId}.

Flujo de Cobros con Split

Con los splitters registrados, el siguiente paso es emitir boletos referenciándolos. Los valores de división se resuelven automáticamente a partir de la configuración almacenada en cada splitter — no es necesario informarlos nuevamente al crear el cobro.

Crear Cobro con Split

El boleto se emite con el campo split completado con el tipo de división y la lista de splitters que deben recibir una parte del valor. Cada elemento de la lista contiene únicamente el splitterId — el sistema recupera el divisionAmount de la configuración registrada.

📘

Parte residual del beneficiario

El valor que queda tras todas las divisiones pertenece automáticamente al propio beneficiario (payee). Este valor residual no necesita declararse en la solicitud y no aparece en la respuesta de creación — es visible únicamente en la consulta del split (GET /{companyId}/banking/split/{splitId}), identificado por el campo isBeneficiary: true.

Solicitud — 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" }
    ]
  }
}

El campo account es la cuenta del propio beneficiario (payee), no la del splitter. El documentNumber debe tener como máximo 15 caracteres. El campo split.type debe coincidir con el splitType configurado en los splitters referenciados.

Se aceptan como máximo 3 splitters por cobro. Todos los splitters referenciados deben estar con estado ACTIVE en el momento de la creación. El valor residual que quedará con el beneficiario debe ser de al menos R$ 0,01.

Respuesta — 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 el campo split.id retornado — es el splitId y se utilizará para seguir el avance de la división.

Consultar Split

Una vez emitido el boleto, es posible consultar el estado completo de la división en cualquier momento utilizando el splitId. Esta consulta retorna todas las partes del split, incluida la parte residual del beneficiario — que no aparece en la respuesta de creación.

El campo splitterInfo dentro de cada parte es un snapshot del splitter en el momento en que el split fue creado. Las actualizaciones posteriores al splitter (nombre, cuenta, configuración) no afectan los registros de split ya existentes.

Respuesta — 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"
}

Tras el pago del boleto, el proveedor externo procesa la distribución y los estados se actualizan de forma asíncrona. El estado global del split avanza de PENDING a PROCESSING y, al finalizar, a SUCCESS. Cada parte (SplitPart) sigue el mismo camino y, al liquidarse, recibe los campos settledAt (fecha de liquidación) y amountPaid (monto efectivamente transferido).

Si el boleto es cancelado mientras el split todavía está en PENDING, este transita a CANCELED. Los splits ya en PROCESSING o en estado terminal no son revertidos.

Eventos de webhook

Los payloads disponibles a continuación representan el contenido del campo data, siguiendo el formato de envío descrito en Eventos.

Evento	Descripción
`collections-split.pending`	Split de cobro creado y en espera del pago del boleto.
`collections-split.processing`	Pago recibido; distribución entre los destinatarios en progreso.
`collections-split.success`	Todas las partes del split fueron liquidadas exitosamente.
`collections-split.failed`	Una o más partes fallaron durante el procesamiento.

📘

Identificación del tenant

El campo tenantId de cada notificación se completa con el taxId de la parte marcada como isPrincipal: true — el propio beneficiario (payee) del cobro. Es ese valor el que el sistema de webhooks usa para enrutar la notificación al tenant correcto.

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`

En el payload del webhook, la parte residual del beneficiario se identifica por isPrincipal: true. En la API REST (GET /banking/split/{splitId}), el mismo concepto se representa mediante isBeneficiary: true. Los dos campos son equivalentes — la diferencia es únicamente de nomenclatura entre las dos capas.

Alcances necesarios​

Split de Cobranza — Visión General de la API

Restricción de tipo​

Flujo de Splitters​

Crear Splitter​

Reactivación automática​

Listado de Splitters​

Buscar Splitter por CNPJ o por ID​

Actualizar Splitter​

Eliminar Splitter​

Flujo de Cobros con Split​

Crear Cobro con Split​

Parte residual del beneficiario​

Consultar Split​

Eventos de webhook​

Identificación del tenant​

collections-split.pending​

collections-split.processing​

collections-split.success​

collections-split.failed​

isPrincipal vs isBeneficiary​