Split

Use este FAQ para validar as regras de split de pagamentos antes de criar ou atualizar cobranças pela API do Asaas.

O split de pagamentos divide automaticamente o valor recebido em uma cobrança entre uma ou mais contas Asaas. Use essa configuração quando sua integração cria cobranças para marketplace, divisão de comissão, repasse para subcontas ou qualquer fluxo em que parte do valor líquido precisa ser enviada a outra conta no momento do recebimento.

Esta página complementa a Introdução - Split de pagamento e ajuda você a confirmar requisitos, limites, exemplos de payload, estados de acompanhamento e cuidados operacionais antes da implementação.

Quando usar split

Use split quando o repasse deve acontecer automaticamente junto com o recebimento da cobrança. Nesse fluxo, sua integração informa os destinatários no campo splits, o Asaas calcula os valores sobre o valor líquido e mantém na conta emissora apenas o saldo que não foi direcionado a outras carteiras.

Não use split quando o repasse precisa ocorrer em uma data futura ou depender de uma aprovação posterior ao pagamento. Nesses casos, crie a cobrança sem split e faça uma transferência entre contas Asaas quando o repasse puder ser executado.

Pré-requisitos

1. Crie ou identifique a conta Asaas que emitirá a cobrança.
2. Obtenha o walletId de cada conta Asaas que receberá parte do valor.
3. Defina se cada repasse usará valor fixo (fixedValue) ou percentual (percentualValue).
4. Valide se a soma dos repasses não excede o valor líquido da cobrança ou 100% nos splits percentuais.
5. Consulte a referência de criação de cobrança ou atualização de cobrança para enviar o campo splits no body da requisição.

Fluxo recomendado de integração

1. Crie ou identifique a conta que emitirá a cobrança. Essa conta recebe automaticamente o saldo líquido que não for distribuído via split.
2. Recupere o walletId de cada conta Asaas que receberá repasse e valide se nenhum deles pertence à própria conta emissora.
3. Calcule os repasses antes de criar a cobrança. Para valor fixo, confirme que a soma não supera o valor líquido previsto; para percentual, confirme que a soma não ultrapassa 100%.
4. Crie a cobrança na conta emissora e envie o array splits com uma entrada para cada conta de destino.
5. Aguarde o pagamento da cobrança. O Asaas executa o split automaticamente no momento do recebimento.
6. Consulte a cobrança ou acompanhe os eventos de webhook para confirmar o status do split.
7. Em caso de ajuste antes do recebimento, atualize a cobrança informando novamente o array splits com a configuração desejada.
8. Se a cobrança for estornada, trate o estorno do split na conciliação das contas que receberam saldo.

Parâmetros do split

Exemplo: split em cobrança avulsa

Adicione o array splits ao body da criação da cobrança. No exemplo abaixo, uma conta recebe R$ 20,00 fixos e outra recebe 10% do valor líquido da cobrança.

{
  "splits": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 20.00
    },
    {
      "walletId": "0b763922-aa88-4cbe-a567-e3fe8511fa06",
      "percentualValue": 10.00
    }
  ]
}

Resultado esperado: quando a cobrança for recebida, o Asaas calcula o valor líquido, executa os repasses configurados e mantém o saldo restante na conta emissora da cobrança.

Checklist de implementação

Antes de liberar o split em produção, valide estes pontos no seu fluxo:

1. Salve o walletId correto de cada destinatário e associe-o ao cadastro interno do recebedor.
2. Registre o identificador interno do repasse em externalReference para facilitar conciliação e reprocessamento.
3. Teste cenários em que o valor líquido final é menor que o esperado, principalmente quando houver taxas, descontos, antecipação ou combinação de split fixo e percentual.
4. Ao atualizar uma cobrança sem alterar o split, não envie splits como null ou [], pois isso desativa a configuração existente.
5. Acompanhe webhooks de cobrança e split para atualizar o status interno do repasse.

Optional: split em parcelamento

Em parcelamentos, você pode informar o valor aplicado em cada parcela com fixedValue ou o valor total do split com totalFixedValue.

Valor por parcela

{
  "totalValue": 100.00,
  "installmentCount": 4,
  "splits": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 10.00
    }
  ]
}

Resultado esperado: o Asaas aplica R$ 10,00 de split em cada uma das 4 parcelas, totalizando R$ 40,00 ao fim da quitação do parcelamento.

Valor total do parcelamento

{
  "totalValue": 300.00,
  "installmentCount": 3,
  "splits": [
    {
      "walletId": "0b763922-aa88-4cbe-a567-e3fe8511fa06",
      "totalFixedValue": 100.00
    }
  ]
}

Resultado esperado: o Asaas divide automaticamente o split total entre as parcelas, aplicando R$ 33,33, R$ 33,33 e R$ 33,34.

Estados do split

Use os status do split para orientar a conciliação financeira da sua integração:

Quando o status é REFUSED, o campo refusalReason pode indicar o motivo. Um motivo possível é RECEIVABLE_UNIT_AFFECTED_BY_EXTERNAL_CONTRACTUAL_EFFECT, quando o split não é executado devido à existência de efeitos de contrato.

Perguntas frequentes

O que acontece quando estorno uma cobrança com split?

Em caso de estorno da cobrança, o split também é estornado. Todas as contas que receberam saldo da cobrança têm a transferência estornada.

Tem limite de carteira (walletId) para realizar split?

Não há limite no número de walletId enviados no split. A limitação é o valor líquido total da cobrança em splits de valor fixo e a distribuição máxima de 100% em splits percentuais.

Posso enviar o dinheiro do split para a minha subconta X dias após o recebimento?

Não. O split é executado automaticamente no momento do recebimento e não permite personalização de data.

Se você precisa repassar valores em uma data futura, crie a cobrança sem split, receba o valor integral na conta emissora e faça uma transferência entre contas Asaas no dia desejado.

É possível utilizar o split sem integração via API?

O split de pagamentos é uma funcionalidade exclusiva da API do Asaas e não pode ser utilizado ou gerenciado diretamente pelo site.

Se você não tem uma integração via API, consulte Usando o split sem API para avaliar alternativas como plugins e conectores.

O que preciso para fazer split de pagamentos no Asaas?

Você precisa do walletId de todas as contas Asaas que receberão repasses. O walletId é retornado na criação de subcontas e também pode ser recuperado pela API quando você possui a chave de API da conta destino.

Quem deve configurar o split de pagamento?

Quem cria a cobrança deve configurar o split. No body da cobrança, informe o walletId da conta que receberá o repasse e o valor fixo ou percentual que será transferido.

Todos os envolvidos precisam ter uma conta Asaas para que o repasse seja realizado corretamente.

Como funciona a divisão de comissão no split?

A divisão de comissão permite que o valor de uma cobrança seja automaticamente dividido entre as partes envolvidas. Você pode configurar cada repasse como percentual ou valor fixo.

Como o sistema calcula o valor repassado quando a comissão é percentual?

Quando a comissão é percentual, o cálculo é feito sobre o valor líquido da cobrança, ou seja, depois do desconto das taxas aplicadas.

Por exemplo: se uma cobrança tem valor líquido de R$ 98,00 e um split de percentualValue igual a 50, o repasse calculado é de R$ 49,00.

É possível definir mais de uma porcentagem para dividir o valor entre várias pessoas?

Sim. Você pode configurar percentuais diferentes para várias contas. A soma dos percentuais não pode ultrapassar 100%.

Como funciona a divisão de comissão com valor fixo?

Quando o split é configurado com valor fixo, você define o valor exato que será repassado. O valor fixo não pode ser superior ao valor líquido da cobrança.

O que acontece se a soma das porcentagens exceder 100%?

O sistema não permite que a configuração do split exceda 100%. Se você tentar configurar percentuais que somem mais de 100%, a API retorna erro e o split não é salvo na cobrança.

Como a taxa do Asaas afeta a divisão por porcentagem?

A taxa do Asaas é descontada antes da divisão entre as partes. A porcentagem é aplicada somente sobre o valor líquido da cobrança.

Posso combinar valor fixo e percentual no mesmo split?

Sim. Você pode combinar repasses com fixedValue e percentualValue na mesma cobrança, desde que o total calculado não ultrapasse o valor líquido.

Exemplo: em uma cobrança com valor líquido de R$ 98,00, um split fixo de R$ 50,00 combinado com um split percentual de 50% resultaria em R$ 99,00 de repasse total. Como esse valor supera o valor líquido, a API retorna exceção.

Quais status um split pode ter?

Os status disponíveis são PENDING, AWAITING_CREDIT, CANCELLED, DONE, REFUSED e REFUNDED. Consulte a seção Estados do split para ver como tratar cada status na sua integração.

Erros comuns e boas práticas

Para reduzir falhas operacionais, armazene o identificador interno do repasse em externalReference, consulte a cobrança antes de reprocessar atualizações e acompanhe webhooks relacionados a cobranças e splits. Se sua integração processa eventos, veja também Como implementar idempotência em Webhooks.

Conteúdos relacionados

Continue pelo conteúdo que corresponde ao tipo de cobrança da sua integração:

Use também as referências da API quando for montar ou ajustar a requisição:

• Criar nova cobrança
• Atualizar cobrança existente com dados resumidos na resposta
• Transferência para conta Asaas