Split de pagamentos
Distribua o valor de uma cobrança entre recebedores cadastrados, por percentual ou valor fixo, e concilie o valor calculado.
O bloco split divide o valor da cobrança entre recebedores cadastrados na sua conta. Cada recebedor tem um recipientId, entregue pela equipe de integração (um por ambiente).
"split": {
"rules": [
{
"recipientId": "ID_DO_RECEBEDOR_PRINCIPAL",
"type": "percentage",
"amount": 90,
"options": { "isPrincipal": true, "chargeMdr": true, "chargebackLiability": true }
},
{
"recipientId": "ID_DO_SEGUNDO_RECEBEDOR",
"type": "percentage",
"amount": 10,
"options": { "isPrincipal": false, "chargeMdr": false, "chargebackLiability": false }
}
]
}Regras
O split divide o valor entre recebedores, mas não muda o escopo da venda: a cobrança segue a conta da chave que a criou. Incluir um recebedor da operação offshore numa cobrança criada com a chave doméstica não a torna offshore. Veja Contas, chaves e identificadores.
| Campo | Como preencher |
|---|---|
recipientId | Identificador do recebedor. Cada um aparece uma única vez nas regras. |
type: "percentage" | amount é percentual, com até quatro casas decimais: 90 significa 90%. A soma precisa fechar em 100%. |
type: "flat" | amount é inteiro positivo em centavos. A soma precisa fechar no total da cobrança. |
options.isPrincipal | Em crédito, marque exatamente um recebedor principal. Use esse formato mesmo com um único recebedor. |
options.chargeMdr | Indica quem arca com a tarifa de processamento, conforme a configuração contratada. |
options.chargebackLiability | Indica quem responde por contestações, conforme a configuração contratada. |
type é sempre em minúsculas. Não misture regras de percentual e de valor fixo na mesma cobrança.
| Erro | Causa |
|---|---|
400 split_amount_mismatch | A soma das regras passa do total da cobrança. |
400 split_percentage_scale_invalid | Percentual com mais de quatro casas decimais, ou fora do intervalo de 0 a 100. |
400 split_flat_amount_must_be_integer_minor_units | Valor fixo com casas decimais. |
400 PaymentIntentCreationError | recipientId repetido, type inválido ou recebedor principal ausente ou duplicado em crédito. O detail descreve o problema. |
Concilie pelo valor calculado
Depois da cobrança, cada regra traz allocatedAmount, o valor em centavos que coube ao recebedor, já com arredondamento. Use esse campo, não a sua própria conta de percentual, para conciliar.
"split": {
"rules": [
{ "recipientId": "ID_DO_RECEBEDOR_PRINCIPAL", "type": "percentage", "amount": 90, "allocatedAmount": 8991 },
{ "recipientId": "ID_DO_SEGUNDO_RECEBEDOR", "type": "percentage", "amount": 10, "allocatedAmount": 999 }
]
}allocatedAmount: null significa que a alocação não foi informada; não interprete como zero. Uma cobrança sem split traz "split": null.