Split (divisão do valor)

Split é dividir o valor de uma venda entre mais de uma conta, na hora em que ela é paga. Em vez de receber tudo e depois transferir pra cada um, você diz na própria cobrança quem fica com quanto. A SwitchPay separa o dinheiro e cada conta recebe a sua parte direto.

Serve pra casos como:

• Marketplace: o comprador paga R$ 150,00; R$ 135,00 são da loja e R$ 15,00 são a sua comissão.
• Parceiro ou afiliado: uma parte de cada venda vai pra quem indicou o cliente.
• Prestador de serviço: a venda é sua, mas uma fatia vai pra quem entrega ou executa.

Como funciona

1. Ao criar a intenção de pagamento, você manda a lista splitRules: uma regra por conta que vai receber uma fatia.
2. Quem vende é sempre a sua empresa (a dona da chave de API). O que sobra depois das fatias fica com ela.
3. Quando a venda é paga, a transação passa a trazer split.receivables: quanto cada conta recebe e em que data.

Sem splitRules, a venda inteira é da sua empresa.

Montando uma regra

Cada item de splitRules é uma fatia:

Dá pra misturar fatias em percentual e em valor fixo na mesma venda.

Exemplo

Um Pix de R$ 150,00 em que 10 % vão pra outra conta:

{
  "amountCents": 15000,
  "paymentMethod": "PIX",
  "buyer": { "name": "Maria Souza", "document": "12345678909", "email": "maria@exemplo.com", "phone": { "country": "55", "area": "11", "number": "987654321" } },
  "splitRules": [
    { "recipientDocument": "11222333000181", "type": "PERCENTAGE", "percentage": 10 }
  ]
}

Depois de paga, a transação mostra como o valor foi dividido:

Na resposta isso vem em split.receivables, uma linha por conta e por parcela:

"split": {
  "receivables": [
    { "recipientDocument": "11222333000181", "role": "CUSTOM_SPLIT_RECIPIENT", "installment": 1, "grossAmountCents": 1500, "feeCents": 0, "amountCents": 1500, "expectedOn": "2026-10-07", "status": "PENDING" },
    { "recipientDocument": "99888777000166", "role": "SELLER", "installment": 1, "grossAmountCents": 13500, "feeCents": 149, "amountCents": 13351, "expectedOn": "2026-10-07", "status": "PENDING" }
  ]
}

Lendo os recebíveis

• grossAmountCents: a fatia antes da taxa. feeCents: a taxa que saiu dela. amountCents: o que a conta recebe de fato.
• expectedOn: a data prevista do repasse.
• status: fala do repasse, não da venda. PENDING = a receber; PAID = já repassado. Uma venda paga normalmente tem recebíveis PENDING até a data prevista.
• Em venda parcelada no cartão, cada conta tem uma linha por parcela, cada uma com a sua data.
• Na transação, feeCents é o total de taxas da venda e netAmountCents é o total que as contas recebem. Os dois somados dão o valor cobrado (amountCents).

Os recebíveis aparecem quando a venda é paga. Enquanto ela está aguardando pagamento, a lista pode vir vazia.

Regras

• A soma das fatias não pode passar do valor da venda. Fatias em percentual não podem somar mais de 100 %.
• Toda regra precisa do valor do seu tipo: percentage pra PERCENTAGE, amountCents pra FIXED.
• Quem recebe precisa ter conta aprovada na SwitchPay.
• A divisão é definida na criação da intenção. Pra dividir de outro jeito, crie outra intenção.

Erros

No sandbox

A conta é a mesma de produção; só o dinheiro não anda. As contas que podem receber split no sandbox têm cadastro próprio: peça à SwitchPay os documentos de teste. Pra ver os recebíveis, pague a venda com POST /v2/sandbox/transactions/{id}/pay.