Split de pagamentos

Visão Geral

O recurso de Splits permite dividir automaticamente o valor de uma transação PIX entre múltiplos destinatários. Ao criar uma cobrança, você configura as regras de divisão e, quando o pagamento for confirmado, os repasses são realizados automaticamente via PIX.

Casos de uso: Marketplaces, divisão de receita, comissões, repasses automáticos a fornecedores.

📤 Criando uma Cobrança com Splits

Adicione o campo splits ao corpo da requisição de criação de cobrança.

`POST /api/v2/invoices`

{
  "method": "pix",
  "total_price_cents": 100000,
  "payer": {
    "name": "Cliente Exemplo",
    "email": "cliente@email.com",
    "cpf_cnpj": "12345678900"
  },
  "items": [
    {
      "title": "Produto",
      "unit_price": 100000,
      "quantity": 1
    }
  ],
  "splits": [
    {
      "pix_key": "12345678900",
      "pix_type": "CPF",
      "recipient_name": "João Silva",
      "percentage_basis_points": 2500,
      "external_id": "comissao-vendedor-001"
    },
    {
      "pix_key": "fornecedor@email.com",
      "pix_type": "EMAIL",
      "recipient_name": "Maria Santos",
      "amount_cents": 30000,
      "external_id": "repasse-fornecedor-042"
    }
  ]
}

📋 Campos do Split

Campo	Tipo	Obrigatório	Descrição
`pix_key`	string	Sim	Chave PIX do destinatário.
`pix_type`	string	Sim	Tipo da chave PIX: `CPF`, `CNPJ`, `PHONE`, `EMAIL` ou `RANDOM`.
`recipient_name`	string	Não	Nome do destinatário (exibido no extrato).
`percentage_basis_points`	integer	Um dos dois	Percentual em basis points (1–10000, onde 100 = 1%).
`amount_cents`	integer	Um dos dois	Valor fixo em centavos.
`external_id`	string	Não	Identificador externo para o split. Propagado ao saque gerado e incluído nos webhooks e postbacks, permitindo rastrear o repasse no seu sistema.

Cada split deve ter ou percentage_basis_points ou amount_cents, nunca ambos.

✅ Regras de Validação

Regra	Descrição
Chave PIX obrigatória	O campo `pix_key` não pode ser vazio.
Exclusividade mútua	Cada split deve ter ou `percentage_basis_points` ou `amount_cents`, não ambos.
Faixa do percentual	`percentage_basis_points` deve estar entre 1 e 10000 (0,01% a 100%).
Valor positivo	`amount_cents` deve ser maior que 0.
Soma dos percentuais	A soma de todos os `percentage_basis_points` não pode exceder 10000 (100%).
Soma dos valores fixos	A soma de todos os `amount_cents` não pode exceder o valor total da transação.
Total combinado	A soma dos valores calculados por percentual + valores fixos não pode exceder o valor da transação.

Exemplo de validação combinada

Uma transação de R

100, 00 co m s pl i t s d e 50

60,00 será rejeitada, pois:

50% de R$ 100,00 = R$ 50,00
R$ 50,00 + R$ 60,00 = R$ 110,00 > R$ 100,00

📊 Status dos Splits

Status	Descrição
`PENDING`	Split criado, aguardando pagamento da transação.
`PROCESSING`	Pagamento confirmado, saque iniciado (aguardando confirmação do banco).
`COMPLETED`	Repasse PIX enviado com sucesso ao destinatário.
`FAILED`	Falha no envio do repasse. Pode ser retentado.

🔔 Webhooks

Cada split gera um saque (withdrawal) ao ser processado. Se você tiver webhooks configurados, receberá notificações com os eventos de saque:

Evento	Descrição
`withdrawal.completed`	O repasse PIX foi enviado com sucesso.
`withdrawal.failed`	O repasse falhou.
`withdrawal.*`	Todos os eventos de saque.

O campo external_id do split é incluído no payload do webhook como external_id dentro do objeto data, permitindo identificar a qual split o saque se refere.

{
  "event": "withdrawal.completed",
  "timestamp": "2026-02-01T12:00:00Z",
  "data": {
    "id": "a1b2c3d4-...",
    "status": "completed",
    "amount": 25000,
    "external_id": "comissao-vendedor-001",
    "end_to_end_id": "E123456...",
    "created_at": "2026-02-01T11:55:00Z",
    "payer": { ... },
    "payee": { ... }
  }
}

📝 Exemplos

Split por Percentual

Dividir 25% de uma transação de R$ 400,00 para um parceiro:

{
  "splits": [
    {
      "pix_key": "parceiro@email.com",
      "pix_type": "EMAIL",
      "recipient_name": "Parceiro Comercial",
      "percentage_basis_points": 2500,
      "external_id": "comissao-parceiro-123"
    }
  ]
}

O parceiro receberá R$ 100,00 (25% de R$ 400,00).

Split por Valor Fixo

Enviar R$ 50,00 fixos para um fornecedor:

{
  "splits": [
    {
      "pix_key": "98765432000199",
      "pix_type": "CNPJ",
      "recipient_name": "Fornecedor LTDA",
      "amount_cents": 5000
    }
  ]
}

O fornecedor receberá R$ 50,00 independentemente do valor total da transação.

Múltiplos Splits (Percentual + Valor Fixo)

Dividir uma transação de R$ 1.000,00 entre dois destinatários:

{
  "splits": [
    {
      "pix_key": "11111111111",
      "pix_type": "CPF",
      "recipient_name": "Vendedor",
      "percentage_basis_points": 5000,
      "external_id": "vendedor-abc"
    },
    {
      "pix_key": "plataforma@email.com",
      "pix_type": "EMAIL",
      "recipient_name": "Plataforma",
      "amount_cents": 20000,
      "external_id": "taxa-plataforma"
    }
  ]
}

Vendedor recebe: R$ 500,00 (50%)

Plataforma recebe: R$ 200,00 (fixo)

Lojista retém: R$ 300,00

Precisa de ajuda?
Entre em contato com nossa equipe de suporte para desenvolvedores para obter assistência.

Visão Geral#

📤 Criando uma Cobrança com Splits#

POST /api/v2/invoices#

📋 Campos do Split#

✅ Regras de Validação#

Exemplo de validação combinada#

📊 Status dos Splits#

🔔 Webhooks#

📝 Exemplos#

Split por Percentual#

Split por Valor Fixo#

Múltiplos Splits (Percentual + Valor Fixo)#