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 operação, 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",
      "account_id": "3382377a-8294-4dc3-8a03-b35a8d971e90",
      "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",
      "account_id": "77f46d26-0ef4-40db-a61e-a7022225e9f8",
      "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
}

📘
O account_id identifica a conta de destino vinculada ao pagamento.
Esse identificador deverá ser utilizado caso seja necessário editar os dados da conta de um pagamento com status ERROR.

Webhook de Status dos Pagamentos

Além da consulta de status via API, o Multi Split permite receber atualizações dos pagamentos por meio de webhook.

Sempre que houver uma atualização no status de um pagamento, a Celcoin enviará uma notificação para a URL previamente cadastrada.

O evento utilizado para atualização dos pagamentos é: multisplit.payments.status_updated

Configuração

Para utilizar o webhook, disponibilize uma URL para recebimento dos eventos e solicite a configuração ao contato Celcoin responsável pela sua conta.

Após a configuração, as atualizações de status dos pagamentos serão enviadas para a URL cadastrada.

Exemplo de evento

{
  "event_type": "multisplit.payments.status_updated",
  "timestamp": "2026-09-08T17:17:17.668212115Z",
  "data": {
    "payout_id": "6648040e-df43-4bb4-88e3-b36390d58c47",
    "account_id": "3382377a-8294-4dc3-8a03-b35a8d971e90",
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234467899",
    "status": "PROCESSING",
    "amount": 50000,
    "sequential_id": "",
    "error_message": ""
  }
}

Entendendo o retorno

Campo	Descrição
`event_type`	Identifica o tipo do evento. Para atualização do status dos pagamentos, será retornado `multisplit.payments.status_updated`.
`timestamp`	Data e horário em que o evento foi gerado.
`payout_id`	Identificador único do pagamento.
`account_id`	Identificador da conta de destino vinculada ao pagamento. Utilize esse ID para editar os dados da conta quando o pagamento estiver com status `ERROR`.
`application_id`	Identificador da operação de crédito relacionada ao pagamento.
`status`	Status atual do pagamento.
`amount`	Valor do pagamento.
`sequential_id`	Identificador sequencial da operação, quando disponível.
`error_message`	Detalhes do erro quando houver falha no processamento do pagamento.

Status dos pagamentos

Status	Descrição
`PENDING`	Pagamento aguardando processamento.
`PROCESSING`	Pagamento em processamento.
`ERROR`	Ocorreu uma falha no processamento do pagamento.
`SUCCESS`	Pagamento realizado com sucesso.

Pagamentos com erro

Quando o pagamento apresentar o status ERROR, o campo error_message poderá conter informações adicionais sobre o motivo da falha.

{
  "event_type": "multisplit.payments.status_updated",
  "timestamp": "2026-09-08T17:08:50.058434Z",
  "data": {
    "payout_id": "6648040e-df43-4bb4-88e3-b36390d58c47",
    "account_id": "3382377a-8294-4dc3-8a03-b35a8d971e90",
    "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234467899",
    "status": "ERROR",
    "amount": 50000,
    "sequential_id": "",
    "error_message": "{\"errorCode\":\"PBE7055\",\"message\":\"Transaction settlement denied due to counterparty response timeout.\"}"
  }
}

📘
Utilize o payout_id para identificar individualmente o pagamento que sofreu a alteração.
O application_id permite relacionar o pagamento à respectiva operação de crédito.
O account_id identifica a conta vinculada ao pagamento e deverá ser utilizado caso seja necessário editar seus dados.

Edição dos Dados da Conta

Quando um pagamento do Multi Split apresentar status ERROR, é possível editar os dados da conta de destino do beneficiário antes de realizar uma nova tentativa de pagamento.

A edição permite corrigir os dados de recebimento sem alterar o valor ou a composição originalmente definida para o Multi Split.

📘
A edição está disponível exclusivamente para pagamentos com status ERROR.

Identificando a conta

Para realizar a edição, utilize o account_id correspondente à conta que deseja atualizar.

O account_id pode ser obtido por meio:

da Consulta de Status dos Pagamentos;
do webhook multisplit.payments.status_updated.

Endpoint

PUT /banking/originator/multisplit/payment-account/{account_id}

Substitua {account_id} pelo identificador da conta vinculada ao pagamento com falha.

Dados que podem ser editados

A edição permite atualizar os dados utilizados para realizar o pagamento do beneficiário.

É possível atualizar:

dados do titular (holder);
chave PIX (pix);
dados bancários (external_bank_account).

Regras de edição

A edição altera somente os dados da conta de destino.

Não é possível alterar por meio desse endpoint:

o valor destinado ao beneficiário;
absolute_amount;
percentage_amount;
a composição do Multi Split.

Também deve ser informada somente uma forma de recebimento para a conta: PIX ou dados bancários.

📘
A edição dos dados da conta não realiza automaticamente uma nova tentativa de pagamento.
Após a atualização, utilize o fluxo de reprocessamento do pagamento para realizar uma nova tentativa com os dados corrigidos.

Fluxo de edição

Pagamento
↓
ERROR
↓
Identificar o account_id
↓
Editar os dados da conta
↓
Conta atualizada
↓
Reprocessar o pagamento
↓
Nova tentativa de pagamento

Restrição de status

A edição será permitida somente quando o pagamento relacionado à conta estiver com status ERROR.

Caso seja solicitada a edição de um pagamento que não esteja elegível, será retornado:

{
  "message": "Multi Split payment can only be edited when status is ERROR.",
  "is_retryable": false
}

Reprocessamento de Pagamentos com Falha

Quando uma operação Multi Split possuir pagamentos com status ERROR, é possível solicitar uma nova tentativa de processamento.

O reprocessamento é realizado pela application_id e considera somente os pagamentos daquela operação que ainda estiverem com falha e elegíveis para uma nova tentativa.

Pagamentos já concluídos ou que estejam em processamento não serão executados novamente.

📘
O reprocessamento é realizado no nível da application_id.
Caso a operação possua mais de um pagamento em ERROR, todos os pagamentos elegíveis poderão ser considerados na nova tentativa.

Endpoint

POST /banking/originator/multisplit/application/{application_id}/reprocess

Substitua {application_id} pelo identificador da operação que possui os pagamentos que deverão ser reprocessados.

Exemplo de requisição

curl --location --request POST 'https://sandbox.platform.flowfinance.com.br/banking/originator/multisplit/application/{{application_id}}/reprocess' \
--header 'Authorization: {{access_token}}' \
--header 'Content-Type: application/json'

Pagamentos elegíveis

Durante o reprocessamento, somente pagamentos com falha e elegíveis para uma nova tentativa serão considerados.

Status	Comportamento
`ERROR`	Poderá ser reprocessado.
`PROCESSING`	Não será reprocessado.
`SUCCESS`	Não será reprocessado.

Correção dos dados antes do reprocessamento

Caso a falha esteja relacionada aos dados da conta de destino, realize primeiro a edição dos dados da conta utilizando o account_id.

Após a correção, solicite o reprocessamento pela application_id.

Pagamento → ERROR
↓
Identificar o motivo da falha
↓
Editar os dados da conta, quando necessário
↓
Solicitar o reprocessamento
↓
Nova tentativa de pagamento

A nova tentativa utilizará os dados atualizados da conta.

📘
Não é necessário editar os dados da conta quando a falha não estiver relacionada às informações de recebimento.
Nesse caso, o reprocessamento poderá ser solicitado diretamente, desde que o pagamento esteja elegível para uma nova tentativa.

Processamento assíncrono

O reprocessamento ocorre de forma assíncrona.

Quando a solicitação for aceita, a API retornará:

HTTP 202 Accepted

O retorno 202 Accepted indica que a solicitação foi aceita para processamento e não representa a conclusão do pagamento.

Após o início da nova tentativa, acompanhe a evolução dos pagamentos por meio da Consulta de Status dos Pagamentos ou do webhook multisplit.payments.status_updated.

Atualização dos status

Após o início do reprocessamento, cada pagamento seguirá novamente seu fluxo de processamento.

ERROR
↓
Solicitação de reprocessamento
↓
202 Accepted
↓
PROCESSING
↓
SUCCESS ou ERROR

As atualizações serão comunicadas individualmente pelo webhook, utilizando o payout_id para identificação do pagamento.

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.

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