Recorrência com Split de Pagamentos

O split na recorrência permite dividir automaticamente cada cobrança de uma assinatura entre múltiplos recebedores. É a base para cenários como marketplaces com assinaturas, comissionamento recorrente e divisão de receita entre parceiros.

Diferente do split em pagamentos avulsos, o split em recorrência é configurado na criação da assinatura e aplicado a todas as cobranças subsequentes geradas pelo plano.

🚧

O split na recorrência não pode ser combinado com cupom nem com planos que possuem setup_fee (taxa de adesão).

O que você pode fazer

Os campos de split disponíveis na API de Pagamento Recorrente permitem que você:

• Ative split em uma assinatura: Defina split_enabled = true no momento da criação.
• Divida por percentual: Utilize method: PERCENTAGE para que cada recebedor receba uma fração proporcional do valor de cada cobrança.
• Divida por valor fixo: Utilize method: FIXED para distribuir valores absolutos entre recebedores.
• Configure responsabilidade por chargeback: Defina, por recebedor, o percentual de transferência da responsabilidade em caso de estorno.

Como utilizar

Para utilizar split em recorrência, você precisa de um Token de autenticação válido e de um plano elegível (sem cupom e sem setup_fee). Confira o passo a passo no guia Token de autenticação.

Idempotência

Como a criação de assinatura é uma operação POST, envie sempre o header x-idempotency-key. Saiba mais em Chaves públicas e de idempotência.

Campos que controlam o split

Fluxo recomendado

1. Garanta que o plano é elegível, sem cupom aplicado e sem setup_fee.
2. Monte o payload de assinatura incluindo split_enabled = true e o bloco splits.
3. Escolha o método de divisão: PERCENTAGE para divisão proporcional, FIXED para valores absolutos.
4. Envie a requisição.
5. Valide a resposta, confirmando que split_enabled = true e que o bloco splits está presente.

Métodos de divisão

O campo splits.method define como o valor de cada cobrança é distribuído entre os recebedores. A API suporta dois métodos, escolhidos conforme a regra de negócio da sua integração:

• PERCENTAGE: Cada recebedor recebe uma fração proporcional do valor da cobrança. Use quando a divisão acompanha o valor (por exemplo, comissão de 5% sobre qualquer valor de assinatura).
• FIXED: Cada recebedor recebe um valor absoluto em centavos. Use quando os valores são pré-definidos e não variam com o total da cobrança.

O método é definido na criação da assinatura e aplicado a todas as cobranças subsequentes, não é possível misturar PERCENTAGE e FIXED no mesmo bloco splits.

PERCENTAGE

Cada recebedor recebe um percentual do valor da cobrança. A soma dos percentuais dos recebedores deve totalizar 100.

{
  "split_enabled": true,
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": { "id": "ACCO_A54FD6CD-E43F-4783-A7F4-E4352285DC87" },
        "amount": { "value": 2.5 },
        "configurations": {
          "chargeback": { "charge_transfer": { "percentage": 0 } }
        }
      },
      {
        "account": { "id": "ACCO_B56C2BB2-7F93-46AD-9AC2-486F43193FE5" },
        "amount": { "value": 97.5 },
        "configurations": {
          "chargeback": { "charge_transfer": { "percentage": 100 } }
        }
      }
    ]
  }
}

FIXED

Cada recebedor recebe um valor absoluto em centavos. A soma dos value dos recebedores deve ser igual ao valor total da cobrança.

{
  "split_enabled": true,
  "splits": {
    "method": "FIXED",
    "receivers": [
      {
        "account": { "id": "ACCO_9A59C5BA-529E-42CD-9E54-821E9AB4F88B" },
        "amount": { "value": 900 }
      },
      {
        "account": { "id": "ACCO_0E502289-C6F3-4F3B-96DC-BDE6E118C55C" },
        "amount": { "value": 100 }
      }
    ]
  }
}

R$ 9,00 + R$ 1,00 = R$ 10,00, que deve corresponder ao valor da cobrança definida pelo plano.

Exemplo completo de payload

Assinatura com split percentual, dois recebedores e configuração de chargeback:

{
  "best_invoice_date": { "day": "5" },
  "split_enabled": true,
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": { "id": "ACCO_A54FD6CD-E43F-4783-A7F4-E4352285DC87" },
        "amount": { "value": 2.5 },
        "configurations": {
          "chargeback": { "charge_transfer": { "percentage": 0 } }
        }
      },
      {
        "account": { "id": "ACCO_B56C2BB2-7F93-46AD-9AC2-486F43193FE5" },
        "amount": { "value": 97.5 },
        "configurations": {
          "chargeback": { "charge_transfer": { "percentage": 100 } }
        }
      }
    ]
  },
  "plan": { "id": "PLAN_0D4FBDE7-8CC0-4505-970F-236553E8EB3C" },
  "payment_method": [
    {
      "type": "CREDIT_CARD",
      "card": { "security_code": "123" }
    }
  ],
  "customer": {
    "email": "[email protected]",
    "name": "Vanda Lismo",
    "tax_id": "01322345805"
  },
  "reference_id": "d11f8622-5647-4910-98ca-e9ea53a29214"
}

Resposta esperada

{
  "id": "SUBS_69397208-DFE4-4401-B5AA-2F4EF592DDCB",
  "status": "OVERDUE",
  "split_enabled": true,
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": { "id": "ACCO_A54FD6CD-E43F-4783-A7F4-E4352285DC87" },
        "amount": { "value": 2.5 }
      },
      {
        "account": { "id": "ACCO_B56C2BB2-7F93-46AD-9AC2-486F43193FE5" },
        "amount": { "value": 97.5 }
      }
    ]
  }
}

A presença de split_enabled = true e do bloco splits na resposta confirma que o split foi aplicado.

Matriz de regras

❗️

OVERDUE não é erro de split

Indica apenas que a cobrança não foi aprovada (cartão recusado, saldo insuficiente, etc.). Se a resposta contém split_enabled = true e o bloco splits, o split foi configurado corretamente. Nesses casos, investigue a cobrança em paralelo.

Validação no Sandbox

Para validar o cenário em que a cobrança é aprovada (PAID), utilize um dos cartões de teste configurados para esse cenário no sandbox:

Como validar

1. Crie a assinatura usando um dos cartões acima no campo payment_method.card.
2. Confirme que a assinatura foi criada (status ACTIVE, ou semelhante, após processamento).
3. Verifique na resposta que split_enabled = true e que o bloco splits está presente.
4. Consulte a cobrança gerada para validar a distribuição entre recebedores.

Pontos de atenção

• split_id não retorna na criação da assinatura. Para consultar detalhes do split aplicado em cada cobrança, utilize o domínio de pagamentos.
• Mudanças no split exigem nova assinatura. A configuração de split é definida na criação e aplicada a todas as cobranças subsequentes do mesmo ciclo.
• Recebedores devem estar habilitados. O account.id precisa corresponder a uma conta PagBank ativa e habilitada para receber splits.

Exemplos de payload inválido

Quando a API rejeita uma requisição com split inválido, retorna as mensagens de erro abaixo. Para a lista completa de códigos de erro, consulte Códigos de erro da API de Pagamento Recorrente.

split_enabled sem splits

{
  "split_enabled": true,
  "plan": { "id": "PLAN_0D4FBDE7-8CC0-4505-970F-236553E8EB3C" }
}

Motivo do erro: Os campos obrigatórios do split devem ser enviados juntos.

splits sem split_enabled

{
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": { "id": "ACCO_A54FD6CD-E43F-4783-A7F4-E4352285DC87" },
        "amount": { "value": 100 }
      }
    ]
  },
  "plan": { "id": "PLAN_0D4FBDE7-8CC0-4505-970F-236553E8EB3C" }
}

Motivo do erro: A API espera split_enabled e splits no mesmo payload.

Split com cupom

{
  "split_enabled": true,
  "coupon": { "id": "COUP_123" },
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": { "id": "ACCO_A54FD6CD-E43F-4783-A7F4-E4352285DC87" },
        "amount": { "value": 100 }
      }
    ]
  }
}

Motivo do erro: Split e cupom não podem coexistir.

Split em plano com setup_fee

{
  "split_enabled": true,
  "splits": {
    "method": "PERCENTAGE",
    "receivers": [
      {
        "account": { "id": "ACCO_A54FD6CD-E43F-4783-A7F4-E4352285DC87" },
        "amount": { "value": 100 }
      }
    ]
  },
  "plan": { "id": "PLAN_COM_SETUP_FEE" }
}

Motivo do erro: Planos com taxa de adesão (setup_fee) bloqueiam a aplicação de split.

Endpoints

A API disponibiliza os seguintes endpoints para gerenciar pagamentos recorrentes com split:

• Criar assinatura: Crie uma nova assinatura com split ativo, enviando split_enabled e o bloco splits no payload.
• Consultar assinatura: Obtenha os detalhes de uma assinatura, incluindo a configuração de split aplicada.