Checkout com Split de Pagamento

Configure Split de Pagamento no Checkout

Adicione splits ao Checkout para distribuir automaticamente parte do valor recebido entre outras contas Asaas.

O Split é executado após o recebimento da cobrança gerada pelo Checkout.

Antes de começar

Antes de configurar:

obtenha o walletId de cada conta que receberá parte do valor;
defina se cada divisão será fixa ou percentual;
valide se a distribuição não ultrapassa o valor líquido da cobrança;
não informe o walletId da própria conta que cria o Checkout;
configure os Webhooks de Checkout e cobranças.

A diferença líquida não destinada aos recebedores permanece na conta que originou a cobrança.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Obter os walletIds"] --> B["Definir os valores do Split"]
    B --> C["Adicionar splits ao Checkout"]
    C --> D["Criar o Checkout"]
    D --> E["Pagador conclui o pagamento"]
    E --> F["Calcular o valor líquido"]
    F --> G["Liquidar os Splits"]
    G --> H["Receber os Webhooks"]

    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,G validacao
    class H sucesso

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

1. Defina os valores do Split

Cada item de splits deve informar o walletId da conta de destino e a regra de distribuição.

Valor fixo

Utilize fixedValue para definir um valor específico:

{
  "walletId": "ID_DA_CARTEIRA_1",
  "fixedValue": 100.00
}

fixedValue aceita até duas casas decimais.

Valor percentual

Utilize percentualValue para definir um percentual:

{
  "walletId": "ID_DA_CARTEIRA_2",
  "percentualValue": 50
}

O percentual é calculado sobre o valor líquido da cobrança (netValue), após o desconto das taxas do Asaas.

percentualValue aceita até quatro casas decimais e a soma dos percentuais não pode ultrapassar 100%.

⚠️
Atenção
É possível combinar fixedValue e percentualValue, mas não existe prioridade entre eles.
O percentual não é calculado sobre o valor restante após os Splits fixos. Todos os valores devem ser compatíveis com o netValue da cobrança.

Consulte as regras do Split de Pagamentos.

2. Adicione o Split ao Checkout

Inclua splits no corpo da criação:

POST /v3/checkouts

Exemplo:

{
  "billingTypes": ["PIX"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://meusite.com/cancelado",
    "expiredUrl": "https://meusite.com/expirado",
    "successUrl": "https://meusite.com/sucesso"
  },
  "items": [
    {
      "name": "Pedido 1001",
      "quantity": 1,
      "value": 300.00
    }
  ],
  "splits": [
    {
      "walletId": "ID_DA_CARTEIRA_1",
      "fixedValue": 100.00
    },
    {
      "walletId": "ID_DA_CARTEIRA_2",
      "percentualValue": 50
    }
  ]
}

Nesse exemplo:

a primeira carteira recebe R$ 100,00;
a segunda recebe 50% do netValue;
o saldo líquido não destinado aos Splits permanece na conta que originou a cobrança.

Consulte o endpoint Criar novo checkout.

Resultado esperado

A API retorna o ID do Checkout.

O Split ainda não é liquidado nesse momento. A distribuição ocorre após o recebimento da cobrança gerada pelo Checkout.

3. Acompanhe o pagamento e a liquidação

Utilize Webhooks para acompanhar etapas diferentes do fluxo:

Evento	O que confirma
`CHECKOUT_PAID`	O Checkout foi pago
`PAYMENT_SPLIT_DONE`	Um Split específico foi liquidado

PAYMENT_SPLIT_DONE é disparado individualmente para cada Split liquidado. Quando houver mais de um recebedor, podem ser enviados vários eventos.

Para identificar qual Split foi liquidado, utilize additionalInfo.splitId no evento PAYMENT_SPLIT_DONE.

Consulte os Eventos para Checkout.

Consulte os Eventos para cobranças.

👍
Recomendado
Utilize Webhooks como mecanismo principal para acompanhar o pagamento e a liquidação dos Splits.
Não realize consultas recorrentes apenas para verificar se um Split atingiu o status de liquidação.

Erros comuns

Se o Checkout com Split não for criado ou processado como esperado, verifique:

se todos os walletId pertencem a contas Asaas válidas;
se o walletId da própria conta emissora não foi informado;
se os valores fixos não ultrapassam o netValue;
se a soma dos percentuais não ultrapassa 100%;
se a combinação entre valores fixos e percentuais continua compatível com o valor líquido da cobrança.

Para outras regras e cenários, consulte Split de Pagamentos.

Próximos passos

Updated 3 days ago

Did this page help you?