Split para contas com Conta Escrow

Quando uma cobrança com Split direciona valores para subcontas com diferentes configurações de Conta Escrow, trate liquidação do Split e disponibilidade do saldo como etapas distintas.

Cada conta recebedora segue sua própria configuração de Conta Escrow. Por isso, valores originados pela mesma cobrança podem ficar disponíveis em momentos diferentes.

Antes de começar

Antes de combinar os recursos:

• obtenha o walletId de cada conta que receberá o Split;
• configure a Conta Escrow nas subcontas que devem manter valores sob garantia;
• defina o daysToExpire de cada subconta individualmente;
• configure a Conta Escrow antes do recebimento que deve ficar sob garantia;
• defina os valores do Split considerando o netValue da cobrança.

Alterações em daysToExpire afetam apenas novos recebimentos processados após a atualização da configuração.

Consulte Configurando a Conta Escrow para as subcontas e Split em cobranças avulsas para os fluxos completos de configuração.

Como funciona

O Split é processado para cada conta recebedora. A disponibilidade do valor depende da configuração aplicada à conta de destino.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Definir os recebedores"] --> B["Criar cobrança com Split"]
    B --> C["Receber a cobrança"]
    C --> D["Liquidar um Split"]
    D --> E["Receber<br/>PAYMENT_SPLIT_DONE"]
    E --> F{"Conta destino usa Conta Escrow?"}

    F --> FSim(("Sim"))
    F --> FNao(("Não"))

    FSim --> G["Manter valor sob garantia"]
    FNao --> I["Disponibilizar valor no saldo"]

    G --> H["Encerrar garantia"]
    H --> I

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

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

    class FSim respostaSim
    class FNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#22C55E,stroke-width:4px
    linkStyle 6 stroke:#EF4444,stroke-width:4px

Quando houver vários recebedores, esse comportamento deve ser considerado individualmente para cada conta.

Exemplo com regras diferentes

Considere uma cobrança cujo Split direciona valores para três subcontas:

Os 10% restantes permanecem na conta que criou a cobrança.

B e C podem receber Splits da mesma cobrança e manter períodos de garantia diferentes, porque daysToExpire pertence à configuração de cada subconta.

1. Configure a Conta Escrow nas contas que devem reter valores

Configure cada recebedor individualmente.

Conta B

POST /v3/accounts/{id}/escrow

{
  "daysToExpire": 10,
  "enabled": true,
  "isFeePayer": true
}

Conta C

POST /v3/accounts/{id}/escrow

{
  "daysToExpire": 15,
  "enabled": true,
  "isFeePayer": true
}

A conta D permanece sem Conta Escrow.

Consulte o endpoint Salvar ou atualizar configuração da Conta Escrow para a subconta.

2. Crie a cobrança com Split

Adicione o array split à criação da cobrança:

POST /v3/payments

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 500.00,
  "dueDate": "2026-09-20",
  "split": [
    {
      "walletId": "<walletId-conta-B>",
      "percentualValue": 20.00
    },
    {
      "walletId": "<walletId-conta-C>",
      "percentualValue": 20.00
    },
    {
      "walletId": "<walletId-conta-D>",
      "percentualValue": 50.00
    }
  ]
}

O percentualValue é calculado sobre o netValue, após as taxas aplicáveis. O valor líquido não direcionado aos recebedores permanece na conta que criou a cobrança.

Consulte o endpoint Criar nova cobrança.

3. Acompanhe a liquidação por Webhook

Utilize o evento:

PAYMENT_SPLIT_DONE

O evento é enviado individualmente quando um Split é liquidado. Em uma cobrança com vários recebedores, cada Split pode gerar sua própria notificação.

Utilize additionalInfo.splitId para identificar o Split correspondente:

{
  "additionalInfo": {
    "splitId": "064a4957-1eee-4d06-9c96-deaf8a17534d"
  }
}

Consulte os Eventos para cobranças.

4. Considere a garantia na conciliação

Para contas com Conta Escrow, não trate um valor como disponível apenas porque o respectivo Split foi liquidado.

Enquanto a garantia estiver ativa:

• o recebimento já ocorreu;
• o valor permanece sob garantia;
• a conta ainda não pode utilizar esse recurso como saldo disponível.

A garantia pode terminar automaticamente ao atingir expirationDate, manualmente pela API ou pela desabilitação da Conta Escrow.

Para consultar e liberar garantias, siga o fluxo de Valores sob garantia da Conta Escrow e Liberação dos Valores em garantia.

Como validar

Após o recebimento da cobrança:

• confirme o PAYMENT_SPLIT_DONE de cada Split esperado;
• trate B e C como valores recebidos, mas ainda sob garantia enquanto a retenção estiver ativa;
• considere o prazo configurado individualmente para cada subconta;
• trate D conforme o fluxo normal de liquidação do Split;
• não utilize consultas recorrentes apenas para verificar a liquidação dos Splits.

Erros comuns

Considerar PAYMENT_SPLIT_DONE como confirmação de saldo disponível

O evento confirma a liquidação do Split. A disponibilidade do valor também depende da Conta Escrow da conta recebedora.

Configurar daysToExpire no Split

O prazo pertence à configuração da Conta Escrow da subconta, não ao array split da cobrança.

Calcular o Split sobre o valor bruto

percentualValue utiliza o netValue. Considere as taxas aplicáveis antes de definir a distribuição.

Usar polling para acompanhar cada Split

Utilize PAYMENT_SPLIT_DONE como mecanismo principal de acompanhamento da liquidação.

Próximos passos

• Split em cobranças avulsas
• Configurando a Conta Escrow para as subcontas
• Valores sob garantia da Conta Escrow
• Liberação dos Valores em garantia
• Eventos para cobranças