Originação com Multi Split de Pagamento

Visão Geral

O Multi Split de Desembolso permite distribuir automaticamente o valor de uma operação para múltiplos recebedores no momento do desembolso.

Com essa funcionalidade, uma única operação pode realizar pagamentos para até 20 contas de destino diferentes, eliminando a necessidade de transferências manuais posteriores e simplificando a conciliação financeira.

Como Funciona

A funcionalidade Multi Split deve ser previamente habilitada para o produto contratado pelo time de Implantação da Celcoin.

Durante a criação da application, o cliente poderá informar até 20 contas beneficiárias, definindo para cada uma delas um percentual (%) ou valor fixo (R$) do valor a ser distribuído.

Quando a application atingir o status PENDING_DISBURSEMENT, o sistema realizará o desembolso integral para a conta do Split. Após a conclusão do desembolso e a transição da application para o status ISSUED, será iniciado automaticamente o processamento dos pagamentos para as contas beneficiárias informadas.

Cada pagamento será processado individualmente, respeitando a configuração de distribuição definida na criação da operação.

Criação da Application
→ Dados das contas beneficiárias 
→ Definição do Split (% ou Valor Fixo)
↓
Desembolso
→ Valor enviado para a conta bolsão do Split
↓
Application → ISSUED
↓
Processamento dos Splits
→ Transferência para as contas beneficiárias informadas

Criação da Application

Endpoint

POST /banking/originator/applications

Payload

Exemplo

{
    "product": {
        "id": "c57b97e5-143f-427d-851d-1d4f078b17a2"
    },
    "borrower": {
        "id": "{{borrower_id}}"
    },
    "funding": {
        "id": "9773c5fb-cbd7-41fa-b6b1-e9c76295259f"
    },
    "requested_amount": 20,
    "interest_rate": 0.04,
    "interest_pre_type": "BASE_365",
    "annual_interest_rate": 0.601032,
    "tac_amount": 10,
    "finance_fee": 0,
    "num_payments": 1,
    "first_payment_date": "2026-12-16",
    "disbursement_date": "2026-08-27",
    "insurance_amount": 1.5,
    "beneficiary_account": {
        "registered_account_id": "3382377a-8294-4dc3-8a03-b35a8d971e90"
    },
    "multisplit_accounts": [
        {
            "holder": {
                "name": "Someone",
                "taxpayer_id": "57381789043"
            },
            "pix": {
                "key": "4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab"
            },
            "absolute_amount": 9.8
        },
        {
            "holder": {
                "name": "Someone",
                "taxpayer_id": "57381789043"
            },
            "external_bank_account": {
                "bank_code": "509",
                "bank_account": "499860",
                "bank_account_digit": "5",
                "bank_branch": "0001",
                "bank_account_type": "TRAN",
                "ispb_code": "13935893"
            },
            "percentage_amount": 0.51
        }
    ]
}

Tipos de Chave PIX Suportados

`key_type`	Formato esperado
`EMAIL`	`[email protected]`
`TAXPAYER_ID`	CPF: `12345678900` · CNPJ: `12345678000100` (somente números)
`PHONE_NUMBER`	`+5511999999999` (com DDI)
`ALEATORY_KEY`	UUID aleatório gerado pelo banco (chave aleatória)

Erros Comuns

Situação	Descrição	Ação Recomendada	Exemplo de Retorno
Soma do Split divergente do valor de desembolso	A soma dos valores informados nos splits não corresponde exatamente ao valor líquido do desembolso.	Ajustar os valores dos beneficiários para que a soma total seja exatamente igual ao valor do desembolso.	`Constraint violation error: multisplit sum amount does not match disbursement amount. Disbursement amount: 20.00, total multisplit amount: 19.90`
Conta beneficiária não informada	O produto exige uma conta beneficiária principal (`beneficiary_account`), mas ela não foi enviada na requisição.	Informar a conta beneficiária obrigatória conforme configuração do produto.	`beneficiary account is required for this product`
PIX e Conta Bancária informados simultaneamente	Foi informado mais de um tipo de conta de destino para o mesmo beneficiário.	Informar apenas uma forma de recebimento: PIX ou Conta Bancária.	`inform either external_bank_account or pix, but not both`
Valor Fixo e Percentual informados simultaneamente	Foi informado `absolute_amount` e `percentage_amount` para o mesmo beneficiário.	Informar apenas uma modalidade de distribuição por beneficiário.	`inform either absolute_amount or percentage_amount, but not both`
Quantidade máxima de beneficiários excedida	Foram enviados mais de 20 beneficiários na operação.	Reduzir a quantidade de beneficiários para no máximo 20 contas.	`Constraint violation error: maximum of 20 multisplit_accounts allowed`
Lista de beneficiários não informada	O produto está configurado para Multi Split, mas nenhum beneficiário foi enviado na requisição.	Informar a lista de beneficiários (`multisplit_accounts`) na criação da operação.	`Constraint violation error: multisplit_accounts are required for this product`

Estrutura de Retorno de Erro

Todos os erros de validação retornam HTTP 400 - Bad Request e seguem o formato abaixo:

{
  "message": "Constraint violation error",
  "detail": {
    "campo": [
      "descrição do erro"
    ]
  },
  "is_retryable": false
}

Regras de Negócio

Regra	Descrição
Limite de Recebedores	É permitido informar até 20 contas beneficiárias por operação. Caso o limite seja excedido, a requisição será rejeitada.
Composição do Split	O cliente poderá optar por uma das modalidades de distribuição: percentual (percentage_amount) ou valor fixo (absolute_amount). Não é permitido misturar as modalidades para o mesmo beneficiário.
Regras para Percentual (percentage_amount)	O campo percentage_amount aceita valores entre 0,001 e 1.
Regras para Valor Fixo (`absolute_amount`)	O campo `absolute_amount`deve respeitar o valor líquido disponível para desembolso. Não é permitido informar simultaneamente os campos `absolute_amount`e percentage_amount para o mesmo beneficiário.
Validação dos Valores	A soma dos valores ou percentuais informados deve corresponder exatamente ao valor líquido do desembolso. Caso contrário, a operação será rejeitada.
Dados da Conta de Destino	Cada beneficiário deverá possuir exclusivamente uma forma de recebimento: Chave PIX ou Dados Bancários. Não é permitido informar ambos simultaneamente para o mesmo beneficiário.
Validade da Simulação	O campo `simulation_id` é obtido através do endpoint de simulação. A simulação possui validade de 24 horas, sendo recomendado criar a application logo após sua geração.

Consulta dos Pagamentos

Endpoint

GET/banking/originator/multisplit/application/{{application_id}}

{
  "content": [
    {
      "id": "627698f5-b1f2-466c-875b-1c58ed824fe5",
      "external_bank_account": null,
      "status": "PENDING | PROCESSING | ERROR | SUCCESS",
      "error_message": "Creditor account invalid",
      "pix": {
        "key": "4ca519ef-0ccc-4c41-b58b-c88f1f47d8ab",
        "key_type": "ALEATORY_KEY"
      },
      "holder": {
        "name": "Someone",
        "taxpayer_id": "57381789043"
      },
      "absolute_amount": 1,
      "percentage_amount": null,
      "version": 0,
      "created_at": "2026-06-09T19:13:42.522059Z",
      "updated_at": null
    },
    {
      "id": "9773c5fb-cbd7-41fa-b6b1-e9c76295259f",
      "external_bank_account": {
        "bank_code": "509",
        "bank_account": "499860",
        "bank_account_digit": "5",
        "bank_branch": "0001",
        "bank_account_type": "TRAN",
        "ispb_code": "13935893"
      },
      "status": "PENDING | PROCESSING | ERROR | SUCCESS",
      "error_message": "",
      "pix": null,
      "holder": {
        "name": "Someone",
        "taxpayer_id": "57381789043"
      },
      "absolute_amount": 0.5,
      "percentage_amount": null,
      "version": 0,
      "created_at": "2026-06-09T19:13:42.532059Z",
      "updated_at": null
    }
  ],
  "page": 0,
  "size": 25,
  "total_pages": 1,
  "total_elements": 2,
  "has_next": false
}

📘
Evolução - Reprocessamento de Falhas
Inicialmente os pagamentos aos beneficiários que ocorrem falha, serão reprocessados uma vez ao dia, de segunda a sexta-feira.
Em uma evolução breve, será disponibilizado um mecanismo para que o próprio cliente possa solicitar o reprocessamento.