Split de Pagamentos (Multi-Recebedores)

O Split de Pagamentos da KavroPay permite que plataformas, marketplaces, SaaS e infoprodutores dividam automaticamente o valor de uma cobrança entre duas ou mais contas no exato instante em que o cliente efetua o pagamento PIX. A liquidação é 100% atômica e auditada: o saldo é creditado em tempo real no saldo disponível de cada parceiro através do motor contábil da KavroPay, gerando registros de conciliação para cada participante.

Como Funciona o Split

Você pode definir as regras de divisão diretamente no momento da criação da cobrança via POST /v1/charges adicionando o array split:

Divisão por Porcentagem (percentage): Define a fatia percentual do valor bruto (ex: 20 para 20%, 10 para 10%). A soma de todas as porcentagens de uma cobrança não pode ultrapassar 100%.
Divisão por Valor Fixo (amount ou amountCents): Define uma quantia exata em Reais (ex: "15.00" ou 1500). A soma dos valores fixos não pode ultrapassar o saldo líquido da cobrança.
Quem Paga a Taxa da Gateway (chargeProcessingFee):
- false (Padrão): O vendedor principal (originador) absorve a taxa integral da gateway, e o parceiro recebe o valor bruto do split.
- true: A taxa da gateway é dividida proporcionalmente e debitada da fatia do recebedor.

Regra de Uniformidade: Em uma mesma cobrança, todas as regras de split devem seguir o mesmo modelo (ou todas por porcentagem, ou todas por valor fixo). Não é permitido misturar regras percentuais e valores fixos no mesmo pagamento para evitar conflitos de precedência.

Parâmetros do Objeto `split`

Cada item dentro do array split suporta os seguintes campos:

Campo	Tipo	Obrigatório	Descrição
`recipientId`	string (UUID)	Sim	ID da empresa cadastrada na KavroPay que receberá a cota (`companyId`).
`percentage`	number \| string	Opcional*	Percentual bruto destinado ao parceiro (ex: `15` para 15%, `25.5` para 25,5%).
`amount`	string \| number	Opcional*	Valor fixo decimal com duas casas (ex: `"25.00"` ou `"25,00"`).
`amountCents`	integer	Opcional*	Valor fixo expresso em centavos inteiros (ex: `2500` = R$ 25,00).
`chargeProcessingFee`	boolean	Opcional	Se `true`, desconta a cota proporcional da taxa do gateway do recebedor. Padrão: `false`.
`description`	string	Opcional	Texto descritivo para identificação no extrato do parceiro (ex: `"Comissão Afiliado #99"`).

*Cada regra deve especificar percentage OU amount / amountCents. A soma das porcentagens não pode ultrapassar 100,00%, e a soma dos valores fixos não pode ultrapassar o valor da cobrança.

Exemplo: Criar Cobrança PIX com Split

curl -X POST https://api.kavropay.online/v1/charges \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150.00",
    "description": "Pedido Marketplace #9842",
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 20,
        "chargeProcessingFee": false,
        "description": "Comissão Vendedor Loja 02"
      },
      {
        "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
        "percentage": 10,
        "chargeProcessingFee": true,
        "description": "Comissão Co-produtor"
      }
    ]
  }'

const axios = require('axios');

async function createChargeWithSplit() {
  const response = await axios.post('https://api.kavropay.online/v1/charges', {
    amount: "150.00",
    description: "Pedido Marketplace #9842",
    split: [
      {
        recipientId: "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        percentage: 20,
        chargeProcessingFee: false,
        description: "Comissão Vendedor Loja 02"
      },
      {
        recipientId: "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
        percentage: 10,
        chargeProcessingFee: true,
        description: "Comissão Co-produtor"
      }
    ]
  }, {
    headers: {
      'Authorization': 'Bearer sk_live_sua_chave_aqui',
      'Content-Type': 'application/json'
    }
  });

  console.log('Cobrança gerada com Split:', response.data);
}

createChargeWithSplit();

import requests

url = "https://api.kavropay.online/v1/charges"
headers = {
    "Authorization": "Bearer sk_live_sua_chave_aqui",
    "Content-Type": "application/json"
}

payload = {
    "amount": "150.00",
    "description": "Pedido Marketplace #9842",
    "split": [
        {
            "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
            "percentage": 20,
            "chargeProcessingFee": False,
            "description": "Comissão Vendedor Loja 02"
        },
        {
            "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
            "percentage": 10,
            "chargeProcessingFee": True,
            "description": "Comissão Co-produtor"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

<?php
$payload = [
  "amount" => "150.00",
  "description" => "Pedido Marketplace #9842",
  "split" => [
    [
      "recipientId" => "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "percentage" => 20,
      "chargeProcessingFee" => false,
      "description" => "Comissão Vendedor Loja 02"
    ],
    [
      "recipientId" => "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
      "percentage" => 10,
      "chargeProcessingFee" => true,
      "description" => "Comissão Co-produtor"
    ]
  ]
];

$ch = curl_init("https://api.kavropay.online/v1/charges");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_live_sua_chave_aqui",
    "Content-Type: application/json"
  ]
]);

$result = curl_exec($ch);
curl_close($ch);
echo $result;

Resposta com o Detalhamento do Split (HTTP 201 Created)

{
  "id": "PAY8F7A1B2C3D4E5F6G",
  "amount": 150.00,
  "fee": 4.99,
  "net": 145.01,
  "status": "waiting_payment",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
  "qr_code_base64": "iVBORw0KGgoAAAANSUhEUg...",
  "split": {
    "totalNet": 145.01,
    "originator": {
      "companyId": "a0000000-0000-0000-0000-000000000001",
      "companyName": "Minha Plataforma LTDA",
      "net": 101.01
    },
    "recipients": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "recipientName": "Loja Parceira 02",
        "type": "percentage",
        "percentage": 20,
        "amount": 30.00,
        "fee": 0.00,
        "net": 30.00,
        "chargeProcessingFee": false,
        "description": "Comissão Vendedor Loja 02",
        "status": "pending"
      },
      {
        "recipientId": "f7e6d5c4-b3a2-1908-fedc-ba9876543210",
        "recipientName": "Co-produtor",
        "type": "percentage",
        "percentage": 10,
        "amount": 15.00,
        "fee": 0.50,
        "net": 14.50,
        "chargeProcessingFee": true,
        "description": "Comissão Co-produtor",
        "status": "pending"
      }
    ]
  },
  "expires_at": "2026-09-28T14:00:00.000Z",
  "created_at": "2026-09-28T13:00:00.000Z"
}

Simulador / Calculadora de Split

Permite que sua aplicação faça uma prévia exata do rateio financeiro antes de submeter uma nova cobrança aos clientes.

cURL

curl -X POST https://api.kavropay.online/v1/splits/calculate \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "split": [
      {
        "recipientId": "b1a2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "percentage": 25
      }
    ]
  }'

Consultar Extrato de Splits

Lista todos os splits enviados ou recebidos pela sua empresa.

Parâmetros de Query String

role: 'all' (padrão), 'originator' (splits gerados pela sua empresa) ou 'recipient' (splits que sua empresa recebeu).
page: Número da página (padrão: 1).
limit: Itens por página (máx: 100).

cURL

curl -X GET "https://api.kavropay.online/v1/splits?role=recipient&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"

Notificações e Webhooks de Split

Assim que a cobrança PIX é liquidada:

O saldo líquido de cada recebedor é creditado instantaneamente em sua conta (available).
Uma notificação é gerada no painel de cada empresa recebedora.
Um registro de transferência interna é gerado para conciliação contábil em tempo real.

Cobranças PIX

Criar cobranças simples e links de checkout

Status Unificado

Consultar status em menos de 10ms

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Split de Pagamentos (Multi-Recebedores)

Como Funciona o Split

Parâmetros do Objeto `split`

Exemplo: Criar Cobrança PIX com Split

Resposta com o Detalhamento do Split (HTTP 201 Created)

Simulador / Calculadora de Split

Consultar Extrato de Splits

Parâmetros de Query String

Notificações e Webhooks de Split

Cobranças PIX

Status Unificado

​Como Funciona o Split

​Parâmetros do Objeto split

​Exemplo: Criar Cobrança PIX com Split

​Resposta com o Detalhamento do Split (HTTP 201 Created)

​Simulador / Calculadora de Split

​Consultar Extrato de Splits

​Parâmetros de Query String

​Notificações e Webhooks de Split

Cobranças PIX

Status Unificado

Como Funciona o Split

Parâmetros do Objeto `split`

Exemplo: Criar Cobrança PIX com Split

Resposta com o Detalhamento do Split (HTTP 201 Created)

Simulador / Calculadora de Split

Consultar Extrato de Splits

Parâmetros de Query String

Notificações e Webhooks de Split