Configure Split em assinaturas

Adicione split à assinatura para definir como os valores das cobranças recorrentes serão distribuídos entre outras contas Asaas.

A configuração funciona como um template: cada nova cobrança gerada pela assinatura recebe o Split definido nela.

Antes de começar

Tenha o walletId de cada conta que receberá parte do valor e defina a regra de repasse com fixedValue ou percentualValue.

As regras de cálculo sobre netValue, limites e combinações estão em Split de Pagamentos.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Definir os recebedores"] --> B["Configurar o Split"]
    B --> C["Criar a assinatura"]
    C --> D["Gerar nova cobrança"]
    D --> E["Aplicar o Split"]
    E --> F["Receber a cobrança"]
    F --> G["Liquidar o Split"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Configure o Split na assinatura

Inclua o array split na criação da assinatura:

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

Consulte o endpoint Criar nova assinatura.

Resultado esperado

A assinatura será criada com a configuração de Split.

Quando uma nova cobrança for gerada, ela receberá o Split definido na assinatura.

2. Atualize o Split da assinatura

Para alterar a configuração, utilize:

PUT /v3/subscriptions/{id}

Envie o novo split:

{
  "split": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 10.00
    }
  ]
}

Consulte o endpoint Atualizar assinatura existente.

A alteração passa a ser utilizada pelas próximas cobranças geradas.

Cobranças já geradas não têm o Split atualizado automaticamente.

Para alterar uma cobrança existente:

1. liste as cobranças já geradas pela assinatura;
2. identifique a cobrança que precisa ser alterada;
3. atualize o split diretamente nessa cobrança.

Liste as cobranças de uma assinatura.

Consulte o endpoint Atualizar cobrança existente.

3. Consulte o Split configurado

Para consultar uma assinatura específica:

GET /v3/subscriptions/{id}

Consulte o endpoint Recuperar uma única assinatura.

Para consultar várias assinaturas, utilize Listar assinaturas.

Acompanhe por Webhooks

Utilize os eventos de assinatura para acompanhar alterações na configuração da recorrência.

Quando precisar confirmar a liquidação de cada Split das cobranças geradas, acompanhe:

PAYMENT_SPLIT_DONE

Esse evento pertence ao ciclo da cobrança e é disparado individualmente para cada Split liquidado.

• Eventos para assinaturas
• Eventos para cobranças

Divergência de Split

Se o valor configurado para o Split ultrapassar o valor líquido disponível, a assinatura pode ser bloqueada e deixar de gerar novas cobranças.

Nesse cenário, trate os eventos:

SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK
SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED

Consulte o fluxo de bloqueio de assinatura por divergência de Split.

Próximos passos

• Consulte as regras gerais do Split de Pagamentos
• Liste as cobranças de uma assinatura
• Acompanhe os Eventos para assinaturas
• Acompanhe os Eventos para cobranças
• Trate bloqueios por divergência de Split
• Consulte o FAQ do Split