Split de Pagamento

O split de pagamento permite dividir um recebimento entre múltiplos sellers. Ideal para marketplaces, plataformas de afiliados, parcerias e outros casos onde o valor precisa ser distribuído entre diferentes partes.

Como Funciona

Quando uma charge é criada com split:

A taxa de Cash In é calculada uma vez sobre o valor total
A taxa é cobrada do seller principal (quem criou a charge)
O valor líquido (após taxa) é dividido entre os sellers conforme especificado
Cada seller recebe sua parte diretamente no saldo

Exemplo Prático

Pagamento de R$ 100,00 com split:

Taxa PIX: 3,99% = R$ 3,99 (cobrada do seller principal)
Valor líquido: R$ 96,01
Split: Seller Principal 10% = R$ 9,60, Seller Parceiro 90% = R$ 86,41

Endpoint

POST /v1/charges

Parâmetros

O campo split é opcional e deve ser um array de objetos:

Parâmetro	Tipo	Obrigatório	Descrição
`split`	array	Não	Array de splits (opcional)
`split[].seller_id`	integer	Sim*	ID do seller que receberá parte do pagamento
`split[].percentage`	number	Sim**	Percentual do valor líquido (0-100)
`split[].amount`	integer	Sim**	Valor fixo em centavos (alternativa ao percentage)
`split[].description`	string	Não	Descrição do split (máx: 255 caracteres)

* Obrigatório se passar split
** Deve passar percentage OU amount, não ambos

Validações

Soma de percentuais: Deve ser exatamente 100% (tolerância 0,01%)
Soma de valores fixos: Não pode exceder o valor total da charge
Valor mínimo: R$ 0,01 por split
Seller: Deve estar ativo, com compliance aprovado e método de pagamento habilitado
Mistura: Não é possível misturar percentuais e valores fixos no mesmo split

Exemplo: Split por Percentual

curl -X POST https://api.apexpy.com.br/v1/charges \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "payment_method": "pix",
    "split": [
      {
        "seller_id": 5,
        "percentage": 10,
        "description": "Comissão plataforma"
      },
      {
        "seller_id": 3,
        "percentage": 90,
        "description": "Vendedor"
      }
    ]
  }'

Exemplo: Split por Valor Fixo

curl -X POST https://api.apexpy.com.br/v1/charges \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "payment_method": "pix",
    "split": [
      {
        "seller_id": 5,
        "amount": 2000,
        "description": "Comissão fixa R$ 20,00"
      }
    ]
  }'

Nota: Quando usar valor fixo, o seller principal recebe o restante (valor líquido - splits fixos).

Resposta com Split

{
  "success": true,
  "data": {
    "id": "ci_123",
    "status": "pending",
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "pix",
    "split": [
      {
        "seller_id": 5,
        "seller_name": "Plataforma XYZ",
        "amount": 9601,
        "percentage": 10,
        "description": "Comissão plataforma"
      },
      {
        "seller_id": 3,
        "seller_name": "Vendedor ABC",
        "amount": 86409,
        "percentage": 90,
        "description": "Vendedor"
      }
    ],
    "pix": {
      "txid": "...",
      "emv": "...",
      "qr_code_image_url": "..."
    },
    "created_at": "2025-11-29T00:00:00Z"
  }
}

Buscar Seller por Email

Para facilitar a configuração de split, use o endpoint de busca:

GET /v1/sellers/[email protected]

Resposta:

{
  "success": true,
  "data": {
    "seller_id": 5,
    "name": "João Silva",
    "email": "[email protected]",
    "status": "active",
    "compliance_status": "approved"
  }
}

Casos de Uso

1. Marketplace

Plataforma recebe comissão, vendedor recebe o restante:

{
  "split": [
    { "seller_id": 1, "percentage": 10, "description": "Comissão plataforma" },
    { "seller_id": 2, "percentage": 90, "description": "Vendedor" }
  ]
}

2. Plataforma de Cursos

Criador recebe 70%, plataforma recebe 30%:

{
  "split": [
    { "seller_id": 3, "percentage": 70, "description": "Criador do curso" },
    { "seller_id": 1, "percentage": 30, "description": "Plataforma" }
  ]
}

3. Afiliados

Afiliado recebe comissão, vendedor recebe o restante:

{
  "split": [
    { "seller_id": 4, "percentage": 15, "description": "Comissão afiliado" },
    { "seller_id": 2, "percentage": 85, "description": "Vendedor" }
  ]
}

Taxas com Split

Importante: A taxa de Cash In é calculada uma vez sobre o valor total e é cobrada do seller principal. Os sellers no split recebem o valor líquido proporcional (sem taxa adicional).

Exemplo:

Pagamento: R$ 100,00
Taxa PIX: 3,99% = R$ 3,99 (seller principal)
Valor líquido: R$ 96,01
Split 10%/90%: R$ 9,60 / R$ 86,41

Split em Produtos (Dashboard)

Ao criar um produto no dashboard, você pode configurar split que será aplicado automaticamente sempre que o produto for usado. O split fica armazenado no produto e é aplicado em todas as charges criadas a partir dele.

Limitações

Split é pontual (específico por charge/produto)
Não aplica automaticamente a todas as charges
Valor mínimo por split: R$ 0,01
Seller no split deve estar ativo, com compliance aprovado e método habilitado

Webhooks com Split

Quando uma charge com split é paga, webhooks são disparados para:

Seller principal (com informações completas do split)
Cada seller no split (com payload específico contendo apenas sua parte)

O payload do webhook inclui o campo split quando aplicável:

{
  "charge_id": "ci_123",
  "status": "paid",
  "split": [
    {
      "seller_id": 5,
      "amount": 9601,
      "percentage": 10
    }
  ]
}