Pagamentos com Split

O split de pagamento permite dividir automaticamente o valor de uma transação entre múltiplas subcontas (submerchants). A divisão é definida no momento da criação do pagamento, e a liquidação de cada recebedor acontece de forma automática — inclusive a reversão em caso de estorno ou chargeback. Casos de uso típicos: lojas que dividem receita com parceiros ou afiliados, marketplaces, plataformas SaaS que repassam valores a parceiros e PSPs/PaaS que operam subcontas.

Pré-requisitos

Produtos habilitados

Os produtos PaaS e Split precisam estar habilitados para o seu merchant. A ativação é feita pela equipe UvviPay — solicite ao seu contato comercial.

Subcontas criadas e aprovadas

As subcontas recebedoras devem estar criadas via POST /v1/submerchants e ativas. Guarde o id (UUID) retornado na criação — ele é usado como recipientId nas regras de split. O owner não precisa de subconta: sem subMerchant no payload, o próprio merchant é o owner.

Como funciona

Em um pagamento com split existem dois papéis:

Papel	Como é definido	Função
Owner	O próprio merchant (padrão) ou o objeto `subMerchant` do payload	Dono da transação. Recebe o valor líquido e é a origem dos valores distribuídos
Recebedores	Array `split` do payload	Subcontas que recebem uma parte do valor líquido

O objeto subMerchant é opcional. Sem ele, o próprio merchant é o owner do split — o caso comum de quem quer apenas dividir valores com parceiros. Quando informado, o subMerchant identifica pelo documento (CPF/CNPJ) uma subconta já cadastrada, que passa a ser owner; se o documento for o do próprio merchant sem subconta cadastrada, o merchant segue como owner.

O owner não precisa (nem pode) aparecer entre os recebedores do split: o restante do líquido já permanece com ele automaticamente.

Base de cálculo: valor líquido

O split é calculado sobre o valor líquido da transação:

líquido = valor bruto - taxas (MDR + taxa fixa) - reserva financeira

As taxas da transação são sempre suportadas pelo owner. O que for definido no split sai do líquido do owner e é creditado aos recebedores; o restante permanece com o owner.

Regras de split

Cada regra do array split tem três campos:

Campo	Tipo	Descrição
`recipientId`	string (UUID)	`id` da subconta recebedora, retornado na criação da subconta
`type`	`percentage` \| `flat`	Forma de cálculo da regra
`amount`	number	Percentual (1 a 100) quando `type=percentage`, ou valor inteiro em centavos quando `type=flat`

Os dois tipos podem ser combinados na mesma transação.

Percentual (`percentage`)

O valor do recebedor é líquido × percentual / 100, arredondado para o centavo mais próximo.

Quando os percentuais somam exatamente 100 (sem regras flat), o último recebedor absorve o resíduo de arredondamento, garantindo que o líquido seja distribuído por completo, centavo a centavo.

Valor fixo (`flat`)

O recebedor recebe exatamente o valor informado, em centavos. O valor deve ser inteiro — centavos fracionados são rejeitados.

Validações

A criação do pagamento é rejeitada com 400 Bad Request quando qualquer regra abaixo é violada:

Regra	Erro
`subMerchant` informado com documento sem subconta cadastrada (e diferente do documento do merchant)	`Subconta owner do split nao encontrada para o documento do subMerchant informado`
Produto PaaS não habilitado para o merchant	`Split requer o produto PaaS habilitado para este merchant`
Produto Split não habilitado para o merchant	`Produto Split nao esta habilitado para este merchant`
Recebedor inexistente ou de outro merchant	`Recebedor de split nao encontrado`
Recebedor inativo	`Recebedor de split inativo`
Recebedor repetido no array	`Recebedor duplicado no split`
Owner incluído como recebedor	`Recebedor de split nao pode ser o subMerchant owner da transacao`
Percentual fora de 1–100 ou soma dos percentuais acima de 100	`Percentual de split deve estar entre 1 e 100` / `A soma dos percentuais de split nao pode exceder 100`
Valor `flat` fracionado	`Valor flat de split deve ser inteiro em centavos`
Soma das regras acima do líquido	`A soma dos valores de split excede o valor liquido da transacao`

Exemplo de requisição

Pagamento PIX de R$ 100,00 com split: 30% para uma subconta e R$ 20,00 fixos para outra. O restante do líquido permanece com o owner — neste exemplo, o próprio merchant (sem subMerchant no payload).

POST /v1/payments

{
  "externalId": "ORDER-12345",
  "amount": 10000,
  "paymentMethod": "pix",
  "customer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": { "number": "12345678901", "type": "cpf" }
  },
  "items": [
    { "title": "Produto Exemplo", "quantity": 1, "unitPrice": 10000 }
  ],
  "split": [
    {
      "recipientId": "5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f",
      "type": "percentage",
      "amount": 30
    },
    {
      "recipientId": "8c1e5f7b-4d3e-4a8b-8c0d-1e2f3a4b5c6d",
      "type": "flat",
      "amount": 2000
    }
  ]
}

Para que uma subconta seja owner (caso PaaS/marketplace), envie também o objeto subMerchant com o documento dela — os demais campos do pagamento não mudam. Supondo taxas + reserva de R$ 5,00 (500 centavos), a distribuição do líquido de R$ 95,00 (9500) seria:

Conta	Valor
Recebedor 1 (30% de 9500)	R$ 28,50
Recebedor 2 (flat)	R$ 20,00
Owner (restante)	R$ 46,50

Split na resposta

A resposta da criação e da consulta (GET /v1/payments/{id}) inclui o campo split com o valor efetivamente calculado para cada recebedor, em centavos. Os webhooks de status da transação (transaction.paid, transaction.refunded, transaction.chargedback etc.) também carregam o mesmo campo split no data:

{
  "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "status": "paid",
  "amount": 10000,
  "paymentMethod": "pix",
  "split": [
    { "recipient_id": "5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f", "amount": 2850 },
    { "recipient_id": "8c1e5f7b-4d3e-4a8b-8c0d-1e2f3a4b5c6d", "amount": 2000 }
  ]
}

Transações com split criadas antes da disponibilização deste campo não retornam split na consulta.

Estorno e chargeback

O split é revertido automaticamente — nenhuma ação adicional é necessária:

Estorno (PUT /v1/payments/{id}/refund): na mesma operação do estorno, cada recebedor é debitado no valor que recebeu e esse valor é creditado de volta ao owner.
Chargeback: mesma reversão, vinculada ao chargeback correspondente.

A reversão usa exatamente os valores distribuídos na venda. Se o saldo de um recebedor for insuficiente, o débito ainda é registrado e o saldo pode ficar negativo até compensação futura.

Perguntas frequentes

Preciso ser marketplace ou PaaS para usar split?

Não — você não precisa operar como marketplace nem como plataforma. A ativação do split usa dois produtos internos, chamados PaaS e Split, habilitados pela equipe UvviPay via contato comercial; o nome do produto não exige que o seu negócio seja um PaaS. Depois de habilitado, basta enviar o array split no pagamento: sem o objeto subMerchant, o próprio merchant é o owner da transação, sem nenhum cadastro adicional.

Preciso me cadastrar como subconta para usar split?

Não. O owner padrão do split é o próprio merchant. Você só cria subcontas para os recebedores (seus parceiros). O objeto subMerchant no pagamento é opcional e serve apenas para operações em que uma subconta é a dona da transação (caso marketplace).

O split incide sobre o valor bruto ou líquido?

Sobre o líquido: valor bruto menos taxas (MDR + taxa fixa) e reserva financeira. As taxas da transação são sempre do owner — os recebedores recebem o valor da regra sem desconto de tarifas.

Como sei quanto foi efetivamente para cada recebedor?

A resposta da criação, a consulta (GET /v1/payments/{id}) e os webhooks de status trazem o campo split com o valor calculado por recebedor, em centavos: [{ "recipient_id": "...", "amount": 2850 }]. É o valor final, já com arredondamento aplicado.

E se a soma dos percentuais for menor que 100?

O restante do líquido permanece com o owner automaticamente. Inválido apenas quando os percentuais ultrapassam 100 ou quando a soma das regras excede o líquido.

Como funciona o arredondamento de percentuais?

Cada regra é arredondada para o centavo mais próximo. Quando os percentuais somam exatamente 100 (sem regras flat), o último recebedor do array absorve o resíduo, garantindo que o líquido seja distribuído por completo.

Posso alterar o split depois que o pagamento foi criado?

Não. O split é definido na criação do pagamento e é imutável. Para uma divisão diferente, crie um novo pagamento. Ajustes excepcionais devem ser tratados com o suporte.

O que acontece com o split em estorno ou chargeback?

A reversão é automática e integral: cada recebedor é debitado exatamente no valor que recebeu, e o valor volta ao owner na mesma operação. Se o saldo do recebedor for insuficiente, ele pode ficar negativo até compensação.

O pagamento foi recusado — o split foi aplicado?

Não. O split só é efetivado na liquidação de pagamentos aprovados. A validação das regras acontece antes da cobrança: se alguma regra for inválida, a transação nem chega a ser cobrada (erro 400).

Quando o recebedor pode usar o valor?

O valor segue a liquidação normal da transação: em PIX entra como saldo disponível; em cartão entra como saldo agendado e fica disponível conforme o cronograma de recebíveis.

Pré-requisitos

Como funciona

Base de cálculo: valor líquido

Regras de split

Percentual (`percentage`)

Valor fixo (`flat`)

Validações

Exemplo de requisição

Split na resposta

Estorno e chargeback

Perguntas frequentes

Próximos passos

Criar pagamento

Criar subconta

​Pré-requisitos

​Como funciona

​Base de cálculo: valor líquido

​Regras de split

​Percentual (percentage)

​Valor fixo (flat)

​Validações

​Exemplo de requisição

​Split na resposta

​Estorno e chargeback

​Perguntas frequentes

​Próximos passos

Criar pagamento

Criar subconta

Pré-requisitos

Como funciona

Base de cálculo: valor líquido

Regras de split

Percentual (`percentage`)

Valor fixo (`flat`)

Validações

Exemplo de requisição

Split na resposta

Estorno e chargeback

Perguntas frequentes

Próximos passos