Split de Pagamentos
Como dividir o valor de uma cobrança entre múltiplos recebedores usando splits inline
O que é Split de Pagamentos?
O split de pagamentos permite dividir o valor de uma cobrança entre múltiplos recebedores (merchants e submerchants) no momento da criação da cobrança. A divisão é definida diretamente no payload, sem necessidade de configuração prévia.
Participantes de um split:
- Recebedores — merchants ou submerchants que recebem parte do valor
- Plataforma — cobra a taxa de processamento (MDR), calculada automaticamente
Como Funciona
Ao criar uma cobrança, envie o array split com as regras de divisão:
curl -X POST https://api.payhubrasil.com.br/v1/charges \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"payment_method": "credit_card",
"product_type": "digital",
"split": [
{
"recipient_id": "uuid-do-submerchant",
"recipient_type": "submerchant",
"type": "fixed",
"amount": 8000
},
{
"recipient_id": "uuid-do-merchant",
"recipient_type": "merchant",
"type": "fixed",
"amount": 2000
}
],
"customer": { "..." },
"items": [{ "..." }],
"payment_details": { "..." }
}'const response = await fetch('https://api.payhubrasil.com.br/v1/charges', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify
Exemplo com uma venda de R$ 100,00:
| Participante | Valor |
|---|---|
| Taxa da plataforma (MDR) | R$ 2,50 (calculada automaticamente) |
| Submerchant | R$ 80,00 |
| Merchant (comissão) | R$ 20,00 |
A taxa da plataforma (MDR) é calculada e deduzida automaticamente do primeiro recebedor do split. Você não precisa incluí-la no array.
Tipos de Split
Cada entrada do array split pode usar um tipo diferente:
| Tipo | Campo amount | Descrição | Exemplo |
|---|---|---|---|
fixed | Valor em centavos | Valor absoluto | 5000 = R$ 50,00 |
percentage | Valor decimal | Porcentagem sobre o valor total | 0.10 = 10% |
Para tipo percentage, o valor deve ser informado como decimal. Por exemplo, 10% deve ser enviado como 0.10, não como 10.
Campos do Objeto Split
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recipient_id | string (uuid) | Sim | ID do merchant ou submerchant recebedor |
recipient_type | string | Sim | merchant ou submerchant |
type | string | Sim | percentage ou fixed |
amount | number | Sim | Valor do split (decimal para %, centavos para fixo) |
cross_company | boolean | Não | Se o recebedor pertence a outra empresa (default: false) |
Split Intercompany (cross_company)
A flag cross_company indica que o recebedor pertence a outra empresa. Isso permite que a plataforma aplique regras específicas de liquidação e compliance para splits entre empresas diferentes.
{
"recipient_id": "uuid-de-outro-merchant",
"recipient_type": "merchant",
"type": "fixed",
"amount": 3000,
"cross_company": true
}Validações
- A soma dos splits não pode exceder o valor total da cobrança
- Cada recebedor deve ter uma subconta ativa na adquirente
- Pelo menos uma entrada de split é obrigatória quando o array é enviado
Erros Comuns
| Código | Descrição | Solução |
|---|---|---|
SPLIT_AMOUNT_EXCEEDS_TOTAL | Soma dos splits excede o valor da cobrança | Ajuste os valores |
RECIPIENT_SUB_ACCOUNT_NOT_FOUND | Recebedor sem subconta na adquirente | Crie a subconta antes |
RECIPIENT_SUB_ACCOUNT_NOT_ACTIVE | Subconta do recebedor não está ativa | Aguarde ativação |
NEGATIVE_NET_AMOUNT_AFTER_FEES | Valor líquido ficou negativo após taxas | Reduza splits ou aumente o valor |