Originação com Split de Pagamento

Visão Geral

O split de pagamento permite que, no momento do desembolso de uma CCB, um percentual ou valor fixo do valor seja direcionado automaticamente para uma conta beneficiária externa — sem intervenção manual. Isso é configurado diretamente no payload de criação da application, via o objeto split_beneficiary_account.

Endpoint

POST /banking/originator/applications

Payload Completo

Exemplo com percentage (percentual)

{
  "borrower": {
    "id": "{{borrowerId}}"
  },
  "product": {
    "id": "{{productId}}"
  },
  "funding": {
    "id": "{{fundingId}}"
  },
  "simulation_id": "cfdd28ea-94aa-4f7b-806e-3b156bd0e90c",
  "signature_collect_method": "LINK",
  "signature_provider": "ZAPSIGN",
  "split_beneficiary_account": {
    "external_bank_account": {},
    "holder": {
      "name": "Felipe Tavares",
      "taxpayer_id": "123456789"
    },
    "pix": {
      "key": "[email protected]",
      "key_type": "EMAIL"
    },
    "percentage": 10
  }
}

Exemplo com amount (valor monetário fixo)

{
  "requested_amount": 10000,
  "interest_rate": 0.01,
  "tac_amount": 0,
  "finance_fee": 0,
  "insurance_amount": 0,
  "num_payments": 12,
  "first_payment_date": "2026-05-17",
  "disbursement_date": "2026-04-17",
  "amortization_type": "PRICE",
  "amortization_frequency": "MONTHLY",
  "grace_period_amortization": [],
  "interest_pre_type": "BASE_360",
  "interest_rate_frequency": "MONTHLY",
  "borrower": {
    "id": "{{borrowerId}}"
  },
  "product": {
    "id": "{{productId}}"
  },
  "funding": {
    "id": "{{fundingId}}"
  },
  "simulation_id": "{{simulationId}}",
  "signature_collect_method": "LINK",
  "signature_provider": "CELCOIN",
  "split_beneficiary_account": {
    "external_bank_account": {
      "ispb_code": "00000000",
      "bank_account": "31231",
      "bank_account_digit": "2",
      "bank_branch": "0001",
      "bank_account_type": "CACC"
    },
    "holder": {
      "name": "Felipe Tavares",
      "taxpayer_id": "12345678900"
    },
    "pix": {
      "key": "[email protected]",
      "key_type": "EMAIL"
    },
    "amount": 1000
  }
}

Referência de Campos

Campos raiz

* split_beneficiary_account é obrigatório apenas quando o produto ou a operação exige split. Se omitido, o desembolso segue o fluxo padrão sem divisão.

Objeto split_beneficiary_account

* pix é obrigatório quando external_bank_account for enviado vazio. Se ambos forem preenchidos, o PIX tem precedência — confirmar comportamento no ambiente de destino.

** percentage vs amount — os dois campos são mutuamente exclusivos. Use percentage para definir um percentual sobre o valor total desembolsado, ou amount para definir um valor fixo em reais. Envie apenas um deles por operação.

Como Funciona o Split

O split é executado automaticamente no momento do desembolso, após a application atingir o estado PENDING_DISBURSEMENT ou SCHEDULED_DISBURSEMENT.

Desembolso aprovado
  → Valor total calculado
  → Split: X% ou R$ X fixo → conta beneficiária (PIX ou conta bancária)
  → Restante → destino padrão do produto
  → Application → ISSUED

Exemplo com percentage: 10 e desembolso de R$ 1.500:

Exemplo com amount: 1000 e desembolso de R$ 10.000:

Tipos de Chave PIX Suportados

Provedores de Assinatura

Observações Importantes

simulation_id — gerado pelo endpoint /preview. Expira após um período configurado no produto. Sempre crie a application logo após a simulação para evitar expiração.

Percentual máximo — o campo percentage aceita valores de 1 a 100. Um split de 100 direciona o valor total ao beneficiário. Validar com o time de produto se há limite configurado por produto.

Valor fixo (amount) — o campo amount deve ser menor que o valor total do desembolso. Não envie amount e percentage simultaneamente no mesmo payload.

Erros Comuns