Multi-splits

Divide automaticamente o valor de um pagamento entre múltiplos merchants da plataforma Moneyfly. Útil pra marketplaces, infoprodutos com afiliados, parcerias.

Como funciona

Ao criar uma cobrança PIX, você passa um array split com usernames e percentuais. Quando o pagamento é confirmado, o Moneyfly distribui automaticamente:

Você (merchant principal): recebe amount - fee_moneyfly - soma(splits)
Cada merchant em split: recebe o percentual configurado

Tudo no nosso ledger, sem enviar múltiplos PIX. A provedora bancária vê só 1 crédito.

Adicionando splits ao depósito

{
  "amount": 10000,
  "payer": { "name": "João", "document": "12345678909" },
  "split": [
    { "username": "parceiro1", "percentage": 10 },
    { "username": "afiliado_xyz", "percentage": 5 }
  ]
}

No exemplo:

Valor bruto: R$ 100,00
Taxa Moneyfly (1,49% + R$ 0,49): R$ 1,98
Split @parceiro1 (10%): R$ 10,00
Split @afiliado_xyz (5%): R$ 5,00
Você recebe: R$ 83,02

Regras de validação

percentage aceita decimal — 5.5 é válido (granularidade até 0.01)
percentage deve ser entre 0.01 e 90
Soma total dos splits não pode ultrapassar 90% (origem precisa ficar com pelo menos 10% pra cobrir taxa do Moneyfly + sobrevivência)
Cada username deve existir no Moneyfly, estar com status active e não ser conta sandbox
Você não pode fazer split pra si mesmo
Não pode repetir o mesmo username em múltiplos splits da mesma cobrança
Máximo de 20 splits por cobrança
Conta sandbox (isDemo) não pode enviar split — pra testar end-to-end, use 2-3 contas reais aprovadas por KYC

Erros comuns

Todos retornam HTTP 422 com code identificando a causa.

Code	Mensagem
`username_not_found`	`Username não disponível pra split: xxx. Verifique se o username está correto e a conta está ativa.`
`sum_exceeds_90`	`Soma dos splits (X.XX%) não pode ultrapassar 90%.`
`self_split`	`Você não pode fazer split pra sua própria conta.`
`duplicate_username`	`Não é permitido repetir o mesmo username em vários splits.`
`demo_cannot_split`	`Conta sandbox não pode enviar split. Use uma conta real aprovada por KYC pra testar split end-to-end.`

Mensagem de username_not_found é genérica de propósito — atacante não consegue distinguir "conta inexistente" de "conta inativa/suspensa" (anti-enumeração).

Como o cálculo funciona

percentage incide sobre o valor bruto da cobrança (campo amount), não sobre o líquido. Origem absorve 100% da taxa do Moneyfly — destinatários recebem percentual cheio.

Exemplo com amount: 10000 (R$ 100,00) e taxa Moneyfly de 1,49% + R$ 0,49:

Linha	Cálculo	Valor
Bruto	—	R$ 100,00
Taxa Moneyfly	1,49% × 100 + 0,49	R$ 1,98
Split 10%	10% × 100	R$ 10,00
Split 5%	5% × 100	R$ 5,00
Origem recebe	100 − 1,98 − 10 − 5	R$ 83,02

Internamente os percentuais são guardados em basis points (1 bp = 0,01%) — 5.5% vira 550 bps. Cálculo em integer puro pra evitar erro de float em valores monetários.

Arredondamento usa floor — se o cálculo der fração de centavo (ex: 33.33% de 100), origem fica com o resíduo. Garante que soma das partes ≤ bruto sempre.

Exemplo completo

curl -X POST https://api.moneyflybr.com/v1/pix/qrcode \
  -H "client-id: mf_pk_live_..." \
  -H "client-secret: mf_sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "payer": {
      "name": "Cliente Final",
      "document": "12345678909"
    },
    "external_id": "venda-com-split-001",
    "split": [
      { "username": "producer", "percentage": 40 },
      { "username": "afiliado_joao", "percentage": 15 },
      { "username": "plataforma", "percentage": 5 }
    ]
  }'

Rastreando splits

Cada merchant que recebeu split pode ver seus splits no painel em app.moneyflybr.com/splits — mostra origem, percentual, valor e status.

Via API, o campo utm e o external_id da transação original são preservados, então você consegue fazer a conciliação completa.

Multi-splits

On this page