Split de pagamento

O split de pagamento deixa uma cobrança Pix repartir o seu valor entre a sua loja e outros lojistas do gateway. É o que sustenta cenários de marketplace, comissionamento e repasse a parceiros: o valor de cada recebedor cai direto no saldo dele, com extrato e saque próprios.

As regras de split viajam com a cobrança — não são uma configuração da conta. O que cada recebedor recebe é congelado no momento em que a cobrança é criada.

Pré-requisito: parceria autorizada

O split não é self-service. Creditar saldo na conta de outra pessoa jurídica é movimentação de dinheiro, então cada par (quem repassa → quem recebe) precisa ser autorizado pela SimPix antes de funcionar.

Sem parceria ativa, a cobrança é recusada

Se você tentar repassar para um lojista sem uma parceria de split ativa, o POST /api/transactions responde 400 e a cobrança não é criada (nenhum QR code é gerado).

Fluxo para habilitar um recebedor:

1. Peça a autorização à SimPix, informando qual lojista vai receber os repasses.
2. A SimPix autoriza a parceria (o recebedor precisa ser um lojista com conta ativa).
3. No painel, em Integração → Split de pagamento, você passa a ver os recebedores autorizados, cada um com o identificador mch_… e um botão para copiar.

Como obter o mch_ do recebedor

O campo recipient de cada split é o identificador público (mch_…) do lojista recebedor. Você encontra os identificadores autorizados no painel do lojista, em Integração → Split de pagamento — é exatamente o valor que vai no payload.

Dica

Cada recebedor listado tem um botão Copiar ao lado do mch_…. Se a lista estiver vazia, ainda não há parceria autorizada: peça à SimPix para liberar o par.

Montando o split

Cada item de splits carrega amount OU percentage — nunca os dois:

• amount — valor fixo em BRL a repassar.
• percentage — percentual do valor bruto da cobrança (no máximo 2 casas decimais, ≤ 100).

Valor fixo

splits com amount

"splits": [
  { "recipient": "mch_VVuz_g_ybTfj", "amount": 40.00, "description": "vendedor A" }
]

Percentual

splits com percentage

"splits": [
  { "recipient": "mch_VVuz_g_ybTfj", "percentage": 15.5, "description": "comissão" }
]

Misto

amount e percentage em recebedores diferentes

"splits": [
  { "recipient": "mch_VVuz_g_ybTfj", "amount": 40.00 },
  { "recipient": "mch_XYZ789abcdef", "percentage": 10 }
]

Veja o exemplo de curl completo e o formato da resposta em Transações → Campo splits.

A ordem do dinheiro: taxa → split → você

Quando a cobrança é liquidada, o valor é distribuído nesta ordem:

1. Taxa da SimPix — sai primeiro e sempre do lojista primário (quem criou a cobrança).
2. Splits — a parte de cada recebedor cai no saldo dele.
3. Primário — fica com o restante (valor − taxa − Σ splits).

Por isso vale sempre a regra:

Nota

Σ splits + taxa ≤ valor da cobrança. Se a soma dos splits mais a taxa ultrapassar o valor, a cobrança é recusada.

Exemplo com cobrança de R$ 250,00, taxa de R$ 6,25 e um split de R$ 40,00:

Destino	Valor
Taxa SimPix	R$ 6,25
Recebedor (split)	R$ 40,00
Sua loja (primário)	R$ 203,75

Arredondamento

Splits em percentual são convertidos para centavos com truncamento (como todo cálculo de centavos do gateway). A eventual sobra de arredondamento fica com o lojista primário — nunca com o recebedor. Assim o recebedor recebe exatamente o valor congelado na criação da cobrança.

Estorno e disputa: clawback proporcional

Se uma cobrança com split for estornada ou perder uma disputa, os valores repassados são devolvidos proporcionalmente (clawback): cada recebedor devolve exatamente o que recebeu.

• Estorno — cada recebedor é debitado do valor do seu split; a taxa e o restante do primário também voltam.
• Disputa perdida — o valor bloqueado volta ao pagador e os recebedores devolvem suas partes ao primário. (A taxa não é devolvida numa disputa perdida.)

O saldo do recebedor pode ficar negativo

Se o recebedor já tiver sacado o valor, o clawback pode deixar o saldo dele negativo. Um payment gateway não pode se recusar a estornar o pagador porque o recebedor gastou o dinheiro. Enquanto o saldo estiver negativo, o saque do recebedor fica bloqueado até ele ser regularizado.

No extrato (GET /api/... /ledger), essas movimentações aparecem com os tipos:

Tipo	Significado
split	Crédito de split recebido (lado do recebedor).
split_reversal	Devolução de split — débito no recebedor e crédito de recuperação no primário.

Em todos eles, a referência é o magic_id da cobrança que gerou o valor, dos dois lados da parceria.

Limites

• Até 10 recebedores por cobrança (configurável pela SimPix).
• percentage aceita no máximo 2 casas decimais e não pode passar de 100.
• amount e percentage são mutuamente exclusivos em cada item.
• O recebedor não pode ser o próprio lojista que cria a cobrança.

Erros comuns

As mensagens abaixo são retornadas com 400 no POST /api/transactions (a menos que indicado):

Situação	Mensagem da API
Recebedor sem parceria autorizada	Splits[0].recipient mch_… is not an authorized split partner of this merchant; ask the operator to authorize it
Parceria suspensa	The split partnership with mch_… is SUSPENDED
Recebedor não existe	Splits[0].recipient mch_… does not exist
Recebedor com conta não ativa	Splits[0].recipient mch_… is not an ACTIVE merchant account (…)
amount e percentage juntos	Splits[0] must carry either amount or percentage, never both
Nenhum dos dois informado	Splits[0] must carry either amount or percentage
Percentual com mais de 2 casas	Splits[0].percentage accepts at most 2 decimal places
Percentual acima de 100	Splits[0].percentage must not exceed 100
Split para si mesmo	Splits[0].recipient cannot be the merchant that owns the charge
Splits + taxa passam do valor	Splits (R$ …) plus the platform fee (R$ …) exceed the charge amount (R$ …)

Dica

O índice do split na mensagem (Splits[0], Splits[1]…) aponta a posição do item com problema no array enviado.

Veja também

• Transações — o campo splits no POST, com exemplo completo.
• Webhooks — o payload de transaction inclui splits quando houver.
• Ambiente de testes (Sandbox) — use os valores mágicos para simular estorno e disputa de cobranças com split.