Split em cobranças avulsas
Configure Split em cobranças avulsas
Para dividir o valor de uma cobrança avulsa, adicione o array split à requisição de criação da cobrança.
As demais configurações da cobrança permanecem iguais ao fluxo sem Split.
Antes de começar
Tenha o walletId de cada conta que receberá parte do valor e defina se o repasse será:
- fixo, com
fixedValue; - percentual, com
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["Adicionar split à cobrança"]
B --> C["Criar a cobrança"]
C --> D["Receber o pagamento"]
D --> E["Liquidar os Splits"]
E --> F["Receber o Webhook"]
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 validacao
class F sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
1. Adicione o Split à cobrança
Inclua split na criação da cobrança:
{
"...": "...",
"split": [
{
"walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
"fixedValue": 20.00
},
{
"walletId": "0b763922-aa88-4cbe-a567-e3fe8511fa06",
"percentualValue": 10.00
}
]
}Nesse exemplo:
- a primeira carteira recebe R$ 20,00;
- a segunda recebe 10% do
netValue; - o saldo líquido não destinado aos recebedores permanece na conta que criou a cobrança.
Consulte o endpoint Criar nova cobrança com dados resumidos na resposta.
Você só precisa adicionar informações de Split das contas que quer transferir uma parte do valor. O saldo restante fica todo na conta que emitiu a cobrança.
Resultado esperado
A cobrança será criada com as configurações de Split associadas.
Os valores serão distribuídos quando ocorrer a liquidação dos respectivos Splits.
2. Atualize o Split
Recupere o ID da cobrança e envie a nova configuração de split na atualização:
PUT /v3/lean/payments/{id}{
"...": "...",
"split": [
{
"walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
"fixedValue": 10.00
}
]
}Consulte o endpoint Atualizar cobrança existente com dados resumidos na resposta.
AtençãoAo atualizar uma cobrança, caso não queira alterar as configurações do Split, não informe o parâmetro splits na requisição, pois passando
nullou[]o Split será desativado.
A atualização de Split possui regras adicionais quando a cobrança já está confirmada. Consulte Atualizar cobrança existente para validar os status e condições permitidos.
ImportanteSe você excluir uma cobrança, as configurações de split serão removidas. Caso a cobrança seja restaurada e paga o split não estará mais configurado e não acontecerá. Portanto, caso a cobrança restaurada possuía split configurado antes da exclusão, certifique-se de configurar novamente o split.
3. Consulte o Split da cobrança
Para recuperar uma cobrança específica, utilize:
GET /v3/lean/payments/{id}Consulte o endpoint Recuperar uma única cobrança com dados resumidos.
Para localizar cobranças por filtros, utilize Listar cobranças com dados resumidos.
Quando houver Split configurado, os dados correspondentes são retornados junto à cobrança.
Prefira Webhooks para acompanhar alterações e liquidação em vez de consultar a cobrança continuamente.
4. Acompanhe a liquidação
Os dados de Split também acompanham os eventos relacionados à cobrança.
Para identificar quando um Split específico for liquidado, trate:
PAYMENT_SPLIT_DONEO evento é enviado individualmente para cada Split liquidado. Utilize additionalInfo.splitId para identificar o Split correspondente.
Consulte os Eventos para cobranças.
Próximos passos
Updated 10 days ago