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 de Status 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
}

Consulta de Comprovantes de Pagamento

A consulta dos comprovantes via API é realizada em duas etapas:

Listar os comprovantes disponíveis para uma operação, utilizando o application_id.
Consultar um comprovante específico, utilizando o payout_id retornado na primeira consulta.

O comprovante poderá ser obtido em PDF ou JSON.

1. Listar os comprovantes da operação

Utilize o application_id da operação para consultar todos os comprovantes de pagamentos disponíveis.

Endpoint:

GET https://platform.flowfinance.com.br/banking/originator/multisplit/application/{application_id}/receipts

Substitua {application_id} pelo ID da operação que deseja consultar.

Exemplo de resposta:

{
  "application_id": "5710f422-5568-4f88-894b-e7ea04515afe",
  "receipts": [
    {
      "payout_id": "4aeed000-621e-4803-87a6-5b5188d82396",
      "status": "SUCCESS",
      "amount": 10.00,
      "created_at": "2026-08-04T13:16:33.261153Z",
      "links": {
        "pdf": "/originator/multisplit/payouts/4aeed000-621e-4803-87a6-5b5188d82396/receipt?format=pdf",
        "json": "/originator/multisplit/payouts/4aeed000-621e-4803-87a6-5b5188d82396/receipt?format=json"
      }
    },
    {
      "payout_id": "a1aad4fd-b181-405c-8817-b8893d902f9e",
      "status": "SUCCESS",
      "amount": 10.00,
      "created_at": "2026-08-04T13:16:34.775Z",
      "links": {
        "pdf": "/originator/multisplit/payouts/a1aad4fd-b181-405c-8817-b8893d902f9e/receipt?format=pdf",
        "json": "/originator/multisplit/payouts/a1aad4fd-b181-405c-8817-b8893d902f9e/receipt?format=json"
      }
    }
  ]
}

Entendendo o retorno

Campo	Descrição
`application_id`	Identificador da operação consultada.
`payout_id`	Identificador do pagamento. Utilize esse ID para consultar o comprovante individual.
`status`	Status do pagamento.
`amount`	Valor do pagamento.
`created_at`	Data e horário de criação do pagamento.
`links.pdf`	Caminho para obtenção do comprovante em PDF.
`links.json`	Caminho para obtenção dos dados do comprovante em JSON.

Importante: uma operação pode possuir mais de um pagamento. Por isso, a resposta poderá retornar vários payout_id, cada um representando um pagamento e seu respectivo comprovante.

2. Consultar um comprovante

Após identificar o payout_id do pagamento desejado, utilize-o para consultar o comprovante.

Endpoint:

GET https://platform.flowfinance.com.br/banking/originator/multisplit/payouts/{payout_id}/receipt?format={format}

Substitua:

{payout_id} pelo identificador do pagamento retornado na consulta anterior.
{format} por json ou pdf, de acordo com o formato desejado.

Header:

Authorization: Bearer <TOKEN>

Formato do comprovante

O parâmetro format define como o comprovante será retornado.

Comprovante em JSON

Para obter os dados do comprovante em JSON, utilize:

GET https://platform.flowfinance.com.br/banking/originator/multisplit/payouts/{payout_id}/receipt?format=json

Exemplo de resposta:

{
  "title": "Comprovante de Desembolso",
  "paid_at": "2026-08-04T13:16:33Z",
  "amount": 10.00,
  "payer": {
    "name": "VIA CAPITAL - SOCIEDADE DE CREDITO DIRETO S/A",
    "institution": "CELCOIN INSTITUICAO DE PAGAMENTO S.A.",
    "branch": "0001",
    "account": "497546184",
    "tax_id": "48632754000190",
    "pix_key": null
  },
  "payee": {
    "name": "Nome completo",
    "institution": "Banco 123",
    "branch": "0001",
    "account": "123456",
    "tax_id": "12312312312",
    "pix_key": "12312312312"
  },
  "end_to_end_id": "1",
  "application_id": "5710f422-5568-4f88-7896-e7ea04515afe",
  "sequential_id": null,
  "transaction_id": "4aeed000-621e-4803-7895-5b5188d82396"
}

Comprovante em PDF

Para obter o comprovante pronto em PDF, utilize:

GET https://platform.flowfinance.com.br/banking/originator/multisplit/payouts/{payout_id}/receipt?format=pdf

Dessa forma, o cliente poderá baixar o comprovante pronto em PDF ou utilizar os dados retornados em JSON para gerar seu próprio comprovante.

📘
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.

📘
Devolução Pix
O serviço de Multi Split não contempla o fluxo de devolução por se tratar de um modelo de produto CDC.