Split de Pagamentos (Subcontas)

Como funciona

O split permite que, no momento da venda, parte do valor já fique separada para um ou mais recebedores — por exemplo, um sócio, um fornecedor ou um parceiro comercial. Por padrão a divisão percentual incide sobre o valor líquido da cobrança (após as taxas da plataforma) e o residual fica com a conta principal; com splitFeePayer: "OWNER" o percentual incide sobre o valor bruto e a taxa sai inteira do residual da conta principal (detalhes abaixo).

1. Cadastre a subconta no painel, em Subcontas > Criar Nova Subconta: dados do titular (PF ou PJ), documentos de verificação (KYC) e a chave PIX de recebimento.
2. Aguarde a aprovação — nossa equipe analisa o cadastro e os documentos. Só subcontas APPROVED podem receber split.
3. Informe o split na cobrança — envie o campo opcional split ao criar a cobrança PIX via API, referenciando o subAccountId.
4. Confirmação do pagamento — quando o PIX é pago, cada parte é creditada no saldo da respectiva subconta e o residual no saldo da conta principal.
5. Repasse automático diário — 1x por dia, o saldo de cada subconta que atingir o valor mínimo é transferido via PIX para a chave cadastrada. Também é possível repassar manualmente pelo painel.

Onde encontrar o subAccountId

Na página Subcontas do painel, cada subconta aprovada exibe o seu ID — use o botão de copiar ao lado do nome. É esse ID que vai no campo split da API.

Contas com a função habilitada também podem criar e consultar subcontas direto pela API (POST/GET /v1/sub-accounts, incluindo o envio dos documentos KYC) — veja Subcontas (Split). A liberação é feita pelo suporte, e a aprovação de cada subconta continua manual, com notificação via webhook subaccount.approved / subaccount.rejected.

Usando na API

O campo split é aceito no endpoint Criar Cobrança PIX:

POST /api/v1/charges
{
  "amount": 150.50,
  "customerName": "João da Silva",
  "customerCpf": "12345678901",
  "externalReference": "ORDER-12345",
  "split": [
    { "subAccountId": "a1b2c3d4-...", "type": "PERCENT", "value": 30 },
    { "subAccountId": "e5f6g7h8-...", "type": "FIXED", "value": 10.00 }
  ]
}

Regras

Webhook com split

Quando a cobrança tem split, o webhook charge.paid (e a consulta de status) inclui o array split com o valor calculado e o status de cada parte:

{
  "event": "charge.paid",
  "data": {
    "chargeId": "...",
    "amount": 150.50,
    "netAmount": 146.00,
    "split": [
      {
        "subAccountId": "a1b2c3d4-...",
        "subAccountName": "Maria Recebedora",
        "type": "PERCENT",
        "value": 30,
        "amount": 43.80,
        "status": "CREDITED"
      },
      {
        "subAccountId": "e5f6g7h8-...",
        "subAccountName": "Sócio Investidor",
        "type": "FIXED",
        "value": 10,
        "amount": 10.00,
        "status": "CREDITED"
      }
    ]
  }
}

• PENDING: cobrança ainda não paga — nada foi creditado
• CREDITED: parte creditada no saldo da subconta
• CANCELLED: parte estornada (ex.: disputa/MED antes do repasse)

Repasses e taxas

• Modo automático (default, autoTransferEnabled: true): o repasse diário transfere o saldo total da subconta para a chave PIX cadastrada, quando o saldo atinge o valor mínimo da plataforma.
• Modo sob demanda (autoTransferEnabled: false): o saldo acumula e só sai quando você solicitar o saque — pelo painel ou por POST /v1/sub-accounts/:id/transfer (aceita valor parcial).
• A taxa de saque da sua conta é aplicada ao repasse. Quem paga é configurável por subconta (transferFeePayer): SUBACCOUNT — deduzida do valor enviado à subconta (default); OWNER — a subconta recebe o valor cheio e a taxa é debitada do saldo da sua conta principal (sem saldo para a taxa, o repasse é bloqueado). No modo OWNER, a taxa gera um lançamento próprio no seu histórico de transações ("Taxa de repasse — subconta"), cancelado automaticamente se o repasse falhar e a taxa for estornada.
• Se o PIX de repasse falhar, o valor volta para o saldo da subconta (e a taxa, quando paga pela conta principal, é devolvida a ela). No modo automático, uma nova tentativa acontece no ciclo seguinte. Acompanhe pelos webhooks subaccount.transfer.completed / subaccount.transfer.failed.

Disputas (MED) e split

Se uma venda com split sofrer MED/disputa, o valor integral é debitado da conta principal (comportamento padrão da plataforma). As partes do split que ainda não foram repassadas via PIX são recuperadas automaticamente do saldo das subcontas e devolvidas à conta principal (status CANCELLED). Valores já repassados ficam sob responsabilidade da conta principal.